---
title: "Start a run"
method: POST
path: "/v1/runs"
---

# Start a run

`POST /v1/runs`

## Request

- Base URL: `https://api.proxymail.qa`
- URL: `https://api.proxymail.qa/v1/runs`
- Auth: HTTP bearer

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.

## Request body

- object
  - `name` string
  - `source` 'ci' | 'agent' | 'api': Where it runs. Default: agent for keys from an MCP sign-in, api for the rest.
  - `meta` object
    - `repository` string
    - `branch` string
    - `commit` string: A commit hash.
    - `pull_request` integer
    - `workflow` string
    - `job_url` string, uri: An https:// link to the job.
    - `agent` string

## Response `201`

The run

- Run
  - `id` string, uuid
  - `name` string
  - `source` 'ci' | 'agent' | 'api'
  - `status` 'running' | 'passed' | 'failed'
  - `meta` object
  - `started_at` string, date-time
  - `finished_at` string, date-time, nullable
  - `url` string, uri: The run in the app.
  - `project` object
    - `id` string
    - `name` string
  - `events` object[]: What the run saw, oldest first. Not in lists.
    - `at` string, date-time
    - `kind` 'address' | 'email' | 'missing' | 'none' | 'count' | 'checks' | 'note' | 'checkout'
    - `address` string, nullable
    - `failed` boolean
    - `detail` object: 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.

## Other responses

- `400`: An error

---

[API](https://skmtc.dev/proxymail/apis/proxy-mail-qa-api.md) · [All operations](https://skmtc.dev/proxymail/apis/proxy-mail-qa-api/llms.txt) · [OpenAPI document](https://skmtc.dev/proxymail/apis/proxy-mail-qa-api/revisions/8f8a5e84cf5c?raw)