{"openapi":"3.1.0","info":{"title":"SendSend API","version":"1.0.0","description":"Transactional email API. Authenticate with a project API key as a bearer token. A 202 on send means the message was queued, not delivered.","contact":{"url":"https://sendsend.email"}},"servers":[{"url":"https://api.sendsend.email"}],"tags":[{"name":"Emails"},{"name":"Domains"},{"name":"Templates"},{"name":"Webhooks"},{"name":"Suppressions"},{"name":"Verification"},{"name":"DMARC"},{"name":"Blocklists"},{"name":"Audiences"},{"name":"Contacts"},{"name":"Contact properties"},{"name":"Topics"},{"name":"Segments"},{"name":"Forms"},{"name":"Broadcasts"},{"name":"Inbound"},{"name":"API keys"},{"name":"Logs"},{"name":"Usage"}],"paths":{"/v1/emails":{"post":{"operationId":"sendEmail","tags":["Emails"],"summary":"Send an email","description":"Queues one message. A `202` means the message was **durably queued**, not delivered: follow its outcome with webhooks or by fetching it. Send either `subject` with `html` and/or `text`, or a `template_id` with `variables`, never both. Up to 50 recipients in total across `to`, `cc` and `bcc`. Live messages must come from a verified domain in the same project. Recipients on your suppression list are skipped.\n\nAdd up to 10 `attachments` (base64 `content` or an https `path` we download, with a `content_id` to show an image inline; up to 10 MB in total; executables and scripts are refused). Attachments are not available in a batch. Add up to 20 of your own `headers` (for example `List-Unsubscribe`); headers SendSend sets itself cannot be overridden.\n\nSend an `Idempotency-Key` header so a retry can never deliver twice.\n\nRequired scope: `emails:send`.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Up to 255 printable characters. The same key with the same body returns the original message; the same key with a different body returns 409. Kept for 24 hours.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"from":{"type":"string"},"to":{"type":"array","items":{"type":"string","maxLength":254}},"cc":{"type":"array","items":{"type":"string","maxLength":254}},"bcc":{"type":"array","items":{"type":"string","maxLength":254}},"reply_to":{"type":"array","items":{"type":"string","maxLength":254}},"subject":{"type":"string","minLength":1,"maxLength":998},"html":{"type":"string","maxLength":1000000},"text":{"type":"string","maxLength":1000000},"template_id":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,63}$"},"template_version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"language":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z]{2,4})?$"},"tags":{"type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$"},"additionalProperties":{"type":"string","maxLength":256}},"scheduled_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"attachments":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"content":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9+/]*={0,2}$"},"path":{"type":"string","maxLength":2000,"format":"uri"},"content_type":{"type":"string","maxLength":100,"pattern":"^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\\/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*$"},"content_id":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,100}$"}},"additionalProperties":false}},"headers":{"type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]{0,63}$"},"additionalProperties":{"type":"string","maxLength":998}}},"required":["from"],"additionalProperties":false},"example":{"from":"Acme <hello@mail.acme.com>","to":["maria@example.com"],"subject":"Welcome to Acme","html":"<p>Thanks for signing up!</p>","text":"Thanks for signing up!","tags":{"application_reference":"signup_123"}}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"example":{"id":"msg_8Xk2pQwLr0aVn3Zt","object":"email","environment":"live","status":"queued","status_reason":null,"simulated":false,"from":"Acme <hello@mail.acme.com>","to":["maria@example.com"],"cc":[],"bcc":[],"reply_to":null,"subject":"Welcome to Acme","template_id":null,"template_version":null,"tags":{"application_reference":"signup_123"},"provider_message_id":"0100019…","request_id":"req_Kd83…","attempts":0,"recipients":[{"address":"maria@example.com","kind":"to","status":"queued"}],"created_at":"2026-10-06T15:04:05.000Z","updated_at":"2026-10-06T15:04:07.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.\n`invalid_variables`: A template variable is missing or has the wrong type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.\n`account_not_approved`: Live sending waits for account approval. Test keys work meanwhile.\n`account_suspended`: The account is paused. Contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`idempotency_conflict`: The Idempotency-Key was used with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`domain_not_verified`: The From domain is not verified in this project.\n`recipient_suppressed`: Every recipient is on your suppression list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`quota_exhausted`: The monthly allowance is used up and overage is off or capped.\n`daily_limit_exceeded`: This project reached its daily sending limit.\n`rate_limited`: Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listEmails","tags":["Emails"],"summary":"List emails","description":"Newest first, with cursor pagination. Pass the `next_cursor` from one page as `cursor` for the next.\n\nRequired scope: `emails:read`.","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100. Default 20.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"description":"Cursor from a previous page.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Only messages with this status.","schema":{"type":"string","enum":["queued","submitting","accepted","ambiguous","failed","suppressed"]}},{"name":"to","in":"query","required":false,"description":"Only messages sent to this address.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"msg_8Xk2pQwLr0aVn3Zt","object":"email","environment":"live","status":"accepted","status_reason":null,"simulated":false,"from":"Acme <hello@mail.acme.com>","to":["maria@example.com"],"cc":[],"bcc":[],"reply_to":null,"subject":"Welcome to Acme","template_id":null,"template_version":null,"tags":{"application_reference":"signup_123"},"provider_message_id":"0100019…","request_id":"req_Kd83…","attempts":1,"recipients":[{"address":"maria@example.com","kind":"to","status":"delivered"}],"created_at":"2026-10-06T15:04:05.000Z","updated_at":"2026-10-06T15:04:07.000Z"}],"next_cursor":null}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/emails/{id}":{"get":{"operationId":"getEmail","tags":["Emails"],"summary":"Retrieve an email","description":"Returns the message, its overall status and the status of each recipient. Delivery means the recipient’s mail server accepted the message, not that it reached the inbox.\n\nRequired scope: `emails:read`.","parameters":[{"name":"id","in":"path","required":true,"description":"The email id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"msg_8Xk2pQwLr0aVn3Zt","object":"email","environment":"live","status":"accepted","status_reason":null,"simulated":false,"from":"Acme <hello@mail.acme.com>","to":["maria@example.com"],"cc":[],"bcc":[],"reply_to":null,"subject":"Welcome to Acme","template_id":null,"template_version":null,"tags":{"application_reference":"signup_123"},"provider_message_id":"0100019…","request_id":"req_Kd83…","attempts":1,"recipients":[{"address":"maria@example.com","kind":"to","status":"delivered"}],"created_at":"2026-10-06T15:04:05.000Z","updated_at":"2026-10-06T15:04:07.000Z"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"patch":{"operationId":"updateEmail","tags":["Emails"],"summary":"Reschedule an email","description":"Changes when a scheduled email goes out, from now up to 30 days ahead. Only possible while the email is still waiting: once it is on its way it returns `409 not_schedulable`.\n\nRequired scope: `emails:send`.","parameters":[{"name":"id","in":"path","required":true,"description":"The email id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"scheduled_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["scheduled_at"],"additionalProperties":false},"example":{"scheduled_at":"2026-10-08T09:00:00-04:00"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"msg_8Xk2…","status":"scheduled","scheduled_at":"2026-10-08T13:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`not_schedulable`: The email is not scheduled any more (sent, cancelled or on its way).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/domains":{"post":{"operationId":"createDomain","tags":["Domains"],"summary":"Add a domain","description":"Registers a sending domain and returns the DNS records to add at your DNS provider. The three DKIM CNAME records are required; MAIL FROM and DMARC records are recommended. Each record carries a `dns` field showing whether we can see it in public DNS yet.\n\nRequired scope: `domains:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"domain":{"type":"string","maxLength":253},"name":{"type":"string","maxLength":253},"region":{"type":"string","maxLength":40},"open_tracking":{"type":"boolean"},"click_tracking":{"type":"boolean"},"custom_return_path":{"type":"string","pattern":"^[a-z0-9]([a-z0-9-]{0,28}[a-z0-9])?$"},"tls":{"type":"string","enum":["opportunistic","enforced"]}},"additionalProperties":false},"example":{"domain":"mail.acme.com"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"dom_DCdfxpkhLqMhmBdY","object":"domain","domain":"mail.acme.com","status":"pending","failure_reason":null,"verified_at":null,"last_checked_at":null,"created_at":"2026-10-06T15:00:00.000Z","records":[{"purpose":"dkim","required":true,"type":"CNAME","name":"abc123._domainkey.mail.acme.com","value":"abc123.dkim.amazonses.com","dns":"unchecked"}],"dns_summary":{"required_total":3,"required_found":0,"checked":false}}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_limit_reached`: Your plan’s domain limit is reached.\n`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`domain_already_registered`: Another project already registered this domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listDomains","tags":["Domains"],"summary":"List domains","description":"All domains in the project.\n\nRequired scope: `domains:manage`.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"dom_DCdfxpkhLqMhmBdY","object":"domain","domain":"mail.acme.com","status":"pending","failure_reason":null,"verified_at":null,"last_checked_at":null,"created_at":"2026-10-06T15:00:00.000Z","records":[{"purpose":"dkim","required":true,"type":"CNAME","name":"abc123._domainkey.mail.acme.com","value":"abc123.dkim.amazonses.com","dns":"unchecked"}],"dns_summary":{"required_total":3,"required_found":0,"checked":false}}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/domains/{id}":{"get":{"operationId":"getDomain","tags":["Domains"],"summary":"Retrieve a domain","description":"Returns the domain, its records and the last check results.\n\nRequired scope: `domains:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The domain id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"dom_DCdfxpkhLqMhmBdY","object":"domain","domain":"mail.acme.com","status":"pending","failure_reason":null,"verified_at":null,"last_checked_at":null,"created_at":"2026-10-06T15:00:00.000Z","records":[{"purpose":"dkim","required":true,"type":"CNAME","name":"abc123._domainkey.mail.acme.com","value":"abc123.dkim.amazonses.com","dns":"unchecked"}],"dns_summary":{"required_total":3,"required_found":0,"checked":false}}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteDomain","tags":["Domains"],"summary":"Remove a domain","description":"Removes the domain from the project. Live sends from it stop immediately.\n\nRequired scope: `domains:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The domain id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"patch":{"operationId":"updateDomain","tags":["Domains"],"summary":"Update a domain","description":"Turn open and click tracking on or off for the domain. Both are off by default. Opens are approximate, because some mail apps load images for the reader. Click tracking rewrites the links in your emails, so leave it off for emails whose links are secrets, such as sign-in and password-reset links. The `tracking.available` field says whether tracking is switched on for the platform; until it is, the settings are saved but have no effect.\n\nRequired scope: `domains:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The domain id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"track_opens":{"type":"boolean"},"track_clicks":{"type":"boolean"},"open_tracking":{"type":"boolean"},"click_tracking":{"type":"boolean"},"tls":{"type":"string","enum":["opportunistic","enforced"]},"custom_return_path":{"type":"string","pattern":"^[a-z0-9]([a-z0-9-]{0,28}[a-z0-9])?$"}},"additionalProperties":false},"example":{"track_opens":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"dom_DCdfxpkhLqMhmBdY","object":"domain","domain":"mail.acme.com","status":"pending","failure_reason":null,"verified_at":null,"last_checked_at":null,"created_at":"2026-10-06T15:00:00.000Z","records":[{"purpose":"dkim","required":true,"type":"CNAME","name":"abc123._domainkey.mail.acme.com","value":"abc123.dkim.amazonses.com","dns":"unchecked"}],"dns_summary":{"required_total":3,"required_found":0,"checked":false},"tracking":{"opens":true,"clicks":false,"available":true}}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/domains/{id}/verify":{"post":{"operationId":"verifyDomain","tags":["Domains"],"summary":"Check a domain now","description":"Re-reads public DNS and the sending provider’s verification immediately. We also re-check automatically; a domain that was verified and loses its records stops sending until it is fixed.\n\nRequired scope: `domains:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The domain id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"dom_DCdfxpkhLqMhmBdY","object":"domain","domain":"mail.acme.com","status":"pending","failure_reason":null,"verified_at":null,"last_checked_at":null,"created_at":"2026-10-06T15:00:00.000Z","records":[{"purpose":"dkim","required":true,"type":"CNAME","name":"abc123._domainkey.mail.acme.com","value":"abc123.dkim.amazonses.com","dns":"unchecked"}],"dns_summary":{"required_total":3,"required_found":0,"checked":false}}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/domains/{id}/insights":{"get":{"operationId":"getDomainInsights","tags":["Domains"],"summary":"Get domain insights","description":"How a domain is doing over the last 1 to 90 days (default 30): delivery, bounce and complaint rates against the limits that pause sending, open and click rates when tracking is on, the state of its DNS setup, and a short list of what to do next. Only live mail counts. This reports what receiving servers told us; it cannot show inbox versus spam placement.\n\nRequired scope: `domains:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The domain id.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Window in days, 1 to 90. Default 30.","schema":{"type":"integer","minimum":1,"maximum":90,"default":30}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"domain_insights","domain":"mail.acme.com","window_days":30,"status":"watch","totals":{"messages":480,"sent":500,"delivered":487,"bounced":11,"complained":0,"failed":0,"suppressed":3,"opened":0,"clicked":0},"rates":{"delivered":0.974,"bounced":0.022,"complained":0,"opened":null,"clicked":null},"setup":{"dkim":"verified","spf_return_path":"aligned","dmarc":"monitoring","tracking":{"opens":false,"clicks":false}},"recommendations":[{"level":"warning","code":"bounce_rate_high","title":"Bounce rate 2.2% is high","detail":"Aim to stay under 2.0%. Check for typos at sign-up, old addresses, or a purchased list."}]}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/templates":{"post":{"operationId":"createTemplate","tags":["Templates"],"summary":"Create or publish a template","description":"Publishes an immutable version. Posting an existing `id` publishes the next version; versions are never edited. Write the content as `html` and/or `text`, or build it from a visual `design` (a list of blocks, the same builder as the dashboard) and we generate the HTML and plain text. If you send only HTML, a plain-text version is made for you. Use `{{name}}` placeholders and declare each one under `variables` (types: string, number, boolean, array, object); values are escaped in HTML when sending. The template language also has `{{name | fallback}}`, filters such as `upper`, `currency:'USD'` and `date`, conditions (`{{#if plan == 'pro'}}…{{else}}…{{/if}}`) and loops (`{{#each items as item}}{{item.name}}{{/each}}`). Add `translations` (`{ fr: { subject, html, text } }`) and send with `language` to use them; anything a translation leaves out comes from the main version. A mistake in a template, or a variable it uses without declaring, is refused with a message that says where.\n\nRequired scope: `templates:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,63}$"},"name":{"type":"string","minLength":1,"maxLength":200},"category":{"type":"string","minLength":1,"maxLength":40},"subject":{"type":"string","minLength":1,"maxLength":998},"html":{"type":"string","maxLength":1000000},"text":{"type":"string","maxLength":1000000},"design":{"type":"object","properties":{"accent":{"default":"#1a56db","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"background":{"default":"#f4f5f7","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"font":{"default":"sans","type":"string","enum":["sans","serif"]},"blocks":{"minItems":1,"maxItems":100,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"heading"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":300},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"text"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":5000},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"button"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"label":{"type":"string","maxLength":80},"url":{"type":"string","maxLength":2000},"align":{"default":"center","type":"string","enum":["left","center","right"]}},"required":["type","label","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"url":{"type":"string","maxLength":2000},"alt":{"default":"","type":"string","maxLength":200},"link":{"default":"","type":"string","maxLength":2000}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"divider"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"spacer"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"height":{"default":24,"type":"integer","minimum":4,"maximum":120}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"footer"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":1000}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"logo"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"url":{"type":"string","maxLength":2000},"alt":{"default":"","type":"string","maxLength":200},"link":{"default":"","type":"string","maxLength":2000},"width":{"default":140,"type":"integer","minimum":40,"maximum":300},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"columns"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"image_url":{"type":"string","maxLength":2000},"image_alt":{"default":"","type":"string","maxLength":200},"title":{"default":"","type":"string","maxLength":200},"text":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"","type":"string","maxLength":80},"button_url":{"default":"","type":"string","maxLength":2000},"image_side":{"default":"left","type":"string","enum":["left","right"]}},"required":["type","image_url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"product"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"image_url":{"default":"","type":"string","maxLength":2000},"name":{"type":"string","maxLength":200},"description":{"default":"","type":"string","maxLength":500},"price":{"default":"","type":"string","maxLength":60},"url":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"View","type":"string","maxLength":80}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"discount"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"headline":{"default":"Your discount","type":"string","maxLength":200},"code":{"type":"string","maxLength":40},"details":{"default":"","type":"string","maxLength":300}},"required":["type","code"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"social"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"links":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["website","x","facebook","instagram","linkedin","youtube","tiktok","github"]},"url":{"type":"string","maxLength":2000}},"required":["network","url"],"additionalProperties":false}},"align":{"default":"center","type":"string","enum":["left","center","right"]}},"required":["type","links"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"list"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","maxLength":300}},"ordered":{"default":false,"type":"boolean"}},"required":["type","items"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"quote"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":1000},"author":{"default":"","type":"string","maxLength":100}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"signature"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"name":{"type":"string","maxLength":100},"title":{"default":"","type":"string","maxLength":100},"company":{"default":"","type":"string","maxLength":100},"email":{"default":"","type":"string","maxLength":200},"phone":{"default":"","type":"string","maxLength":40},"website":{"default":"","type":"string","maxLength":2000}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"event"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"title":{"type":"string","maxLength":200},"date":{"type":"string","maxLength":100},"time":{"default":"","type":"string","maxLength":100},"place":{"default":"","type":"string","maxLength":200},"url":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"Add to calendar","type":"string","maxLength":80}},"required":["type","title","date"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"rating"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"question":{"type":"string","maxLength":200},"url":{"type":"string","maxLength":2000},"low_label":{"default":"","type":"string","maxLength":40},"high_label":{"default":"","type":"string","maxLength":40}},"required":["type","question","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"table"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"rows":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"columns":{"minItems":1,"maxItems":6,"type":"array","items":{"type":"object","properties":{"header":{"type":"string","maxLength":60},"field":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"format":{"default":"text","type":"string","enum":["text","currency","number","date"]}},"required":["header","field"],"additionalProperties":false}},"currency":{"default":"USD","type":"string","pattern":"^[A-Za-z]{3}$"}},"required":["type","rows","columns"],"additionalProperties":false}]}}},"required":["blocks"],"additionalProperties":false},"translations":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z]{2,4})?$"},"additionalProperties":{"type":"object","properties":{"subject":{"type":"string","minLength":1,"maxLength":998},"html":{"type":"string","maxLength":1000000},"text":{"type":"string","maxLength":1000000},"design":{"type":"object","properties":{"accent":{"default":"#1a56db","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"background":{"default":"#f4f5f7","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"font":{"default":"sans","type":"string","enum":["sans","serif"]},"blocks":{"minItems":1,"maxItems":100,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"heading"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":300},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"text"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":5000},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"button"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"label":{"type":"string","maxLength":80},"url":{"type":"string","maxLength":2000},"align":{"default":"center","type":"string","enum":["left","center","right"]}},"required":["type","label","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"url":{"type":"string","maxLength":2000},"alt":{"default":"","type":"string","maxLength":200},"link":{"default":"","type":"string","maxLength":2000}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"divider"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"spacer"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"height":{"default":24,"type":"integer","minimum":4,"maximum":120}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"footer"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":1000}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"logo"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"url":{"type":"string","maxLength":2000},"alt":{"default":"","type":"string","maxLength":200},"link":{"default":"","type":"string","maxLength":2000},"width":{"default":140,"type":"integer","minimum":40,"maximum":300},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"columns"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"image_url":{"type":"string","maxLength":2000},"image_alt":{"default":"","type":"string","maxLength":200},"title":{"default":"","type":"string","maxLength":200},"text":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"","type":"string","maxLength":80},"button_url":{"default":"","type":"string","maxLength":2000},"image_side":{"default":"left","type":"string","enum":["left","right"]}},"required":["type","image_url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"product"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"image_url":{"default":"","type":"string","maxLength":2000},"name":{"type":"string","maxLength":200},"description":{"default":"","type":"string","maxLength":500},"price":{"default":"","type":"string","maxLength":60},"url":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"View","type":"string","maxLength":80}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"discount"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"headline":{"default":"Your discount","type":"string","maxLength":200},"code":{"type":"string","maxLength":40},"details":{"default":"","type":"string","maxLength":300}},"required":["type","code"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"social"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"links":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["website","x","facebook","instagram","linkedin","youtube","tiktok","github"]},"url":{"type":"string","maxLength":2000}},"required":["network","url"],"additionalProperties":false}},"align":{"default":"center","type":"string","enum":["left","center","right"]}},"required":["type","links"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"list"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","maxLength":300}},"ordered":{"default":false,"type":"boolean"}},"required":["type","items"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"quote"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":1000},"author":{"default":"","type":"string","maxLength":100}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"signature"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"name":{"type":"string","maxLength":100},"title":{"default":"","type":"string","maxLength":100},"company":{"default":"","type":"string","maxLength":100},"email":{"default":"","type":"string","maxLength":200},"phone":{"default":"","type":"string","maxLength":40},"website":{"default":"","type":"string","maxLength":2000}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"event"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"title":{"type":"string","maxLength":200},"date":{"type":"string","maxLength":100},"time":{"default":"","type":"string","maxLength":100},"place":{"default":"","type":"string","maxLength":200},"url":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"Add to calendar","type":"string","maxLength":80}},"required":["type","title","date"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"rating"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"question":{"type":"string","maxLength":200},"url":{"type":"string","maxLength":2000},"low_label":{"default":"","type":"string","maxLength":40},"high_label":{"default":"","type":"string","maxLength":40}},"required":["type","question","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"table"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"rows":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"columns":{"minItems":1,"maxItems":6,"type":"array","items":{"type":"object","properties":{"header":{"type":"string","maxLength":60},"field":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"format":{"default":"text","type":"string","enum":["text","currency","number","date"]}},"required":["header","field"],"additionalProperties":false}},"currency":{"default":"USD","type":"string","pattern":"^[A-Za-z]{3}$"}},"required":["type","rows","columns"],"additionalProperties":false}]}}},"required":["blocks"],"additionalProperties":false}},"additionalProperties":false}},"variables":{"default":{},"type":"object","propertyNames":{"type":"string","pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"additionalProperties":{"type":"object","properties":{"type":{"default":"string","type":"string","enum":["string","number","boolean","array","object"]},"required":{"default":true,"type":"boolean"}},"additionalProperties":false}}},"required":["id","subject"],"additionalProperties":false},"example":{"id":"welcome","name":"Welcome","subject":"Welcome, {{first_name}}","html":"<p>Hi {{first_name}}!</p>","variables":{"first_name":{"type":"string","required":true}}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"object":"template","id":"welcome","version":1}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listTemplates","tags":["Templates"],"summary":"List templates","description":"Templates with their latest version.\n\nRequired scope: `templates:manage`.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"welcome","name":"Welcome","latest_version":1,"versions":1,"created_at":"2026-10-06T15:00:00.000Z"}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/templates/{id}":{"patch":{"operationId":"updateTemplate","tags":["Templates"],"summary":"Update a template’s details","description":"Renames a template, files it under a category, or shares traffic across its versions (a split test). `split` lists 2 to 5 versions with percentages that add up to 100. Sends that name no version then use them: a recipient is always given the same version, so the same person does not see both. Sends that name a version always get that version. Use `null` to turn it off.\n\nRequired scope: `templates:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The template id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"category":{"anyOf":[{"type":"string","minLength":1,"maxLength":40},{"type":"null"}]},"split":{"anyOf":[{"minItems":2,"maxItems":5,"type":"array","items":{"type":"object","properties":{"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"percent":{"type":"integer","minimum":1,"maximum":100}},"required":["version","percent"],"additionalProperties":false}},{"type":"null"}]}},"additionalProperties":false},"example":{"category":"Onboarding","split":[{"version":1,"percent":50},{"version":2,"percent":50}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"template","id":"welcome","name":"Welcome","category":"Onboarding","split":[{"version":1,"percent":50},{"version":2,"percent":50}]}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"getTemplate","tags":["Templates"],"summary":"Retrieve a template","description":"Returns every version of the template, newest first.\n\nRequired scope: `templates:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The template id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteTemplate","tags":["Templates"],"summary":"Delete a template","description":"Removes the template and all its versions. Emails you already sent are not affected: each keeps the subject and body it was sent with.\n\nRequired scope: `templates:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The template id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/templates/{id}/versions/{version}":{"get":{"operationId":"getTemplateVersion","tags":["Templates"],"summary":"Retrieve a template version","description":"One stored version with its subject, HTML, text, visual design, translations and variables.\n\nRequired scope: `templates:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The template id.","schema":{"type":"string"}},{"name":"version","in":"path","required":true,"description":"The version number.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"template_version","template_id":"welcome","version":1,"subject":"Welcome, {{first_name}}","html":"<p>Hi {{first_name}}!</p>","text":"Hi {{first_name}}!","design":null,"translations":{},"variables":{"first_name":{"type":"string","required":true}},"created_at":"2026-10-15T09:00:00.000Z"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/templates/{id}/restore":{"post":{"operationId":"restoreTemplateVersion","tags":["Templates"],"summary":"Restore an earlier version","description":"Publishes a copy of an earlier version as the newest. Nothing is lost: the versions in between stay, and sends that name them keep working.\n\nRequired scope: `templates:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The template id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["version"],"additionalProperties":false},"example":{"version":1}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"object":"template","id":"welcome","version":3,"restored_from":1}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/templates/{id}/test":{"post":{"operationId":"testTemplate","tags":["Templates"],"summary":"Send a test email from a template","description":"Sends the template to one address so you can see it in a real inbox. It goes through the normal sending path, so it needs a verified `from` domain, counts toward your plan, and the key also needs `emails:send`. Test sends are left out of the template’s stats.\n\nRequired scope: `templates:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The template id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"from":{"type":"string"},"to":{"type":"string","maxLength":254},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"language":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z]{2,4})?$"},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["from","to"],"additionalProperties":false},"example":{"from":"Acme <hello@mail.acme.com>","to":"me@acme.com","variables":{"first_name":"Maria"}}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"example":{"id":"msg_8Xk2pQwLr0aVn3Zt","object":"email","status":"queued"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/templates/{id}/stats":{"get":{"operationId":"getTemplateStats","tags":["Templates"],"summary":"See how each version did","description":"For each version sent in the last `days` days (1 to 90, default 30): sent, delivered, bounced, complained, and unique opens and clicks when tracking is on for the sending domain. Use it to compare the versions of a split test.\n\nRequired scope: `templates:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The template id.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Look back this many days, 1 to 90. Default 30.","schema":{"type":"integer","minimum":1,"maximum":90,"default":30}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"template_stats","template_id":"welcome","days":30,"split":null,"versions":[{"version":2,"sent":480,"delivered":471,"bounced":9,"complained":0,"opened":301,"clicked":88,"delivery_rate":0.98,"open_rate":0.64,"click_rate":0.19}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/template-library":{"get":{"operationId":"listLibraryTemplates","tags":["Templates"],"summary":"List ready-made templates","description":"A library of sixty transactional templates, grouped into categories: onboarding, security, e-commerce, WooCommerce (every store email), billing and notifications. Each declares its variables. Add one to your project with “Create a template from the library”.\n\nRequired scope: `templates:manage`.","parameters":[{"name":"category","in":"query","required":false,"description":"Onboarding, Security, E-commerce, WooCommerce, Billing or Notifications.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","categories":["Onboarding","Security","E-commerce","Billing","Notifications"],"data":[{"id":"password-reset","object":"library_template","name":"Password reset","category":"Security","description":"A reset link that expires.","subject":"Reset your password","variables":{"reset_url":{"type":"string","required":true}}}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/template-library/{id}":{"get":{"operationId":"getLibraryTemplate","tags":["Templates"],"summary":"Retrieve a library template","description":"The full design, sample data, and a preview rendered with the sample data in your project’s brand.\n\nRequired scope: `templates:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The library template id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"password-reset","object":"library_template","name":"Password reset","category":"Security","subject":"Reset your password","sample":{"reset_url":"https://example.com/reset/abc"},"html":"<!doctype html>…","text":"RESET YOUR PASSWORD…"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/templates/from-library":{"post":{"operationId":"createTemplateFromLibrary","tags":["Templates"],"summary":"Create a template from the library","description":"Adds a ready-made template to your project as version 1, in your brand kit’s colors, font, logo and footer unless you pass `apply_brand: false`. You can then edit it by publishing new versions.\n\nRequired scope: `templates:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"library_id":{"type":"string","minLength":1,"maxLength":60},"id":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,63}$"},"name":{"type":"string","minLength":1,"maxLength":200},"apply_brand":{"default":true,"type":"boolean"}},"required":["library_id","id"],"additionalProperties":false},"example":{"library_id":"password-reset","id":"reset"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"object":"template","id":"reset","version":1,"from":"password-reset"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/saved-blocks":{"post":{"operationId":"createSavedBlock","tags":["Templates"],"summary":"Save a block for reuse","description":"Stores one block of a design (a signature, a discount box, a footer) so you can drop it into other templates. A project can keep 100.\n\nRequired scope: `templates:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"block":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"heading"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":300},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"text"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":5000},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"button"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"label":{"type":"string","maxLength":80},"url":{"type":"string","maxLength":2000},"align":{"default":"center","type":"string","enum":["left","center","right"]}},"required":["type","label","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"url":{"type":"string","maxLength":2000},"alt":{"default":"","type":"string","maxLength":200},"link":{"default":"","type":"string","maxLength":2000}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"divider"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"spacer"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"height":{"default":24,"type":"integer","minimum":4,"maximum":120}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"footer"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":1000}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"logo"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"url":{"type":"string","maxLength":2000},"alt":{"default":"","type":"string","maxLength":200},"link":{"default":"","type":"string","maxLength":2000},"width":{"default":140,"type":"integer","minimum":40,"maximum":300},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"columns"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"image_url":{"type":"string","maxLength":2000},"image_alt":{"default":"","type":"string","maxLength":200},"title":{"default":"","type":"string","maxLength":200},"text":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"","type":"string","maxLength":80},"button_url":{"default":"","type":"string","maxLength":2000},"image_side":{"default":"left","type":"string","enum":["left","right"]}},"required":["type","image_url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"product"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"image_url":{"default":"","type":"string","maxLength":2000},"name":{"type":"string","maxLength":200},"description":{"default":"","type":"string","maxLength":500},"price":{"default":"","type":"string","maxLength":60},"url":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"View","type":"string","maxLength":80}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"discount"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"headline":{"default":"Your discount","type":"string","maxLength":200},"code":{"type":"string","maxLength":40},"details":{"default":"","type":"string","maxLength":300}},"required":["type","code"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"social"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"links":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["website","x","facebook","instagram","linkedin","youtube","tiktok","github"]},"url":{"type":"string","maxLength":2000}},"required":["network","url"],"additionalProperties":false}},"align":{"default":"center","type":"string","enum":["left","center","right"]}},"required":["type","links"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"list"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","maxLength":300}},"ordered":{"default":false,"type":"boolean"}},"required":["type","items"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"quote"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":1000},"author":{"default":"","type":"string","maxLength":100}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"signature"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"name":{"type":"string","maxLength":100},"title":{"default":"","type":"string","maxLength":100},"company":{"default":"","type":"string","maxLength":100},"email":{"default":"","type":"string","maxLength":200},"phone":{"default":"","type":"string","maxLength":40},"website":{"default":"","type":"string","maxLength":2000}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"event"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"title":{"type":"string","maxLength":200},"date":{"type":"string","maxLength":100},"time":{"default":"","type":"string","maxLength":100},"place":{"default":"","type":"string","maxLength":200},"url":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"Add to calendar","type":"string","maxLength":80}},"required":["type","title","date"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"rating"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"question":{"type":"string","maxLength":200},"url":{"type":"string","maxLength":2000},"low_label":{"default":"","type":"string","maxLength":40},"high_label":{"default":"","type":"string","maxLength":40}},"required":["type","question","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"table"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"rows":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"columns":{"minItems":1,"maxItems":6,"type":"array","items":{"type":"object","properties":{"header":{"type":"string","maxLength":60},"field":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"format":{"default":"text","type":"string","enum":["text","currency","number","date"]}},"required":["header","field"],"additionalProperties":false}},"currency":{"default":"USD","type":"string","pattern":"^[A-Za-z]{3}$"}},"required":["type","rows","columns"],"additionalProperties":false}]}},"required":["name","block"],"additionalProperties":false},"example":{"name":"Support signature","block":{"type":"signature","name":"Sam","title":"Support"}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"blk_4Tq…","object":"saved_block","name":"Support signature","block":{"type":"signature","name":"Sam","title":"Support"},"created_at":"2026-10-15T09:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listSavedBlocks","tags":["Templates"],"summary":"List saved blocks","description":"The blocks saved for reuse in this project, newest first.\n\nRequired scope: `templates:manage`.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"blk_4Tq…","object":"saved_block","name":"Support signature","block":{"type":"signature","name":"Sam"},"created_at":"2026-10-15T09:00:00.000Z"}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/saved-blocks/{id}":{"delete":{"operationId":"deleteSavedBlock","tags":["Templates"],"summary":"Delete a saved block","description":"Removes it from the saved list. Designs that already use it are not changed.\n\nRequired scope: `templates:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The saved block id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"saved_block","id":"blk_4Tq…","deleted":true}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/brand":{"get":{"operationId":"getBrandKit","tags":["Templates"],"summary":"Retrieve the brand kit","description":"The project’s look: logo, accent and background colors, font and footer text. It is applied when you add a template from the library and in the dashboard’s builder.\n\nRequired scope: `templates:manage`.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"brand_kit","logo_url":"https://acme.com/logo.png","logo_width":140,"accent":"#1a56db","background":"#f4f5f7","font":"sans","footer_text":"Acme Inc, 1 Main St"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"put":{"operationId":"updateBrandKit","tags":["Templates"],"summary":"Update the brand kit","description":"Changes only the fields you send. Use `null` to clear one.\n\nRequired scope: `templates:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"logo_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"logo_width":{"anyOf":[{"type":"integer","minimum":40,"maximum":300},{"type":"null"}]},"accent":{"anyOf":[{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},{"type":"null"}]},"background":{"anyOf":[{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},{"type":"null"}]},"font":{"anyOf":[{"type":"string","enum":["sans","serif"]},{"type":"null"}]},"footer_text":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]}},"additionalProperties":false},"example":{"accent":"#ff5500","logo_url":"https://acme.com/logo.png"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"brand_kit","logo_url":"https://acme.com/logo.png","logo_width":null,"accent":"#ff5500","background":null,"font":null,"footer_text":null}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/templates/{id}/preview":{"post":{"operationId":"previewTemplate","tags":["Templates"],"summary":"Preview a template","description":"Renders a template version with sample variables and sends nothing. It renders whatever it can and lists `problems` (missing or mistyped variables, or a mistake in the template), so a preview never fails just because a sample value is not filled in yet. Omit `version` for the latest, and pass `language` to preview a translation.\n\nRequired scope: `templates:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The template id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"version":1,"subject":"Welcome, Maria","html":"<p>Hi Maria!</p>","text":null,"variables":{"first_name":{"type":"string","required":true}},"problems":[]}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/webhooks":{"post":{"operationId":"createWebhook","tags":["Webhooks"],"summary":"Create a webhook endpoint","description":"Registers an HTTPS endpoint for delivery events. The signing `secret` is shown **once**, in this response. Requests to private network addresses are refused.\n\nRequired scope: `webhooks:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string","maxLength":2000},"endpoint":{"type":"string","maxLength":2000},"events":{"default":["email.sent","email.delivered","email.bounced","email.complained","email.failed","email.opened","email.clicked","email.delivery_delayed","email.scheduled","email.suppressed","email.received"],"minItems":1,"type":"array","items":{"type":"string","enum":["email.sent","email.delivered","email.bounced","email.complained","email.failed","email.opened","email.clicked","email.delivery_delayed","email.scheduled","email.suppressed","email.received"]}}},"additionalProperties":false},"example":{"url":"https://acme.com/hooks/sendsend","events":["email.delivered","email.bounced"]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"whe_3Hq…","object":"webhook_endpoint","url":"https://acme.com/hooks/sendsend","events":["email.delivered","email.bounced"],"active":true,"created_at":"2026-10-06T15:00:00.000Z","secret":"whsec_…"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_limit_reached`: Your plan’s webhook limit is reached.\n`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listWebhooks","tags":["Webhooks"],"summary":"List webhook endpoints","description":"Active endpoints in the project.\n\nRequired scope: `webhooks:manage`.","responses":{"200":{"description":"Success"},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","tags":["Webhooks"],"summary":"Delete a webhook endpoint","description":"Stops deliveries to the endpoint.\n\nRequired scope: `webhooks:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The webhook endpoint id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"getWebhook","tags":["Webhooks"],"summary":"Retrieve a webhook endpoint","description":"Returns the endpoint. The signing secret is never shown again after creation.\n\nRequired scope: `webhooks:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The webhook endpoint id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"whe_3Hq…","object":"webhook_endpoint","url":"https://acme.com/hooks/sendsend","events":["email.delivered","email.bounced"],"active":true,"created_at":"2026-10-06T15:00:00.000Z"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"patch":{"operationId":"updateWebhook","tags":["Webhooks"],"summary":"Update a webhook endpoint","description":"Change where the endpoint points or which events it receives. Its secret and delivery history are kept. The new URL goes through the same safety checks as when you create one.\n\nRequired scope: `webhooks:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The webhook endpoint id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string","maxLength":2000},"endpoint":{"type":"string","maxLength":2000},"events":{"minItems":1,"type":"array","items":{"type":"string","enum":["email.sent","email.delivered","email.bounced","email.complained","email.failed","email.opened","email.clicked","email.delivery_delayed","email.scheduled","email.suppressed","email.received"]}}},"additionalProperties":false},"example":{"events":["email.bounced","email.complained"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"whe_3Hq…","object":"webhook_endpoint","url":"https://acme.com/hooks/sendsend","events":["email.bounced","email.complained"],"active":true,"created_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/webhooks/{id}/rotate-secret":{"post":{"operationId":"rotateWebhookSecret","tags":["Webhooks"],"summary":"Rotate the signing secret","description":"Issues a new secret, shown once. The old secret keeps signing alongside the new one for 24 hours so you can switch over without dropping events.\n\nRequired scope: `webhooks:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The webhook endpoint id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"whe_3Hq…","secret":"whsec_…","previous_secret_valid_for_hours":24}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/webhooks/{id}/deliveries":{"get":{"operationId":"listWebhookDeliveries","tags":["Webhooks"],"summary":"List deliveries","description":"The most recent 100 deliveries to the endpoint, with their status and last response.\n\nRequired scope: `webhooks:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The webhook endpoint id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/webhooks/{id}/deliveries/{did}":{"get":{"operationId":"getWebhookDelivery","tags":["Webhooks"],"summary":"Retrieve a delivery","description":"One delivery with each attempt: status code, error and duration.\n\nRequired scope: `webhooks:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The webhook endpoint id.","schema":{"type":"string"}},{"name":"did","in":"path","required":true,"description":"The delivery id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/webhooks/{id}/deliveries/{did}/replay":{"post":{"operationId":"replayWebhookDelivery","tags":["Webhooks"],"summary":"Replay a delivery","description":"Sends the same event again (same event id and payload) as a new attempt. It never creates a new event, so your idempotency on `SendSend-Event-Id` keeps working.\n\nRequired scope: `webhooks:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The webhook endpoint id.","schema":{"type":"string"}},{"name":"did","in":"path","required":true,"description":"The delivery id.","schema":{"type":"string"}}],"responses":{"202":{"description":"Success"},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/dmarc/domains":{"post":{"operationId":"createDmarcDomain","tags":["DMARC"],"summary":"Monitor a domain’s DMARC","description":"Starts DMARC monitoring for a domain. We give you a report address; add it to your domain’s DMARC record as `rua=mailto:…` (the `record` field is a ready-made record for a domain with none). Mailbox providers such as Google, Microsoft and Yahoo then send a daily summary of the mail they saw using your domain, and we turn it into who is sending, whether it passes, and what to fix. The first reports usually arrive within a day or two. Reports are kept for 90 days. How many domains you can monitor depends on your plan.\n\nRequired scope: `domains:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"domain":{"type":"string","minLength":3,"maxLength":253}},"required":["domain"],"additionalProperties":false},"example":{"domain":"acme.com"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"dmd_3f9a…","object":"dmarc_domain","domain":"acme.com","report_address":"a1b2c3d4e5f60718293a@dmarc.sendsend.email","record":"v=DMARC1; p=none; rua=mailto:a1b2c3d4e5f60718293a@dmarc.sendsend.email","status":"waiting_for_reports","last_report_at":null,"created_at":"2026-10-14T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.\n`plan_limit_reached`: Your plan’s DMARC domains are all in use.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`domain_already_registered`: This domain is already monitored in the project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listDmarcDomains","tags":["DMARC"],"summary":"List monitored domains","description":"The domains monitored in this project, with their report address and whether reports are arriving.\n\nRequired scope: `domains:manage`.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"dmd_3f9a…","object":"dmarc_domain","domain":"acme.com","report_address":"a1b2c3d4e5f60718293a@dmarc.sendsend.email","record":"v=DMARC1; p=none; rua=mailto:a1b2c3d4e5f60718293a@dmarc.sendsend.email","status":"waiting_for_reports","last_report_at":null,"created_at":"2026-10-14T15:00:00.000Z"}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/dmarc/domains/{id}":{"get":{"operationId":"getDmarcDomain","tags":["DMARC"],"summary":"Get a domain’s DMARC summary","description":"How the domain is doing over the last `days` days (1 to 90, default 30): messages seen, how many passed DMARC (an aligned SPF or DKIM pass), how many were quarantined or rejected, daily totals, the policy your domain publishes, whether your DNS record points at us (`record_check`: `ok`, `missing`, `not_pointing_here` or `unknown`), and plain advice on whether it is safe to move to a stricter policy.\n\nRequired scope: `domains:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The DMARC domain id.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Look back this many days, 1 to 90. Default 30.","schema":{"type":"integer","minimum":1,"maximum":90,"default":30}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"dmd_3f9a…","object":"dmarc_domain","domain":"acme.com","report_address":"a1b2c3d4e5f60718293a@dmarc.sendsend.email","record":"v=DMARC1; p=none; rua=mailto:a1b2c3d4e5f60718293a@dmarc.sendsend.email","status":"receiving","last_report_at":"2026-10-14T00:00:00.000Z","created_at":"2026-10-14T15:00:00.000Z","record_check":"ok","published_record":"v=DMARC1; p=none; rua=mailto:a1b2c3d4e5f60718293a@dmarc.sendsend.email","policy":{"domain":"acme.com","p":"none","pct":100},"summary":{"days":30,"messages":12840,"pass":12610,"fail":230,"pass_rate":0.982,"quarantined":0,"rejected":0,"spf_pass":11900,"dkim_pass":12500,"reports":54,"daily":[{"day":"2026-10-13","messages":430,"pass":421,"fail":9}]},"advice":"Nearly all mail passes. You can move to p=quarantine, then to p=reject once it stays that way."}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteDmarcDomain","tags":["DMARC"],"summary":"Stop monitoring a domain","description":"Removes the domain and every report we stored for it. Reports sent to its address afterwards are discarded.\n\nRequired scope: `domains:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The DMARC domain id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"dmarc_domain","id":"dmd_3f9a…","deleted":true}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/dmarc/domains/{id}/sources":{"get":{"operationId":"listDmarcSources","tags":["DMARC"],"summary":"List who sends as your domain","description":"Every server that sent mail using the domain in the period, busiest first: its address and reverse-DNS name, the service it belongs to when we recognise it (Amazon SES, Google Workspace, SendGrid and so on), how many messages passed and failed, and what to do about it.\n\nRequired scope: `domains:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The DMARC domain id.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Look back this many days, 1 to 90. Default 30.","schema":{"type":"integer","minimum":1,"maximum":90,"default":30}},{"name":"limit","in":"query","required":false,"description":"At most this many senders, 1 to 200. Default 50.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","domain_id":"dmd_3f9a…","days":30,"data":[{"object":"dmarc_source","ip":"54.240.8.12","host":"a8-12.smtp-out.amazonses.com","service":"Amazon SES","messages":9200,"pass":9200,"fail":0,"pass_rate":1,"verdict":"passing","advice":"Amazon SES passes DMARC."}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/blocklist/monitors":{"post":{"operationId":"createBlocklistMonitor","tags":["Blocklists"],"summary":"Monitor a domain or IP for blocklists","description":"Watches a domain name or a public IPv4 address against well-known public spam blocklists (Spamhaus, SURBL, URIBL, SpamCop and others). It is checked straight away, then again every six hours, and the account’s owners and admins are emailed when it becomes listed and when it is cleared. Domains are checked against domain blocklists and IPs against IP blocklists. A list that refuses to answer is reported as not checked and never counted as clean.\n\nRequired scope: `domains:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"target":{"type":"string","minLength":3,"maxLength":253}},"required":["target"],"additionalProperties":false},"example":{"target":"acme.com"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"blm_7c1d…","object":"blocklist_monitor","kind":"domain","target":"acme.com","status":"clean","listed_on":[],"listed_since":null,"last_checked_at":"2026-10-15T09:00:00.000Z","created_at":"2026-10-15T08:59:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.\n`plan_limit_reached`: Your plan’s blocklist monitors are all in use.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`domain_already_registered`: This target is already monitored in the project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listBlocklistMonitors","tags":["Blocklists"],"summary":"List blocklist monitors","description":"Every monitored domain and IP in this project with its current status: `clean`, `listed` (see `listed_on` for the lists and the reasons), `unknown` (no list could be checked) or `pending`.\n\nRequired scope: `domains:manage`.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"blm_7c1d…","object":"blocklist_monitor","kind":"domain","target":"acme.com","status":"clean","listed_on":[],"listed_since":null,"last_checked_at":"2026-10-15T09:00:00.000Z","created_at":"2026-10-15T08:59:00.000Z"}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/blocklist/monitors/{id}":{"get":{"operationId":"getBlocklistMonitor","tags":["Blocklists"],"summary":"Get a blocklist monitor","description":"One monitor with its recent history of being listed and cleared.\n\nRequired scope: `domains:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The blocklist monitor id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"blm_7c1d…","object":"blocklist_monitor","kind":"domain","target":"acme.com","status":"clean","listed_on":[],"listed_since":null,"last_checked_at":"2026-10-15T09:00:00.000Z","created_at":"2026-10-15T08:59:00.000Z","events":[{"at":"2026-10-10T04:00:00.000Z","event":"cleared","lists":[]}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteBlocklistMonitor","tags":["Blocklists"],"summary":"Stop monitoring","description":"Removes the monitor and its history.\n\nRequired scope: `domains:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The blocklist monitor id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"blocklist_monitor","id":"blm_7c1d…","deleted":true}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/blocklist/monitors/{id}/check":{"post":{"operationId":"checkBlocklistMonitor","tags":["Blocklists"],"summary":"Check a monitor now","description":"Checks the lists right away, for example after you asked a list to remove you. A monitor can be checked at most once a minute.\n\nRequired scope: `domains:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The blocklist monitor id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"blm_7c1d…","object":"blocklist_monitor","kind":"domain","target":"acme.com","status":"clean","listed_on":[],"listed_since":null,"last_checked_at":"2026-10-15T09:00:00.000Z","created_at":"2026-10-15T08:59:00.000Z"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/verify":{"post":{"operationId":"verifyEmail","tags":["Verification"],"summary":"Verify an email address","description":"Checks one address before you send to it: that it is well formed, that its domain exists and accepts mail, whether it is a throwaway inbox or a role address such as info@, whether the domain looks like a typo of a popular one (with a suggestion), and whether it is on your suppression list. It does not contact the recipient’s mail server, so `valid` means worth sending to, not guaranteed to arrive. Results: `valid`, `invalid` (will bounce), `risky` (see `reasons`) and `unknown` (DNS did not answer; try again). Each address uses one of your plan’s monthly verifications.\n\nRequired scope: `emails:verify`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"email":{"type":"string","minLength":1,"maxLength":320}},"required":["email"],"additionalProperties":false},"example":{"email":"maria@example.com"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"email_verification","email":"maria@example.com","result":"valid","reasons":[],"suggestion":null,"free_provider":false,"role_account":false,"disposable":false,"mail_servers":["mx1.example.com"],"verifications":{"used":12,"limit":5000}}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`quota_exhausted`: The month’s verifications for your plan are used up.\n`rate_limited`: Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/verify/batch":{"post":{"operationId":"verifyEmails","tags":["Verification"],"summary":"Verify up to 100 email addresses","description":"The same checks as verifying one address, for a list of up to 100. Results come back in the order you sent them, with a count of each outcome. Every address uses one verification, and the whole request is refused if your remaining verifications would not cover it.\n\nRequired scope: `emails:verify`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"emails":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":320}}},"required":["emails"],"additionalProperties":false},"example":{"emails":["maria@example.com","bad@@example"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"object":"email_verification","email":"maria@example.com","result":"valid","reasons":[],"suggestion":null,"free_provider":false,"role_account":false,"disposable":false,"mail_servers":["mx1.example.com"]},{"object":"email_verification","email":"bad@@example","result":"invalid","reasons":["invalid_syntax"],"suggestion":null,"free_provider":false,"role_account":false,"disposable":false,"mail_servers":[]}],"summary":{"valid":1,"invalid":1,"risky":0,"unknown":0},"verifications":{"used":14,"limit":5000}}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`quota_exhausted`: The month’s verifications for your plan would be exceeded.\n`rate_limited`: Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/usage":{"get":{"operationId":"getUsage","tags":["Usage"],"summary":"Retrieve usage","description":"This month’s sending against your allowance, the project’s daily limit, spending settings and sending health. Test-environment sends are not counted.\n\nRequired scope: `emails:read`.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"period":"2026-10","environment":"live","allowance":50000,"submitted":1240,"reserved":3,"hard_limit":50000,"overage_enabled":false,"daily":{"limit":1000000,"used":87}}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/emails/{id}/cancel":{"post":{"operationId":"cancelEmail","tags":["Emails"],"summary":"Cancel a scheduled email","description":"Stops a scheduled email before it is sent and gives its quota back. A message that is already on its way cannot be cancelled.\n\nRequired scope: `emails:send`.","parameters":[{"name":"id","in":"path","required":true,"description":"The email id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"msg_8Xk2…","status":"cancelled"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`not_schedulable`: The email is not scheduled any more (sent, already cancelled or on its way).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/emails/batch":{"post":{"operationId":"sendBatchEmails","tags":["Emails"],"summary":"Send a batch of emails","description":"Queues up to 100 messages in one request, each with the same fields as Send an email. Every message is validated first, so one invalid message rejects the whole request before anything is queued. After that each message is queued on its own: one that fails (a suppressed recipient, a quota) is reported in its own slot and never blocks the others.\n\nSend an `Idempotency-Key` to make the whole batch safe to retry. Message N uses `<key>:N`.\n\nRequired scope: `emails:send`.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Up to 240 printable characters.","schema":{"type":"string","maxLength":240}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"emails":{"minItems":1,"maxItems":100,"type":"array","items":{}}},"required":["emails"],"additionalProperties":false},"example":{"emails":[{"from":"Acme <hello@mail.acme.com>","to":["a@example.com"],"subject":"Hello A","text":"Hi A"},{"from":"Acme <hello@mail.acme.com>","to":["b@example.com"],"subject":"Hello B","text":"Hi B"}]}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"example":{"object":"batch","accepted":1,"failed":1,"data":[{"id":"msg_8Xk2…","request_id":"req_Kd83…","status":"queued","created_at":"2026-10-06T15:04:05.000Z"},{"object":"error","error":{"code":"recipient_suppressed","message":"All recipients are suppressed"}}]}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/suppressions":{"post":{"operationId":"addSuppression","tags":["Suppressions"],"summary":"Add a suppression","description":"Stops all mail to an address. The suppression list belongs to your organization, so every project shares it. Addresses are stored in lower case. Adding an address that is already listed re-activates it.\n\nRequired scope: `suppressions:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"address":{"type":"string","maxLength":254},"reason":{"default":"manual","type":"string","minLength":1,"maxLength":200}},"required":["address"],"additionalProperties":false},"example":{"address":"maria@example.com","reason":"asked to unsubscribe"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"sup_4Gh2…","object":"suppression","address":"maria@example.com","reason":"bounce","source":"provider","created_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listSuppressions","tags":["Suppressions"],"summary":"List suppressions","description":"Active suppressions, newest first, with cursor pagination.\n\nRequired scope: `suppressions:manage`.","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100. Default 20.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from a previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"sup_4Gh2…","object":"suppression","address":"maria@example.com","reason":"bounce","source":"provider","created_at":"2026-10-06T15:00:00.000Z"}],"next_cursor":null}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/suppressions/batch":{"post":{"operationId":"addBatchSuppressions","tags":["Suppressions"],"summary":"Add suppressions in bulk","description":"Adds up to 1,000 addresses at once. Duplicates are ignored.\n\nRequired scope: `suppressions:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"addresses":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"string","maxLength":254}},"reason":{"default":"manual","type":"string","minLength":1,"maxLength":200}},"required":["addresses"],"additionalProperties":false},"example":{"addresses":["a@example.com","b@example.com"]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"object":"suppression_batch","added":2}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/suppressions/{id}":{"get":{"operationId":"getSuppression","tags":["Suppressions"],"summary":"Retrieve a suppression","description":"Look up by suppression id or by email address (URL-encoded).\n\nRequired scope: `suppressions:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The suppression (or email address) id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"sup_4Gh2…","object":"suppression","address":"maria@example.com","reason":"bounce","source":"provider","created_at":"2026-10-06T15:00:00.000Z"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"removeSuppression","tags":["Suppressions"],"summary":"Remove a suppression","description":"Lets mail to the address resume. The removal is recorded in your audit log. If the address bounces permanently or complains again, it is suppressed again. Only remove an address you are sure wants your mail.\n\nRequired scope: `suppressions:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The suppression (or email address) id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/suppressions/remove-batch":{"post":{"operationId":"removeBatchSuppressions","tags":["Suppressions"],"summary":"Remove suppressions in bulk","description":"Removes up to 1,000 addresses. Addresses that are not listed are ignored.\n\nRequired scope: `suppressions:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"addresses":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"string","maxLength":254}}},"required":["addresses"],"additionalProperties":false},"example":{"addresses":["a@example.com"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"suppression_batch","removed":1}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/templates/{id}/duplicate":{"post":{"operationId":"duplicateTemplate","tags":["Templates"],"summary":"Duplicate a template","description":"Copies a version (the latest unless you name one) into a new template, at version 1.\n\nRequired scope: `templates:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The template id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,63}$"},"name":{"type":"string","minLength":1,"maxLength":200},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["id"],"additionalProperties":false},"example":{"id":"welcome-copy"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"object":"template","id":"welcome-copy","version":1}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/metrics":{"get":{"operationId":"getMetrics","tags":["Usage"],"summary":"Retrieve metrics","description":"Recipient outcomes per day for the project: sent, delivered, bounced, complained, failed and suppressed, with totals and rates, plus unique opens and clicks when tracking is on (measured against delivered). `sent` counts recipients the provider accepted. Days are in UTC. The default range is the last 30 days, and the longest is 92.\n\nRequired scope: `emails:read`.","parameters":[{"name":"from","in":"query","required":false,"description":"First day, `YYYY-MM-DD`.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Last day, `YYYY-MM-DD`. Default today.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"environment":"live","from":"2026-09-07","to":"2026-10-06","totals":{"sent":1240,"delivered":1198,"bounced":18,"complained":1,"failed":2,"suppressed":6,"opened":540,"clicked":120},"rates":{"delivered":0.966,"bounced":0.0145,"complained":0.0008,"opened":0.451,"clicked":0.1},"daily":[{"day":"2026-10-06","sent":87,"delivered":84,"bounced":1,"complained":0,"failed":0,"suppressed":0,"opened":40,"clicked":9}]}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/api-keys":{"post":{"operationId":"createApiKey","tags":["API keys"],"summary":"Create an API key","description":"Creates a key for the same project as the key making the call. The new key can only have permissions that the calling key has itself, so this can never be used to gain more access. The secret is shown **once**. No key has the `api_keys:manage` scope by default; grant it deliberately.\n\nRequired scope: `api_keys:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"scopes":{"minItems":1,"type":"array","items":{"type":"string","enum":["emails:send","emails:read","domains:manage","webhooks:manage","templates:manage","suppressions:manage","api_keys:manage","contacts:manage","broadcasts:manage","inbound:manage","emails:verify"]}},"permission":{"type":"string","enum":["full_access","sending_access"]},"domain_id":{"type":"string","maxLength":64},"expires_in_days":{"type":"integer","minimum":1,"maximum":3650}},"required":["name"],"additionalProperties":false},"example":{"name":"ci","scopes":["emails:send"]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"key_9Fq…","object":"api_key","name":"ci","scopes":["emails:send"],"secret":"ss_live_ab12cd34_…","note":"Copy this key now. It will not be shown again."}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key lacks `api_keys:manage`, or you asked for a permission it does not have.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listApiKeys","tags":["API keys"],"summary":"List API keys","description":"The project’s keys, newest first. Secrets are never shown.\n\nRequired scope: `api_keys:manage`.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"key_9Fq…","object":"api_key","name":"ci","display":"ss_live_ab12cd34_…","scopes":["emails:send"],"created_at":"2026-10-06T15:00:00.000Z","last_used_at":null,"expires_at":null,"revoked_at":null}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/api-keys/{id}":{"patch":{"operationId":"updateApiKey","tags":["API keys"],"summary":"Update an API key","description":"Rename a key or change its permissions. You can only give a key permissions you have, and you cannot change a key that is more powerful than yours.\n\nRequired scope: `api_keys:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The API key id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"scopes":{"minItems":1,"type":"array","items":{"type":"string","enum":["emails:send","emails:read","domains:manage","webhooks:manage","templates:manage","suppressions:manage","api_keys:manage","contacts:manage","broadcasts:manage","inbound:manage","emails:verify"]}}},"additionalProperties":false},"example":{"name":"ci (staging)"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"key_9Fq…","object":"api_key","name":"ci (staging)","display":"ss_live_ab12cd34_…","scopes":["emails:send"],"created_at":"2026-10-06T15:00:00.000Z","last_used_at":null,"expires_at":null,"revoked_at":null}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"revokeApiKey","tags":["API keys"],"summary":"Revoke an API key","description":"The key stops working immediately. You cannot revoke a key that is more powerful than yours.\n\nRequired scope: `api_keys:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The API key id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/logs":{"get":{"operationId":"listLogs","tags":["Logs"],"summary":"List request logs","description":"The last 30 days of calls made with this project’s API keys, newest first: what was called, the status, the time it took and the request id. Message content, recipients and request bodies are never stored. Reading the log does not add to it.\n\nRequired scope: `emails:read`.","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100. Default 20.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from a previous page.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"`success` (below 400) or `error` (400 and above).","schema":{"type":"string","enum":["success","error"]}},{"name":"method","in":"query","required":false,"description":"Only this HTTP method.","schema":{"type":"string","enum":["GET","POST","PATCH","PUT","DELETE"]}},{"name":"request_id","in":"query","required":false,"description":"Find one request by its id (`req_…`).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"log_Kd83…","object":"log","method":"POST","route":"/v1/emails","resource_id":null,"status":202,"error_code":null,"duration_ms":41,"request_id":"req_Kd83…","key_id":"key_9Fq…","created_at":"2026-10-06T15:04:05.000Z"}],"next_cursor":null}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/logs/{id}":{"get":{"operationId":"getLog","tags":["Logs"],"summary":"Retrieve a request log","description":"One logged call.\n\nRequired scope: `emails:read`.","parameters":[{"name":"id","in":"path","required":true,"description":"The log id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"log_Kd83…","object":"log","method":"POST","route":"/v1/emails","resource_id":null,"status":202,"error_code":null,"duration_ms":41,"request_id":"req_Kd83…","key_id":"key_9Fq…","created_at":"2026-10-06T15:04:05.000Z"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/audiences":{"post":{"operationId":"createAudience","tags":["Audiences"],"summary":"Create an audience","description":"An audience is a list of contacts you send broadcasts to. A project can have 20.\n\nRequired scope: `contacts:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100}},"required":["name"],"additionalProperties":false},"example":{"name":"Customers"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"aud_7Qe2…","object":"audience","name":"Customers","created_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listAudiences","tags":["Audiences"],"summary":"List audiences","description":"All audiences in the project.\n\nRequired scope: `contacts:manage`.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"aud_7Qe2…","object":"audience","name":"Customers","created_at":"2026-10-06T15:00:00.000Z"}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/audiences/{id}":{"get":{"operationId":"getAudience","tags":["Audiences"],"summary":"Retrieve an audience","description":"Includes how many contacts it holds and how many have unsubscribed.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The audience id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"aud_7Qe2…","object":"audience","name":"Customers","created_at":"2026-10-06T15:00:00.000Z","contacts":1200,"unsubscribed":14}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteAudience","tags":["Audiences"],"summary":"Delete an audience","description":"Deletes the audience and its contacts. Refused while a broadcast to it is scheduled or sending, and for audiences that have already sent a broadcast, which are kept for your records.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The audience id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"audience","id":"xxx_…","deleted":true}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`validation_error`: A broadcast is still using it, or it has sent broadcasts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/audiences/{id}/contacts":{"post":{"operationId":"createContact","tags":["Contacts"],"summary":"Create a contact","description":"Adds one person to an audience. Properties must be created first with the contact properties endpoints. An audience holds up to 50,000 contacts.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The audience id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"email":{"type":"string","maxLength":254},"first_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"unsubscribed":{"type":"boolean"},"properties":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"additionalProperties":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"}]}}},"required":["email"],"additionalProperties":false},"example":{"email":"maria@example.com","first_name":"Maria","properties":{"plan":"pro"}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"con_Hk3v…","object":"contact","audience_id":"aud_7Qe2…","email":"maria@example.com","first_name":"Maria","last_name":null,"unsubscribed":false,"properties":{"plan":"pro"},"created_at":"2026-10-06T15:00:00.000Z","updated_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`validation_error`: That email is already in the audience.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listContacts","tags":["Contacts"],"summary":"List contacts","description":"Contacts in an audience, with cursor pagination.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The audience id.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100. Default 20.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from a previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","has_more":false,"data":[{"id":"con_Hk3v…","object":"contact","audience_id":"aud_7Qe2…","email":"maria@example.com","first_name":"Maria","last_name":null,"unsubscribed":false,"properties":{"plan":"pro"},"created_at":"2026-10-06T15:00:00.000Z","updated_at":"2026-10-06T15:00:00.000Z"}],"next_cursor":null}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/audiences/{id}/contacts/import":{"post":{"operationId":"importContacts","tags":["Contacts"],"summary":"Import contacts","description":"Adds or updates up to 1,000 contacts in one request. Emails that exist are updated, and an import never resubscribes someone who unsubscribed.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The audience id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"contacts":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":254},"first_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"unsubscribed":{"type":"boolean"},"properties":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"additionalProperties":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"}]}}},"required":["email"],"additionalProperties":false}}},"required":["contacts"],"additionalProperties":false},"example":{"contacts":[{"email":"maria@example.com"},{"email":"li@example.com","first_name":"Li"}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"import","created":2,"updated":0}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/audiences/{id}/contacts/{contact}":{"get":{"operationId":"getContact","tags":["Contacts"],"summary":"Retrieve a contact","description":"Look a contact up by id or by email address.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The audience id.","schema":{"type":"string"}},{"name":"contact","in":"path","required":true,"description":"The contact id or email address.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"con_Hk3v…","object":"contact","audience_id":"aud_7Qe2…","email":"maria@example.com","first_name":"Maria","last_name":null,"unsubscribed":false,"properties":{"plan":"pro"},"created_at":"2026-10-06T15:00:00.000Z","updated_at":"2026-10-06T15:00:00.000Z"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"patch":{"operationId":"updateContact","tags":["Contacts"],"summary":"Update a contact","description":"Change names, email, properties or the unsubscribed flag. Properties you send are merged with the ones already set.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The audience id.","schema":{"type":"string"}},{"name":"contact","in":"path","required":true,"description":"The contact id or email address.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"email":{"type":"string","maxLength":254},"first_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"unsubscribed":{"type":"boolean"},"properties":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"additionalProperties":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"}]}}},"additionalProperties":false},"example":{"first_name":"Maria"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"con_Hk3v…","object":"contact","audience_id":"aud_7Qe2…","email":"maria@example.com","first_name":"Maria","last_name":null,"unsubscribed":false,"properties":{"plan":"pro"},"created_at":"2026-10-06T15:00:00.000Z","updated_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteContact","tags":["Contacts"],"summary":"Delete a contact","description":"Removes the contact from the audience.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The audience id.","schema":{"type":"string"}},{"name":"contact","in":"path","required":true,"description":"The contact id or email address.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"contact","id":"xxx_…","deleted":true}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/audiences/{id}/contacts/{contact}/topics":{"get":{"operationId":"getContactTopics","tags":["Contacts"],"summary":"List a contact’s topics","description":"Every topic in the project and whether this contact is subscribed. A topic they have not chosen uses its default.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The audience id.","schema":{"type":"string"}},{"name":"contact","in":"path","required":true,"description":"The contact id or email address.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"top_Xa9…","name":"Product news","description":null,"subscription":"opt_in"}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"patch":{"operationId":"updateContactTopics","tags":["Contacts"],"summary":"Update a contact’s topics","description":"Subscribe or unsubscribe a contact from topics.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The audience id.","schema":{"type":"string"}},{"name":"contact","in":"path","required":true,"description":"The contact id or email address.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"topics":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":64},"subscription":{"type":"string","enum":["opt_in","opt_out"]}},"required":["id","subscription"],"additionalProperties":false}}},"required":["topics"],"additionalProperties":false},"example":{"topics":[{"id":"top_Xa9…","subscription":"opt_out"}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"contact","id":"con_Hk3v…","updated":1}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/contact-properties":{"post":{"operationId":"createContactProperty","tags":["Contact properties"],"summary":"Create a contact property","description":"A custom field you can store on contacts and use in broadcasts as `{{{key}}}`. The fallback is used when a contact has no value.\n\nRequired scope: `contacts:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"type":{"type":"string","enum":["string","number"]},"fallback_value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":500},{"type":"number"}]},{"type":"null"}]}},"required":["key","type"],"additionalProperties":false},"example":{"key":"plan","type":"string","fallback_value":"free"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"prop_Lm4…","object":"contact_property","key":"plan","type":"string","fallback_value":"free","created_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`validation_error`: A property with that key exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listContactProperties","tags":["Contact properties"],"summary":"List contact properties","description":"All custom fields in the project.\n\nRequired scope: `contacts:manage`.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"prop_Lm4…","object":"contact_property","key":"plan","type":"string","fallback_value":"free","created_at":"2026-10-06T15:00:00.000Z"}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/contact-properties/{id}":{"get":{"operationId":"getContactProperty","tags":["Contact properties"],"summary":"Retrieve a contact property","description":"By id or by key.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The contact property id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"prop_Lm4…","object":"contact_property","key":"plan","type":"string","fallback_value":"free","created_at":"2026-10-06T15:00:00.000Z"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"patch":{"operationId":"updateContactProperty","tags":["Contact properties"],"summary":"Update a contact property","description":"Change the fallback value. The key and type cannot change.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The contact property id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"fallback_value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":500},{"type":"number"}]},{"type":"null"}]}},"required":["fallback_value"],"additionalProperties":false},"example":{"fallback_value":"starter"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"prop_Lm4…","object":"contact_property","key":"plan","type":"string","fallback_value":"starter","created_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteContactProperty","tags":["Contact properties"],"summary":"Delete a contact property","description":"Removes the field and its value from every contact.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The contact property id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"contact_property","id":"xxx_…","deleted":true}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/topics":{"post":{"operationId":"createTopic","tags":["Topics"],"summary":"Create a topic","description":"A kind of email people can opt in or out of, such as product news. A broadcast with a topic goes only to contacts subscribed to it, and its unsubscribe link removes them from that topic alone.\n\nRequired scope: `contacts:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"default_subscription":{"default":"opt_in","type":"string","enum":["opt_in","opt_out"]}},"required":["name"],"additionalProperties":false},"example":{"name":"Product news","default_subscription":"opt_in"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"top_Xa9…","object":"topic","name":"Product news","description":"Releases and tips","default_subscription":"opt_in","created_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listTopics","tags":["Topics"],"summary":"List topics","description":"All topics in the project.\n\nRequired scope: `contacts:manage`.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"top_Xa9…","object":"topic","name":"Product news","description":"Releases and tips","default_subscription":"opt_in","created_at":"2026-10-06T15:00:00.000Z"}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/topics/{id}":{"get":{"operationId":"getTopic","tags":["Topics"],"summary":"Retrieve a topic","description":"One topic.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The topic id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"top_Xa9…","object":"topic","name":"Product news","description":"Releases and tips","default_subscription":"opt_in","created_at":"2026-10-06T15:00:00.000Z"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"patch":{"operationId":"updateTopic","tags":["Topics"],"summary":"Update a topic","description":"Rename it, change its description or its default.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The topic id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"default_subscription":{"type":"string","enum":["opt_in","opt_out"]}},"additionalProperties":false},"example":{"description":"Releases and tips"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"top_Xa9…","object":"topic","name":"Product news","description":"Releases and tips","default_subscription":"opt_in","created_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteTopic","tags":["Topics"],"summary":"Delete a topic","description":"Removes the topic and every contact’s choice about it.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The topic id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"topic","id":"xxx_…","deleted":true}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/broadcasts":{"post":{"operationId":"createBroadcast","tags":["Broadcasts"],"summary":"Create a broadcast","description":"Saves a draft email to send to everyone in an audience. Use `{{{FIRST_NAME|there}}}`, `{{{LAST_NAME}}}`, `{{{EMAIL}}}` or any contact property; text after `|` is used when a contact has no value. Every message gets an unsubscribe link and the one-click unsubscribe headers, and a footer link is added if you leave out `{{{UNSUBSCRIBE_URL}}}`. Instead of `html` you can send a `design`: a list of blocks (heading, text, button, image, divider, spacer, footer) with an accent color, background and font. We turn it into email-safe HTML and a plain-text version, and the dashboard can open it in the visual editor. Pass `segment_id` to send to a segment of the audience instead of everyone in it. Pass `ab_test` to split test it: your subject and content are version A, each entry in `ab_test.variants` is another version (B, C, D) that replaces whatever it sets, `test_percent` of the audience (5 to 50) is divided between the versions, and after `wait_hours` (1 to 72) the version with the best `winner_by` (`opens` or `clicks`) is sent to everyone else. A split test needs open (or click) tracking on the sending domain. Nothing is sent until you call send.\n\nRequired scope: `broadcasts:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","maxLength":200},"audience_id":{"type":"string","maxLength":64},"topic_id":{"type":"string","maxLength":64},"segment_id":{"type":"string","maxLength":64},"from":{"type":"string"},"subject":{"type":"string","minLength":1,"maxLength":998},"reply_to":{"type":"string","maxLength":254},"preview_text":{"type":"string","maxLength":200},"html":{"type":"string","maxLength":1000000},"text":{"type":"string","maxLength":1000000},"design":{"type":"object","properties":{"accent":{"default":"#1a56db","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"background":{"default":"#f4f5f7","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"font":{"default":"sans","type":"string","enum":["sans","serif"]},"blocks":{"minItems":1,"maxItems":100,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"heading"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":300},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"text"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":5000},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"button"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"label":{"type":"string","maxLength":80},"url":{"type":"string","maxLength":2000},"align":{"default":"center","type":"string","enum":["left","center","right"]}},"required":["type","label","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"url":{"type":"string","maxLength":2000},"alt":{"default":"","type":"string","maxLength":200},"link":{"default":"","type":"string","maxLength":2000}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"divider"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"spacer"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"height":{"default":24,"type":"integer","minimum":4,"maximum":120}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"footer"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":1000}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"logo"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"url":{"type":"string","maxLength":2000},"alt":{"default":"","type":"string","maxLength":200},"link":{"default":"","type":"string","maxLength":2000},"width":{"default":140,"type":"integer","minimum":40,"maximum":300},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"columns"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"image_url":{"type":"string","maxLength":2000},"image_alt":{"default":"","type":"string","maxLength":200},"title":{"default":"","type":"string","maxLength":200},"text":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"","type":"string","maxLength":80},"button_url":{"default":"","type":"string","maxLength":2000},"image_side":{"default":"left","type":"string","enum":["left","right"]}},"required":["type","image_url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"product"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"image_url":{"default":"","type":"string","maxLength":2000},"name":{"type":"string","maxLength":200},"description":{"default":"","type":"string","maxLength":500},"price":{"default":"","type":"string","maxLength":60},"url":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"View","type":"string","maxLength":80}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"discount"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"headline":{"default":"Your discount","type":"string","maxLength":200},"code":{"type":"string","maxLength":40},"details":{"default":"","type":"string","maxLength":300}},"required":["type","code"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"social"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"links":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["website","x","facebook","instagram","linkedin","youtube","tiktok","github"]},"url":{"type":"string","maxLength":2000}},"required":["network","url"],"additionalProperties":false}},"align":{"default":"center","type":"string","enum":["left","center","right"]}},"required":["type","links"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"list"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","maxLength":300}},"ordered":{"default":false,"type":"boolean"}},"required":["type","items"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"quote"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":1000},"author":{"default":"","type":"string","maxLength":100}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"signature"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"name":{"type":"string","maxLength":100},"title":{"default":"","type":"string","maxLength":100},"company":{"default":"","type":"string","maxLength":100},"email":{"default":"","type":"string","maxLength":200},"phone":{"default":"","type":"string","maxLength":40},"website":{"default":"","type":"string","maxLength":2000}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"event"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"title":{"type":"string","maxLength":200},"date":{"type":"string","maxLength":100},"time":{"default":"","type":"string","maxLength":100},"place":{"default":"","type":"string","maxLength":200},"url":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"Add to calendar","type":"string","maxLength":80}},"required":["type","title","date"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"rating"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"question":{"type":"string","maxLength":200},"url":{"type":"string","maxLength":2000},"low_label":{"default":"","type":"string","maxLength":40},"high_label":{"default":"","type":"string","maxLength":40}},"required":["type","question","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"table"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"rows":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"columns":{"minItems":1,"maxItems":6,"type":"array","items":{"type":"object","properties":{"header":{"type":"string","maxLength":60},"field":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"format":{"default":"text","type":"string","enum":["text","currency","number","date"]}},"required":["header","field"],"additionalProperties":false}},"currency":{"default":"USD","type":"string","pattern":"^[A-Za-z]{3}$"}},"required":["type","rows","columns"],"additionalProperties":false}]}}},"required":["blocks"],"additionalProperties":false},"ab_test":{"anyOf":[{"type":"object","properties":{"variants":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"object","properties":{"subject":{"type":"string","minLength":1,"maxLength":998},"preview_text":{"type":"string","maxLength":200},"html":{"type":"string","maxLength":1000000},"text":{"type":"string","maxLength":1000000},"design":{"type":"object","properties":{"accent":{"default":"#1a56db","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"background":{"default":"#f4f5f7","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"font":{"default":"sans","type":"string","enum":["sans","serif"]},"blocks":{"minItems":1,"maxItems":100,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"heading"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":300},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"text"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":5000},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"button"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"label":{"type":"string","maxLength":80},"url":{"type":"string","maxLength":2000},"align":{"default":"center","type":"string","enum":["left","center","right"]}},"required":["type","label","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"url":{"type":"string","maxLength":2000},"alt":{"default":"","type":"string","maxLength":200},"link":{"default":"","type":"string","maxLength":2000}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"divider"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"spacer"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"height":{"default":24,"type":"integer","minimum":4,"maximum":120}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"footer"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":1000}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"logo"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"url":{"type":"string","maxLength":2000},"alt":{"default":"","type":"string","maxLength":200},"link":{"default":"","type":"string","maxLength":2000},"width":{"default":140,"type":"integer","minimum":40,"maximum":300},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"columns"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"image_url":{"type":"string","maxLength":2000},"image_alt":{"default":"","type":"string","maxLength":200},"title":{"default":"","type":"string","maxLength":200},"text":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"","type":"string","maxLength":80},"button_url":{"default":"","type":"string","maxLength":2000},"image_side":{"default":"left","type":"string","enum":["left","right"]}},"required":["type","image_url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"product"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"image_url":{"default":"","type":"string","maxLength":2000},"name":{"type":"string","maxLength":200},"description":{"default":"","type":"string","maxLength":500},"price":{"default":"","type":"string","maxLength":60},"url":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"View","type":"string","maxLength":80}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"discount"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"headline":{"default":"Your discount","type":"string","maxLength":200},"code":{"type":"string","maxLength":40},"details":{"default":"","type":"string","maxLength":300}},"required":["type","code"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"social"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"links":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["website","x","facebook","instagram","linkedin","youtube","tiktok","github"]},"url":{"type":"string","maxLength":2000}},"required":["network","url"],"additionalProperties":false}},"align":{"default":"center","type":"string","enum":["left","center","right"]}},"required":["type","links"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"list"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","maxLength":300}},"ordered":{"default":false,"type":"boolean"}},"required":["type","items"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"quote"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":1000},"author":{"default":"","type":"string","maxLength":100}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"signature"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"name":{"type":"string","maxLength":100},"title":{"default":"","type":"string","maxLength":100},"company":{"default":"","type":"string","maxLength":100},"email":{"default":"","type":"string","maxLength":200},"phone":{"default":"","type":"string","maxLength":40},"website":{"default":"","type":"string","maxLength":2000}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"event"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"title":{"type":"string","maxLength":200},"date":{"type":"string","maxLength":100},"time":{"default":"","type":"string","maxLength":100},"place":{"default":"","type":"string","maxLength":200},"url":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"Add to calendar","type":"string","maxLength":80}},"required":["type","title","date"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"rating"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"question":{"type":"string","maxLength":200},"url":{"type":"string","maxLength":2000},"low_label":{"default":"","type":"string","maxLength":40},"high_label":{"default":"","type":"string","maxLength":40}},"required":["type","question","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"table"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"rows":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"columns":{"minItems":1,"maxItems":6,"type":"array","items":{"type":"object","properties":{"header":{"type":"string","maxLength":60},"field":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"format":{"default":"text","type":"string","enum":["text","currency","number","date"]}},"required":["header","field"],"additionalProperties":false}},"currency":{"default":"USD","type":"string","pattern":"^[A-Za-z]{3}$"}},"required":["type","rows","columns"],"additionalProperties":false}]}}},"required":["blocks"],"additionalProperties":false}},"additionalProperties":false}},"test_percent":{"default":20,"type":"integer","minimum":5,"maximum":50},"wait_hours":{"default":4,"type":"integer","minimum":1,"maximum":72},"winner_by":{"default":"opens","type":"string","enum":["opens","clicks"]}},"required":["variants"],"additionalProperties":false},{"type":"null"}]}},"required":["audience_id","from","subject"],"additionalProperties":false},"example":{"audience_id":"aud_7Qe2…","from":"Acme <news@mail.acme.com>","subject":"What’s new, {{{FIRST_NAME|there}}}","html":"<p>Hi {{{FIRST_NAME|there}}}, here is what shipped.</p><p><a href=\"{{{UNSUBSCRIBE_URL}}}\">Unsubscribe</a></p>"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"bcast_Tz8…","object":"broadcast","name":"October update","audience_id":"aud_7Qe2…","topic_id":null,"from":"Acme <news@mail.acme.com>","subject":"What’s new, {{{FIRST_NAME|there}}}","status":"draft","status_reason":null,"scheduled_at":null,"sent":0,"skipped":0,"failed":0,"created_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listBroadcasts","tags":["Broadcasts"],"summary":"List broadcasts","description":"Newest first, without the message bodies.\n\nRequired scope: `broadcasts:manage`.","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100. Default 20.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from a previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","has_more":false,"data":[{"id":"bcast_Tz8…","object":"broadcast","name":"October update","audience_id":"aud_7Qe2…","topic_id":null,"from":"Acme <news@mail.acme.com>","subject":"What’s new, {{{FIRST_NAME|there}}}","status":"draft","status_reason":null,"scheduled_at":null,"sent":0,"skipped":0,"failed":0,"created_at":"2026-10-06T15:00:00.000Z"}],"next_cursor":null}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/broadcasts/{id}":{"get":{"operationId":"getBroadcast","tags":["Broadcasts"],"summary":"Retrieve a broadcast","description":"Includes how many contacts it was sent to, skipped (unsubscribed or suppressed) and failed.\n\nRequired scope: `broadcasts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The broadcast id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"bcast_Tz8…","object":"broadcast","name":"October update","audience_id":"aud_7Qe2…","topic_id":null,"from":"Acme <news@mail.acme.com>","subject":"What’s new, {{{FIRST_NAME|there}}}","status":"sent","status_reason":null,"scheduled_at":null,"sent":1180,"skipped":20,"failed":0,"created_at":"2026-10-06T15:00:00.000Z"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"patch":{"operationId":"updateBroadcast","tags":["Broadcasts"],"summary":"Update a broadcast","description":"Only while it is a draft.\n\nRequired scope: `broadcasts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The broadcast id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","maxLength":200},"audience_id":{"type":"string","maxLength":64},"topic_id":{"type":"string","maxLength":64},"segment_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"from":{"type":"string"},"subject":{"type":"string","minLength":1,"maxLength":998},"reply_to":{"type":"string","maxLength":254},"preview_text":{"type":"string","maxLength":200},"html":{"type":"string","maxLength":1000000},"text":{"type":"string","maxLength":1000000},"design":{"type":"object","properties":{"accent":{"default":"#1a56db","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"background":{"default":"#f4f5f7","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"font":{"default":"sans","type":"string","enum":["sans","serif"]},"blocks":{"minItems":1,"maxItems":100,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"heading"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":300},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"text"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":5000},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"button"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"label":{"type":"string","maxLength":80},"url":{"type":"string","maxLength":2000},"align":{"default":"center","type":"string","enum":["left","center","right"]}},"required":["type","label","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"url":{"type":"string","maxLength":2000},"alt":{"default":"","type":"string","maxLength":200},"link":{"default":"","type":"string","maxLength":2000}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"divider"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"spacer"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"height":{"default":24,"type":"integer","minimum":4,"maximum":120}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"footer"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":1000}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"logo"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"url":{"type":"string","maxLength":2000},"alt":{"default":"","type":"string","maxLength":200},"link":{"default":"","type":"string","maxLength":2000},"width":{"default":140,"type":"integer","minimum":40,"maximum":300},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"columns"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"image_url":{"type":"string","maxLength":2000},"image_alt":{"default":"","type":"string","maxLength":200},"title":{"default":"","type":"string","maxLength":200},"text":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"","type":"string","maxLength":80},"button_url":{"default":"","type":"string","maxLength":2000},"image_side":{"default":"left","type":"string","enum":["left","right"]}},"required":["type","image_url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"product"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"image_url":{"default":"","type":"string","maxLength":2000},"name":{"type":"string","maxLength":200},"description":{"default":"","type":"string","maxLength":500},"price":{"default":"","type":"string","maxLength":60},"url":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"View","type":"string","maxLength":80}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"discount"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"headline":{"default":"Your discount","type":"string","maxLength":200},"code":{"type":"string","maxLength":40},"details":{"default":"","type":"string","maxLength":300}},"required":["type","code"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"social"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"links":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["website","x","facebook","instagram","linkedin","youtube","tiktok","github"]},"url":{"type":"string","maxLength":2000}},"required":["network","url"],"additionalProperties":false}},"align":{"default":"center","type":"string","enum":["left","center","right"]}},"required":["type","links"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"list"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","maxLength":300}},"ordered":{"default":false,"type":"boolean"}},"required":["type","items"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"quote"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":1000},"author":{"default":"","type":"string","maxLength":100}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"signature"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"name":{"type":"string","maxLength":100},"title":{"default":"","type":"string","maxLength":100},"company":{"default":"","type":"string","maxLength":100},"email":{"default":"","type":"string","maxLength":200},"phone":{"default":"","type":"string","maxLength":40},"website":{"default":"","type":"string","maxLength":2000}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"event"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"title":{"type":"string","maxLength":200},"date":{"type":"string","maxLength":100},"time":{"default":"","type":"string","maxLength":100},"place":{"default":"","type":"string","maxLength":200},"url":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"Add to calendar","type":"string","maxLength":80}},"required":["type","title","date"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"rating"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"question":{"type":"string","maxLength":200},"url":{"type":"string","maxLength":2000},"low_label":{"default":"","type":"string","maxLength":40},"high_label":{"default":"","type":"string","maxLength":40}},"required":["type","question","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"table"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"rows":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"columns":{"minItems":1,"maxItems":6,"type":"array","items":{"type":"object","properties":{"header":{"type":"string","maxLength":60},"field":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"format":{"default":"text","type":"string","enum":["text","currency","number","date"]}},"required":["header","field"],"additionalProperties":false}},"currency":{"default":"USD","type":"string","pattern":"^[A-Za-z]{3}$"}},"required":["type","rows","columns"],"additionalProperties":false}]}}},"required":["blocks"],"additionalProperties":false},"ab_test":{"anyOf":[{"type":"object","properties":{"variants":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"object","properties":{"subject":{"type":"string","minLength":1,"maxLength":998},"preview_text":{"type":"string","maxLength":200},"html":{"type":"string","maxLength":1000000},"text":{"type":"string","maxLength":1000000},"design":{"type":"object","properties":{"accent":{"default":"#1a56db","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"background":{"default":"#f4f5f7","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"font":{"default":"sans","type":"string","enum":["sans","serif"]},"blocks":{"minItems":1,"maxItems":100,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"heading"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":300},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"text"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":5000},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"button"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"label":{"type":"string","maxLength":80},"url":{"type":"string","maxLength":2000},"align":{"default":"center","type":"string","enum":["left","center","right"]}},"required":["type","label","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"url":{"type":"string","maxLength":2000},"alt":{"default":"","type":"string","maxLength":200},"link":{"default":"","type":"string","maxLength":2000}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"divider"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"spacer"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"height":{"default":24,"type":"integer","minimum":4,"maximum":120}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"footer"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":1000}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"logo"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"url":{"type":"string","maxLength":2000},"alt":{"default":"","type":"string","maxLength":200},"link":{"default":"","type":"string","maxLength":2000},"width":{"default":140,"type":"integer","minimum":40,"maximum":300},"align":{"default":"left","type":"string","enum":["left","center","right"]}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"columns"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"image_url":{"type":"string","maxLength":2000},"image_alt":{"default":"","type":"string","maxLength":200},"title":{"default":"","type":"string","maxLength":200},"text":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"","type":"string","maxLength":80},"button_url":{"default":"","type":"string","maxLength":2000},"image_side":{"default":"left","type":"string","enum":["left","right"]}},"required":["type","image_url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"product"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"image_url":{"default":"","type":"string","maxLength":2000},"name":{"type":"string","maxLength":200},"description":{"default":"","type":"string","maxLength":500},"price":{"default":"","type":"string","maxLength":60},"url":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"View","type":"string","maxLength":80}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"discount"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"headline":{"default":"Your discount","type":"string","maxLength":200},"code":{"type":"string","maxLength":40},"details":{"default":"","type":"string","maxLength":300}},"required":["type","code"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"social"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"links":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["website","x","facebook","instagram","linkedin","youtube","tiktok","github"]},"url":{"type":"string","maxLength":2000}},"required":["network","url"],"additionalProperties":false}},"align":{"default":"center","type":"string","enum":["left","center","right"]}},"required":["type","links"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"list"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","maxLength":300}},"ordered":{"default":false,"type":"boolean"}},"required":["type","items"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"quote"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"text":{"type":"string","maxLength":1000},"author":{"default":"","type":"string","maxLength":100}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"signature"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"name":{"type":"string","maxLength":100},"title":{"default":"","type":"string","maxLength":100},"company":{"default":"","type":"string","maxLength":100},"email":{"default":"","type":"string","maxLength":200},"phone":{"default":"","type":"string","maxLength":40},"website":{"default":"","type":"string","maxLength":2000}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"event"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"title":{"type":"string","maxLength":200},"date":{"type":"string","maxLength":100},"time":{"default":"","type":"string","maxLength":100},"place":{"default":"","type":"string","maxLength":200},"url":{"default":"","type":"string","maxLength":2000},"button_label":{"default":"Add to calendar","type":"string","maxLength":80}},"required":["type","title","date"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"rating"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"question":{"type":"string","maxLength":200},"url":{"type":"string","maxLength":2000},"low_label":{"default":"","type":"string","maxLength":40},"high_label":{"default":"","type":"string","maxLength":40}},"required":["type","question","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"table"},"when":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.@' =!<>-]*$"},"rows":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"columns":{"minItems":1,"maxItems":6,"type":"array","items":{"type":"object","properties":{"header":{"type":"string","maxLength":60},"field":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"format":{"default":"text","type":"string","enum":["text","currency","number","date"]}},"required":["header","field"],"additionalProperties":false}},"currency":{"default":"USD","type":"string","pattern":"^[A-Za-z]{3}$"}},"required":["type","rows","columns"],"additionalProperties":false}]}}},"required":["blocks"],"additionalProperties":false}},"additionalProperties":false}},"test_percent":{"default":20,"type":"integer","minimum":5,"maximum":50},"wait_hours":{"default":4,"type":"integer","minimum":1,"maximum":72},"winner_by":{"default":"opens","type":"string","enum":["opens","clicks"]}},"required":["variants"],"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"example":{"subject":"October update"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"bcast_Tz8…","object":"broadcast","name":"October update","audience_id":"aud_7Qe2…","topic_id":null,"from":"Acme <news@mail.acme.com>","subject":"October update","status":"draft","status_reason":null,"scheduled_at":null,"sent":0,"skipped":0,"failed":0,"created_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`validation_error`: The broadcast is no longer a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteBroadcast","tags":["Broadcasts"],"summary":"Delete a broadcast","description":"Only a draft or cancelled broadcast.\n\nRequired scope: `broadcasts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The broadcast id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"broadcast","id":"xxx_…","deleted":true}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`validation_error`: The broadcast has been sent or is sending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/broadcasts/{id}/stats":{"get":{"operationId":"getBroadcastStats","tags":["Broadcasts"],"summary":"Get broadcast stats","description":"How a broadcast did: delivered, bounced and complained counts, unique opens and clicks, the links people clicked, and the unsubscribes it caused. Opens and clicks are counted once per recipient and only exist when tracking is on for the sending domain (`tracking` says whether it is). Opens are approximate: some mail apps load images for the reader. For a split test, `ab_test` shows each version’s results from the test slice, the phase (`test`, `waiting` or `final`), and the winner once chosen.\n\nRequired scope: `broadcasts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The broadcast id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"broadcast_stats","broadcast_id":"bcast_Tz8…","status":"sent","tracking":{"opens":true,"clicks":true,"available":true},"totals":{"sent":1180,"delivered":1166,"bounced":14,"complained":1,"failed":0,"suppressed":0,"opened":412,"clicked":97,"unsubscribed":6,"skipped":20},"rates":{"delivered":0.988,"bounced":0.012,"complained":0.0008,"opened":0.353,"clicked":0.083,"unsubscribed":0.005},"top_links":[{"url":"https://acme.com/changelog","clicks":61}],"daily":[{"day":"2026-10-07","opened":380,"clicked":90}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/broadcasts/{id}/links":{"get":{"operationId":"listBroadcastLinks","tags":["Broadcasts"],"summary":"List clicked links","description":"Every link recipients clicked in a broadcast, most clicked first. Each link is counted once per recipient, the same as in the stats (which show only the top ten). Clicks only exist when click tracking is on for the sending domain.\n\nRequired scope: `broadcasts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The broadcast id.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100. Default 20.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from a previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","broadcast_id":"bcast_Tz8…","has_more":false,"data":[{"object":"broadcast_link","url":"https://acme.com/changelog","clicks":61}],"next_cursor":null}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/broadcasts/{id}/duplicate":{"post":{"operationId":"duplicateBroadcast","tags":["Broadcasts"],"summary":"Duplicate a broadcast","description":"Creates a new draft with the same audience, segment, topic, sender, subject and content, named “Copy of …”. Works on a broadcast in any state, so you can resend last month’s update with changes. Nothing is sent until you call send on the copy.\n\nRequired scope: `broadcasts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The broadcast id.","schema":{"type":"string"}}],"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"bcast_Tz8…","object":"broadcast","name":"Copy of October update","audience_id":"aud_7Qe2…","topic_id":null,"from":"Acme <news@mail.acme.com>","subject":"What’s new, {{{FIRST_NAME|there}}}","status":"draft","status_reason":null,"scheduled_at":null,"sent":0,"skipped":0,"failed":0,"created_at":"2026-10-06T15:00:00.000Z"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/broadcasts/{id}/send":{"post":{"operationId":"sendBroadcast","tags":["Broadcasts"],"summary":"Send a broadcast","description":"Starts sending now, or at `scheduled_at`. Contacts who unsubscribed (or are not subscribed to the broadcast’s topic) are skipped, and every message goes through the same checks as any other email: your plan’s allowance, daily limit, verified domain and account review. If a limit is reached the broadcast pauses with the reason; call send again to continue where it stopped, without resending to anyone.\n\nRequired scope: `broadcasts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The broadcast id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"scheduled_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"additionalProperties":false},"example":{"scheduled_at":"2026-10-08T14:00:00Z"}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"example":{"id":"bcast_Tz8…","object":"broadcast","name":"October update","audience_id":"aud_7Qe2…","topic_id":null,"from":"Acme <news@mail.acme.com>","subject":"What’s new, {{{FIRST_NAME|there}}}","status":"scheduled","status_reason":null,"scheduled_at":"2026-10-08T14:00:00.000Z","sent":0,"skipped":0,"failed":0,"created_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`not_schedulable`: The broadcast is already sending, sent or cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/broadcasts/{id}/cancel":{"post":{"operationId":"cancelBroadcast","tags":["Broadcasts"],"summary":"Cancel a broadcast","description":"Stops a scheduled, sending or paused broadcast. Messages already sent are not recalled.\n\nRequired scope: `broadcasts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The broadcast id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"bcast_Tz8…","object":"broadcast","name":"October update","audience_id":"aud_7Qe2…","topic_id":null,"from":"Acme <news@mail.acme.com>","subject":"What’s new, {{{FIRST_NAME|there}}}","status":"cancelled","status_reason":null,"scheduled_at":null,"sent":0,"skipped":0,"failed":0,"created_at":"2026-10-06T15:00:00.000Z"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`not_schedulable`: The broadcast is a draft or already finished.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/inbound":{"get":{"operationId":"getInboundAddress","tags":["Inbound"],"summary":"Get the receiving address","description":"Every project has its own address. Mail to any name at that domain (support@, orders@, anything) is received, scanned for viruses and spam, and stored for your retention period (30 days by default). The first call creates the address; it stays the same after that.\n\nRequired scope: `inbound:manage`.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"inbound_address","domain":"k3x9m2qf7a.inbound.sendsend.email","example":"support@k3x9m2qf7a.inbound.sendsend.email","enabled":true}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/received-emails":{"get":{"operationId":"listReceivedEmails","tags":["Inbound"],"summary":"List received emails","description":"Newest first, without bodies. Spam-flagged mail is included with `spam: true`, and does not trigger an `email.received` webhook.\n\nRequired scope: `inbound:manage`.","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100. Default 20.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from a previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","has_more":false,"data":[{"id":"rcv_Qw3…","object":"received_email","from":"Maria <maria@example.org>","to":["support@k3x9m2qf7a.inbound.sendsend.email"],"cc":[],"reply_to":null,"subject":"Question about my order","message_id":"<abc@example.org>","in_reply_to":null,"spam":false,"size":4821,"created_at":"2026-10-06T15:04:05.000Z","attachment_count":1}],"next_cursor":null}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/received-emails/{id}":{"get":{"operationId":"getReceivedEmail","tags":["Inbound"],"summary":"Retrieve a received email","description":"Includes the text and HTML bodies, the headers and the attachment list. The content comes from the sender, so treat the HTML as untrusted: never render it in your own page without sandboxing.\n\nRequired scope: `inbound:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The received email id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"rcv_Qw3…","object":"received_email","from":"Maria <maria@example.org>","to":["support@k3x9m2qf7a.inbound.sendsend.email"],"cc":[],"reply_to":null,"subject":"Question about my order","message_id":"<abc@example.org>","in_reply_to":null,"spam":false,"size":4821,"created_at":"2026-10-06T15:04:05.000Z","attachments":[{"id":"0","filename":"receipt.pdf","content_type":"application/pdf","size":20480,"content_id":null,"inline":false,"available":true}],"text":"Hello…","html":"<p>Hello…</p>","headers":{"subject":"Question about my order"}}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteReceivedEmail","tags":["Inbound"],"summary":"Delete a received email","description":"Removes the message and its attachments now, rather than waiting for the retention period.\n\nRequired scope: `inbound:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The received email id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"received_email","id":"rcv_Qw3…","deleted":true}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/received-emails/{id}/raw":{"get":{"operationId":"getReceivedEmailRaw","tags":["Inbound"],"summary":"Download the original message","description":"The message exactly as it arrived, as an `.eml` file. Kept for messages up to 15 MB.\n\nRequired scope: `inbound:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The received email id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/received-emails/{id}/attachments":{"get":{"operationId":"listReceivedAttachments","tags":["Inbound"],"summary":"List attachments","description":"Attachments on a received email. `available` is false for files over 10 MB, which are listed but not kept.\n\nRequired scope: `inbound:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The received email id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"0","filename":"receipt.pdf","content_type":"application/pdf","size":20480,"content_id":null,"inline":false,"available":true}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/received-emails/{id}/attachments/{attachment}":{"get":{"operationId":"getReceivedAttachment","tags":["Inbound"],"summary":"Download an attachment","description":"The file itself, always as a download. Scan files before opening them: anyone can send them.\n\nRequired scope: `inbound:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The received email id.","schema":{"type":"string"}},{"name":"attachment","in":"path","required":true,"description":"The attachment id from the list (0, 1, 2…).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/segments":{"post":{"operationId":"createSegment","tags":["Segments"],"summary":"Create a segment","description":"A saved filter over one audience's contacts. A broadcast can be sent to a segment instead of the whole audience, and the people it matches are worked out when each batch is sent, so late changes to a contact count. Each rule has a `field` (`email`, `first_name`, `last_name`, `status`, `created_at`, `property` with a `key`, or `topic` with a `topic_id`), an `op` and usually a `value`. Text operators: `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `is_set`, `is_not_set` (case-insensitive). Number properties also take `gt`, `gte`, `lt`, `lte`. `status` is `subscribed` or `unsubscribed`. `created_at` takes `before` or `after` with a date, or `within_days` or `older_than_days` with a number. `topic` takes `subscribed` or `not_subscribed`. `match` is `all` (every rule) or `any` (at least one). Up to 10 rules.\n\nRequired scope: `contacts:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"audience_id":{"type":"string","maxLength":64},"name":{"type":"string","minLength":1,"maxLength":100},"match":{"default":"all","type":"string","enum":["all","any"]},"rules":{"minItems":1,"maxItems":10,"type":"array","items":{"oneOf":[{"type":"object","properties":{"field":{"type":"string","enum":["email","first_name","last_name"]},"op":{"type":"string","enum":["equals","not_equals","contains","not_contains","starts_with","ends_with","is_set","is_not_set"]},"value":{"type":"string","maxLength":200}},"required":["field","op"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","const":"status"},"op":{"type":"string","const":"is"},"value":{"type":"string","enum":["subscribed","unsubscribed","pending"]}},"required":["field","op","value"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","const":"created_at"},"op":{"type":"string","enum":["before","after","within_days","older_than_days"]},"value":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"integer","minimum":1,"maximum":3650}]}},"required":["field","op","value"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","const":"property"},"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"op":{"type":"string","enum":["equals","not_equals","contains","not_contains","starts_with","ends_with","is_set","is_not_set","gt","gte","lt","lte"]},"value":{"anyOf":[{"type":"string","maxLength":200},{"type":"number"}]}},"required":["field","key","op"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","const":"topic"},"topic_id":{"type":"string","maxLength":64},"op":{"type":"string","enum":["subscribed","not_subscribed"]}},"required":["field","topic_id","op"],"additionalProperties":false}]}}},"required":["audience_id","name","rules"],"additionalProperties":false},"example":{"audience_id":"aud_7Qe2…","name":"Pro customers","match":"all","rules":[{"field":"property","key":"plan","op":"equals","value":"pro"},{"field":"status","op":"is","value":"subscribed"}]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"seg_Pm4…","object":"segment","audience_id":"aud_7Qe2…","name":"Pro customers","match":"all","rules":[{"field":"property","key":"plan","op":"equals","value":"pro"},{"field":"status","op":"is","value":"subscribed"}],"created_at":"2026-10-06T15:00:00.000Z","updated_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listSegments","tags":["Segments"],"summary":"List segments","description":"All segments in the project, or those of one audience.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"audience_id","in":"query","required":false,"description":"Only segments of this audience.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"seg_Pm4…","object":"segment","audience_id":"aud_7Qe2…","name":"Pro customers","match":"all","rules":[{"field":"property","key":"plan","op":"equals","value":"pro"},{"field":"status","op":"is","value":"subscribed"}],"created_at":"2026-10-06T15:00:00.000Z","updated_at":"2026-10-06T15:00:00.000Z"}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/segments/preview":{"post":{"operationId":"previewSegment","tags":["Segments"],"summary":"Preview a segment","description":"Try rules out before you save them: how many contacts match, and up to five of their addresses. Nothing is stored.\n\nRequired scope: `contacts:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"audience_id":{"type":"string","maxLength":64},"match":{"default":"all","type":"string","enum":["all","any"]},"rules":{"minItems":1,"maxItems":10,"type":"array","items":{"oneOf":[{"type":"object","properties":{"field":{"type":"string","enum":["email","first_name","last_name"]},"op":{"type":"string","enum":["equals","not_equals","contains","not_contains","starts_with","ends_with","is_set","is_not_set"]},"value":{"type":"string","maxLength":200}},"required":["field","op"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","const":"status"},"op":{"type":"string","const":"is"},"value":{"type":"string","enum":["subscribed","unsubscribed","pending"]}},"required":["field","op","value"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","const":"created_at"},"op":{"type":"string","enum":["before","after","within_days","older_than_days"]},"value":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"integer","minimum":1,"maximum":3650}]}},"required":["field","op","value"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","const":"property"},"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"op":{"type":"string","enum":["equals","not_equals","contains","not_contains","starts_with","ends_with","is_set","is_not_set","gt","gte","lt","lte"]},"value":{"anyOf":[{"type":"string","maxLength":200},{"type":"number"}]}},"required":["field","key","op"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","const":"topic"},"topic_id":{"type":"string","maxLength":64},"op":{"type":"string","enum":["subscribed","not_subscribed"]}},"required":["field","topic_id","op"],"additionalProperties":false}]}}},"required":["audience_id","rules"],"additionalProperties":false},"example":{"audience_id":"aud_7Qe2…","match":"all","rules":[{"field":"property","key":"plan","op":"equals","value":"pro"},{"field":"status","op":"is","value":"subscribed"}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"segment_preview","count":184,"sample":["maria@example.com","li@example.com"]}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/segments/{id}":{"get":{"operationId":"getSegment","tags":["Segments"],"summary":"Retrieve a segment","description":"Includes how many contacts match right now.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The segment id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"seg_Pm4…","object":"segment","audience_id":"aud_7Qe2…","name":"Pro customers","match":"all","rules":[{"field":"property","key":"plan","op":"equals","value":"pro"},{"field":"status","op":"is","value":"subscribed"}],"created_at":"2026-10-06T15:00:00.000Z","updated_at":"2026-10-06T15:00:00.000Z","contacts":184}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"patch":{"operationId":"updateSegment","tags":["Segments"],"summary":"Update a segment","description":"Rename it, or change its rules or `match`. Rules replace the old ones. Each rule has a `field` (`email`, `first_name`, `last_name`, `status`, `created_at`, `property` with a `key`, or `topic` with a `topic_id`), an `op` and usually a `value`. Text operators: `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `is_set`, `is_not_set` (case-insensitive). Number properties also take `gt`, `gte`, `lt`, `lte`. `status` is `subscribed` or `unsubscribed`. `created_at` takes `before` or `after` with a date, or `within_days` or `older_than_days` with a number. `topic` takes `subscribed` or `not_subscribed`. `match` is `all` (every rule) or `any` (at least one). Up to 10 rules.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The segment id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"match":{"type":"string","enum":["all","any"]},"rules":{"minItems":1,"maxItems":10,"type":"array","items":{"oneOf":[{"type":"object","properties":{"field":{"type":"string","enum":["email","first_name","last_name"]},"op":{"type":"string","enum":["equals","not_equals","contains","not_contains","starts_with","ends_with","is_set","is_not_set"]},"value":{"type":"string","maxLength":200}},"required":["field","op"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","const":"status"},"op":{"type":"string","const":"is"},"value":{"type":"string","enum":["subscribed","unsubscribed","pending"]}},"required":["field","op","value"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","const":"created_at"},"op":{"type":"string","enum":["before","after","within_days","older_than_days"]},"value":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"integer","minimum":1,"maximum":3650}]}},"required":["field","op","value"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","const":"property"},"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"op":{"type":"string","enum":["equals","not_equals","contains","not_contains","starts_with","ends_with","is_set","is_not_set","gt","gte","lt","lte"]},"value":{"anyOf":[{"type":"string","maxLength":200},{"type":"number"}]}},"required":["field","key","op"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","const":"topic"},"topic_id":{"type":"string","maxLength":64},"op":{"type":"string","enum":["subscribed","not_subscribed"]}},"required":["field","topic_id","op"],"additionalProperties":false}]}}},"additionalProperties":false},"example":{"name":"Pro and trial"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"seg_Pm4…","object":"segment","audience_id":"aud_7Qe2…","name":"Pro and trial","match":"all","rules":[{"field":"property","key":"plan","op":"equals","value":"pro"},{"field":"status","op":"is","value":"subscribed"}],"created_at":"2026-10-06T15:00:00.000Z","updated_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteSegment","tags":["Segments"],"summary":"Delete a segment","description":"Refused while a scheduled, sending or paused broadcast uses it. Finished broadcasts keep their history without the segment.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The segment id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"segment","id":"xxx_…","deleted":true}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`validation_error`: A broadcast is still using it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/segments/{id}/contacts":{"get":{"operationId":"listSegmentContacts","tags":["Segments"],"summary":"List a segment’s contacts","description":"The contacts that match now, with a total and cursor pagination.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The segment id.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100. Default 20.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from a previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","total":184,"has_more":true,"data":[{"id":"con_Hk3v…","object":"contact","audience_id":"aud_7Qe2…","email":"maria@example.com","first_name":"Maria","last_name":null,"unsubscribed":false,"properties":{"plan":"pro"},"created_at":"2026-10-06T15:00:00.000Z","updated_at":"2026-10-06T15:00:00.000Z"}],"next_cursor":"con_Hk3v…"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/inbound/domains":{"post":{"operationId":"createInboundDomain","tags":["Inbound"],"summary":"Receive on your own domain","description":"Start receiving mail at a domain you control, such as `support.acme.com`, instead of the project address. Publish the two records in the response: an MX record pointing at us, and a TXT record that proves you own the domain. We check them every minute, and for up to 72 hours, and the domain turns `active` once both are right. The MX must be the only MX at that name: a second one would send some of your mail elsewhere.\n\n**Use a subdomain.** Pointing a root domain such as `acme.com` here sends all of its mail to SendSend and none to the mailboxes it has now. The response includes a `warning` for root domains. A project can receive on up to 5 domains.\n\nRequired scope: `inbound:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"domain":{"type":"string","maxLength":253}},"required":["domain"],"additionalProperties":false},"example":{"domain":"support.acme.com"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"ind_Wq7…","object":"inbound_domain","domain":"support.acme.com","status":"pending","mx_ok":false,"txt_ok":false,"records":[{"purpose":"mx","type":"MX","name":"support.acme.com","value":"inbound-smtp.us-east-2.amazonaws.com","priority":10,"status":"missing"},{"purpose":"verification","type":"TXT","name":"_sendsend-inbound.support.acme.com","value":"sendsend-verify=k3x…","status":"missing"}],"last_checked_at":null,"verified_at":null,"created_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`domain_already_registered`: Another project already has this domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listInboundDomains","tags":["Inbound"],"summary":"List inbound domains","description":"The domains this project receives on, and whether each one’s DNS is in place.\n\nRequired scope: `inbound:manage`.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"ind_Wq7…","object":"inbound_domain","domain":"support.acme.com","status":"pending","mx_ok":false,"txt_ok":false,"records":[{"purpose":"mx","type":"MX","name":"support.acme.com","value":"inbound-smtp.us-east-2.amazonaws.com","priority":10,"status":"missing"},{"purpose":"verification","type":"TXT","name":"_sendsend-inbound.support.acme.com","value":"sendsend-verify=k3x…","status":"missing"}],"last_checked_at":null,"verified_at":null,"created_at":"2026-10-06T15:00:00.000Z"}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/inbound/domains/{id}":{"get":{"operationId":"getInboundDomain","tags":["Inbound"],"summary":"Retrieve an inbound domain","description":"One domain, with the state of each record.\n\nRequired scope: `inbound:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The inbound domain id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"ind_Wq7…","object":"inbound_domain","domain":"support.acme.com","status":"pending","mx_ok":false,"txt_ok":false,"records":[{"purpose":"mx","type":"MX","name":"support.acme.com","value":"inbound-smtp.us-east-2.amazonaws.com","priority":10,"status":"missing"},{"purpose":"verification","type":"TXT","name":"_sendsend-inbound.support.acme.com","value":"sendsend-verify=k3x…","status":"missing"}],"last_checked_at":null,"verified_at":null,"created_at":"2026-10-06T15:00:00.000Z"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteInboundDomain","tags":["Inbound"],"summary":"Stop receiving on a domain","description":"Closes receiving for the domain straight away. Remove the MX record too, or mail sent to it will bounce. Mail already received is kept until its retention period ends.\n\nRequired scope: `inbound:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The inbound domain id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"inbound_domain","id":"ind_Wq7…","deleted":true}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/inbound/domains/{id}/verify":{"post":{"operationId":"verifyInboundDomain","tags":["Inbound"],"summary":"Check an inbound domain now","description":"Looks the records up immediately instead of waiting for the next automatic check. A domain that gave up after 72 hours starts waiting again.\n\nRequired scope: `inbound:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The inbound domain id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"ind_Wq7…","object":"inbound_domain","domain":"support.acme.com","status":"active","mx_ok":true,"txt_ok":true,"records":[{"purpose":"mx","type":"MX","name":"support.acme.com","value":"inbound-smtp.us-east-2.amazonaws.com","priority":10,"status":"missing"},{"purpose":"verification","type":"TXT","name":"_sendsend-inbound.support.acme.com","value":"sendsend-verify=k3x…","status":"missing"}],"last_checked_at":null,"verified_at":null,"created_at":"2026-10-06T15:00:00.000Z"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/forms":{"post":{"operationId":"createForm","tags":["Forms"],"summary":"Create a signup form","description":"A form that adds people to an audience. Each form has a hosted page at its `url`, which you can link to or embed in a frame, and the same address accepts a plain HTML form `POST` from your own site. For JavaScript, post JSON to `https://api.sendsend.email/public/forms/{id}/subscribe` with `{ \"email\": \"…\", \"first_name\": \"…\" }`; it allows requests from any site.\n\nWith `double_opt_in` (the default) a new person is held as pending, we email them a confirmation link from `from`, and they are only subscribed when they press the button in it. Pending contacts are never sent a broadcast. Anyone who unsubscribed before must confirm again, even on a form without double opt-in, so nobody can be put back on a list by someone else typing their address. The response never says whether an address was already on the list. Signups are rate limited, and we send at most one confirmation to an address every ten minutes.\n\nRequired scope: `contacts:manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"audience_id":{"type":"string","maxLength":64},"name":{"type":"string","minLength":1,"maxLength":100},"title":{"type":"string","maxLength":120},"double_opt_in":{"default":true,"type":"boolean"},"from":{"type":"string"},"confirm_subject":{"type":"string","minLength":1,"maxLength":200},"success_url":{"type":"string","maxLength":2000},"confirmed_url":{"type":"string","maxLength":2000},"topic_ids":{"default":[],"maxItems":50,"type":"array","items":{"type":"string","maxLength":64}},"collect_name":{"default":false,"type":"boolean"},"active":{"default":true,"type":"boolean"}},"required":["audience_id","name"],"additionalProperties":false},"example":{"audience_id":"aud_7Qe2…","name":"Footer signup","from":"Acme <news@mail.acme.com>","confirmed_url":"https://acme.com/welcome"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"frm_Bn6…","object":"form","audience_id":"aud_7Qe2…","name":"Footer signup","title":"Join the newsletter","double_opt_in":true,"from":"Acme <news@mail.acme.com>","confirm_subject":null,"success_url":null,"confirmed_url":"https://acme.com/welcome","topic_ids":[],"collect_name":false,"active":true,"url":"https://api.sendsend.email/f/frm_Bn6…","created_at":"2026-10-06T15:00:00.000Z","updated_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"listForms","tags":["Forms"],"summary":"List signup forms","description":"All forms in the project, or those of one audience.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"audience_id","in":"query","required":false,"description":"Only forms of this audience.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"list","data":[{"id":"frm_Bn6…","object":"form","audience_id":"aud_7Qe2…","name":"Footer signup","title":"Join the newsletter","double_opt_in":true,"from":"Acme <news@mail.acme.com>","confirm_subject":null,"success_url":null,"confirmed_url":"https://acme.com/welcome","topic_ids":[],"collect_name":false,"active":true,"url":"https://api.sendsend.email/f/frm_Bn6…","created_at":"2026-10-06T15:00:00.000Z","updated_at":"2026-10-06T15:00:00.000Z"}]}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/forms/{id}":{"get":{"operationId":"getForm","tags":["Forms"],"summary":"Retrieve a signup form","description":"One form, with the address of its hosted page.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The form id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"frm_Bn6…","object":"form","audience_id":"aud_7Qe2…","name":"Footer signup","title":"Join the newsletter","double_opt_in":true,"from":"Acme <news@mail.acme.com>","confirm_subject":null,"success_url":null,"confirmed_url":"https://acme.com/welcome","topic_ids":[],"collect_name":false,"active":true,"url":"https://api.sendsend.email/f/frm_Bn6…","created_at":"2026-10-06T15:00:00.000Z","updated_at":"2026-10-06T15:00:00.000Z"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"patch":{"operationId":"updateForm","tags":["Forms"],"summary":"Update a signup form","description":"Change any setting. Set `active` to false to stop accepting signups without deleting the form. Send `null` to clear the title, confirmation subject or a redirect.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The form id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"title":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"double_opt_in":{"type":"boolean"},"from":{"type":["string","null"]},"confirm_subject":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"success_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"confirmed_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"topic_ids":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":64}},"collect_name":{"type":"boolean"},"active":{"type":"boolean"}},"additionalProperties":false},"example":{"collect_name":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"frm_Bn6…","object":"form","audience_id":"aud_7Qe2…","name":"Footer signup","title":"Join the newsletter","double_opt_in":true,"from":"Acme <news@mail.acme.com>","confirm_subject":null,"success_url":null,"confirmed_url":"https://acme.com/welcome","topic_ids":[],"collect_name":true,"active":true,"url":"https://api.sendsend.email/f/frm_Bn6…","created_at":"2026-10-06T15:00:00.000Z","updated_at":"2026-10-06T15:00:00.000Z"}}}},"400":{"description":"`validation_error`: The request body or parameters are invalid. The message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteForm","tags":["Forms"],"summary":"Delete a signup form","description":"The form stops working at once. Contacts it already added stay in the audience.\n\nRequired scope: `contacts:manage`.","parameters":[{"name":"id","in":"path","required":true,"description":"The form id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"object":"form","id":"xxx_…","deleted":true}}}},"401":{"description":"`unauthorized`: The API key is missing, invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: The key does not have the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No such resource in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"ss_live_… or ss_test_… project API key."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"details":{"type":"object"}},"required":["code","message","request_id"]}},"required":["error"]}}}}