# Yara Email API

Transactional and marketing email. 202 means queued, not delivered. Test keys simulate sending.

- [Interactive documentation](/docs)
- [OpenAPI 3.1 JSON](/openapi.json)
- [Agent index](/llms.txt)

## Headless agents

MCP clients with a browser connect to `https://email.tryyara.co/mcp` and sign in with OAuth. A headless agent uses an API key instead:

1. Create an API key in Yara Email > API keys with only the permissions the agent needs (read, send, manage) and the right environment (test or live).
2. Configure the MCP client with URL `https://email.tryyara.co/mcp` and header `Authorization: Bearer <key>`.

```json
{
  "mcpServers": {
    "yara-email": {
      "url": "https://email.tryyara.co/mcp",
      "headers": {
        "Authorization": "Bearer ${YARA_EMAIL_KEY}"
      }
    }
  }
}
```

The session gets that key's environment, permissions and sender domains. Read-only keys only see read tools. Credential tools are not available over MCP. Revoking the key ends access immediately.

## Auth

- [List MCP connections](/docs/operations/listMcpConnections.md): `GET /v1/mcp-connections`
- [Revoke MCP connection](/docs/operations/revokeMcpConnection.md): `POST /v1/mcp-connections/{id}/revoke`
- [Get current identity](/docs/operations/getCurrentIdentity.md): `GET /v1/me`
- [List agent tokens](/docs/operations/listAgentTokens.md): `GET /v1/agent-tokens`
- [Create agent token](/docs/operations/createAgentToken.md): `POST /v1/agent-tokens`
- [Revoke agent token](/docs/operations/revokeAgentToken.md): `POST /v1/agent-tokens/{id}/revoke`

## ApiKeys

- [List api keys](/docs/operations/listApiKeys.md): `GET /v1/api-keys`
- [Create api key](/docs/operations/createApiKey.md): `POST /v1/api-keys`
- [Revoke api key](/docs/operations/revokeApiKey.md): `POST /v1/api-keys/{id}/revoke`

## Audience

- [List contacts](/docs/operations/listContacts.md): `GET /v1/contacts`
- [Create contact](/docs/operations/createContact.md): `POST /v1/contacts`
- [Get contact](/docs/operations/getContact.md): `GET /v1/contacts/{id}`
- [Update contact](/docs/operations/updateContact.md): `PATCH /v1/contacts/{id}`
- [Delete contact](/docs/operations/deleteContact.md): `DELETE /v1/contacts/{id}`
- [List contact lists](/docs/operations/listContactLists.md): `GET /v1/lists`
- [Create contact list](/docs/operations/createContactList.md): `POST /v1/lists`
- [Get contact list](/docs/operations/getContactList.md): `GET /v1/lists/{id}`
- [Update contact list](/docs/operations/updateContactList.md): `PATCH /v1/lists/{id}`
- [Delete contact list](/docs/operations/deleteContactList.md): `DELETE /v1/lists/{id}`
- [List list members](/docs/operations/listListMembers.md): `GET /v1/lists/{id}/members`
- [Add list members](/docs/operations/addListMembers.md): `POST /v1/lists/{id}/members`
- [Remove list member](/docs/operations/removeListMember.md): `DELETE /v1/lists/{id}/members/{contactId}`
- [List segments](/docs/operations/listSegments.md): `GET /v1/segments`
- [Create segment](/docs/operations/createSegment.md): `POST /v1/segments`
- [Get segment](/docs/operations/getSegment.md): `GET /v1/segments/{id}`
- [Update segment](/docs/operations/updateSegment.md): `PATCH /v1/segments/{id}`
- [Delete segment](/docs/operations/deleteSegment.md): `DELETE /v1/segments/{id}`
- [Preview segment](/docs/operations/previewSegment.md): `POST /v1/segments/{id}/preview`
- [List contact imports](/docs/operations/listContactImports.md): `GET /v1/contact-imports`
- [Preview contact import](/docs/operations/previewContactImport.md): `POST /v1/contact-imports`
- [Get contact import](/docs/operations/getContactImport.md): `GET /v1/contact-imports/{id}`
- [Commit contact import](/docs/operations/commitContactImport.md): `POST /v1/contact-imports/{id}/commit`
- [Query audience](/docs/operations/queryAudience.md): `POST /v1/audience-query/query`
- [Plan audience mutation](/docs/operations/planAudienceMutation.md): `POST /v1/audience-query/plan`
- [Apply audience plan](/docs/operations/applyAudiencePlan.md): `POST /v1/audience-query/apply`

## Consent

- [List contact consent events](/docs/operations/listContactConsentEvents.md): `GET /v1/contacts/{id}/consent`
- [Update contact consent](/docs/operations/updateContactConsent.md): `POST /v1/contacts/{id}/consent`
- [Unsubscribe by link](/docs/operations/unsubscribeByLink.md): `GET /unsubscribe/{token}`
- [Unsubscribe one click](/docs/operations/unsubscribeOneClick.md): `POST /unsubscribe/{token}`

## Templates

- [List campaign templates](/docs/operations/listCampaignTemplates.md): `GET /v1/templates`
- [Create campaign template](/docs/operations/createCampaignTemplate.md): `POST /v1/templates`
- [Get campaign template facets](/docs/operations/getCampaignTemplateFacets.md): `GET /v1/templates/facets`
- [Get campaign template](/docs/operations/getCampaignTemplate.md): `GET /v1/templates/{id}`
- [Update campaign template](/docs/operations/updateCampaignTemplate.md): `PATCH /v1/templates/{id}`
- [Delete campaign template](/docs/operations/deleteCampaignTemplate.md): `DELETE /v1/templates/{id}`
- [Publish campaign template](/docs/operations/publishCampaignTemplate.md): `POST /v1/templates/{id}/publish`
- [Preview campaign template](/docs/operations/previewCampaignTemplate.md): `GET /v1/templates/{id}/preview`
- [Render campaign template preview image](/docs/operations/renderCampaignTemplatePreviewImage.md): `GET /v1/templates/{id}/preview-image`
- [Set campaign template organization](/docs/operations/setCampaignTemplateOrganization.md): `PATCH /v1/templates/{id}/organization`
- [Set campaign template archived](/docs/operations/setCampaignTemplateArchived.md): `PATCH /v1/templates/{id}/archive`
- [Upload template asset](/docs/operations/uploadTemplateAsset.md): `POST /v1/template-assets`
- [Import template image](/docs/operations/importTemplateImage.md): `POST /v1/template-assets/import`
- [Get template asset](/docs/operations/getTemplateAsset.md): `GET /v1/template-assets/{id}`
- [Delete template asset](/docs/operations/deleteTemplateAsset.md): `DELETE /v1/template-assets/{id}`
- [Get template asset content](/docs/operations/getTemplateAssetContent.md): `GET /v1/template-assets/{id}/content`

## Emails

- [Send email](/docs/operations/sendEmail.md): `POST /v1/emails/send`
- [Send email batch](/docs/operations/sendEmailBatch.md): `POST /v1/emails/batch`
- [List emails](/docs/operations/listEmails.md): `GET /v1/emails`
- [Get email](/docs/operations/getEmail.md): `GET /v1/emails/{id}`
- [Get email content](/docs/operations/getEmailContent.md): `GET /v1/emails/{id}/content`
- [List email events](/docs/operations/listEmailEvents.md): `GET /v1/emails/{id}/events`

## Attachments

- [Upload attachment](/docs/operations/uploadAttachment.md): `POST /v1/attachments`
- [Get attachment](/docs/operations/getAttachment.md): `GET /v1/attachments/{id}`
- [Delete attachment](/docs/operations/deleteAttachment.md): `DELETE /v1/attachments/{id}`
- [Get attachment content](/docs/operations/getAttachmentContent.md): `GET /v1/attachments/{id}/content`

## Campaigns

- [List campaigns](/docs/operations/listCampaigns.md): `GET /v1/campaigns`
- [Create campaign](/docs/operations/createCampaign.md): `POST /v1/campaigns`
- [Get campaign](/docs/operations/getCampaign.md): `GET /v1/campaigns/{id}`
- [Update campaign](/docs/operations/updateCampaign.md): `PATCH /v1/campaigns/{id}`
- [Delete campaign](/docs/operations/deleteCampaign.md): `DELETE /v1/campaigns/{id}`
- [Get campaign content guide](/docs/operations/getCampaignContentGuide.md): `GET /v1/campaign-content-guide`
- [Preview campaign](/docs/operations/previewCampaign.md): `GET /v1/campaigns/{id}/preview`
- [Render campaign preview image](/docs/operations/renderCampaignPreviewImage.md): `GET /v1/campaigns/{id}/preview-image`
- [Get campaign state](/docs/operations/getCampaignState.md): `GET /v1/campaigns/{id}/state`
- [Set campaign archived](/docs/operations/setCampaignArchived.md): `PATCH /v1/campaigns/{id}/archive`
- [Preview campaign audience](/docs/operations/previewCampaignAudience.md): `POST /v1/campaigns/{id}/audience-preview`
- [Test campaign](/docs/operations/testCampaign.md): `POST /v1/campaigns/{id}/test`
- [Review campaign](/docs/operations/reviewCampaign.md): `POST /v1/campaigns/{id}/review`
- [Start campaign review](/docs/operations/startCampaignReview.md): `POST /v1/campaigns/{id}/reviews`
- [Get campaign review](/docs/operations/getCampaignReview.md): `GET /v1/campaigns/{id}/reviews/{reviewId}`
- [Send campaign](/docs/operations/sendCampaign.md): `POST /v1/campaigns/{id}/send`
- [Schedule campaign](/docs/operations/scheduleCampaign.md): `POST /v1/campaigns/{id}/schedule`
- [Cancel campaign](/docs/operations/cancelCampaign.md): `POST /v1/campaigns/{id}/cancel`

## Settings

- [Get workspace settings](/docs/operations/getWorkspaceSettings.md): `GET /v1/settings/workspace`
- [Update workspace settings](/docs/operations/updateWorkspaceSettings.md): `PATCH /v1/settings/workspace`
- [Get ses settings](/docs/operations/getSesSettings.md): `GET /v1/settings/ses`

## Domains

- [List domains](/docs/operations/listDomains.md): `GET /v1/domains`
- [Create domain](/docs/operations/createDomain.md): `POST /v1/domains`
- [Configure domain mail from](/docs/operations/configureDomainMailFrom.md): `POST /v1/domains/{id}/mail-from`
- [Get domain](/docs/operations/getDomain.md): `GET /v1/domains/{id}`
- [Verify domain](/docs/operations/verifyDomain.md): `POST /v1/domains/{id}/verify`

## Webhooks

- [List webhooks](/docs/operations/listWebhooks.md): `GET /v1/webhooks`
- [Create webhook](/docs/operations/createWebhook.md): `POST /v1/webhooks`
- [Get webhook](/docs/operations/getWebhook.md): `GET /v1/webhooks/{id}`
- [Update webhook](/docs/operations/updateWebhook.md): `PATCH /v1/webhooks/{id}`
- [Delete webhook](/docs/operations/deleteWebhook.md): `DELETE /v1/webhooks/{id}`
- [Reveal webhook secret](/docs/operations/revealWebhookSecret.md): `GET /v1/webhooks/{id}/secret`
- [Rotate webhook secret](/docs/operations/rotateWebhookSecret.md): `POST /v1/webhooks/{id}/rotate-secret`
- [Test webhook](/docs/operations/testWebhook.md): `POST /v1/webhooks/{id}/test`
- [List webhook deliveries](/docs/operations/listWebhookDeliveries.md): `GET /v1/webhooks/{id}/deliveries`
- [Get webhook delivery](/docs/operations/getWebhookDelivery.md): `GET /v1/webhooks/{id}/deliveries/{deliveryId}`
- [Retry webhook delivery](/docs/operations/retryWebhookDelivery.md): `POST /v1/webhooks/{id}/deliveries/{deliveryId}/retry`

## Events

- [Receive ses sns event](/docs/operations/receiveSesSnsEvent.md): `POST /v1/events/ses`

## Metrics

- [Get metrics](/docs/operations/getMetrics.md): `GET /v1/metrics`

## Sequences

- [List sequences](/docs/operations/listSequences.md): `GET /v1/sequences`
- [Create sequence](/docs/operations/createSequence.md): `POST /v1/sequences`
- [Get sequence](/docs/operations/getSequence.md): `GET /v1/sequences/{id}`
- [Update sequence](/docs/operations/updateSequence.md): `PUT /v1/sequences/{id}`
- [Set sequence status](/docs/operations/setSequenceStatus.md): `POST /v1/sequences/{id}/status`
- [Validate sequence](/docs/operations/validateSequence.md): `POST /v1/sequences/{id}/validate`
- [List sequence runs](/docs/operations/listSequenceRuns.md): `GET /v1/sequences/{id}/runs`
- [Exit sequence run](/docs/operations/exitSequenceRun.md): `POST /v1/sequences/{id}/runs/{runId}/exit`
- [List events](/docs/operations/listEvents.md): `GET /v1/events`
- [Ingest events](/docs/operations/ingestEvents.md): `POST /v1/events`
- [Ingest posthog events](/docs/operations/ingestPosthogEvents.md): `POST /v1/events/posthog`

## Regions

- [List regions](/docs/operations/listRegions.md): `GET /v1/regions`
- [Configure region](/docs/operations/configureRegion.md): `PUT /v1/regions/{region}`
- [Discover region](/docs/operations/discoverRegion.md): `GET /v1/regions/{region}/discovery`
- [Provision region](/docs/operations/provisionRegion.md): `POST /v1/regions/{region}/provision`
- [Configure region auto validation](/docs/operations/configureRegionAutoValidation.md): `PUT /v1/regions/{region}/auto-validation`

## List MCP connections

`GET /v1/mcp-connections`



Operation ID: `listMcpConnections`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/mcp-connections', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/mcp-connections' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Revoke MCP connection

`POST /v1/mcp-connections/{id}/revoke`



Operation ID: `revokeMcpConnection`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/mcp-connections/resource_123/revoke', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/mcp-connections/resource_123/revoke' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get current identity

`GET /v1/me`



Operation ID: `getCurrentIdentity`



### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/me', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/me' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List agent tokens

`GET /v1/agent-tokens`



Operation ID: `listAgentTokens`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |
| `includeInactive` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/agent-tokens', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/agent-tokens' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Create agent token

`POST /v1/agent-tokens`

Creates a nonrefreshable, short-lived API token for temporary uncommitted scripts. Requires an MCP OAuth principal and cannot delegate permissions beyond that originating approval. Manage tokens cannot administer credentials.

Operation ID: `createAgentToken`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `permissions` | string[] | yes |  |
| `environment` | string | yes |  |
| `expiresInSeconds` | integer | yes |  |
| `domains` | string[] | no |  |
| `purpose` | string | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/agent-tokens', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "permissions": [
      "read"
    ],
    "environment": "live",
    "expiresInSeconds": 30,
    "domains": [],
    "purpose": "Your message is ready."
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/agent-tokens' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "permissions": [
    "read"
  ],
  "environment": "live",
  "expiresInSeconds": 30,
  "domains": [],
  "purpose": "Your message is ready."
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Revoke agent token

`POST /v1/agent-tokens/{id}/revoke`



Operation ID: `revokeAgentToken`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/agent-tokens/resource_123/revoke', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/agent-tokens/resource_123/revoke' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List api keys

`GET /v1/api-keys`



Operation ID: `listApiKeys`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |
| `includeRevoked` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/api-keys', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/api-keys' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Create api key

`POST /v1/api-keys`



Operation ID: `createApiKey`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `environment` | string | no |  |
| `permissions` | string[] | no |  |
| `domains` | string[] | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/api-keys', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Example",
    "environment": "live",
    "permissions": [
      "send"
    ],
    "domains": []
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/api-keys' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example",
  "environment": "live",
  "permissions": [
    "send"
  ],
  "domains": []
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Success | value |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Revoke api key

`POST /v1/api-keys/{id}/revoke`



Operation ID: `revokeApiKey`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/api-keys/resource_123/revoke', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/api-keys/resource_123/revoke' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List contacts

`GET /v1/contacts`

Active contacts with current list IDs. Search is a case-insensitive literal email/name substring. Consent and suppression filters are independent.

Operation ID: `listContacts`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |
| `search` | query | string | no |  |
| `consent` | query | string | no |  |
| `suppressed` | query | string | no |  |
| `listId` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/contacts', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/contacts' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Create contact

`POST /v1/contacts`



Operation ID: `createContact`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | yes |  |
| `name` | string | no |  |
| `properties` | object | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/contacts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "recipient@example.com",
    "properties": {}
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/contacts' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "recipient@example.com",
  "properties": {}
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get contact

`GET /v1/contacts/{id}`



Operation ID: `getContact`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/contacts/resource_123', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/contacts/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | value |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Update contact

`PATCH /v1/contacts/{id}`



Operation ID: `updateContact`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string or null | no |  |
| `properties` | object | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/contacts/resource_123', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request PATCH \
  --url 'https://email.tryyara.co/v1/contacts/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Delete contact

`DELETE /v1/contacts/{id}`

Remove contact profile and memberships, retaining minimal consent/suppression to prevent accidental re-enrollment.

Operation ID: `deleteContact`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/contacts/resource_123', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request DELETE \
  --url 'https://email.tryyara.co/v1/contacts/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List contact consent events

`GET /v1/contacts/{id}/consent`



Operation ID: `listContactConsentEvents`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/contacts/resource_123/consent', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/contacts/resource_123/consent' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Update contact consent

`POST /v1/contacts/{id}/consent`

Set marketing subscription status. Source, policy version, evidence and occurrence time are optional audit context; Yara Email records the actor and current time when omitted. Does not lift delivery suppression. Imports/profile edits cannot establish consent.

Operation ID: `updateContactConsent`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | yes |  |
| `source` | string | no |  |
| `policyVersion` | string | no |  |
| `evidence` | string | no |  |
| `occurredAt` | string | no |  |
| `confirmResubscribe` | boolean | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/contacts/resource_123/consent', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "status": "subscribed",
    "confirmResubscribe": false
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/contacts/resource_123/consent' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "subscribed",
  "confirmResubscribe": false
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List contact lists

`GET /v1/lists`



Operation ID: `listContactLists`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |
| `search` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/lists', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/lists' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Create contact list

`POST /v1/lists`



Operation ID: `createContactList`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `description` | string | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/lists', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Example",
    "description": ""
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/lists' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example",
  "description": ""
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get contact list

`GET /v1/lists/{id}`



Operation ID: `getContactList`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/lists/resource_123', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/lists/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Update contact list

`PATCH /v1/lists/{id}`



Operation ID: `updateContactList`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no |  |
| `description` | string | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/lists/resource_123', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "description": ""
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request PATCH \
  --url 'https://email.tryyara.co/v1/lists/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "description": ""
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Delete contact list

`DELETE /v1/lists/{id}`



Operation ID: `deleteContactList`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/lists/resource_123', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request DELETE \
  --url 'https://email.tryyara.co/v1/lists/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List list members

`GET /v1/lists/{id}/members`



Operation ID: `listListMembers`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |
| `search` | query | string | no |  |
| `consent` | query | string | no |  |
| `suppressed` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/lists/resource_123/members', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/lists/resource_123/members' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Add list members

`POST /v1/lists/{id}/members`



Operation ID: `addListMembers`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contactIds` | string[] | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/lists/resource_123/members', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contactIds": [
      "contact_123"
    ]
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/lists/resource_123/members' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "contactIds": [
    "contact_123"
  ]
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Remove list member

`DELETE /v1/lists/{id}/members/{contactId}`



Operation ID: `removeListMember`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |
| `contactId` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/lists/resource_123/members/contact_123', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request DELETE \
  --url 'https://email.tryyara.co/v1/lists/resource_123/members/contact_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List segments

`GET /v1/segments`



Operation ID: `listSegments`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |
| `search` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/segments', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/segments' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Create segment

`POST /v1/segments`



Operation ID: `createSegment`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `rule` | object or object or object | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/segments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Example",
    "rule": {
      "field": "email",
      "operator": "eq",
      "value": "example"
    }
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/segments' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example",
  "rule": {
    "field": "email",
    "operator": "eq",
    "value": "example"
  }
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get segment

`GET /v1/segments/{id}`



Operation ID: `getSegment`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/segments/resource_123', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/segments/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Update segment

`PATCH /v1/segments/{id}`



Operation ID: `updateSegment`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no |  |
| `rule` | object or object or object | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/segments/resource_123', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request PATCH \
  --url 'https://email.tryyara.co/v1/segments/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Delete segment

`DELETE /v1/segments/{id}`



Operation ID: `deleteSegment`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/segments/resource_123', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request DELETE \
  --url 'https://email.tryyara.co/v1/segments/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Preview segment

`POST /v1/segments/{id}/preview`

Bounded to 1000 matches. Unknown observation history is never classified as inactive. Counts separate suppressed and other non-consenting contacts.

Operation ID: `previewSegment`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `listId` | string | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/segments/resource_123/preview', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/segments/resource_123/preview' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List contact imports

`GET /v1/contact-imports`



Operation ID: `listContactImports`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/contact-imports', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/contact-imports' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Preview contact import

`POST /v1/contact-imports`

Persist a preview before commit. Feature limit: 1 MiB UTF-8 CSV, 1000 rows, 100 columns. Map headers explicitly. Valid rows can commit alongside a retained row-error report; imports never modify consent or suppression.

Operation ID: `previewContactImport`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `csv` | string | yes |  |
| `listId` | string | no |  |
| `mapping` | object | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/contact-imports', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "csv": "example",
    "mapping": {
      "email": "recipient@example.com"
    }
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/contact-imports' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "csv": "example",
  "mapping": {
    "email": "recipient@example.com"
  }
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get contact import

`GET /v1/contact-imports/{id}`



Operation ID: `getContactImport`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/contact-imports/resource_123', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/contact-imports/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Commit contact import

`POST /v1/contact-imports/{id}/commit`



Operation ID: `commitContactImport`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/contact-imports/resource_123/commit', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/contact-imports/resource_123/commit' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Query audience

`POST /v1/audience-query/query`

Execute a bounded read-only AudienceQL SELECT against the virtual contacts schema.

Operation ID: `queryAudience`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `statement` | string | yes | AudienceQL statement. Supported: SELECT fields\|count(*) FROM contacts [WHERE ...] [LIMIT n]; UPDATE contacts SET name\|consent\|properties.key = value WHERE ...; ADD contacts TO LIST 'name-or-id' WHERE ...; REMOVE contacts FROM LIST 'name-or-id' WHERE .... WHERE supports AND with =, !=, CONTAINS, IS NULL, IS NOT NULL and timestamp comparisons over id, email, name, consent, suppressed, list, segment, lastOpenAt, lastClickAt and properties.key. No raw tables, joins, comments or semicolons. |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/audience-query/query', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "statement": "example"
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/audience-query/query' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "statement": "example"
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Plan audience mutation

`POST /v1/audience-query/plan`

Create a 15-minute immutable plan for a bounded AudienceQL bulk mutation. Does not modify contacts or memberships.

Operation ID: `planAudienceMutation`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `statement` | string | yes | AudienceQL statement. Supported: SELECT fields\|count(*) FROM contacts [WHERE ...] [LIMIT n]; UPDATE contacts SET name\|consent\|properties.key = value WHERE ...; ADD contacts TO LIST 'name-or-id' WHERE ...; REMOVE contacts FROM LIST 'name-or-id' WHERE .... WHERE supports AND with =, !=, CONTAINS, IS NULL, IS NOT NULL and timestamp comparisons over id, email, name, consent, suppressed, list, segment, lastOpenAt, lastClickAt and properties.key. No raw tables, joins, comments or semicolons. |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/audience-query/plan', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "statement": "example"
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/audience-query/plan' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "statement": "example"
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Apply audience plan

`POST /v1/audience-query/apply`

Apply an immutable AudienceQL plan once. Prior opt-outs require confirmResubscribe.

Operation ID: `applyAudiencePlan`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `planId` | string | yes |  |
| `confirmResubscribe` | boolean | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/audience-query/apply', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "planId": "plan_123",
    "confirmResubscribe": false
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/audience-query/apply' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "planId": "plan_123",
  "confirmResubscribe": false
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List campaign templates

`GET /v1/templates`

Lists templates newest first. category and folder filter exactly and combine with search, archived, publishedOnly and format. category and folder organize templates. They are stored on the template itself, outside the draft and published content: changing them never bumps revision, never needs a publish, and works on archived templates.

Operation ID: `listCampaignTemplates`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |
| `search` | query | string | no | Matches name, description or folder. |
| `archived` | query | string | no |  |
| `publishedOnly` | query | string | no |  |
| `format` | query | string | no | Only templates of this format. |
| `category` | query | string | no | Only templates with this category. |
| `folder` | query | string | no | Only templates in this folder (exact name). |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/templates', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/templates' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Create campaign template

`POST /v1/templates`

Templates have one of two formats. blocks (default): html is concrete Yara Email block HTML shared with the visual editor and renderer, styled by Yara Email; call getContentGuide before writing it. html: html is a complete email document (tables, head styles, conditional comments) stored and previewed verbatim; scripts, event handlers, script URLs and embedded frames are rejected. Only blocks templates can create campaigns; creating a campaign from an html template returns 422 TEMPLATE_FORMAT_UNSUPPORTED. Optional category and folder organize the new template. category and folder organize templates. They are stored on the template itself, outside the draft and published content: changing them never bumps revision, never needs a publish, and works on archived templates.

Operation ID: `createCampaignTemplate`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `description` | string | no |  |
| `format` | string | no | Templates have one of two formats. blocks (default): html is concrete Yara Email block HTML shared with the visual editor and renderer, styled by Yara Email; call getContentGuide before writing it. html: html is a complete email document (tables, head styles, conditional comments) stored and previewed verbatim; scripts, event handlers, script URLs and embedded frames are rejected. Only blocks templates can create campaigns; creating a campaign from an html template returns 422 TEMPLATE_FORMAT_UNSUPPORTED. |
| `category` | string | no | Organizing label: transactional (account and request mail), product (digests, nudges and product moments), marketing (promotional), or admin (internal notifications). |
| `folder` | string | no | Folder that groups related templates, for example "Auth & sign-in". Exact names; no nesting. |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/templates', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Example",
    "description": "",
    "format": "blocks"
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/templates' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example",
  "description": "",
  "format": "blocks"
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get campaign template facets

`GET /v1/templates/facets`

Counts templates per category and per folder (folders sorted by name, each with its own per-category counts) for the same search, archived, publishedOnly and format filters as the list, so a navigation can render every group without paging through templates.

Operation ID: `getCampaignTemplateFacets`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `search` | query | string | no | Matches name, description or folder. |
| `archived` | query | string | no |  |
| `publishedOnly` | query | string | no |  |
| `format` | query | string | no | Only templates of this format. |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/templates/facets', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/templates/facets' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get campaign template

`GET /v1/templates/{id}`



Operation ID: `getCampaignTemplate`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/templates/resource_123', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/templates/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Update campaign template

`PATCH /v1/templates/{id}`



Operation ID: `updateCampaignTemplate`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revision` | integer | yes |  |
| `draft` | object | yes | Templates have one of two formats. blocks (default): html is concrete Yara Email block HTML shared with the visual editor and renderer, styled by Yara Email; call getContentGuide before writing it. html: html is a complete email document (tables, head styles, conditional comments) stored and previewed verbatim; scripts, event handlers, script URLs and embedded frames are rejected. Only blocks templates can create campaigns; creating a campaign from an html template returns 422 TEMPLATE_FORMAT_UNSUPPORTED. |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/templates/resource_123', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "revision": 1,
    "draft": {
      "name": "Example",
      "description": "",
      "subject": "",
      "replyTo": [],
      "attachments": []
    }
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request PATCH \
  --url 'https://email.tryyara.co/v1/templates/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "revision": 1,
  "draft": {
    "name": "Example",
    "description": "",
    "subject": "",
    "replyTo": [],
    "attachments": []
  }
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Delete campaign template

`DELETE /v1/templates/{id}`



Operation ID: `deleteCampaignTemplate`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/templates/resource_123', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request DELETE \
  --url 'https://email.tryyara.co/v1/templates/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Publish campaign template

`POST /v1/templates/{id}/publish`



Operation ID: `publishCampaignTemplate`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revision` | integer | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/templates/resource_123/publish', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "revision": 1
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/templates/resource_123/publish' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "revision": 1
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Preview campaign template

`GET /v1/templates/{id}/preview`

Returns the email document and plain-text alternative. Blocks templates are rendered with Yara Email styling; html templates return their stored document unchanged, with the stored text or text derived from the document.

Operation ID: `previewCampaignTemplate`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |
| `published` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/templates/resource_123/preview', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/templates/resource_123/preview' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Render campaign template preview image

`GET /v1/templates/{id}/preview-image`

Renders a template draft or published revision as a full-page PNG: blocks through the Yara Email renderer, html documents exactly as stored. Inline template assets are embedded, so agents can verify the result without browser automation.

Operation ID: `renderCampaignTemplatePreviewImage`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |
| `published` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/templates/resource_123/preview-image', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/templates/resource_123/preview-image' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Set campaign template organization

`PATCH /v1/templates/{id}/organization`

Sets or clears a template's category and folder; omitted fields keep their value. Needs no revision. category and folder organize templates. They are stored on the template itself, outside the draft and published content: changing them never bumps revision, never needs a publish, and works on archived templates.

Operation ID: `setCampaignTemplateOrganization`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

category and folder organize templates. They are stored on the template itself, outside the draft and published content: changing them never bumps revision, never needs a publish, and works on archived templates.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `category` | string or null | no | New category, or null to clear it. Omit to keep the current one. |
| `folder` | string or null | no | New folder, or null to clear it. Omit to keep the current one. |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/templates/resource_123/organization', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request PATCH \
  --url 'https://email.tryyara.co/v1/templates/resource_123/organization' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Set campaign template archived

`PATCH /v1/templates/{id}/archive`



Operation ID: `setCampaignTemplateArchived`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `archived` | boolean | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/templates/resource_123/archive', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "archived": false
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request PATCH \
  --url 'https://email.tryyara.co/v1/templates/resource_123/archive' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "archived": false
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Upload template asset

`POST /v1/template-assets`



Operation ID: `uploadTemplateAsset`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filename` | string | yes |  |
| `contentType` | string | no |  |
| `disposition` | string | no |  |
| `contentId` | string | no |  |
| `content` | string | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/template-assets', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filename": "Example",
    "contentType": "application/octet-stream",
    "disposition": "attachment",
    "content": "example"
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/template-assets' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "filename": "Example",
  "contentType": "application/octet-stream",
  "disposition": "attachment",
  "content": "example"
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Import template image

`POST /v1/template-assets/import`

Downloads a public HTTPS PNG, JPEG, GIF or WebP into private global template assets. Add asset.id to draft.attachments and use src in an img block. This is preferred over hotlinking and requires no browser automation or base64 in model context.

Operation ID: `importTemplateImage`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `filename` | string | no |  |
| `contentId` | string | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/template-assets/import', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://example.com/webhook"
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/template-assets/import' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://example.com/webhook"
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get template asset

`GET /v1/template-assets/{id}`



Operation ID: `getTemplateAsset`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/template-assets/resource_123', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/template-assets/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Delete template asset

`DELETE /v1/template-assets/{id}`



Operation ID: `deleteTemplateAsset`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/template-assets/resource_123', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request DELETE \
  --url 'https://email.tryyara.co/v1/template-assets/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get template asset content

`GET /v1/template-assets/{id}/content`



Operation ID: `getTemplateAssetContent`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/template-assets/resource_123/content', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/template-assets/resource_123/content' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | value |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Send email

`POST /v1/emails/send`



Operation ID: `sendEmail`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string | yes |  |
| `fromName` | string | no |  |
| `to` | string or string[] | yes |  |
| `cc` | string[] | no |  |
| `bcc` | string[] | no |  |
| `replyTo` | string[] | no |  |
| `region` | string | no | Defaults to the installation’s persisted default region when omitted. |
| `kind` | string | no |  |
| `subject` | string | no |  |
| `html` | string | no |  |
| `text` | string | no |  |
| `template` | object | no | Uses native SES stored-template rendering and snapshots its rendered MIME. SES does not automatically escape HTML; callers must escape untrusted HTML-context values. Test keys do not contact SES or render the template. |
| `attachments` | string[] | no |  |
| `tracking` | boolean | no |  |
| `headers` | object | no | Optional message headers. Only List-Unsubscribe, List-Unsubscribe-Post, X-Entity-Ref-ID are accepted, with these exact names. Marketing messages cannot set the List-Unsubscribe headers because Yara Email adds its own unsubscribe link and headers. Stored with the email and returned by getEmailContent. |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/emails/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "from": "sender@example.com",
    "to": "recipient@example.com",
    "cc": [],
    "bcc": [],
    "replyTo": [],
    "kind": "transactional",
    "attachments": [],
    "subject": "Hello from Yara Email",
    "text": "Your message is ready."
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/emails/send' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "from": "sender@example.com",
  "to": "recipient@example.com",
  "cc": [],
  "bcc": [],
  "replyTo": [],
  "kind": "transactional",
  "attachments": [],
  "subject": "Hello from Yara Email",
  "text": "Your message is ready."
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `202` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Send email batch

`POST /v1/emails/batch`



Operation ID: `sendEmailBatch`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `emails` | object[] | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/emails/batch', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "emails": [
      {
        "from": "sender@example.com",
        "to": "recipient@example.com",
        "cc": [],
        "bcc": [],
        "replyTo": [],
        "kind": "transactional",
        "attachments": [],
        "subject": "Hello from Yara Email",
        "text": "Your message is ready."
      }
    ]
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/emails/batch' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "emails": [
    {
      "from": "sender@example.com",
      "to": "recipient@example.com",
      "cc": [],
      "bcc": [],
      "replyTo": [],
      "kind": "transactional",
      "attachments": [],
      "subject": "Hello from Yara Email",
      "text": "Your message is ready."
    }
  ]
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `202` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List emails

`GET /v1/emails`



Operation ID: `listEmails`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |
| `campaignId` | query | string | no |  |
| `status` | query | string | no |  |
| `region` | query | string | no |  |
| `kind` | query | string | no |  |
| `search` | query | string | no |  |
| `from` | query | string | no |  |
| `to` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/emails', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/emails' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get email

`GET /v1/emails/{id}`



Operation ID: `getEmail`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/emails/resource_123', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/emails/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get email content

`GET /v1/emails/{id}/content`

Manage keys receive full snapshots. Other readers receive app unsubscribe tokens redacted from subject/HTML/text and raw MIME withheld (null), since MIME encodings can conceal capabilities. Other transactional bearer links are not sanitized; grant content-read access only to trusted integrations.

Operation ID: `getEmailContent`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/emails/resource_123/content', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/emails/resource_123/content' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List email events

`GET /v1/emails/{id}/events`



Operation ID: `listEmailEvents`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/emails/resource_123/events', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/emails/resource_123/events' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Upload attachment

`POST /v1/attachments`



Operation ID: `uploadAttachment`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filename` | string | yes |  |
| `contentType` | string | no |  |
| `content` | string | yes | Standard padded base64; no data URLs. Maximum decoded bytes: 8 MiB. |
| `disposition` | string | no |  |
| `contentId` | string | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/attachments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filename": "Example",
    "contentType": "application/octet-stream",
    "content": "example",
    "disposition": "attachment"
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/attachments' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "filename": "Example",
  "contentType": "application/octet-stream",
  "content": "example",
  "disposition": "attachment"
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get attachment

`GET /v1/attachments/{id}`



Operation ID: `getAttachment`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/attachments/resource_123', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/attachments/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Delete attachment

`DELETE /v1/attachments/{id}`



Operation ID: `deleteAttachment`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/attachments/resource_123', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request DELETE \
  --url 'https://email.tryyara.co/v1/attachments/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get attachment content

`GET /v1/attachments/{id}/content`

Returns the private attachment as canonical base64 JSON, scoped like its metadata. At most 8 MiB decoded; never a public object URL or executable inline response.

Operation ID: `getAttachmentContent`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/attachments/resource_123/content', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/attachments/resource_123/content' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | value |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List campaigns

`GET /v1/campaigns`

Returns bounded campaign metadata summaries. Fetch an individual campaign for its full editable draft; list drafts omit bodies, defaults, attachments and audience exclusions.

Operation ID: `listCampaigns`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |
| `region` | query | string | no |  |
| `status` | query | string | no |  |
| `archived` | query | string | no | False lists active campaigns; true lists archived campaigns only. |
| `search` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/campaigns' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Create campaign

`POST /v1/campaigns`

Create a campaign; only a name is required. templateId copies an active published global template, including its content and assets, into this environment as an independent draft. Omitted region uses the installation default. Returns a dashboard URL so an agent and user can continue editing together.

Operation ID: `createCampaign`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `from` | string or string | no |  |
| `fromName` | string | no |  |
| `previewText` | string | no | Optional preheader text. Inserted as escaped hidden text into each outgoing HTML snapshot; draft HTML is unchanged. When set, supply HTML without its own duplicate preheader. |
| `replyTo` | string[] | no |  |
| `region` | string | no | Defaults to the installation’s persisted default region when omitted. |
| `subject` | string or string | no |  |
| `attachments` | string[] | no |  |
| `tracking` | boolean | no |  |
| `audience` | object | no |  |
| `defaults` | object | no |  |
| `html` | string | no | Block HTML: h1-h3, p, ul/ol, blockquote, pre>code, hr, img, buttons, columns and styled sections with inline formatting. A constrained email-safe style attribute supports color, typography, spacing, borders, radius and dimensions; arbitrary CSS remains rejected. No wrappers, tables, class or id. Call getContentGuide in MCP or GET /v1/campaign-content-guide for the full vocabulary and examples. |
| `templateId` | string | no | Copies the active published revision of this global campaign template into a new independent campaign draft. |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Example",
    "from": "sender@example.com",
    "replyTo": [],
    "subject": "Hello from Yara Email",
    "attachments": [],
    "audience": {},
    "defaults": {}
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/campaigns' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example",
  "from": "sender@example.com",
  "replyTo": [],
  "subject": "Hello from Yara Email",
  "attachments": [],
  "audience": {},
  "defaults": {}
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get campaign

`GET /v1/campaigns/{id}`



Operation ID: `getCampaign`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns/resource_123', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/campaigns/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Update campaign

`PATCH /v1/campaigns/{id}`

Replace the whole draft at the current revision. Read the campaign first: html is block HTML that people may have edited in the dashboard composer, so send the complete updated html rather than a fragment. Rejected content names the unsupported tag or attribute.

Operation ID: `updateCampaign`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revision` | integer | yes |  |
| `draft` | object | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns/resource_123', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "revision": 1,
    "draft": {
      "name": "Example",
      "from": "sender@example.com",
      "replyTo": [],
      "subject": "Hello from Yara Email",
      "attachments": [],
      "tracking": true,
      "audience": {},
      "defaults": {}
    }
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request PATCH \
  --url 'https://email.tryyara.co/v1/campaigns/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "revision": 1,
  "draft": {
    "name": "Example",
    "from": "sender@example.com",
    "replyTo": [],
    "subject": "Hello from Yara Email",
    "attachments": [],
    "tracking": true,
    "audience": {},
    "defaults": {}
  }
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Delete campaign

`DELETE /v1/campaigns/{id}`



Operation ID: `deleteCampaign`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns/resource_123', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request DELETE \
  --url 'https://email.tryyara.co/v1/campaigns/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get campaign content guide

`GET /v1/campaign-content-guide`

The complete campaign and template content vocabulary, personalization syntax, restrictions and examples as Markdown. Read it once before writing or editing html.

Operation ID: `getCampaignContentGuide`



### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaign-content-guide', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/campaign-content-guide' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Preview campaign

`GET /v1/campaigns/{id}/preview`

Renders the saved draft’s block HTML as the styled email and its plain-text alternative, without personalization or the unsubscribe footer. Placeholders remain visible as {{name}}.

Operation ID: `previewCampaign`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns/resource_123/preview', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/campaigns/resource_123/preview' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Render campaign preview image

`GET /v1/campaigns/{id}/preview-image`

Renders the saved campaign draft as a full-page, 720 px wide PNG for visual review. Inline CID images are embedded; remote HTTPS images are loaded by the isolated renderer.

Operation ID: `renderCampaignPreviewImage`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns/resource_123/preview-image', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/campaigns/resource_123/preview-image' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get campaign state

`GET /v1/campaigns/{id}/state`

Compact authenticated state for draft sync polling; fetch the full campaign with getCampaign when state changes. Compare all returned fields, not only revision: review, archive and status changes need not increment the draft revision. Omits draft content and delivery counts.

Operation ID: `getCampaignState`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns/resource_123/state', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/campaigns/resource_123/state' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Set campaign archived

`PATCH /v1/campaigns/{id}/archive`

Archive a campaign to hide it from default lists, or restore it. Preserves its content, revision, delivery status and history. Scheduled or sending campaigns must finish or be canceled before archiving. Archived campaigns cannot be edited, reviewed, tested or sent until restored.

Operation ID: `setCampaignArchived`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `archived` | boolean | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns/resource_123/archive', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "archived": false
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request PATCH \
  --url 'https://email.tryyara.co/v1/campaigns/resource_123/archive' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "archived": false
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Preview campaign audience

`POST /v1/campaigns/{id}/audience-preview`



Operation ID: `previewCampaignAudience`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns/resource_123/audience-preview', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/campaigns/resource_123/audience-preview' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Test campaign

`POST /v1/campaigns/{id}/test`



Operation ID: `testCampaign`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `to` | string | yes |  |
| `data` | object | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns/resource_123/test', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "to": "recipient@example.com",
    "data": {}
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/campaigns/resource_123/test' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "to": "recipient@example.com",
  "data": {}
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `202` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Review campaign

`POST /v1/campaigns/{id}/review`



Operation ID: `reviewCampaign`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revision` | integer | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns/resource_123/review', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "revision": 1
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/campaigns/resource_123/review' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "revision": 1
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | value |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Start campaign review

`POST /v1/campaigns/{id}/reviews`

Opt in to durable preparation for up to 1,000,000 matching contacts. Captures one fixed audience snapshot, then validates every message in bounded jobs. Poll getCampaignReview until ready before asking for send confirmation. The existing /review endpoint remains synchronous.

Operation ID: `startCampaignReview`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revision` | integer | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns/resource_123/reviews', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "revision": 1
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/campaigns/resource_123/reviews' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "revision": 1
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `202` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get campaign review

`GET /v1/campaigns/{id}/reviews/{reviewId}`

Read fixed audience counts and durable preparation progress. A ready review is usable only while it remains the campaign’s current review and revision.

Operation ID: `getCampaignReview`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |
| `reviewId` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns/resource_123/reviews/review_123', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/campaigns/resource_123/reviews/review_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Send campaign

`POST /v1/campaigns/{id}/send`

Accept the current revision for durable background delivery. Omit reviewId to snapshot and validate the complete audience automatically before any provider attempt; supply an existing completed reviewId to reuse it. The 202 count is accepted recipient intents, not SES acceptance or delivery.

Operation ID: `sendCampaign`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reviewId` | string | no | Optional completed review. Omit to snapshot and validate the current revision automatically before delivery. |
| `revision` | integer | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns/resource_123/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "revision": 1
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/campaigns/resource_123/send' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "revision": 1
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `202` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Schedule campaign

`POST /v1/campaigns/{id}/schedule`

Accept the current revision for durable scheduled delivery. Omit reviewId to snapshot and validate automatically; no recipient is materialized or sent before scheduledAt. The 202 count is accepted recipient intents.

Operation ID: `scheduleCampaign`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reviewId` | string | no | Optional completed review. Omit to snapshot and validate the current revision automatically before delivery. |
| `revision` | integer | yes |  |
| `scheduledAt` | string | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns/resource_123/schedule', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "revision": 1,
    "scheduledAt": "2026-09-18T19:00:00Z"
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/campaigns/resource_123/schedule' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "revision": 1,
  "scheduledAt": "2026-09-18T19:00:00Z"
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `202` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Cancel campaign

`POST /v1/campaigns/{id}/cancel`



Operation ID: `cancelCampaign`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/campaigns/resource_123/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/campaigns/resource_123/cancel' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get workspace settings

`GET /v1/settings/workspace`



Operation ID: `getWorkspaceSettings`



### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/settings/workspace', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/settings/workspace' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Update workspace settings

`PATCH /v1/settings/workspace`



Operation ID: `updateWorkspaceSettings`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/settings/workspace', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Example"
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request PATCH \
  --url 'https://email.tryyara.co/v1/settings/workspace' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example"
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get ses settings

`GET /v1/settings/ses`



Operation ID: `getSesSettings`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `region` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/settings/ses', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/settings/ses' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List domains

`GET /v1/domains`

Refreshes at most 10 identities, sequentially with one second between SES reads. Use refresh=false for cached sender selection without AWS calls. Default page size is 5; use individual domain detail for a single live refresh. Concurrent refresh clients may still encounter account-level throttling.

Operation ID: `listDomains`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |
| `region` | query | string | no |  |
| `refresh` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/domains', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/domains' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Create domain

`POST /v1/domains`



Operation ID: `createDomain`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `region` | string | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/domains', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Example",
    "region": "us-east-1"
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/domains' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example",
  "region": "us-east-1"
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Configure domain mail from

`POST /v1/domains/{id}/mail-from`

Configure a custom SES MAIL FROM subdomain with fallback to the default amazonses.com MAIL FROM value while DNS is unavailable.

Operation ID: `configureDomainMailFrom`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mailFromDomain` | string | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/domains/resource_123/mail-from', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "mailFromDomain": "example"
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/domains/resource_123/mail-from' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "mailFromDomain": "example"
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get domain

`GET /v1/domains/{id}`



Operation ID: `getDomain`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/domains/resource_123', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/domains/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Verify domain

`POST /v1/domains/{id}/verify`



Operation ID: `verifyDomain`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/domains/resource_123/verify', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/domains/resource_123/verify' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List webhooks

`GET /v1/webhooks`



Operation ID: `listWebhooks`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/webhooks', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/webhooks' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Create webhook

`POST /v1/webhooks`



Operation ID: `createWebhook`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |
| `description` | string | no |  |
| `eventTypes` | string[] | no |  |
| `regions` | array or null | no |  |
| `paused` | boolean | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://example.com/webhook",
    "description": "",
    "eventTypes": [
      "email.sent",
      "email.delivered",
      "email.bounced",
      "email.complained",
      "email.rejected",
      "email.rendering_failed",
      "email.delivery_delayed"
    ],
    "paused": false
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/webhooks' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://example.com/webhook",
  "description": "",
  "eventTypes": [
    "email.sent",
    "email.delivered",
    "email.bounced",
    "email.complained",
    "email.rejected",
    "email.rendering_failed",
    "email.delivery_delayed"
  ],
  "paused": false
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get webhook

`GET /v1/webhooks/{id}`



Operation ID: `getWebhook`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/webhooks/resource_123', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/webhooks/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Update webhook

`PATCH /v1/webhooks/{id}`



Operation ID: `updateWebhook`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | no |  |
| `description` | string | no |  |
| `eventTypes` | string[] | no |  |
| `regions` | array or null | no |  |
| `paused` | boolean | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/webhooks/resource_123', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request PATCH \
  --url 'https://email.tryyara.co/v1/webhooks/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Delete webhook

`DELETE /v1/webhooks/{id}`



Operation ID: `deleteWebhook`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/webhooks/resource_123', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request DELETE \
  --url 'https://email.tryyara.co/v1/webhooks/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Reveal webhook secret

`GET /v1/webhooks/{id}/secret`



Operation ID: `revealWebhookSecret`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/webhooks/resource_123/secret', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/webhooks/resource_123/secret' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Rotate webhook secret

`POST /v1/webhooks/{id}/rotate-secret`



Operation ID: `rotateWebhookSecret`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/webhooks/resource_123/rotate-secret', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/webhooks/resource_123/rotate-secret' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Test webhook

`POST /v1/webhooks/{id}/test`



Operation ID: `testWebhook`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/webhooks/resource_123/test', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/webhooks/resource_123/test' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `202` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List webhook deliveries

`GET /v1/webhooks/{id}/deliveries`



Operation ID: `listWebhookDeliveries`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/webhooks/resource_123/deliveries', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/webhooks/resource_123/deliveries' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get webhook delivery

`GET /v1/webhooks/{id}/deliveries/{deliveryId}`



Operation ID: `getWebhookDelivery`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |
| `deliveryId` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/webhooks/resource_123/deliveries/delivery_123', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/webhooks/resource_123/deliveries/delivery_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | value |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Retry webhook delivery

`POST /v1/webhooks/{id}/deliveries/{deliveryId}/retry`



Operation ID: `retryWebhookDelivery`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |
| `deliveryId` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/webhooks/resource_123/deliveries/delivery_123/retry', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/webhooks/resource_123/deliveries/delivery_123/retry' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `202` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Receive ses sns event

`POST /v1/events/ses`



Operation ID: `receiveSesSnsEvent`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `Type` | string | yes |  |
| `MessageId` | string | yes |  |
| `TopicArn` | string | yes |  |
| `Message` | string | yes |  |
| `Timestamp` | string | yes |  |
| `SignatureVersion` | string | yes |  |
| `Signature` | string | yes |  |
| `SigningCertURL` | string | yes |  |
| `Subject` | string | no |  |
| `SubscribeURL` | string | no |  |
| `Token` | string | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/events/ses', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "Type": "Notification",
    "MessageId": "message_123",
    "TopicArn": "example",
    "Message": "example",
    "Timestamp": "2026-09-18T19:00:00Z",
    "SignatureVersion": "1",
    "Signature": "example",
    "SigningCertURL": "https://example.com/webhook"
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/events/ses' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "Type": "Notification",
  "MessageId": "message_123",
  "TopicArn": "example",
  "Message": "example",
  "Timestamp": "2026-09-18T19:00:00Z",
  "SignatureVersion": "1",
  "Signature": "example",
  "SigningCertURL": "https://example.com/webhook"
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `202` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Unsubscribe by link

`GET /unsubscribe/{token}`



Operation ID: `unsubscribeByLink`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/unsubscribe/example', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/unsubscribe/example' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Marketing consent is now unsubscribed. | - |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Unsubscribe one click

`POST /unsubscribe/{token}`



Operation ID: `unsubscribeOneClick`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/unsubscribe/example', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/unsubscribe/example' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Marketing consent is now unsubscribed. | - |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get metrics

`GET /v1/metrics`

Operational created-cohort metrics, not invoicing or provider reputation. Selects emails created in [from,to), scoped by email region and stream. Outcomes use current email state and all recorded events, including events after to; this is not a historical state snapshot. Each outcome counts distinct emails, so replays do not inflate counts and outcomes may overlap. Accepted (bucket sent) means evidence of provider acceptance, not merely queued/created. Daily UTC creation buckets contain count=created emails. Granularity defaults to day; granularity=hour additionally returns hourly UTC creation buckets with canonical ISO dates such as 2026-09-12T01:00:00.000Z, while preserving daily buckets and totals. Absent buckets mean zero created emails and zero outcomes; no moving averages are applied. Engagement is observed, not verified human activity.

Operation ID: `getMetrics`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `region` | query | string | no |  |
| `from` | query | string | no |  |
| `to` | query | string | no |  |
| `stream` | query | string | no |  |
| `granularity` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/metrics', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/metrics' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List sequences

`GET /v1/sequences`

Lists sequences in the key's environment, most recently updated first, with run counts. Full guide: /docs/operations/createSequence.md (definition) and /docs/operations/ingestEvents.md (events).

Operation ID: `listSequences`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |
| `status` | query | string | no | Omit to list every sequence except archived ones. |
| `search` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/sequences', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/sequences' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Create sequence

`POST /v1/sequences`

Creates a draft sequence. definition is optional (a minimal draft is used) and may be incomplete: drafts save with their validation result in lastValidation; activating requires a valid definition. Sequence definition JSON. Shape: {"trigger": {"event": "signed_up", "where": [Condition]}, "category": "transactional|product|marketing|admin", "reentry": "once" (default) | "always" | {"after": "30d"}, "exitOn": [{"event": "goal_event", "where": [Condition]}], "start": "<node id>", "nodes": {"<id>": Node}, "from": "notifications@yara.so" (optional sender), "fromName": "Yara" (optional), "layout": {"<id>": {"x": 0, "y": 0}} (UI only; preserved, ignored by the engine)}. Node ids match ^[a-z0-9_]{1,40}$, at most 50 nodes, every id referenced must exist and be reachable from start, and a loop must pass through a wait or waitForEvent. Every node may carry "label" (<= 80 chars). Nodes: {"type": "wait", "duration": "1h", "next": "id"}; {"type": "branch", "match": "all"|"any", "if": [Condition], "then": "id", "else": "id"}; {"type": "waitForEvent", "event": "portfolio_published", "where": [Condition], "within": "3d", "then": "id", "timeout": "id"} (only events received after the run starts waiting count); {"type": "send", "template": "tpl_...", "next": "id", "subject": "optional override", "fromName": "optional", "from": "optional sender", "replyTo": "optional address"}; {"type": "exit"}. Durations are <n>s|m|h|d from 30s to 90d. Condition: {"source": "event"|"person"|"yara"|"history", "property": "plan", "op": "eq", "value": "pro"}. event reads the trigger event's properties (inside exitOn.where and waitForEvent.where it reads the incoming event); person reads the latest PostHog person properties seen for the person; yara reads Yara audience facts (user_id, email, username, first_name, signed_up_at, onboarding_completed, is_verified, in_yara_network, network_status, has_published_portfolio, portfolio_count, plan, applications_count, is_admin, is_internal_or_test, consent.marketing/lifecycle/notifications), and is false whenever facts are unavailable; history checks whether "event" was ingested for the person: {"source": "history", "event": "x", "op": "occurred"|"not_occurred", "within": "7d"|"since_enrollment"} (default: the 90 retained days). Ops: eq neq gt gte lt lte contains in exists not_exists; properties accept dotted paths. Category decides the consent checked before each send (marketing -> consent.marketing, product -> consent.lifecycle, transactional -> consent.notifications, admin -> none); unknown or false consent skips that send and the run continues. Blocks templates personalize {{first_name}}, {{name}}, {{email}}, {{person.key}}, {{yara.key}}, {{event.key}} with optional defaults {{first_name|there}} (template content requires the default form); html templates are sent verbatim. Every send carries the unsubscribe footer and List-Unsubscribe headers, skips suppressed or unsubscribed addresses, and is idempotent per run and node.

Operation ID: `createSequence`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `description` | string | no |  |
| `definition` | object | no | Sequence definition JSON. Shape: {"trigger": {"event": "signed_up", "where": [Condition]}, "category": "transactional\|product\|marketing\|admin", "reentry": "once" (default) \| "always" \| {"after": "30d"}, "exitOn": [{"event": "goal_event", "where": [Condition]}], "start": "<node id>", "nodes": {"<id>": Node}, "from": "notifications@yara.so" (optional sender), "fromName": "Yara" (optional), "layout": {"<id>": {"x": 0, "y": 0}} (UI only; preserved, ignored by the engine)}. Node ids match ^[a-z0-9_]{1,40}$, at most 50 nodes, every id referenced must exist and be reachable from start, and a loop must pass through a wait or waitForEvent. Every node may carry "label" (<= 80 chars). Nodes: {"type": "wait", "duration": "1h", "next": "id"}; {"type": "branch", "match": "all"\|"any", "if": [Condition], "then": "id", "else": "id"}; {"type": "waitForEvent", "event": "portfolio_published", "where": [Condition], "within": "3d", "then": "id", "timeout": "id"} (only events received after the run starts waiting count); {"type": "send", "template": "tpl_...", "next": "id", "subject": "optional override", "fromName": "optional", "from": "optional sender", "replyTo": "optional address"}; {"type": "exit"}. Durations are <n>s\|m\|h\|d from 30s to 90d. Condition: {"source": "event"\|"person"\|"yara"\|"history", "property": "plan", "op": "eq", "value": "pro"}. event reads the trigger event's properties (inside exitOn.where and waitForEvent.where it reads the incoming event); person reads the latest PostHog person properties seen for the person; yara reads Yara audience facts (user_id, email, username, first_name, signed_up_at, onboarding_completed, is_verified, in_yara_network, network_status, has_published_portfolio, portfolio_count, plan, applications_count, is_admin, is_internal_or_test, consent.marketing/lifecycle/notifications), and is false whenever facts are unavailable; history checks whether "event" was ingested for the person: {"source": "history", "event": "x", "op": "occurred"\|"not_occurred", "within": "7d"\|"since_enrollment"} (default: the 90 retained days). Ops: eq neq gt gte lt lte contains in exists not_exists; properties accept dotted paths. Category decides the consent checked before each send (marketing -> consent.marketing, product -> consent.lifecycle, transactional -> consent.notifications, admin -> none); unknown or false consent skips that send and the run continues. Blocks templates personalize {{first_name}}, {{name}}, {{email}}, {{person.key}}, {{yara.key}}, {{event.key}} with optional defaults {{first_name\|there}} (template content requires the default form); html templates are sent verbatim. Every send carries the unsubscribe footer and List-Unsubscribe headers, skips suppressed or unsubscribed addresses, and is idempotent per run and node. |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/sequences', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Example"
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/sequences' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example"
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Success | value |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Get sequence

`GET /v1/sequences/{id}`

Returns one sequence with its definition, per-node stats and last validation. Full guide: /docs/operations/createSequence.md (definition) and /docs/operations/ingestEvents.md (events).

Operation ID: `getSequence`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/sequences/resource_123', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/sequences/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | value |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Update sequence

`PUT /v1/sequences/{id}`

Replaces the definition (and optionally name/description). Send the version you read; a newer one returns 409 STALE_SEQUENCE_VERSION. Every save increments version. Runs already in progress keep the version they enrolled with; new enrollments use the latest. An active sequence only accepts a valid definition (422 SEQUENCE_INVALID lists error.issues); drafts save with their validation in lastValidation. Full guide: /docs/operations/createSequence.md (definition) and /docs/operations/ingestEvents.md (events).

Operation ID: `updateSequence`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | integer | yes |  |
| `name` | string | no |  |
| `description` | string | no |  |
| `definition` | object | yes | Sequence definition JSON. Shape: {"trigger": {"event": "signed_up", "where": [Condition]}, "category": "transactional\|product\|marketing\|admin", "reentry": "once" (default) \| "always" \| {"after": "30d"}, "exitOn": [{"event": "goal_event", "where": [Condition]}], "start": "<node id>", "nodes": {"<id>": Node}, "from": "notifications@yara.so" (optional sender), "fromName": "Yara" (optional), "layout": {"<id>": {"x": 0, "y": 0}} (UI only; preserved, ignored by the engine)}. Node ids match ^[a-z0-9_]{1,40}$, at most 50 nodes, every id referenced must exist and be reachable from start, and a loop must pass through a wait or waitForEvent. Every node may carry "label" (<= 80 chars). Nodes: {"type": "wait", "duration": "1h", "next": "id"}; {"type": "branch", "match": "all"\|"any", "if": [Condition], "then": "id", "else": "id"}; {"type": "waitForEvent", "event": "portfolio_published", "where": [Condition], "within": "3d", "then": "id", "timeout": "id"} (only events received after the run starts waiting count); {"type": "send", "template": "tpl_...", "next": "id", "subject": "optional override", "fromName": "optional", "from": "optional sender", "replyTo": "optional address"}; {"type": "exit"}. Durations are <n>s\|m\|h\|d from 30s to 90d. Condition: {"source": "event"\|"person"\|"yara"\|"history", "property": "plan", "op": "eq", "value": "pro"}. event reads the trigger event's properties (inside exitOn.where and waitForEvent.where it reads the incoming event); person reads the latest PostHog person properties seen for the person; yara reads Yara audience facts (user_id, email, username, first_name, signed_up_at, onboarding_completed, is_verified, in_yara_network, network_status, has_published_portfolio, portfolio_count, plan, applications_count, is_admin, is_internal_or_test, consent.marketing/lifecycle/notifications), and is false whenever facts are unavailable; history checks whether "event" was ingested for the person: {"source": "history", "event": "x", "op": "occurred"\|"not_occurred", "within": "7d"\|"since_enrollment"} (default: the 90 retained days). Ops: eq neq gt gte lt lte contains in exists not_exists; properties accept dotted paths. Category decides the consent checked before each send (marketing -> consent.marketing, product -> consent.lifecycle, transactional -> consent.notifications, admin -> none); unknown or false consent skips that send and the run continues. Blocks templates personalize {{first_name}}, {{name}}, {{email}}, {{person.key}}, {{yara.key}}, {{event.key}} with optional defaults {{first_name\|there}} (template content requires the default form); html templates are sent verbatim. Every send carries the unsubscribe footer and List-Unsubscribe headers, skips suppressed or unsubscribed addresses, and is idempotent per run and node. |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/sequences/resource_123', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "version": 1,
    "definition": {}
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request PUT \
  --url 'https://email.tryyara.co/v1/sequences/resource_123' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "version": 1,
  "definition": {}
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | value |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Set sequence status

`POST /v1/sequences/{id}/status`

Activates, pauses, returns to draft or archives a sequence. active validates strictly (templates must exist and be published) and returns 422 SEQUENCE_INVALID with error.issues; only active sequences enroll people and advance runs. paused and draft hold runs where they are; archived ends every open run. Status changes do not change version.

Operation ID: `setSequenceStatus`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/sequences/resource_123/status', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "status": "draft"
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/sequences/resource_123/status' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "draft"
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | value |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Validate sequence

`POST /v1/sequences/{id}/validate`

Validates the saved definition, or the supplied one, without saving. errors block activation; warnings do not. With simulate, also walks a valid definition using the given event/person/yara data and history (event names that occurred) and returns path, the node ids visited. Read-only. Sequence definition JSON. Shape: {"trigger": {"event": "signed_up", "where": [Condition]}, "category": "transactional|product|marketing|admin", "reentry": "once" (default) | "always" | {"after": "30d"}, "exitOn": [{"event": "goal_event", "where": [Condition]}], "start": "<node id>", "nodes": {"<id>": Node}, "from": "notifications@yara.so" (optional sender), "fromName": "Yara" (optional), "layout": {"<id>": {"x": 0, "y": 0}} (UI only; preserved, ignored by the engine)}. Node ids match ^[a-z0-9_]{1,40}$, at most 50 nodes, every id referenced must exist and be reachable from start, and a loop must pass through a wait or waitForEvent. Every node may carry "label" (<= 80 chars). Nodes: {"type": "wait", "duration": "1h", "next": "id"}; {"type": "branch", "match": "all"|"any", "if": [Condition], "then": "id", "else": "id"}; {"type": "waitForEvent", "event": "portfolio_published", "where": [Condition], "within": "3d", "then": "id", "timeout": "id"} (only events received after the run starts waiting count); {"type": "send", "template": "tpl_...", "next": "id", "subject": "optional override", "fromName": "optional", "from": "optional sender", "replyTo": "optional address"}; {"type": "exit"}. Durations are <n>s|m|h|d from 30s to 90d. Condition: {"source": "event"|"person"|"yara"|"history", "property": "plan", "op": "eq", "value": "pro"}. event reads the trigger event's properties (inside exitOn.where and waitForEvent.where it reads the incoming event); person reads the latest PostHog person properties seen for the person; yara reads Yara audience facts (user_id, email, username, first_name, signed_up_at, onboarding_completed, is_verified, in_yara_network, network_status, has_published_portfolio, portfolio_count, plan, applications_count, is_admin, is_internal_or_test, consent.marketing/lifecycle/notifications), and is false whenever facts are unavailable; history checks whether "event" was ingested for the person: {"source": "history", "event": "x", "op": "occurred"|"not_occurred", "within": "7d"|"since_enrollment"} (default: the 90 retained days). Ops: eq neq gt gte lt lte contains in exists not_exists; properties accept dotted paths. Category decides the consent checked before each send (marketing -> consent.marketing, product -> consent.lifecycle, transactional -> consent.notifications, admin -> none); unknown or false consent skips that send and the run continues. Blocks templates personalize {{first_name}}, {{name}}, {{email}}, {{person.key}}, {{yara.key}}, {{event.key}} with optional defaults {{first_name|there}} (template content requires the default form); html templates are sent verbatim. Every send carries the unsubscribe footer and List-Unsubscribe headers, skips suppressed or unsubscribed addresses, and is idempotent per run and node.

Operation ID: `validateSequence`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `definition` | value | no |  |
| `simulate` | object | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/sequences/resource_123/validate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/sequences/resource_123/validate' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | value |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List sequence runs

`GET /v1/sequences/{id}/runs`

Lists runs (one person walking the sequence) newest enrollment first, each with its step history. Filter by state, current nodeId or email.

Operation ID: `listSequenceRuns`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |
| `state` | query | string | no |  |
| `nodeId` | query | string | no |  |
| `email` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/sequences/resource_123/runs', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/sequences/resource_123/runs' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Exit sequence run

`POST /v1/sequences/{id}/runs/{runId}/exit`

Ends one active or waiting run now (exitReason manual). Ended runs are returned unchanged.

Operation ID: `exitSequenceRun`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |
| `runId` | path | string | yes |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/sequences/resource_123/runs/run_123/exit', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/sequences/resource_123/runs/run_123/exit' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List events

`GET /v1/events`

Lists recently ingested product events (90-day retention), newest first, for debugging sequences. Filter by exact event name, distinctId or email.

Operation ID: `listEvents`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no |  |
| `event` | query | string | no |  |
| `distinctId` | query | string | no |  |
| `email` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/events', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/events' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Ingest events

`POST /v1/events`

Ingests 1 to 100 product events for sequences in the key's environment (test keys reach test sequences, whose sends are simulated). Each event is stored for 90 days (history conditions, waitForEvent, GET /v1/events), deduplicated on uuid, ends runs whose exitOn matches, wakes runs waiting for it, and enrolls people into active sequences it triggers. Runs then advance in the background. email falls back to personProperties.email, then properties.email. Requires send permission.

Operation ID: `ingestEvents`


### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `events` | object[] | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "events": [
      {
        "event": "example",
        "distinctId": "distinct_123"
      }
    ]
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/events' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "events": [
    {
      "event": "example",
      "distinctId": "distinct_123"
    }
  ]
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Ingest posthog events

`POST /v1/events/posthog`

PostHog webhook destination target: accepts the default payload {"event": {"uuid", "event", "distinct_id", "properties", "timestamp"}, "person": {"id", "properties"}}, one object or an array of up to 100, and ingests it like POST /v1/events (email from person.properties.email, then event.properties.email). Configure the destination with header Authorization: Bearer <Yara Email API key with send permission>; the key's environment receives the events. Filter events in PostHog to the ones sequences use.

Operation ID: `ingestPosthogEvents`


### Request body

Type: `object or object[]`

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/events/posthog', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "event": {
      "event": "example",
      "distinct_id": "distinct__123"
    }
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/events/posthog' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "event": {
    "event": "example",
    "distinct_id": "distinct__123"
  }
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## List regions

`GET /v1/regions`

Lists persisted region settings and cached discovery/job status without AWS calls. The environment default only seeds installation settings during migration.

Operation ID: `listRegions`



### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/regions', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/regions' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Configure region

`PUT /v1/regions/{region}`

Enable/disable a region or choose the default. Changes are shared by live and test modes; requires unrestricted live management access. Disabling never deletes AWS resources or historical mail.

Operation ID: `configureRegion`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `region` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | no |  |
| `makeDefault` | boolean | no |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/regions/us-east-1', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request PUT \
  --url 'https://email.tryyara.co/v1/regions/us-east-1' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Discover region

`GET /v1/regions/{region}/discovery`

Read-only AWS discovery. Caches observations in PostgreSQL for 15 minutes; refresh=true forces AWS reads. Never creates resources or subscribes endpoints. Credential or public-origin changes invalidate the cache.

Operation ID: `discoverRegion`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `region` | path | string | yes |  |
| `refresh` | query | string | no |  |


### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/regions/us-east-1/discovery', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
  },
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request GET \
  --url 'https://email.tryyara.co/v1/regions/us-east-1/discovery' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY"
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Provision region

`POST /v1/regions/{region}/provision`

Explicitly queue idempotent setup of this installation's SES configuration sets, SNS topic/policy/event destinations and signed HTTPS subscription. Never sends email, changes DNS, or grants SES production approval. Repeated requests reuse the active job; inspect listRegions and discovery for completion and remaining blockers.

Operation ID: `provisionRegion`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `region` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `confirm` | boolean | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/regions/us-east-1/provision', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "confirm": true
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request POST \
  --url 'https://email.tryyara.co/v1/regions/us-east-1/provision' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "confirm": true
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `202` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |

---

## Configure region auto validation

`PUT /v1/regions/{region}/auto-validation`

Set SES Auto Validation for one of this installation's configuration sets. This changes real AWS behavior and requires unrestricted live management access plus explicit confirmation.

Operation ID: `configureRegionAutoValidation`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `region` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `stream` | string | yes |  |
| `mode` | string | yes |  |
| `confirm` | boolean | yes |  |

### TypeScript

```ts
const response = await fetch('https://email.tryyara.co/v1/regions/us-east-1/auto-validation', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.YARA_EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "stream": "transactional",
    "mode": "off",
    "confirm": true
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);

console.log(result);
```

### cURL

```sh
curl --request PUT \
  --url 'https://email.tryyara.co/v1/regions/us-east-1/auto-validation' \
  --header "Authorization: Bearer $YARA_EMAIL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "stream": "transactional",
  "mode": "off",
  "confirm": true
}'
```

### Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Success | object |
| `400` | Request failed; use error.code and requestId to diagnose. | object |
| `401` | Request failed; use error.code and requestId to diagnose. | object |
| `403` | Request failed; use error.code and requestId to diagnose. | object |
| `404` | Request failed; use error.code and requestId to diagnose. | object |
| `409` | Request failed; use error.code and requestId to diagnose. | object |
| `413` | Request failed; use error.code and requestId to diagnose. | object |
| `422` | Request failed; use error.code and requestId to diagnose. | object |
| `429` | Request failed; use error.code and requestId to diagnose. | object |
| `500` | Request failed; use error.code and requestId to diagnose. | object |
| `503` | Request failed; use error.code and requestId to diagnose. | object |