---
title: "Start a run | Proxy Mail QA"
description: "Developer docs for Proxy Mail QA: the MCP server for coding agents, the REST API for test suites, and the Chrome extension."
url: https://proxymail.qa/docs/reference/operations/startrun
---

# Start a run

POST

/v1/runs

```js
const url = 'https://api.proxymail.qa/v1/runs';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"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"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```sh
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

- **[apiKey](https://proxymail.qa/docs/reference.html#apikey)**

## Request Body

Media typeapplication/json

### object

**name**

string

default: Run <= 120 characters

### Example 

```plaintext
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 

```plaintext
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 

```plaintext
Claude Code
```

## Responses

### 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 

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

### 400

An error

Media typeapplication/json

### object

**error**

string

**message**

string

#### Example generated

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

[Previous List the project’s runs, newest first](https://proxymail.qa/docs/reference/operations/listruns.html) [Next Read a run and its evidence](https://proxymail.qa/docs/reference/operations/getrun.html)