Skip to content
Docs

Start a run

POST
/v1/runs
curl --request POST \
  --url https://api.proxymail.qa/v1/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Run", "source": "ci", "meta": { "repository": "acme/web", "branch": "example", "commit": "example", "pull_request": 1, "workflow": "example", "job_url": "https://example.com", "agent": "Claude Code" } }'

Groups a CI job or an agent session as one run, with a report for a pull request. Send its id in the Proxy-Mail-QA-Run header of later calls and each adds what it saw: addresses made, emails that arrived and how long after since, the code, a link’s site and path (never its query or anything that looks like a token), email checks, counts, and emails that never came or came when none should. Then finish it. Runs are kept 90 days, and the project’s people can open them in the app. The GitHub Action (https://proxymail.qa/docs/ci) does all of this for you.

Authorizations

Section titled “Authorizations”

Request Body

Section titled “Request Body”
Media typeapplication/json
object
name
string
default: Run <= 120 characters

Example 

Sign-up tests
source

Where it runs. Default: agent for keys from an MCP sign-in, api for the rest.

string
Allowed values: ci agent api
meta
object
repository
string

Example 

acme/web
branch
string
commit

A commit hash.

string
pull_request
integer
workflow
string
job_url

An https:// link to the job.

string format: uri
agent
string

Example 

Claude Code

Responses

Section titled “Responses”

201

Section titled “201”

The run

Media typeapplication/json
object
id
string format: uuid
name
string
source
string
Allowed values: ci agent api
status
string
Allowed values: running passed failed
meta
object
started_at
string format: date-time
finished_at
string | null format: date-time
url

The run in the app.

string format: uri
project
object
id
string
name
string
events

What the run saw, oldest first. Not in lists.

Array<object>
object
at
string format: date-time
kind
string
Allowed values: address email missing none count checks note checkout
address
string | null
failed
boolean
detail

Email: type, subtype, service, received_at, after_seconds, and code or link and goes_to ({ site, path }). missing: what was waited for and hint. none: arrived, since, until. count: count. checks: passed, failed, warnings and notes. note: text.

object

Example 

{
  "source": "ci",
  "status": "running",
  "events": [
    {
      "kind": "address"
    }
  ]
}

400

Section titled “400”

An error

Media typeapplication/json
object
error
string
message
string

Example generated

{
  "error": "example",
  "message": "example"
}