# Deliverability and ops endpoints
> Ingest deliverability events, manage the suppression list, replay dead-lettered tasks, manage warmup routing rules, reply templates, and org-level outreach settings.
Source: https://docs.ayinbox.com/api/reference/deliverability-ops/
This group covers the operational control surface for sending: posting deliverability signals (bounces, complaints, unsubscribes) back into the platform, listing and replaying dead-lettered tasks, defining premium-pool warmup routing preferences, managing reply templates, and reading or updating organization-wide advanced outreach settings. All routes are organization-scoped, so the caller must have an active organization selected (API keys are always bound to one organization).
Errors follow the shared `{error, message, code, request_id}` envelope. See [error codes](/api/error-codes/) for the full list, and [authentication](/api/authentication/) for how scopes and organization permissions combine.
Get outreach settings [#get-outreach-settings]
`GET /outreach/settings`
Returns the organization's advanced outreach settings: the bounce pipeline, task reliability, A/B testing, reply-intent, send-time optimization, preflight, and deliverability-dashboard configuration blocks.
Auth: **Scope** `WRITE_CAMPAIGNS` · **Org permission** `manage_settings`
Response [#response]
Returns the `AdvancedOutreachSettings` object directly (not wrapped in an envelope).
```json
{
"bounce_pipeline": {
"enabled": true,
"auto_suppress_on_bounce": true,
"auto_suppress_on_complaint": true,
"auto_suppress_on_unsubscribe": true,
"auto_pause_campaign_on_spike": true,
"pause_bounce_rate_threshold": 8,
"pause_complaint_rate_threshold": 1.5
},
"task_reliability": {
"enabled": true,
"dlq_enabled": true,
"max_attempts": 5,
"execution_window_seconds": 300
},
"ab_testing": {
"enabled": true,
"default_winning_rule": "reply_rate",
"auto_promote_winner": false,
"min_sample_size": 30
},
"reply_intent": {
"enabled": true,
"positive_keywords": ["interested", "demo", "pricing"],
"negative_keywords": ["not interested", "unsubscribe", "stop"],
"out_of_office_keywords": ["out of office", "ooo", "vacation", "abwesenheitsnotiz"],
"question_keywords": ["?", "how", "price"],
"auto_create_crm_task": true,
"crm_task_intents": ["positive", "question", "neutral", "negative"],
"auto_pause_on_negative": false,
"auto_suppress_on_unsubscribe_keyword": true,
"hold_on_out_of_office": true,
"out_of_office_hold_days": 7,
"stop_all_campaigns_on_reply": false
},
"send_time_optimization": {
"enabled": false,
"use_contact_timezone": true,
"default_contact_timezone": "UTC",
"preferred_hours": [9, 10, 11, 14, 15, 16],
"weekend_weight_multiplier": 0.5
},
"preflight": {
"enabled": true,
"check_tracking_domain": true,
"check_unsubscribe_header": true,
"check_ab_variant_configured": false,
"check_daily_limit": true,
"check_schedule_window": true,
"check_content_score": true,
"min_content_score": 60
},
"dashboard": {
"enabled": true,
"show_suppression_log": true,
"show_intent_summary": true,
"show_dlq_stats": true
},
"unsubscribe": {
"mode": "text",
"text": "If this isn't relevant, just reply and let me know and I won't email you again.",
"link_intro": "Not the right person, or not interested?",
"link_text": "Unsubscribe"
},
"custom": {}
}
```
The `unsubscribe` block is the workspace default for the opt-out appended after the signature of every campaign email: `mode` is `text` (a reply-to-opt-out sentence, the default), `link` (a sentence with the recipient's own unsubscribe link) or `off`; a campaign's own `unsubscribe_mode` (`inherit` by default) overrides it. Copy fields are single lines of at most 300 characters and fall back to the defaults when blank. See the [unsubscribe guide](/guides/unsubscribe/).
`reply_intent.auto_create_crm_task` opens a CRM task when a classified reply lands, and `reply_intent.crm_task_intents` names which intents are worth one. Omit the field (or send `null`) and the default applies: `positive`, `question`, `neutral`, `negative`, which is every human intent and no automated one. Send `["positive"]` to narrow it, `["positive", "question", "neutral", "negative", "out_of_office", "automated"]` to include auto-responders and bounces, or `[]` to open nothing (the same as turning the switch off). An intent outside that vocabulary is refused with `400`. See [Tasks](/guides/contacts-crm/#tasks).
`preflight.min_content_score` is stored clamped to `1`-`100`. A value outside that range is corrected on write rather than rejected, so a floor above `100` cannot flag every campaign permanently. Set `preflight.check_content_score` to `false` to turn the check off; the score never blocks or delays a send either way. See [Content checks](/guides/campaigns/).
`reply_intent.hold_on_out_of_office` defaults to `true`. When a recipient's mailbox answers a campaign step with an away message, the contact's next step in that campaign is held until they are back: the return date in the auto-reply when one can be read, plus a working day, and `out_of_office_hold_days` (1 to 90, default `7`) when none can. An auto-reply is never counted as a human reply, so without this the follow-up goes out on schedule while the person is away. `out_of_office_keywords` feeds the reply-intent record and is workspace-editable; detection itself carries its own multilingual vocabulary and does not depend on it. See [out of office and pausing one lead](/guides/campaigns/#out-of-office-and-pausing-one-lead) and [pause a lead](/api/reference/campaigns/#pause-a-lead).
`reply_intent.stop_all_campaigns_on_reply` defaults to `false`. It takes effect only while `reply_intent.enabled` is `true` (the default): with reply automation off, no reply holds anything. Set it to `true` and a human reply also holds the contact in every other campaign they are a lead of that has not completed, for 365 days, with the reason `replied to another campaign` and the source `inbox_tagging`. Automatic replies never trigger it, the answered campaign is left to its own stop on reply, and a member's own pause is never replaced. Lift it like any hold, with [resume a lead](/api/reference/campaigns/#pause-a-lead). Omitting the field keeps it off. See [other campaigns the contact is in](/guides/sequences/#other-campaigns-the-contact-is-in).
`send_time_optimization.enabled` defaults to `false`. Set it to `true` and campaign scheduling holds each send until the recipient's local clock reaches one of `preferred_hours`, resolving the recipient's timezone from the contact's `timezone` custom field, then the country-code suffix of its email domain, then `default_contact_timezone`. It can only delay a send: the campaign window, the mailbox's sending profile, its daily cap, and the campaign end date all still bind. See [Sending behavior](/guides/sending-behavior/).
`inbox_tagging.action_required_in_inbox` defaults to `true`. With automatic inbox tagging on, each automated notification is also asked whether it needs someone to act (a failed payment, a suspended account, a suspicious sign-in, a sending limit, a service about to expire), and the ones that do stay in the inbox labelled Action required instead of moving to the Automated view. A question in `inbox_tagging.questions` with `automated: true` is also asked of notifications. See [Mail that needs your action](/guides/inbox-tagging/#mail-that-needs-your-action).
Update outreach settings [#update-outreach-settings]
`PATCH /outreach/settings`
Replaces the organization's advanced outreach settings with the supplied object. Send the full settings block (the value is upserted, not deep-merged). A field the object omits takes its default, not its previous value. Returns no body on success.
Auth: **Scope** `WRITE_CAMPAIGNS` · **Org permission** `manage_settings`
Request body [#request-body]
| Field | Type | Required | Description |
| ---------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `settings` | object | Yes | The full `AdvancedOutreachSettings` object (same shape as the GET response). |
```json
{
"settings": {
"bounce_pipeline": {
"enabled": true,
"auto_suppress_on_bounce": true,
"auto_suppress_on_complaint": true,
"auto_suppress_on_unsubscribe": true,
"auto_pause_campaign_on_spike": true,
"pause_bounce_rate_threshold": 8,
"pause_complaint_rate_threshold": 1.5
},
"task_reliability": {
"enabled": true,
"dlq_enabled": true,
"max_attempts": 5,
"execution_window_seconds": 300
},
"ab_testing": {
"enabled": true,
"default_winning_rule": "reply_rate",
"auto_promote_winner": false,
"min_sample_size": 30
}
}
}
```
Response [#response-1]
`204 No Content`.
Ingest a deliverability event [#ingest-a-deliverability-event]
`POST /deliverability/events`
Posts a single deliverability signal (bounce, complaint, unsubscribe, open, click, or reply) into the platform. This is API-key callable so downstream pipelines (for example an SES bounce processor) can report events without a human in the loop. Depending on the org's bounce-pipeline settings, a bounce, complaint, or unsubscribe may auto-suppress the recipient. Supply an `idempotency_key` to make retries safe.
Auth: **Scope** `WRITE_CAMPAIGNS` · **Org permission** `send_campaigns`
Request body [#request-body-1]
| Field | Type | Required | Description |
| ----------------- | ------ | -------- | ---------------------------------------------------------------------- |
| `event_type` | string | Yes | One of `bounce`, `complaint`, `unsubscribe`, `open`, `click`, `reply`. |
| `recipient_email` | string | Yes | The recipient address the event is about. |
| `campaign_id` | uuid | No | Campaign the event is attributed to. |
| `task_id` | uuid | No | Send task the event is attributed to. |
| `contact_id` | uuid | No | Contact the event is attributed to. |
| `provider` | string | No | Source provider label (e.g. `ses`, `postmark`). |
| `reason` | string | No | Human-readable reason or diagnostic text. |
| `idempotency_key` | string | No | De-duplicates retried events. |
| `metadata` | object | No | Free-form JSON attached to the event. |
```json
{
"event_type": "bounce",
"recipient_email": "prospect@example.com",
"campaign_id": "8f1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
"provider": "ses",
"reason": "550 5.1.1 mailbox does not exist",
"idempotency_key": "ses-bounce-01hzx9q",
"metadata": { "bounce_type": "Permanent" }
}
```
Response [#response-2]
`202 Accepted` with no body. The event is queued for processing.
List the suppression list [#list-the-suppression-list]
`GET /suppressions`
Pages the workspace suppression list, newest first: every address and domain no campaign will email, whatever put it there. Entries whose `expires_at` has passed are not returned.
Auth: **Scope** `READ_CONTACTS` · **Org permission** `view_contacts`
| Parameter | In | Type | Description |
| --------- | ----- | ------- | ---------------------------------------------------------------- |
| `q` | query | string | Substring filter on the address or domain. |
| `limit` | query | integer | Page size, 1 to 200. Default 50. |
| `cursor` | query | string | Opaque cursor from the previous page's `pagination.next_cursor`. |
Response [#response-3]
```json
{
"data": [
{
"id": "5a0c...",
"organization_id": "9b1e...",
"email": "dana@acme.com",
"kind": "email",
"reason": "clicked the unsubscribe link",
"source": "unsubscribe",
"campaign_id": "c1...",
"metadata": { "via": "link" },
"created_at": "2026-09-01T10:12:00Z",
"updated_at": "2026-09-01T10:12:00Z"
},
{
"id": "7d2f...",
"organization_id": "9b1e...",
"email": "competitor.io",
"kind": "domain",
"reason": "Competitor",
"source": "manual",
"metadata": { "added_by": "4e5f..." },
"created_at": "2026-08-20T09:00:00Z",
"updated_at": "2026-08-20T09:00:00Z"
}
],
"pagination": { "next_cursor": null, "has_more": false }
}
```
`kind` is `email` or `domain`; a domain entry keeps the bare host in `email` and matches every address at it. `source` is `bounce`, `complaint`, `unsubscribe`, `manual` (added one at a time) or `import` (added as a batch). An invalid `limit` or `cursor` returns `400`.
Add to the suppression list [#add-to-the-suppression-list]
`POST /suppressions`
Adds addresses and domains. A value containing `@` is an address; a bare host, with or without a leading `@`, is a domain. Values that are neither are reported in `skipped` rather than failing the request, and a value already on the list is updated in place, so the call is safe to repeat. At most 5000 entries per request.
Auth: **Scope** `WRITE_CONTACTS` · **Org permission** `manage_contacts`
Request [#request]
```json
{
"entries": [
{ "value": "dana@acme.com", "reason": "Asked us by phone" },
{ "value": "acme.com" },
{ "value": "@partner.io" }
],
"reason": "Existing customers"
}
```
`reason` on the request applies to every entry without its own. Adding an address also switches off the matching contact's `subscribed` flag.
Response [#response-4]
```json
{ "added": 3, "skipped": [] }
```
Remove from the suppression list [#remove-from-the-suppression-list]
`DELETE /suppressions/:id`
Lifts one entry, so campaigns can email the address (or every address at the domain) again. Removing an address entry also restores the matching contact's `subscribed` flag. The removal is written to the audit log with the entry's value, kind and source, since lifting an opt-out the recipient made themselves is the action a compliance review looks for.
Auth: **Scope** `WRITE_CONTACTS` · **Org permission** `manage_contacts`
Returns `204` on success and `404` when the entry does not exist in this organization.
List task dead letters [#list-task-dead-letters]
`GET /tasks/dlq`
Lists tasks that exhausted their retry budget and landed in the dead-letter queue (failed sends, syncs, and other side-effectful work). Use this to inspect failures before replaying them.
Auth: **Scope** `SEND_CAMPAIGNS` · **Org permission** `send_campaigns`
| Parameter | In | Type | Description |
| --------- | ----- | ------- | ---------------------------------------------------------------- |
| `status` | query | string | Optional status filter (e.g. `pending`, `replayed`, `resolved`). |
| `limit` | query | integer | Max rows to return, 1 to 200 (default 100). |
Response [#response-5]
Returns a `data` array of dead-letter records. This endpoint is not cursor-paginated; it returns up to `limit` rows in one response.
Send dead letters become `resolved` only after an authoritative worker or operator-confirmed send outcome is reconciled. Recovery does not resend mail: the original payload, error and attempts stay available for inspection. Unknown outcomes remain pending and held. A missing Sent-folder copy, reservation marker or executor marker is not proof that nothing was sent.
```json
{
"data": [
{
"id": "1a2b3c4d-5e6f-7081-9293-a4b5c6d7e8f9",
"task_id": "9f8e7d6c-5b4a-3021-8f7e-6d5c4b3a2110",
"task_type": "send_campaign_email",
"payload": { "campaign_id": "8f1b2c3d-...", "email_account_id": "..." },
"last_error": "smtp: 421 too many connections",
"attempts": 5,
"max_attempts": 5,
"status": "pending",
"next_retry_at": null,
"replayed_at": null,
"created_at": "2026-06-11T14:02:09Z",
"updated_at": "2026-06-11T14:31:50Z"
}
]
}
```
Replay a task dead letter [#replay-a-task-dead-letter]
`POST /tasks/dlq/:id/replay`
Replays only a dead-lettered campaign wakeup with explicit durable wakeup intent, rechecked under its campaign lock. Once a task binds a contact or sequence for sending, its send intent stays restrictive even after either record is deleted. Legacy or imported tasks without verified wakeup intent and all send-capable tasks return `409 Conflict` and retain their dead-letter evidence. A retry date, JSON payload, null contact/sequence, or missing send marker cannot grant replay. This route requires the send permission rather than plain write access.
Database downgrades refuse to discard this provenance while send-intent or unresolved unverified dead-letter rows exist. Keep the schema and roll forward instead.
Auth: **Scope** `SEND_CAMPAIGNS` · **Org permission** `send_campaigns`
| Parameter | In | Type | Description |
| --------- | ---- | ---- | ---------------------------------------------------------------------------- |
| `id` | path | uuid | The dead-letter record ID (the `id` field from the DLQ list, not `task_id`). |
Response [#response-6]
`200 OK`.
```json
{ "status": "replayed" }
```
List warmup routing rules [#list-warmup-routing-rules]
`GET /warmup/routing`
Returns every warmup routing rule for the organization, ordered by `priority` ascending (first to evaluate). Rules express premium-pool partner preferences, for example "only send to Gmail recipients from Google-classified senders".
Auth: **Scope** `WARMUP_ROUTING` · **Org permission** `manage_settings`
Response [#response-7]
Returns the rules under a `rules` key (always an array, never null).
```json
{
"rules": [
{
"id": "c1d2e3f4-5061-7283-94a5-b6c7d8e9f0a1",
"organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
"name": "Gmail to Gmail only",
"priority": 10,
"sender_match_type": "provider",
"sender_match_value": "google",
"recipient_match_type": "provider",
"recipient_match_value": "google",
"weight": 1.0,
"enabled": true,
"created_at": "2026-06-01T09:00:00Z",
"updated_at": "2026-06-01T09:00:00Z"
}
]
}
```
Create a warmup routing rule [#create-a-warmup-routing-rule]
`POST /warmup/routing`
Creates a routing rule for the organization. Both the sender and recipient side are matched; a rule applies only when both sides match. Match values are lowercased and trimmed on write.
Auth: **Scope** `WARMUP_ROUTING` · **Org permission** `manage_settings`
Request body [#request-body-2]
| Field | Type | Required | Description |
| ----------------------- | ------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | Yes | Display name for the rule. |
| `priority` | integer | No | Evaluation order, ascending. Lower runs first. |
| `sender_match_type` | string | Yes | One of `any`, `domain`, `tld`, `provider`. |
| `sender_match_value` | string | Conditional | Required unless `sender_match_type` is `any`. Domain (`acme.com`), TLD (`com`), or provider bucket (`google`, `microsoft`, `yahoo`, `apple`, `proton`, `zoho`, `custom`). |
| `recipient_match_type` | string | Yes | One of `any`, `domain`, `tld`, `provider`. |
| `recipient_match_value` | string | Conditional | Required unless `recipient_match_type` is `any`. Same value forms as the sender side. |
| `weight` | number | No | Selection weight, must be `>= 0`. Above `1` prefers the pairing, below `1` avoids it, and exactly `0` excludes it: a matching pair is never chosen, even when nothing else is available, and is not replied to either. |
| `enabled` | boolean | No | Whether the rule is active. |
```json
{
"name": "Gmail to Gmail only",
"priority": 10,
"sender_match_type": "provider",
"sender_match_value": "google",
"recipient_match_type": "provider",
"recipient_match_value": "google",
"weight": 1.0,
"enabled": true
}
```
Response [#response-8]
`201 Created` with the full rule object (same shape as a list item, with server-managed `id`, `organization_id`, `created_at`, `updated_at`).
```json
{
"id": "c1d2e3f4-5061-7283-94a5-b6c7d8e9f0a1",
"organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
"name": "Gmail to Gmail only",
"priority": 10,
"sender_match_type": "provider",
"sender_match_value": "google",
"recipient_match_type": "provider",
"recipient_match_value": "google",
"weight": 1.0,
"enabled": true,
"created_at": "2026-06-11T16:20:00Z",
"updated_at": "2026-06-11T16:20:00Z"
}
```
Update a warmup routing rule [#update-a-warmup-routing-rule]
`PATCH /warmup/routing/:id`
Replaces a rule by ID. The body is the same full payload as create (all fields are applied, not deep-merged), and the same validation rules apply.
Auth: **Scope** `WARMUP_ROUTING` · **Org permission** `manage_settings`
| Parameter | In | Type | Description |
| --------- | ---- | ---- | ------------ |
| `id` | path | uuid | The rule ID. |
Request body [#request-body-3]
Same fields as [create a warmup routing rule](#create-a-warmup-routing-rule).
```json
{
"name": "Gmail to Gmail only",
"priority": 5,
"sender_match_type": "provider",
"sender_match_value": "google",
"recipient_match_type": "provider",
"recipient_match_value": "google",
"weight": 2.0,
"enabled": true
}
```
Response [#response-9]
`200 OK` with the updated rule object.
Delete a warmup routing rule [#delete-a-warmup-routing-rule]
`DELETE /warmup/routing/:id`
Removes a routing rule by ID.
Auth: **Scope** `WARMUP_ROUTING` · **Org permission** `manage_settings`
| Parameter | In | Type | Description |
| --------- | ---- | ---- | ------------ |
| `id` | path | uuid | The rule ID. |
Response [#response-10]
`204 No Content`.
List reply templates [#list-reply-templates]
`GET /templates`
Lists the organization's reply templates, ordered by position. An optional `q` filter matches against name and subject (case-insensitive).
Auth: **Scope** `READ_TEMPLATES` · **Org permission** `view_campaigns`
| Parameter | In | Type | Description |
| --------- | ----- | ------ | ------------------------------------------------------- |
| `q` | query | string | Optional case-insensitive search over name and subject. |
Response [#response-11]
Returns templates under a `data` key (not cursor-paginated).
```json
{
"data": [
{
"id": "11111111-2222-3333-4444-555555555555",
"organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
"user_id": "99999999-8888-7777-6666-555555555555",
"name": "Pricing follow-up",
"subject": "Re: pricing for {{.Company}}",
"body_html": "Hi {{.FirstName}},
",
"body_plain": "Hi {{.FirstName}},",
"position": 1,
"created_at": "2026-05-20T10:00:00Z",
"updated_at": "2026-05-20T10:00:00Z"
}
]
}
```
Create a reply template [#create-a-reply-template]
`POST /templates`
Creates a reply template owned by the calling user, appended to the end of the org's list. A workspace keeps at most 200 reply templates; one more answers `409` until one is deleted, also when several are created at once. Duplicating a template counts the same way.
Auth: **Scope** `WRITE_TEMPLATES` · **Org permission** `manage_campaigns`
Request body [#request-body-4]
| Field | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------------------------------------------------- |
| `name` | string | Yes | Template name, max 255 characters. |
| `subject` | string | No | Subject line (may contain `{{.Key}}` placeholders), max 1024 bytes. |
| `body_html` | string | No | HTML body, max 16 KB. Link images rather than embedding them. |
| `body_plain` | string | No | Plain-text body, max 16 KB. |
```json
{
"name": "Pricing follow-up",
"subject": "Re: pricing for {{.Company}}",
"body_html": "Hi {{.FirstName}},
",
"body_plain": "Hi {{.FirstName}},"
}
```
Response [#response-12]
`200 OK` with the created `ReplyTemplate`.
```json
{
"id": "11111111-2222-3333-4444-555555555555",
"organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
"user_id": "99999999-8888-7777-6666-555555555555",
"name": "Pricing follow-up",
"subject": "Re: pricing for {{.Company}}",
"body_html": "Hi {{.FirstName}},
",
"body_plain": "Hi {{.FirstName}},",
"position": 3,
"created_at": "2026-06-11T17:00:00Z",
"updated_at": "2026-06-11T17:00:00Z"
}
```
Reorder reply templates [#reorder-reply-templates]
`PATCH /templates/reorder`
Repositions templates to match the supplied ID order (1-indexed). IDs omitted from the list are left untouched. Returns the full reordered list.
Auth: **Scope** `WRITE_TEMPLATES` · **Org permission** `manage_campaigns`
Request body [#request-body-5]
| Field | Type | Required | Description |
| ----- | ------------- | -------- | -------------------------------- |
| `ids` | array of uuid | Yes | Template IDs in their new order. |
```json
{
"ids": [
"33333333-3333-3333-3333-333333333333",
"11111111-2222-3333-4444-555555555555"
]
}
```
Response [#response-13]
`200 OK` with the reordered list under `data` (same shape as [list reply templates](#list-reply-templates)).
Get a reply template [#get-a-reply-template]
`GET /templates/:id`
Retrieves a single reply template by ID.
Auth: **Scope** `READ_TEMPLATES` · **Org permission** `view_campaigns`
| Parameter | In | Type | Description |
| --------- | ---- | ---- | ---------------- |
| `id` | path | uuid | The template ID. |
Response [#response-14]
`200 OK` with the `ReplyTemplate` object (same shape as a list item).
Update a reply template [#update-a-reply-template]
`PATCH /templates/:id`
Updates a reply template. All fields are optional; omitted fields are left unchanged.
Auth: **Scope** `WRITE_TEMPLATES` · **Org permission** `manage_campaigns`
| Parameter | In | Type | Description |
| --------- | ---- | ---- | ---------------- |
| `id` | path | uuid | The template ID. |
Request body [#request-body-6]
| Field | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------------- |
| `name` | string | No | New name. |
| `subject` | string | No | New subject, max 1024 bytes. |
| `body_html` | string | No | New HTML body, max 16 KB. |
| `body_plain` | string | No | New plain-text body, max 16 KB. |
```json
{
"subject": "Re: updated pricing for {{.Company}}"
}
```
Response [#response-15]
`200 OK` with the updated `ReplyTemplate`.
Delete a reply template [#delete-a-reply-template]
`DELETE /templates/:id`
Deletes a reply template by ID.
Auth: **Scope** `WRITE_TEMPLATES` · **Org permission** `manage_campaigns`
| Parameter | In | Type | Description |
| --------- | ---- | ---- | ---------------- |
| `id` | path | uuid | The template ID. |
Response [#response-16]
`204 No Content`.
Duplicate a reply template [#duplicate-a-reply-template]
`POST /templates/:id/duplicate`
Clones a template, appending " (copy)" to the name and placing the clone at the end of the org's list.
Auth: **Scope** `WRITE_TEMPLATES` · **Org permission** `manage_campaigns`
| Parameter | In | Type | Description |
| --------- | ---- | ---- | ----------------------- |
| `id` | path | uuid | The source template ID. |
Response [#response-17]
`200 OK` with the newly created `ReplyTemplate` (same shape as create).
Render a reply template [#render-a-reply-template]
`POST /templates/:id/render`
Expands `{{.Key}}` placeholders in the template's subject and body using a caller-supplied variable map. Used to preview a reply before sending. The body is optional; an empty map renders all placeholders empty.
Auth: **Scope** `READ_TEMPLATES` · **Org permission** `view_campaigns`
| Parameter | In | Type | Description |
| --------- | ---- | ---- | ---------------- |
| `id` | path | uuid | The template ID. |
Request body [#request-body-7]
| Field | Type | Required | Description |
| ----------- | ------------------------- | -------- | ------------------------------------------------ |
| `variables` | object (string to string) | No | Values substituted into `{{.Key}}` placeholders. |
```json
{
"variables": {
"FirstName": "Dana",
"Company": "Acme"
}
}
```
Response [#response-18]
`200 OK` with the rendered subject and body.
```json
{
"subject": "Re: pricing for Acme",
"body_html": "Hi Dana,
",
"body_plain": "Hi Dana,"
}
```
Score template content [#score-template-content]
`POST /templates/score`
Returns an advisory deliverability content score (0 to 100, higher is safer) for a subject and body, plus the issues found. This is advisory only and never blocks sending. It does not read a stored template; it scores the content in the request body.
Auth: **Scope** `READ_TEMPLATES` · **Org permission** `view_campaigns`
Request body [#request-body-8]
| Field | Type | Required | Description |
| ------------ | ------ | -------- | -------------------------------------------------- |
| `subject` | string | No | Subject line to score. |
| `body_html` | string | No | HTML body (used when `body_plain` is empty). |
| `body_plain` | string | No | Plain-text body, preferred over HTML when present. |
```json
{
"subject": "Quick question about {{.Company}}",
"body_plain": "Hi Dana, are you the right person to talk to about outreach?"
}
```
Response [#response-19]
`200 OK` with the score and any advisory issues.
Each issue is located. `field` is `subject` or `body` when the issue lives in exactly one of them, and absent when it straddles both or describes the send as a whole (an attachment count). `spans` quote the exact fragments that caused it, with the 1-based line within that field and the whole line for context. `suggestion` is the fix in one sentence.
```json
{
"score": 84,
"issues": [
{
"severity": "warn",
"code": "spam_trigger_terms",
"message": "2 spam-trigger term(s): free, limited time.",
"field": "body",
"spans": [
{
"field": "body",
"text": "free",
"line": 3,
"excerpt": "Here is a free look at what we do."
},
{
"field": "body",
"text": "limited time",
"line": 5,
"excerpt": "This is a limited time offer."
}
],
"suggestion": "Rewrite those words in plain language, or cut the sentence they sit in."
}
]
}
```
A `spans` list is capped at eight entries. The count that drives the deduction is taken before that cap, so a message naming fourteen links is consistent with a score that deducted for fourteen.
Analyze template content with AI [#analyze-template-content-with-ai]
`POST /templates/analyze`
Runs the deployment's configured AI provider over the same subject and body and returns what to change: the specific word or sentence, quoted from the copy, whether it is in the subject or the body, why it hurts, and what to write instead. The rules-based pass runs in the same request and comes back under `rules`, so both halves are scored from one reading of the copy.
Advisory only, exactly like `/templates/score`: nothing here blocks or delays a send.
Auth: **Scope** `WRITE_TEMPLATES` · **Org permission** `view_campaigns` and `use_ai`
It writes no template, but it spends the workspace's AI credits, so it takes the write scope: a read-only key must not be able to spend money. A signed-in member still needs only `view_campaigns`, plus `use_ai`.
This endpoint spends AI credits (see [AI credits](/guides/ai-credits/)), unless the deployment runs an unmetered model (`AI_PROVIDER=ollama`, or any provider with `AI_FREE=true`), where `credits_charged` comes back `0`. Send an `Idempotency-Key` header to make a retry safe; the same key is never charged twice.
Request body [#request-body-9]
Identical to `/templates/score`.
| Field | Type | Required | Description |
| ------------ | ------ | -------- | -------------------------------------------------- |
| `subject` | string | No | Subject line to analyze. |
| `body_html` | string | No | HTML body (used when `body_plain` is empty). |
| `body_plain` | string | No | Plain-text body, preferred over HTML when present. |
At least one of the three must carry something, and the three together are capped at 60,000 bytes.
Response [#response-20]
`200 OK` with the analysis.
```json
{
"score": 62,
"verdict": "This reads like a promotion rather than a note from a person.",
"findings": [
{
"severity": "high",
"field": "subject",
"text": "FREE bonus inside",
"line": 1,
"excerpt": "Your FREE bonus inside",
"issue": "Capitalised offer wording in the subject is one of the strongest promotional signals a filter reads.",
"suggestion": "Name the thing you noticed about them instead, in lower case.",
"category": "trigger_word"
}
],
"suggested_subject": "quick question about your onboarding",
"improvements": [
"Cut the closing paragraph. One ask lands better than three."
],
"rules": {
"score": 84,
"issues": []
},
"model": "gpt-6-luna",
"tokens_used": 812,
"credits_remaining": 248,
"credits_charged": 2
}
```
| Field | Description |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `score` | Overall deliverability score, 0 to 100, higher is safer. Grounded on `rules`, never argued against it. |
| `verdict` | One sentence on how the email will land. |
| `findings` | Located problems, most severe first. `severity` is `high`, `warn` or `info`; `field` is `subject` or `body`, absent only when the model labelled neither and nothing in the finding could be anchored in the copy; `category` is one of `trigger_word`, `tone`, `formatting`, `links`, `structure`, `authenticity`, and is absent when the model named something outside that set. |
| `findings[].text` | The fragment quoted from your copy. Absent when the finding is about the email as a whole. |
| `suggested_subject` | A rewritten subject, or absent when the current one is fine. |
| `improvements` | Copy-level advice with no single fragment to quote. |
| `rules` | The `/templates/score` result for the same content. |
Every `text` is checked against the submitted subject and body before it is returned. A fragment that is not in the copy is dropped and the finding keeps only its `issue` and `suggestion`, so a response never quotes a sentence you did not send. A finding whose quote was found in the other half has its `field` corrected.
The analysis runs at a fixed temperature, so re-analyzing unchanged copy returns the same score. A change in the score means a change in the copy, which is what makes re-checking after an edit worth doing.
Errors [#errors]
| Status | When |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Nothing written to analyze, or the template is over the size cap. |
| `402` | The workspace is out of AI credits. Nothing is charged and no provider call is made. |
| `403` | The plan or trial does not cover AI, or the member lacks `use_ai`. |
| `503` | No AI provider is configured on this deployment (`code` is `ai_not_configured`, which is permanent for that deployment), or the provider failed (`code` is `service_unavailable`, and the reserved credits are refunded). |