{"openapi":"3.1.0","info":{"title":"SendHQ API","version":"2026-09-07","description":"Send and receive expected email, manage verified domains and hosted templates, and inspect delivery outcomes. Stable major versions use URL paths such as /api/v1. Additive changes remain within the current major; breaking changes use a new major path. See /docs/versioning for the deprecation and sunset policy.","x-versioning-policy":{"strategy":"URL path major versioning","currentMajor":"v1","additiveChanges":"Backward-compatible fields and operations may be added within v1.","breakingChanges":"Breaking changes require a new major URL path and migration documentation.","deprecationDocumentation":"https://sendhq.cc/docs/versioning","minimumSunsetDays":90}},"servers":[{"url":"https://sendhq.cc/api/v1"}],"tags":[{"name":"Emails and threads","description":"Send, retrieve, search, reply, and inspect delivery events."},{"name":"Labels and filing rules","description":"Organize sent and received mail into folders automatically or by hand."},{"name":"Drafts and attachments","description":"Build composer flows with private attachment storage."},{"name":"Hosted templates","description":"Draft, render, test, version, publish, and send reusable content."},{"name":"Domains","description":"Provision sender identities and understand DNS verification state."},{"name":"Inbound email","description":"Create addresses and work with received conversations."},{"name":"Deliverability","description":"Inspect events, reputation outcomes, and blocked recipients."},{"name":"Webhooks","description":"Receive signed, retried email events (sent, delivered, delayed, bounced, complained, failed, received) at your own endpoints."},{"name":"Campaigns","description":"Store contacts with their consent basis, tags, and custom fields, organize them into lists with hosted double opt-in signup forms, welcome emails, and public newsletter sites, target segments, import and export CSV files, and send, test, and schedule broadcasts with merge tags, per-list one-click unsubscribe, pre-send checks, bot-filtered open and click reports, and per-recipient outcomes."},{"name":"Account and billing","description":"Read account usage, analytics, and key metadata with an API key; billing changes and key creation or revocation require a dashboard session."}],"paths":{"/emails":{"post":{"operationId":"post_emails","tags":["Emails and threads"],"summary":"Send one email","description":"Send transactional HTML, text, or hosted-template content from a verified workspace domain. Direct sends may set message_class to marketing when enabled for the verified sender domain. Marketing adds managed unsubscribe headers unless a configured first-party integration supplies its own visible HTTPS one-click URL.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Stable for one logical request. Reuse with an identical JSON body; changed bodies return 409."}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"providerMessageId":{"type":"string"},"threadId":{"type":"string"}},"required":["id","providerMessageId","threadId"],"additionalProperties":false},"example":{"id":"em_…","providerMessageId":"provider-id","threadId":"em_…"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEmailRequest"},"example":{"from":"Acme <hello@example.com>","to":["customer@example.net"],"subject":"Welcome aboard","html":"<h1>Welcome</h1><p>Your workspace is ready.</p>","text":"Welcome. Your workspace is ready."}}}}},"get":{"operationId":"get_emails","tags":["Emails and threads"],"summary":"List sent and received email","description":"Newest-first list with filters. `query` searches subjects, bodies, participants, and attachment filenames. `label`, `domain`, and `category` accept one value or a comma-separated list (matches any); labels may be IDs or names. `outcome` filters sent mail to `bounced`, `complained`, `failed`, or `rejected` (comma-separated, matches any). `archived=false` returns the Inbox view for received mail. Received mail is classified as `primary`, `updates` (newsletters, bulk, and automated mail), or `spam`, and flagged `important`; spam is excluded unless `category=spam` or `include_spam=true`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["in","out"]}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","succeeded","failed"]}},{"name":"outcome","in":"query","required":false,"schema":{"type":"string"}},{"name":"domain","in":"query","required":false,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"label","in":"query","required":false,"schema":{"type":"string"}},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"important","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"include_spam","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}},{"name":"unread","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"query","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}},"count":{"type":"integer"}},"required":["data","count"],"additionalProperties":false},"example":{"data":[],"count":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/emails/batch":{"post":{"operationId":"post_emails_batch","tags":["Emails and threads"],"summary":"Send up to 100 individualized messages","description":"Send up to 100 individualized messages","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Stable for one logical request. Reuse with an identical JSON body; changed bodies return 409."}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"ok":{"type":"boolean"},"id":{"type":"string"}},"required":["index","ok","id"],"additionalProperties":false}},"count":{"type":"integer"},"successful":{"type":"integer"},"failed":{"type":"integer"}},"required":["data","count","successful","failed"],"additionalProperties":false},"example":{"data":[{"index":0,"ok":true,"id":"em_…"}],"count":1,"successful":1,"failed":0}}}},"207":{"description":"Successful response with partial outcomes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"ok":{"type":"boolean"},"id":{"type":"string"}},"required":["index","ok","id"],"additionalProperties":false}},"count":{"type":"integer"},"successful":{"type":"integer"},"failed":{"type":"integer"}},"required":["data","count","successful","failed"],"additionalProperties":false},"example":{"data":[{"index":0,"ok":true,"id":"em_…"}],"count":1,"successful":1,"failed":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emails"],"properties":{"emails":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/SendEmailRequest"}}},"additionalProperties":false},"example":{"emails":[{"from":"Acme <hello@example.com>","to":["customer@example.net"],"subject":"Welcome aboard","html":"<h1>Welcome</h1><p>Your workspace is ready.</p>","text":"Welcome. Your workspace is ready."}]}}}}}},"/emails/{id}":{"get":{"operationId":"get_emails_id","tags":["Emails and threads"],"summary":"Retrieve an email and its attachments","description":"Retrieve an email and its attachments","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"direction":{"type":"string"},"status":{"type":"string"},"attachments":{"type":"array","items":{}}},"required":["id","direction","status","attachments"],"additionalProperties":false},"example":{"id":"em_…","direction":"out","status":"sent","attachments":[]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patch_emails_id","tags":["Emails and threads"],"summary":"Update read, archive, spam, category, or importance","description":"Set `read`, `archived`, `category` (`primary`, `updates`, or `spam` — received mail only), and `important`. Changing `category` or `important` teaches SendHQ about the sender: reported spam sends that sender's future mail to spam, `Not spam` overrides automatic spam checks for them, and importance sticks to the sender. Pass `learn: false` to change only this message.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"readAt":{"type":"string","format":"date-time"},"archivedAt":{},"category":{"type":"string"},"important":{"type":"boolean"},"classification":{"type":"string"}},"required":["id","readAt","archivedAt","category","important","classification"],"additionalProperties":false},"example":{"id":"em_…","readAt":"2026-08-23T12:00:00.000Z","archivedAt":null,"category":"spam","important":false,"classification":"you moved it here"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"}},"required":["category"],"additionalProperties":false},"example":{"category":"spam"}}}}},"delete":{"operationId":"delete_emails_id","tags":["Emails and threads"],"summary":"Delete a retained email","description":"Delete a retained email","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/emails/{id}/labels":{"post":{"operationId":"post_emails_id_labels","tags":["Labels and filing rules"],"summary":"Add or remove labels on an email","description":"Add and remove labels by name or lbl_ ID. Unknown names in `add` are created unless `create` is false. An email may carry at most 10 labels.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"}},"required":["id","name","color"],"additionalProperties":false}}},"required":["id","labels"],"additionalProperties":false},"example":{"id":"em_…","labels":[{"id":"lbl_…","name":"Billing","color":"#188038"}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"add":{"type":"array","items":{"type":"string"}},"remove":{"type":"array","items":{"type":"string"}}},"required":["add","remove"],"additionalProperties":false},"example":{"add":["Billing"],"remove":["Support"]}}}}}},"/emails/{id}/events":{"get":{"operationId":"get_emails_id_events","tags":["Emails and threads"],"summary":"List delivery events for an email","description":"List delivery events for an email","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}},"count":{"type":"integer"}},"required":["data","count"],"additionalProperties":false},"example":{"data":[],"count":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/threads/{id}":{"get":{"operationId":"get_threads_id","tags":["Emails and threads"],"summary":"Retrieve a conversation chronologically","description":"Retrieve a conversation chronologically","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"data":{"type":"array","items":{}},"count":{"type":"integer"}},"required":["id","data","count"],"additionalProperties":false},"example":{"id":"em_…","data":[],"count":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/labels":{"get":{"operationId":"get_labels","tags":["Labels and filing rules"],"summary":"List labels with message counts and filing rules","description":"List labels with message counts and filing rules","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}},"count":{"type":"integer"},"mailbox":{"type":"object","properties":{"inboxUnread":{"type":"integer"},"updatesUnread":{"type":"integer"},"spamTotal":{"type":"integer"},"importantUnread":{"type":"integer"},"resortPending":{"type":"integer"}},"required":["inboxUnread","updatesUnread","spamTotal","importantUnread","resortPending"],"additionalProperties":false}},"required":["data","count","mailbox"],"additionalProperties":false},"example":{"data":[],"count":0,"mailbox":{"inboxUnread":0,"updatesUnread":0,"spamTotal":0,"importantUnread":0,"resortPending":0}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"post_labels","tags":["Labels and filing rules"],"summary":"Create a label, optionally with auto-filing rules","description":"Create a folder-style label. Set `skip_inbox: true` to make it a bucket: received mail that gets this label (from a rule, from a reply to a conversation sent with the label, or added by hand) is archived so it appears only in the label, never the Inbox. Optional `rules` file new sent or received mail automatically: every condition set on a rule must match (inbox_id, direction, and case-insensitive from/to/subject substrings). Set `apply_to_existing` to file retained mail too.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"skipInbox":{"type":"boolean"},"totalCount":{"type":"integer"},"unreadCount":{"type":"integer"},"rules":{"type":"array","items":{}}},"required":["id","name","color","skipInbox","totalCount","unreadCount","rules"],"additionalProperties":false},"example":{"id":"lbl_…","name":"Agent/Orders","color":"#188038","skipInbox":true,"totalCount":0,"unreadCount":0,"rules":[]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"skip_inbox":{"type":"boolean"},"rules":{"type":"array","items":{"type":"object","properties":{"inbox_id":{"type":"string"}},"required":["inbox_id"],"additionalProperties":false}},"apply_to_existing":{"type":"boolean"}},"required":["name","color","skip_inbox","rules","apply_to_existing"],"additionalProperties":false},"example":{"name":"Agent/Orders","color":"#188038","skip_inbox":true,"rules":[{"inbox_id":"inb_…"}],"apply_to_existing":true}}}}}},"/labels/{id}":{"get":{"operationId":"get_labels_id","tags":["Labels and filing rules"],"summary":"Retrieve a label by ID or name","description":"Retrieve a label by ID or name","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"skipInbox":{"type":"boolean"},"totalCount":{"type":"integer"},"unreadCount":{"type":"integer"},"rules":{"type":"array","items":{}}},"required":["id","name","color","skipInbox","totalCount","unreadCount","rules"],"additionalProperties":false},"example":{"id":"lbl_…","name":"Billing","color":"#188038","skipInbox":false,"totalCount":0,"unreadCount":0,"rules":[]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patch_labels_id","tags":["Labels and filing rules"],"summary":"Rename, recolor, or turn a label into a bucket","description":"Change `name`, `color`, or `skip_inbox`. Turning `skip_inbox` on also archives received mail already in the label unless `apply_to_existing` is false.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"skipInbox":{"type":"boolean"}},"required":["id","name","color","skipInbox"],"additionalProperties":false},"example":{"id":"lbl_…","name":"Finance/Billing","color":"#1a73e8","skipInbox":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"skip_inbox":{"type":"boolean"}},"required":["name","color","skip_inbox"],"additionalProperties":false},"example":{"name":"Finance/Billing","color":"#1a73e8","skip_inbox":true}}}}},"delete":{"operationId":"delete_labels_id","tags":["Labels and filing rules"],"summary":"Delete a label without deleting its email","description":"Delete a label without deleting its email","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/labels/{id}/rules":{"post":{"operationId":"post_labels_id_rules","tags":["Labels and filing rules"],"summary":"Add an auto-filing rule to a label","description":"Add an auto-filing rule to a label","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"labelId":{"type":"string"},"direction":{"type":"string"},"inboxId":{},"from":{"type":"string"},"to":{},"subject":{"type":"string"},"skipInbox":{"type":"boolean"}},"required":["id","labelId","direction","inboxId","from","to","subject","skipInbox"],"additionalProperties":false},"example":{"id":"lrule_…","labelId":"lbl_…","direction":"in","inboxId":null,"from":"@stripe.com","to":null,"subject":"invoice","skipInbox":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"direction":{"type":"string"},"from":{"type":"string"},"subject":{"type":"string"},"skip_inbox":{"type":"boolean"},"apply_to_existing":{"type":"boolean"}},"required":["direction","from","subject","skip_inbox","apply_to_existing"],"additionalProperties":false},"example":{"direction":"in","from":"@stripe.com","subject":"invoice","skip_inbox":true,"apply_to_existing":false}}}}}},"/labels/{id}/rules/{rule_id}":{"delete":{"operationId":"delete_labels_id_rules_rule_id","tags":["Labels and filing rules"],"summary":"Delete an auto-filing rule","description":"Delete an auto-filing rule","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"rule_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts":{"post":{"operationId":"post_drafts","tags":["Drafts and attachments"],"summary":"Create a composer draft","description":"Create a composer draft","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"attachments":{"type":"array","items":{}}},"required":["id","attachments"],"additionalProperties":false},"example":{"id":"dr_…","attachments":[]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","format":"email"},"to":{"type":"array","items":{"type":"string","format":"email"}},"subject":{"type":"string"}},"required":["from","to","subject"],"additionalProperties":false},"example":{"from":"hello@example.com","to":["customer@example.net"],"subject":"Hello"}}}}},"get":{"operationId":"get_drafts","tags":["Drafts and attachments"],"summary":"List composer drafts","description":"List composer drafts","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}},"count":{"type":"integer"}},"required":["data","count"],"additionalProperties":false},"example":{"data":[],"count":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts/{id}":{"get":{"operationId":"get_drafts_id","tags":["Drafts and attachments"],"summary":"Retrieve a draft and attachments","description":"Retrieve a draft and attachments","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"attachments":{"type":"array","items":{}}},"required":["id","attachments"],"additionalProperties":false},"example":{"id":"dr_…","attachments":[]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"put_drafts_id","tags":["Drafts and attachments"],"summary":"Replace draft content","description":"Replace draft content","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false},"example":{"id":"dr_…"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","format":"email"},"to":{"type":"array","items":{"type":"string","format":"email"}},"subject":{"type":"string"},"text":{"type":"string"}},"required":["from","to","subject","text"],"additionalProperties":false},"example":{"from":"hello@example.com","to":["customer@example.net"],"subject":"Updated subject","text":"Updated body"}}}}},"delete":{"operationId":"delete_drafts_id","tags":["Drafts and attachments"],"summary":"Discard a draft","description":"Discard a draft","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts/{id}/attachments":{"post":{"operationId":"post_drafts_id_attachments","tags":["Drafts and attachments"],"summary":"Upload an attachment to a draft","description":"Upload raw file bytes. Set Content-Type and X-Filename. A message can contain at most 10 files and 10 MB total.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Filename","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"sizeBytes":{"type":"integer"},"available":{"type":"boolean"}},"required":["id","filename","sizeBytes","available"],"additionalProperties":false},"example":{"id":"att_…","filename":"invoice.pdf","sizeBytes":48231,"available":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","contentEncoding":"binary"}}}}}},"/attachments/{id}":{"get":{"operationId":"get_attachments_id","tags":["Drafts and attachments"],"summary":"Download a private attachment","description":"Download a private attachment","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/octet-stream":{"schema":{"type":"string","contentEncoding":"binary"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"delete_attachments_id","tags":["Drafts and attachments"],"summary":"Delete a private attachment","description":"Delete a private attachment","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sending-identities":{"get":{"operationId":"get_sending_identities","tags":["Drafts and attachments"],"summary":"List verified sender identities","description":"List verified sender identities","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{}},"addresses":{"type":"array","items":{}},"localParts":{"type":"array","items":{}}},"required":["domains","addresses","localParts"],"additionalProperties":false},"example":{"domains":[],"addresses":[],"localParts":[]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates":{"get":{"operationId":"get_templates","tags":["Hosted templates"],"summary":"List hosted templates","description":"List hosted templates","security":[{"bearerAuth":[]}],"parameters":[{"name":"lifecycle","in":"query","required":false,"schema":{"type":"string","enum":["active","archived","all"]}},{"name":"query","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}},"count":{"type":"integer"}},"required":["data","count"],"additionalProperties":false},"example":{"data":[],"count":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"post_templates","tags":["Hosted templates"],"summary":"Create a hosted template","description":"Create a hosted template","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"}},"required":["id","key"],"additionalProperties":false}},"required":["template"],"additionalProperties":false},"example":{"template":{"id":"tmpl_…","key":"account-welcome"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"starter":{"type":"string"}},"required":["name","key","starter"],"additionalProperties":false},"example":{"name":"Account welcome","key":"account-welcome","starter":"welcome"}}}}}},"/templates/{id}":{"get":{"operationId":"get_templates_id","tags":["Hosted templates"],"summary":"Retrieve drafts, releases, and usage","description":"Retrieve drafts, releases, and usage","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false},"versions":{"type":"array","items":{}},"draft":{},"activeVersion":{},"usage":{"type":"array","items":{}}},"required":["template","versions","draft","activeVersion","usage"],"additionalProperties":false},"example":{"template":{"id":"tmpl_…"},"versions":[],"draft":null,"activeVersion":null,"usage":[]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates/{id}/draft":{"put":{"operationId":"put_templates_id_draft","tags":["Hosted templates"],"summary":"Autosave a template draft","description":"Autosave a template draft","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"draft":{"type":"object","properties":{"id":{"type":"string"},"revision":{"type":"integer"}},"required":["id","revision"],"additionalProperties":false}},"required":["draft"],"additionalProperties":false},"example":{"draft":{"id":"tmplv_…","revision":2}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"revision":{"type":"integer"},"name":{"type":"string"},"subjectTemplate":{"type":"string"},"htmlTemplate":{"type":"string"},"textTemplate":{"type":"string"},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"required":{"type":"boolean"}},"required":["key","type","required"],"additionalProperties":false}},"sampleData":{"type":"object","properties":{"first_name":{"type":"string"}},"required":["first_name"],"additionalProperties":false}},"required":["revision","name","subjectTemplate","htmlTemplate","textTemplate","variables","sampleData"],"additionalProperties":false},"example":{"revision":1,"name":"Account welcome","subjectTemplate":"Welcome, {{first_name}}","htmlTemplate":"<h1>Welcome, {{first_name}}</h1>","textTemplate":"Welcome, {{first_name}}","variables":[{"key":"first_name","type":"string","required":true}],"sampleData":{"first_name":"Asha"}}}}}},"post":{"operationId":"post_templates_id_draft","tags":["Hosted templates"],"summary":"Create a new draft from the published release","description":"Create a new draft from the published release","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"draft":{"type":"object","properties":{"id":{"type":"string"},"revision":{"type":"integer"}},"required":["id","revision"],"additionalProperties":false}},"required":["draft"],"additionalProperties":false},"example":{"draft":{"id":"tmplv_…","revision":1}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates/{id}/render":{"post":{"operationId":"post_templates_id_render","tags":["Hosted templates"],"summary":"Render exact server output","description":"Render exact server output","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"findings":{"type":"array","items":{}}},"required":["subject","html","text","findings"],"additionalProperties":false},"example":{"subject":"Welcome, Asha","html":"<h1>Welcome, Asha</h1>","text":"Welcome, Asha","findings":[]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"first_name":{"type":"string"}},"required":["first_name"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"first_name":"Asha"}}}}}}},"/templates/{id}/test":{"post":{"operationId":"post_templates_id_test","tags":["Hosted templates"],"summary":"Send a test snapshot","description":"Send a test snapshot","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"isTest":{"type":"boolean"}},"required":["id","isTest"],"additionalProperties":false},"example":{"id":"em_…","isTest":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string","format":"email"}},"from":{"type":"string","format":"email"},"data":{"type":"object","properties":{"first_name":{"type":"string"}},"required":["first_name"],"additionalProperties":false}},"required":["to","from","data"],"additionalProperties":false},"example":{"to":["owner@example.com"],"from":"hello@example.com","data":{"first_name":"Asha"}}}}}}},"/templates/{id}/publish":{"post":{"operationId":"post_templates_id_publish","tags":["Hosted templates"],"summary":"Publish an immutable template release","description":"Publish an immutable template release","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string"}},"required":["id","state"],"additionalProperties":false}},"required":["version"],"additionalProperties":false},"example":{"version":{"id":"tmplv_…","state":"published"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates/{id}/archive":{"post":{"operationId":"post_templates_id_archive","tags":["Hosted templates"],"summary":"Archive a template","description":"Archive a template","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"id":{"type":"string"},"lifecycle":{"type":"string"}},"required":["id","lifecycle"],"additionalProperties":false}},"required":["template"],"additionalProperties":false},"example":{"template":{"id":"tmpl_…","lifecycle":"archived"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates/{id}/restore":{"post":{"operationId":"post_templates_id_restore","tags":["Hosted templates"],"summary":"Restore an archived template","description":"Restore an archived template","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"id":{"type":"string"},"lifecycle":{"type":"string"}},"required":["id","lifecycle"],"additionalProperties":false}},"required":["template"],"additionalProperties":false},"example":{"template":{"id":"tmpl_…","lifecycle":"active"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains":{"post":{"operationId":"post_domains","tags":["Domains"],"summary":"Add a sending domain","description":"Add a sending domain","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"records":{"type":"array","items":{}}},"required":["id","name","status","records"],"additionalProperties":false},"example":{"id":"dom_…","name":"example.com","status":"pending","records":[]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false},"example":{"name":"example.com"}}}}},"get":{"operationId":"get_domains","tags":["Domains"],"summary":"List domains and cached DNS state","description":"List domains and cached DNS state","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}},"count":{"type":"integer"}},"required":["data","count"],"additionalProperties":false},"example":{"data":[],"count":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{id}":{"get":{"operationId":"get_domains_id","tags":["Domains"],"summary":"Retrieve domain setup details","description":"Retrieve domain setup details","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"setup_status":{"type":"string"},"records":{"type":"array","items":{}},"dns_issues":{"type":"array","items":{}}},"required":["id","name","setup_status","records","dns_issues"],"additionalProperties":false},"example":{"id":"dom_…","name":"example.com","setup_status":"checking","records":[],"dns_issues":[]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"delete_domains_id","tags":["Domains"],"summary":"Delete a domain","description":"Delete a domain","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{id}/verify":{"post":{"operationId":"post_domains_id_verify","tags":["Domains"],"summary":"Refresh domain and DNS verification","description":"Refresh domain and DNS verification","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"],"additionalProperties":false},"checks":{"type":"object","properties":{"ses":{"type":"boolean"}},"required":["ses"],"additionalProperties":false},"status":{"type":"string"}},"required":["domain","checks","status"],"additionalProperties":false},"example":{"domain":{"id":"dom_…","status":"verified"},"checks":{"ses":true},"status":"verified"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{id}/inbound/setup":{"post":{"operationId":"post_domains_id_inbound_setup","tags":["Inbound email"],"summary":"Provision inbound receiving","description":"Provision inbound receiving","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string"},"record":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"}},"required":["type","name","value"],"additionalProperties":false}},"required":["domain","status","record"],"additionalProperties":false},"example":{"domain":"inbound.example.com","status":"dns_pending","record":{"type":"MX","name":"inbound.example.com","value":"10 inbound-smtp.us-east-1.amazonaws.com"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{id}/inbound/verify":{"post":{"operationId":"post_domains_id_inbound_verify","tags":["Inbound email"],"summary":"Verify inbound MX routing","description":"Verify inbound MX routing","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string"},"record":{"type":"object","properties":{"type":{"type":"string"}},"required":["type"],"additionalProperties":false}},"required":["domain","status","record"],"additionalProperties":false},"example":{"domain":"inbound.example.com","status":"ready","record":{"type":"MX"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/dns/provider":{"get":{"operationId":"get_dns_provider","tags":["Domains"],"summary":"Detect the authoritative DNS provider and relative record hosts","description":"Detect the domain's authoritative DNS provider from live nameservers, return the relative host to enter for every required record, the recommended DMARC record, inbound MX state, and which one-click setup methods are available.","security":[{"bearerAuth":[]}],"parameters":[{"name":"domain_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"detectionStatus":{"type":"string"},"detected":{"type":"string"},"zone":{"type":"string"},"nameservers":{"type":"array","items":{"type":"string"}},"recordHosts":{"type":"object","properties":{},"required":[],"additionalProperties":false},"inbound":{"type":"object","properties":{"available":{"type":"boolean"},"domain":{},"status":{"type":"string"},"record":{}},"required":["available","domain","status","record"],"additionalProperties":false},"recommendations":{"type":"array","items":{}},"authentication":{"type":"object","properties":{},"required":[],"additionalProperties":false},"providers":{"type":"object","properties":{"domainConnect":{"type":"object","properties":{"available":{"type":"boolean"},"providerName":{}},"required":["available","providerName"],"additionalProperties":false},"cloudflare":{"type":"object","properties":{"configured":{"type":"boolean"},"oauthPublic":{"type":"boolean"}},"required":["configured","oauthPublic"],"additionalProperties":false}},"required":["domainConnect","cloudflare"],"additionalProperties":false}},"required":["detectionStatus","detected","zone","nameservers","recordHosts","inbound","recommendations","authentication","providers"],"additionalProperties":false},"example":{"detectionStatus":"confirmed","detected":"cloudflare","zone":"example.com","nameservers":["ada.ns.cloudflare.com"],"recordHosts":{},"inbound":{"available":true,"domain":null,"status":"not_configured","record":null},"recommendations":[],"authentication":{},"providers":{"domainConnect":{"available":false,"providerName":null},"cloudflare":{"configured":false,"oauthPublic":false}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/dns/domain-connect/connect":{"get":{"operationId":"get_dns_domain_connect_connect","tags":["Domains"],"summary":"Create a Domain Connect consent link for one-click DNS setup","description":"When the authoritative DNS provider supports the SendHQ Domain Connect template, return a signed provider consent URL. A person must open the URL and approve the change at the DNS provider; SendHQ never receives standing DNS credentials. Returns 409 when the provider does not support the template.","security":[{"bearerAuth":[]}],"parameters":[{"name":"domain_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"next","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"providerName":{"type":"string"}},"required":["url","providerName"],"additionalProperties":false},"example":{"url":"https://dns-provider.example/v2/domainTemplates/…","providerName":"Example DNS"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inboxes":{"post":{"operationId":"post_inboxes","tags":["Inbound email"],"summary":"Create an inbound address","description":"Create an inbound address","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string","format":"email"},"status":{"type":"string"}},"required":["id","address","status"],"additionalProperties":false},"example":{"id":"inb_…","address":"support@inbound.example.com","status":"active"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain_id":{"type":"string"},"local_part":{"type":"string"},"name":{"type":"string"}},"required":["domain_id","local_part","name"],"additionalProperties":false},"example":{"domain_id":"dom_…","local_part":"support","name":"Support"}}}}},"get":{"operationId":"get_inboxes","tags":["Inbound email"],"summary":"List inbound addresses","description":"List inbound addresses","security":[{"bearerAuth":[]}],"parameters":[{"name":"domain_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}},"count":{"type":"integer"}},"required":["data","count"],"additionalProperties":false},"example":{"data":[],"count":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inboxes/{id}":{"get":{"operationId":"get_inboxes_id","tags":["Inbound email"],"summary":"Retrieve an inbound address","description":"Retrieve an inbound address","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string","format":"email"},"status":{"type":"string"}},"required":["id","address","status"],"additionalProperties":false},"example":{"id":"inb_…","address":"support@example.com","status":"active"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patch_inboxes_id","tags":["Inbound email"],"summary":"Rename, enable, or disable an inbox","description":"Rename, enable, or disable an inbox","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"],"additionalProperties":false},"example":{"id":"inb_…","status":"active"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string"}},"required":["name","status"],"additionalProperties":false},"example":{"name":"Customer support","status":"active"}}}}},"delete":{"operationId":"delete_inboxes_id","tags":["Inbound email"],"summary":"Delete an inbox while retaining messages","description":"Delete an inbox while retaining messages","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inboxes/{id}/forwarding":{"put":{"operationId":"put_inboxes_id_forwarding","tags":["Inbound email"],"summary":"Forward an inbox's received mail to another address","description":"Set `forward_to` to an email address, or null to turn forwarding off. The account owner's own address activates immediately; any other address receives a confirmation email (sent from the inbox's verified domain and metered as one recipient) and forwarding stays pending until the link is confirmed. Forwarded copies are sent from the inbox address with the original sender as Reply-To, respect suppressions and plan limits, and are never re-forwarded.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string","format":"email"},"forwardTo":{"type":"string","format":"email"},"forwardStatus":{"type":"string"}},"required":["id","address","forwardTo","forwardStatus"],"additionalProperties":false},"example":{"id":"inb_…","address":"support@example.com","forwardTo":"team@example.net","forwardStatus":"pending"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"forward_to":{"type":"string","format":"email"}},"required":["forward_to"],"additionalProperties":false},"example":{"forward_to":"team@example.net"}}}}}},"/deliverability/stats":{"get":{"operationId":"get_deliverability_stats","tags":["Deliverability"],"summary":"Retrieve 30-day delivery statistics","description":"Retrieve 30-day delivery statistics","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"window":{"type":"string"},"sent":{"type":"integer"},"delivery":{"type":"integer"},"bounce":{"type":"integer"},"complaint":{"type":"integer"},"deliveryRate":{}},"required":["window","sent","delivery","bounce","complaint","deliveryRate"],"additionalProperties":false},"example":{"window":"30d","sent":0,"delivery":0,"bounce":0,"complaint":0,"deliveryRate":null}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deliverability/reputation":{"get":{"operationId":"get_deliverability_reputation","tags":["Deliverability"],"summary":"List reputation state by exact sender identity","description":"List reputation state by exact sender identity","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"sender":{"type":"string","format":"email"},"status":{"type":"string"},"dailyLimit":{"type":"integer"},"reason":{},"cleanSince":{"type":"string","format":"date-time"},"warnedAt":{},"pausedAt":{},"evaluatedAt":{"type":"string","format":"date-time"}},"required":["sender","status","dailyLimit","reason","cleanSince","warnedAt","pausedAt","evaluatedAt"],"additionalProperties":false}},"count":{"type":"integer"}},"required":["data","count"],"additionalProperties":false},"example":{"data":[{"sender":"alerts@example.com","status":"active","dailyLimit":2000,"reason":null,"cleanSince":"2026-09-01T00:00:00.000Z","warnedAt":null,"pausedAt":null,"evaluatedAt":"2026-09-07T00:00:00.000Z"}],"count":1}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deliverability/account":{"get":{"operationId":"get_deliverability_account","tags":["Deliverability"],"summary":"Account delivery rates, daily ladder, and bounce trend","description":"Daily trend for at most 30 days, counted per message. The rolling 7-day hard-bounce and complaint rates are per recipient, the same counts the sending ladder uses, divided by committed recipient units. `days` is 7 or 30. `limit` on the related domain and sender routes is at most 97.","security":[{"bearerAuth":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","enum":[7,30,90]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer"},"trendUnit":{"type":"string"},"trend":{"type":"array","items":{}},"rolling7d":{"type":"object","properties":{"unit":{"type":"string"},"sent":{"type":"integer"},"hardBounce":{"type":"integer"},"softBounce":{"type":"integer"},"complaint":{"type":"integer"},"hardBounceRate":{},"complaintRate":{}},"required":["unit","sent","hardBounce","softBounce","complaint","hardBounceRate","complaintRate"],"additionalProperties":false},"thresholds":{"type":"object","properties":{},"required":[],"additionalProperties":false},"ladder":{}},"required":["days","trendUnit","trend","rolling7d","thresholds","ladder"],"additionalProperties":false},"example":{"days":30,"trendUnit":"message","trend":[],"rolling7d":{"unit":"recipient","sent":0,"hardBounce":0,"softBounce":0,"complaint":0,"hardBounceRate":null,"complaintRate":null},"thresholds":{},"ladder":null}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deliverability/domains":{"get":{"operationId":"get_deliverability_domains","tags":["Deliverability"],"summary":"Per-domain sent, delivered, hard and soft bounces, complaints, and failures","description":"Each message counts once, however many recipients it had. This is a different unit from the 7-day ladder rate, which counts recipients. A new domain includes its Gmail cap, and an active 4.7.28 backoff includes the step and until time. `limit` is at most 97.","security":[{"bearerAuth":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","enum":[7,30,90]}},{"name":"domain","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer"},"unit":{"type":"string"},"data":{"type":"array","items":{}},"count":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["days","unit","data","count","limit","offset"],"additionalProperties":false},"example":{"days":30,"unit":"message","data":[],"count":0,"limit":50,"offset":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deliverability/senders":{"get":{"operationId":"get_deliverability_senders","tags":["Deliverability"],"summary":"Per-From-address delivery rates","description":"Each message counts once. `limit` is at most 97.","security":[{"bearerAuth":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","enum":[7,30,90]}},{"name":"domain","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer"},"unit":{"type":"string"},"data":{"type":"array","items":{}},"count":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["days","unit","data","count","limit","offset"],"additionalProperties":false},"example":{"days":30,"unit":"message","data":[],"count":0,"limit":50,"offset":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/emails/{id}/delivery":{"get":{"operationId":"get_emails_id_delivery","tags":["Emails and threads"],"summary":"Delivery timeline for one email, with bounce and complaint reasons","description":"Delivery timeline for one email, with bounce and complaint reasons","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"emailId":{"type":"string"},"status":{"type":"string"},"timeline":{"type":"array","items":{}},"count":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["emailId","status","timeline","count","limit","offset"],"additionalProperties":false},"example":{"emailId":"em_123","status":"bounced","timeline":[],"count":0,"limit":50,"offset":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/threads/{id}/delivery":{"get":{"operationId":"get_threads_id_delivery","tags":["Emails and threads"],"summary":"Per-thread delivery counts and per-message failure reasons","description":"Per-thread delivery counts and per-message failure reasons","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"threadId":{"type":"string"},"delivered":{"type":"integer"},"bounced":{"type":"integer"},"complained":{"type":"integer"},"failed":{"type":"integer"},"messages":{"type":"array","items":{}}},"required":["threadId","delivered","bounced","complained","failed","messages"],"additionalProperties":false},"example":{"threadId":"thr_123","delivered":0,"bounced":0,"complained":0,"failed":0,"messages":[]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/suppressions":{"get":{"operationId":"get_suppressions","tags":["Deliverability"],"summary":"List workspace suppressions","description":"List workspace suppressions","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}},"count":{"type":"integer"}},"required":["data","count"],"additionalProperties":false},"example":{"data":[],"count":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/suppressions/{email}":{"delete":{"operationId":"delete_suppressions_email","tags":["Deliverability"],"summary":"Remove an eligible bounce suppression","description":"Remove an eligible bounce suppression","security":[{"bearerAuth":[]}],"parameters":[{"name":"email","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/blocked-recipients":{"get":{"operationId":"get_blocked_recipients","tags":["Deliverability"],"summary":"List bounces, complaints, and unsubscribes","description":"List bounces, complaints, and unsubscribes","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}},"count":{"type":"integer"},"summary":{"type":"object","properties":{"total":{"type":"integer"},"unsubscribe":{"type":"integer"},"bounce":{"type":"integer"},"complaint":{"type":"integer"}},"required":["total","unsubscribe","bounce","complaint"],"additionalProperties":false}},"required":["data","count","summary"],"additionalProperties":false},"example":{"data":[],"count":0,"summary":{"total":0,"unsubscribe":0,"bounce":0,"complaint":0}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"operationId":"get_webhooks","tags":["Webhooks"],"summary":"List webhook endpoints","description":"List webhook endpoints","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}},"count":{"type":"integer"},"eventTypes":{"type":"array","items":{"type":"string"}}},"required":["data","count","eventTypes"],"additionalProperties":false},"example":{"data":[],"count":0,"eventTypes":["email.sent","email.delivered","email.delivery_delayed","email.bounced","email.complained","email.failed","email.received"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"post_webhooks","tags":["Webhooks"],"summary":"Create a webhook endpoint","description":"Subscribe an https URL to email events. Omit `events` to receive every event type. The response includes the signing secret (`whsec_…`). Each delivery is signed with the Standard Webhooks scheme (`webhook-id`, `webhook-timestamp`, `webhook-signature`) and retried up to 8 times over about 27 hours. Up to 10 endpoints per workspace.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"secret":{"type":"string"}},"required":["id","url","events","status","secret"],"additionalProperties":false},"example":{"id":"wh_…","url":"https://example.com/webhooks/sendhq","events":["email.delivered","email.bounced"],"status":"enabled","secret":"whsec_…"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"description":{"type":"string"}},"required":["url","events","description"],"additionalProperties":false},"example":{"url":"https://example.com/webhooks/sendhq","events":["email.delivered","email.bounced"],"description":"Production"}}}}}},"/webhooks/{id}":{"get":{"operationId":"get_webhooks_id","tags":["Webhooks"],"summary":"Retrieve a webhook endpoint and its secret","description":"Retrieve a webhook endpoint and its secret","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{}},"status":{"type":"string"},"secret":{"type":"string"}},"required":["id","url","events","status","secret"],"additionalProperties":false},"example":{"id":"wh_…","url":"https://example.com/webhooks/sendhq","events":[],"status":"enabled","secret":"whsec_…"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patch_webhooks_id","tags":["Webhooks"],"summary":"Update, enable, or disable a webhook endpoint","description":"Update, enable, or disable a webhook endpoint","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"],"additionalProperties":false},"example":{"id":"wh_…","status":"disabled"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}},"required":["status"],"additionalProperties":false},"example":{"status":"disabled"}}}}},"delete":{"operationId":"delete_webhooks_id","tags":["Webhooks"],"summary":"Delete a webhook endpoint and its delivery log","description":"Delete a webhook endpoint and its delivery log","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/rotate-secret":{"post":{"operationId":"post_webhooks_id_rotate_secret","tags":["Webhooks"],"summary":"Rotate an endpoint signing secret","description":"Rotate an endpoint signing secret","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"secret":{"type":"string"}},"required":["id","secret"],"additionalProperties":false},"example":{"id":"wh_…","secret":"whsec_…"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/test":{"post":{"operationId":"post_webhooks_id_test","tags":["Webhooks"],"summary":"Send a signed webhook.test event now","description":"Send a signed webhook.test event now","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"delivery":{"type":"object","properties":{"id":{"type":"string"},"eventType":{"type":"string"},"status":{"type":"string"},"attempts":{"type":"integer"}},"required":["id","eventType","status","attempts"],"additionalProperties":false},"ok":{"type":"boolean"}},"required":["delivery","ok"],"additionalProperties":false},"example":{"delivery":{"id":"msg_…","eventType":"webhook.test","status":"succeeded","attempts":1},"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/deliveries":{"get":{"operationId":"get_webhooks_id_deliveries","tags":["Webhooks"],"summary":"List delivery attempts for an endpoint","description":"List delivery attempts for an endpoint","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","succeeded","failed"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}},"count":{"type":"integer"}},"required":["data","count"],"additionalProperties":false},"example":{"data":[],"count":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/deliveries/{deliveryId}":{"get":{"operationId":"get_webhooks_id_deliveries_deliveryId","tags":["Webhooks"],"summary":"Retrieve one delivery and its payload","description":"Retrieve one delivery and its payload","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"eventType":{"type":"string"},"status":{"type":"string"},"attempts":{"type":"integer"},"payload":{"type":"object","properties":{"type":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"email_id":{"type":"string"}},"required":["email_id"],"additionalProperties":false}},"required":["type","created_at","data"],"additionalProperties":false}},"required":["id","eventType","status","attempts","payload"],"additionalProperties":false},"example":{"id":"msg_…","eventType":"email.delivered","status":"succeeded","attempts":1,"payload":{"type":"email.delivered","created_at":"2026-10-29T12:00:00.000Z","data":{"email_id":"em_…"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/deliveries/{deliveryId}/retry":{"post":{"operationId":"post_webhooks_id_deliveries_deliveryId_retry","tags":["Webhooks"],"summary":"Retry a delivery now","description":"Retry a delivery now","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"delivery":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"attempts":{"type":"integer"}},"required":["id","status","attempts"],"additionalProperties":false},"ok":{"type":"boolean"}},"required":["delivery","ok"],"additionalProperties":false},"example":{"delivery":{"id":"msg_…","status":"succeeded","attempts":2},"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts":{"get":{"operationId":"get_contacts","tags":["Campaigns"],"summary":"List contacts","description":"Newest-first contacts with consent evidence, tags, engagement, and the lists they are subscribed to. Filter by `list_id`, `status` (`subscribed`, `pending`, `unsubscribed`, `bounced`, `complained`, or `dormant`), `query` (email or name substring; `*` is a wildcard on the email, as in `*@example.com`), `tag`, `source` (`form`, `api`, or `import`), signup time (`after`, `before`), or `segment_id`. Engagement counts come from open and click tracking: opens are estimates (privacy proxies and security scanners load images on their own, and requests that look automated are left out), never proof that someone read a message. A dormant contact stopped opening, did not answer a list-cleanup email, and no longer gets broadcasts until it engages again.","security":[{"bearerAuth":[]}],"parameters":[{"name":"list_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["subscribed","pending","unsubscribed","bounced","complained","dormant"]}},{"name":"query","in":"query","required":false,"schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"schema":{"type":"string"}},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["form","api","import"]}},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"segment_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"fields":{"type":"object","properties":{"plan":{"type":"string"}},"required":["plan"],"additionalProperties":false},"status":{"type":"string"},"consent":{"type":"object","properties":{"source":{"type":"string"},"basis":{"type":"string"},"importId":{},"optedInAt":{"type":"string","format":"date-time"},"confirmedAt":{},"ip":{},"userAgent":{}},"required":["source","basis","importId","optedInAt","confirmedAt","ip","userAgent"],"additionalProperties":false},"unsubscribedAt":{},"dormant":{"type":"boolean"},"dormantAt":{},"engagement":{"type":"object","properties":{"sent":{"type":"integer"},"opens":{"type":"integer"},"clicks":{"type":"integer"},"lastSentAt":{"type":"string","format":"date-time"},"lastOpenedAt":{"type":"string","format":"date-time"},"lastClickedAt":{"type":"string","format":"date-time"},"sendsSinceEngaged":{"type":"integer"}},"required":["sent","opens","clicks","lastSentAt","lastOpenedAt","lastClickedAt","sendsSinceEngaged"],"additionalProperties":false},"country":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"lists":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","email","name","fields","status","consent","unsubscribedAt","dormant","dormantAt","engagement","country","tags","lists","createdAt","updatedAt"],"additionalProperties":false}},"count":{"type":"integer"},"total":{"type":"integer"}},"required":["data","count","total"],"additionalProperties":false},"example":{"data":[{"id":"ct_…","email":"ada@example.net","name":"Ada Lovelace","fields":{"plan":"pro"},"status":"subscribed","consent":{"source":"api","basis":"Ticked the newsletter box at checkout on acme.com","importId":null,"optedInAt":"2026-10-25T12:00:00.000Z","confirmedAt":null,"ip":null,"userAgent":null},"unsubscribedAt":null,"dormant":false,"dormantAt":null,"engagement":{"sent":4,"opens":3,"clicks":1,"lastSentAt":"2026-10-30T09:00:00.000Z","lastOpenedAt":"2026-10-30T09:12:00.000Z","lastClickedAt":"2026-10-30T09:13:00.000Z","sendsSinceEngaged":0},"country":"GB","tags":["VIP"],"lists":["lst_…"],"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}],"count":1,"total":1}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"post_contacts","tags":["Campaigns"],"summary":"Add a contact with its consent basis","description":"Add one contact. A subscribed contact (the default) requires `consent_basis`: how this person agreed to receive your email. Use `status: \"unsubscribed\"` to record an opt-out. Addresses already suppressed or unsubscribed from the workspace are stored with that status, never as subscribed. Optional `tags` (up to 50, each up to 60 characters) are attached to the new contact. Returns 409 when the email already exists.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"fields":{"type":"object","properties":{"plan":{"type":"string"}},"required":["plan"],"additionalProperties":false},"status":{"type":"string"},"consent":{"type":"object","properties":{"source":{"type":"string"},"basis":{"type":"string"},"importId":{},"optedInAt":{"type":"string","format":"date-time"},"confirmedAt":{},"ip":{},"userAgent":{}},"required":["source","basis","importId","optedInAt","confirmedAt","ip","userAgent"],"additionalProperties":false},"unsubscribedAt":{},"dormant":{"type":"boolean"},"dormantAt":{},"engagement":{"type":"object","properties":{"sent":{"type":"integer"},"opens":{"type":"integer"},"clicks":{"type":"integer"},"lastSentAt":{"type":"string","format":"date-time"},"lastOpenedAt":{"type":"string","format":"date-time"},"lastClickedAt":{"type":"string","format":"date-time"},"sendsSinceEngaged":{"type":"integer"}},"required":["sent","opens","clicks","lastSentAt","lastOpenedAt","lastClickedAt","sendsSinceEngaged"],"additionalProperties":false},"country":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"lists":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","email","name","fields","status","consent","unsubscribedAt","dormant","dormantAt","engagement","country","tags","lists","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"ct_…","email":"ada@example.net","name":"Ada Lovelace","fields":{"plan":"pro"},"status":"subscribed","consent":{"source":"api","basis":"Ticked the newsletter box at checkout on acme.com","importId":null,"optedInAt":"2026-10-25T12:00:00.000Z","confirmedAt":null,"ip":null,"userAgent":null},"unsubscribedAt":null,"dormant":false,"dormantAt":null,"engagement":{"sent":4,"opens":3,"clicks":1,"lastSentAt":"2026-10-30T09:00:00.000Z","lastOpenedAt":"2026-10-30T09:12:00.000Z","lastClickedAt":"2026-10-30T09:13:00.000Z","sendsSinceEngaged":0},"country":"GB","tags":["VIP"],"lists":["lst_…"],"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"fields":{"type":"object","properties":{"plan":{"type":"string"}},"required":["plan"],"additionalProperties":false},"tags":{"type":"array","items":{"type":"string"}},"list_ids":{"type":"array","items":{"type":"string"}},"consent_basis":{"type":"string"}},"required":["email","name","fields","tags","list_ids","consent_basis"],"additionalProperties":false},"example":{"email":"ada@example.net","name":"Ada Lovelace","fields":{"plan":"pro"},"tags":["VIP"],"list_ids":["lst_…"],"consent_basis":"Ticked the newsletter box at checkout on acme.com"}}}}}},"/contacts/bulk":{"post":{"operationId":"post_contacts_bulk","tags":["Campaigns"],"summary":"Tag, move, unsubscribe, or delete many contacts at once","description":"Apply one `action` to up to 10,000 contacts: the IDs in `contact_ids`, or every contact matching `filter` (the same filters as GET /contacts). Actions: `tag` and `untag` (with `tags`), `add_to_list` and `remove_from_list` (with `list_id`), `unsubscribe`, and `delete`. Adding to a list mirrors each contact's status, so nobody is resubscribed. `delete` is permanent and requires `confirm_count` equal to the number of contacts it would delete; without it the API returns 409 with that `count`. IDs from another workspace are ignored.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"action":{"type":"string"},"count":{"type":"integer"}},"required":["ok","action","count"],"additionalProperties":false},"example":{"ok":true,"action":"tag","count":120}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["tag","untag","add_to_list","remove_from_list","unsubscribe","delete"]},"contact_ids":{"type":"array","maxItems":10000,"items":{"type":"string"}},"filter":{"type":"object","description":"The same filters as GET /contacts.","properties":{"list_id":{"type":"string"},"status":{"type":"string","enum":["subscribed","pending","unsubscribed","bounced","complained","dormant"]},"query":{"type":"string","maxLength":200,"description":"Email or name substring; `*` is a wildcard on the email (`*@example.com`)."},"tag":{"type":"string","maxLength":60},"source":{"type":"string","enum":["form","api","import"]},"after":{"type":"string","format":"date-time","description":"Signed up at or after."},"before":{"type":"string","format":"date-time","description":"Signed up before."},"segment_id":{"type":"string"}},"additionalProperties":false},"tags":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":60},"description":"For `tag` and `untag`."},"list_id":{"type":"string","description":"For `add_to_list` and `remove_from_list`."},"confirm_count":{"type":"integer","minimum":0,"description":"For `delete`: the number of contacts that will be deleted."}},"anyOf":[{"required":["contact_ids"]},{"required":["filter"]}],"additionalProperties":false},"example":{"action":"tag","tags":["october"],"filter":{"list_id":"lst_…","status":"subscribed"}}}}}}},"/contacts/export":{"get":{"operationId":"get_contacts_export","tags":["Campaigns"],"summary":"Export contacts as CSV","description":"A CSV file of up to 100,000 contacts matching the same filters as GET /contacts, in the column layout the importer reads, so it imports back unchanged: `email`, `name`, `status` (`dormant` for dormant contacts), `tags` (separated by `;`), `signed_up_at`, `source`, `consent`, `opens`, `clicks`, `last_opened_at`, then up to 50 custom fields.","security":[{"bearerAuth":[]}],"parameters":[{"name":"list_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["subscribed","pending","unsubscribed","bounced","complained","dormant"]}},{"name":"query","in":"query","required":false,"schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"schema":{"type":"string"}},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["form","api","import"]}},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"segment_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts/{id}":{"get":{"operationId":"get_contacts_id","tags":["Campaigns"],"summary":"Retrieve a contact by ID or email","description":"Retrieve a contact by ID or email","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"fields":{"type":"object","properties":{"plan":{"type":"string"}},"required":["plan"],"additionalProperties":false},"status":{"type":"string"},"consent":{"type":"object","properties":{"source":{"type":"string"},"basis":{"type":"string"},"importId":{},"optedInAt":{"type":"string","format":"date-time"},"confirmedAt":{},"ip":{},"userAgent":{}},"required":["source","basis","importId","optedInAt","confirmedAt","ip","userAgent"],"additionalProperties":false},"unsubscribedAt":{},"dormant":{"type":"boolean"},"dormantAt":{},"engagement":{"type":"object","properties":{"sent":{"type":"integer"},"opens":{"type":"integer"},"clicks":{"type":"integer"},"lastSentAt":{"type":"string","format":"date-time"},"lastOpenedAt":{"type":"string","format":"date-time"},"lastClickedAt":{"type":"string","format":"date-time"},"sendsSinceEngaged":{"type":"integer"}},"required":["sent","opens","clicks","lastSentAt","lastOpenedAt","lastClickedAt","sendsSinceEngaged"],"additionalProperties":false},"country":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"lists":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","email","name","fields","status","consent","unsubscribedAt","dormant","dormantAt","engagement","country","tags","lists","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"ct_…","email":"ada@example.net","name":"Ada Lovelace","fields":{"plan":"pro"},"status":"subscribed","consent":{"source":"api","basis":"Ticked the newsletter box at checkout on acme.com","importId":null,"optedInAt":"2026-10-25T12:00:00.000Z","confirmedAt":null,"ip":null,"userAgent":null},"unsubscribedAt":null,"dormant":false,"dormantAt":null,"engagement":{"sent":4,"opens":3,"clicks":1,"lastSentAt":"2026-10-30T09:00:00.000Z","lastOpenedAt":"2026-10-30T09:12:00.000Z","lastClickedAt":"2026-10-30T09:13:00.000Z","sendsSinceEngaged":0},"country":"GB","tags":["VIP"],"lists":["lst_…"],"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patch_contacts_id","tags":["Campaigns"],"summary":"Update a contact's name, fields, or tags, or unsubscribe it","description":"Change `name`, merge `fields` (a null value removes a field), change tags (`tags` replaces the whole set; `add_tags` and `remove_tags` change it), or set `status` to `unsubscribed`. A contact can never be resubscribed through the API: only the recipient can, by confirming a signup form, which clears their earlier unsubscribe from that list and from the workspace but never a bounce or complaint suppression.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"fields":{"type":"object","properties":{"plan":{"type":"string"}},"required":["plan"],"additionalProperties":false},"status":{"type":"string"},"consent":{"type":"object","properties":{"source":{"type":"string"},"basis":{"type":"string"},"importId":{},"optedInAt":{"type":"string","format":"date-time"},"confirmedAt":{},"ip":{},"userAgent":{}},"required":["source","basis","importId","optedInAt","confirmedAt","ip","userAgent"],"additionalProperties":false},"unsubscribedAt":{},"dormant":{"type":"boolean"},"dormantAt":{},"engagement":{"type":"object","properties":{"sent":{"type":"integer"},"opens":{"type":"integer"},"clicks":{"type":"integer"},"lastSentAt":{"type":"string","format":"date-time"},"lastOpenedAt":{"type":"string","format":"date-time"},"lastClickedAt":{"type":"string","format":"date-time"},"sendsSinceEngaged":{"type":"integer"}},"required":["sent","opens","clicks","lastSentAt","lastOpenedAt","lastClickedAt","sendsSinceEngaged"],"additionalProperties":false},"country":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"lists":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","email","name","fields","status","consent","unsubscribedAt","dormant","dormantAt","engagement","country","tags","lists","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"ct_…","email":"ada@example.net","name":"Ada Lovelace","fields":{"plan":"pro"},"status":"subscribed","consent":{"source":"api","basis":"Ticked the newsletter box at checkout on acme.com","importId":null,"optedInAt":"2026-10-25T12:00:00.000Z","confirmedAt":null,"ip":null,"userAgent":null},"unsubscribedAt":null,"dormant":false,"dormantAt":null,"engagement":{"sent":4,"opens":3,"clicks":1,"lastSentAt":"2026-10-30T09:00:00.000Z","lastOpenedAt":"2026-10-30T09:12:00.000Z","lastClickedAt":"2026-10-30T09:13:00.000Z","sendsSinceEngaged":0},"country":"GB","tags":["VIP"],"lists":["lst_…"],"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"fields":{"type":"object","properties":{"plan":{"type":"string"}},"required":["plan"],"additionalProperties":false},"add_tags":{"type":"array","items":{"type":"string"}},"remove_tags":{"type":"array","items":{"type":"string"}}},"required":["name","fields","add_tags","remove_tags"],"additionalProperties":false},"example":{"name":"Ada King","fields":{"plan":"team"},"add_tags":["beta"],"remove_tags":["trial"]}}}}},"delete":{"operationId":"delete_contacts_id","tags":["Campaigns"],"summary":"Delete a contact and its list memberships","description":"Removes the contact, its memberships, and its tags. Suppressions and recorded unsubscribes are kept, so a deleted address still cannot be mailed if it is added again.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contact-imports":{"post":{"operationId":"post_contact_imports","tags":["Campaigns"],"summary":"Import contacts from CSV","description":"Import up to 5,000 rows (5 MB) per request. The header row needs an `email` column; `name` (or `first_name` and `last_name`), `status`, and `tags` (separated by `;` or `|`) are recognized and other columns become custom fields. `consent_basis` is required and is recorded on every new contact. Optional `tags` are added to every accepted row. Rows whose status says unsubscribed import as unsubscribed. Existing contacts keep their status; set `update_existing` to merge names and fields. Duplicate rows are skipped and invalid rows are reported by line.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"listId":{"type":"string"},"consentBasis":{"type":"string"},"totalRows":{"type":"integer"},"accepted":{"type":"integer"},"created":{"type":"integer"},"existing":{"type":"integer"},"skipped":{"type":"integer"},"invalid":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"line":{"type":"integer"},"reason":{"type":"string"}},"required":["line","reason"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","listId","consentBasis","totalRows","accepted","created","existing","skipped","invalid","errors","tags","createdAt"],"additionalProperties":false},"example":{"id":"imp_…","listId":"lst_…","consentBasis":"Newsletter signups exported from Mailchimp (double opt-in)","totalRows":1,"accepted":1,"created":1,"existing":0,"skipped":0,"invalid":0,"errors":[{"line":3,"reason":"invalid email address"}],"tags":["VIP","beta","imported"],"createdAt":"2026-10-25T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"csv":{"type":"string"},"list_id":{"type":"string"},"consent_basis":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"update_existing":{"type":"boolean"}},"required":["csv","list_id","consent_basis","tags","update_existing"],"additionalProperties":false},"example":{"csv":"email,name,plan,tags\nada@example.net,Ada Lovelace,pro,VIP;beta\n","list_id":"lst_…","consent_basis":"Newsletter signups exported from Mailchimp (double opt-in)","tags":["imported"],"update_existing":false}}}}},"get":{"operationId":"get_contact_imports","tags":["Campaigns"],"summary":"List recent contact imports","description":"List recent contact imports","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"listId":{"type":"string"},"consentBasis":{"type":"string"},"totalRows":{"type":"integer"},"accepted":{"type":"integer"},"skipped":{"type":"integer"},"invalid":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","listId","consentBasis","totalRows","accepted","skipped","invalid","createdAt"],"additionalProperties":false}},"count":{"type":"integer"}},"required":["data","count"],"additionalProperties":false},"example":{"data":[{"id":"imp_…","listId":"lst_…","consentBasis":"Newsletter signups exported from Mailchimp (double opt-in)","totalRows":1,"accepted":1,"skipped":0,"invalid":0,"createdAt":"2026-10-25T12:00:00.000Z"}],"count":1}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tags":{"get":{"operationId":"get_tags","tags":["Campaigns"],"summary":"List contact tags with how many contacts carry each","description":"The workspace's tags, most used first (up to 500). Tags are free text: they are created by tagging a contact and disappear when no contact carries them.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string"},"count":{"type":"integer"}},"required":["tag","count"],"additionalProperties":false}},"count":{"type":"integer"}},"required":["data","count"],"additionalProperties":false},"example":{"data":[{"tag":"VIP","count":42}],"count":1}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contact-fields":{"get":{"operationId":"get_contact_fields","tags":["Campaigns"],"summary":"List custom contact field definitions","description":"Defined custom fields with their label and type (`text`, `number`, or `date`). Definitions label fields in the dashboard, make merge tags such as `{{fields.plan}}` known to the pre-send checks, and type segment conditions. Contacts can still carry values for keys that are not defined.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["key","label","type","createdAt"],"additionalProperties":false}},"count":{"type":"integer"},"types":{"type":"array","items":{"type":"string"}}},"required":["data","count","types"],"additionalProperties":false},"example":{"data":[{"key":"plan","label":"Plan","type":"text","createdAt":"2026-11-01T12:00:00.000Z"}],"count":1,"types":["text","number","date"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contact-fields/{key}":{"put":{"operationId":"put_contact_fields_key","tags":["Campaigns"],"summary":"Define or change a custom contact field","description":"Create or update the field `key` (a lowercase letter, then up to 39 of a-z, 0-9, and `_`). `type` is `text` (default), `number`, or `date`. Built-in merge tags (`email`, `name`, `first_name`, `last_name`, `fields`, `unsubscribe_url`) cannot be used. A workspace may define 50 fields.","security":[{"bearerAuth":[]}],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["key","label","type","createdAt"],"additionalProperties":false},"example":{"key":"plan","label":"Plan","type":"text","createdAt":"2026-11-01T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"type":{"type":"string"}},"required":["label","type"],"additionalProperties":false},"example":{"label":"Plan","type":"text"}}}}},"delete":{"operationId":"delete_contact_fields_key","tags":["Campaigns"],"summary":"Delete a custom field definition","description":"Removes the definition only. Values already stored on contacts are kept. Returns 404 when the field is not defined.","security":[{"bearerAuth":[]}],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/segments":{"get":{"operationId":"get_segments","tags":["Campaigns"],"summary":"List saved segments with live counts","description":"Saved segments, newest first, each with `count`: the subscribed, non-dormant contacts in the whole workspace that match now. `fields` lists every condition field and the operators it accepts. A broadcast with a segment sends to the members of its list that match.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"match":{"type":"string"},"conditions":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string"},"value":{}},"required":["field","op","value"],"additionalProperties":false}},"count":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","match","conditions","count","createdAt","updatedAt"],"additionalProperties":false}},"count":{"type":"integer"},"fields":{"type":"object","properties":{"tag":{"type":"array","items":{"type":"string"}},"list":{"type":"array","items":{"type":"string"}},"status":{"type":"array","items":{"type":"string"}},"source":{"type":"array","items":{"type":"string"}},"email":{"type":"array","items":{"type":"string"}},"name":{"type":"array","items":{"type":"string"}},"signed_up":{"type":"array","items":{"type":"string"}},"opened":{"type":"array","items":{"type":"string"}},"clicked":{"type":"array","items":{"type":"string"}},"opens":{"type":"array","items":{"type":"string"}},"sends_without_open":{"type":"array","items":{"type":"string"}},"country":{"type":"array","items":{"type":"string"}},"field":{"type":"array","items":{"type":"string"}}},"required":["tag","list","status","source","email","name","signed_up","opened","clicked","opens","sends_without_open","country","field"],"additionalProperties":false}},"required":["data","count","fields"],"additionalProperties":false},"example":{"data":[{"id":"seg_…","name":"Engaged pro customers","match":"all","conditions":[{"field":"name","op":"is_set","value":null},{"field":"fields.plan","op":"equals","value":"pro"},{"field":"opened","op":"in_last_days","value":90}],"count":120,"createdAt":"2026-11-01T12:00:00.000Z","updatedAt":"2026-11-01T12:00:00.000Z"}],"count":1,"fields":{"tag":["has","not_has"],"list":["in","not_in"],"status":["is","is_not"],"source":["is","is_not"],"email":["contains","not_contains","ends_with"],"name":["is_set","not_set"],"signed_up":["before","after","in_last_days","not_in_last_days"],"opened":["in_last_days","not_in_last_days","ever","never"],"clicked":["in_last_days","not_in_last_days","ever","never"],"opens":["gte","lte"],"sends_without_open":["gte","lte"],"country":["is","is_not"],"field":["equals","not_equals","contains","gt","lt","before","after","is_set","not_set"]}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"post_segments","tags":["Campaigns"],"summary":"Save a segment","description":"Save up to 20 `conditions` joined by `match` (`all`, the default, or `any`). Each condition is `{ field, op, value }`: `tag` (has, not_has), `list` (in, not_in a list ID), `status` (is, is_not, including `dormant`), `source` (is, is_not), `email` (contains, not_contains, ends_with), `name` (is_set, not_set), `signed_up` (before, after a date; in_last_days, not_in_last_days), `opened` and `clicked` (in_last_days, not_in_last_days, ever, never), `opens` and `sends_without_open` (gte, lte), `country` (is, is_not a two-letter code), and custom fields as `fields.<key>` or `{ field: \"field\", key }` (equals, not_equals, contains, gt, lt, before, after, is_set, not_set). Opened and clicked use estimated, bot-filtered engagement. A workspace may have 200 segments.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"match":{"type":"string"},"conditions":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string"},"value":{}},"required":["field","op","value"],"additionalProperties":false}},"count":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","match","conditions","count","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"seg_…","name":"Engaged pro customers","match":"all","conditions":[{"field":"name","op":"is_set","value":null},{"field":"fields.plan","op":"equals","value":"pro"},{"field":"opened","op":"in_last_days","value":90}],"count":120,"createdAt":"2026-11-01T12:00:00.000Z","updatedAt":"2026-11-01T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"match":{"type":"string","enum":["all","any"],"default":"all"},"conditions":{"type":"array","maxItems":20,"items":{"type":"object","required":["field","op"],"properties":{"field":{"type":"string","description":"One of tag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as `fields.<key>` (or `field` with `key`)."},"key":{"type":"string","description":"Custom field key when `field` is `field`."},"op":{"type":"string","description":"Operator allowed for the field (see `fields` in GET /segments)."},"value":{"type":["string","number","null"],"description":"Required except for is_set, not_set, ever, and never. Day counts and numbers for in_last_days, not_in_last_days, gte, lte, gt, and lt; YYYY-MM-DD for before and after."}},"additionalProperties":false}}},"additionalProperties":false,"required":["name"]},"example":{"name":"Engaged pro customers","match":"all","conditions":[{"field":"fields.plan","op":"equals","value":"pro"},{"field":"opened","op":"in_last_days","value":90}]}}}}}},"/segments/preview":{"post":{"operationId":"post_segments_preview","tags":["Campaigns"],"summary":"Count and sample the contacts that match unsaved conditions","description":"Evaluate `match` and `conditions` without saving them: the number of subscribed, non-dormant contacts that match and up to five of them.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"sample":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"fields":{"type":"object","properties":{"plan":{"type":"string"}},"required":["plan"],"additionalProperties":false},"status":{"type":"string"},"consent":{"type":"object","properties":{"source":{"type":"string"},"basis":{"type":"string"},"importId":{},"optedInAt":{"type":"string","format":"date-time"},"confirmedAt":{},"ip":{},"userAgent":{}},"required":["source","basis","importId","optedInAt","confirmedAt","ip","userAgent"],"additionalProperties":false},"unsubscribedAt":{},"dormant":{"type":"boolean"},"dormantAt":{},"engagement":{"type":"object","properties":{"sent":{"type":"integer"},"opens":{"type":"integer"},"clicks":{"type":"integer"},"lastSentAt":{"type":"string","format":"date-time"},"lastOpenedAt":{"type":"string","format":"date-time"},"lastClickedAt":{"type":"string","format":"date-time"},"sendsSinceEngaged":{"type":"integer"}},"required":["sent","opens","clicks","lastSentAt","lastOpenedAt","lastClickedAt","sendsSinceEngaged"],"additionalProperties":false},"country":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"lists":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","email","name","fields","status","consent","unsubscribedAt","dormant","dormantAt","engagement","country","tags","lists","createdAt","updatedAt"],"additionalProperties":false}}},"required":["count","sample"],"additionalProperties":false},"example":{"count":42,"sample":[{"id":"ct_…","email":"ada@example.net","name":"Ada Lovelace","fields":{"plan":"pro"},"status":"subscribed","consent":{"source":"api","basis":"Ticked the newsletter box at checkout on acme.com","importId":null,"optedInAt":"2026-10-25T12:00:00.000Z","confirmedAt":null,"ip":null,"userAgent":null},"unsubscribedAt":null,"dormant":false,"dormantAt":null,"engagement":{"sent":4,"opens":3,"clicks":1,"lastSentAt":"2026-10-30T09:00:00.000Z","lastOpenedAt":"2026-10-30T09:12:00.000Z","lastClickedAt":"2026-10-30T09:13:00.000Z","sendsSinceEngaged":0},"country":"GB","tags":["VIP"],"lists":["lst_…"],"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"match":{"type":"string","enum":["all","any"],"default":"all"},"conditions":{"type":"array","maxItems":20,"items":{"type":"object","required":["field","op"],"properties":{"field":{"type":"string","description":"One of tag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as `fields.<key>` (or `field` with `key`)."},"key":{"type":"string","description":"Custom field key when `field` is `field`."},"op":{"type":"string","description":"Operator allowed for the field (see `fields` in GET /segments)."},"value":{"type":["string","number","null"],"description":"Required except for is_set, not_set, ever, and never. Day counts and numbers for in_last_days, not_in_last_days, gte, lte, gt, and lt; YYYY-MM-DD for before and after."}},"additionalProperties":false}}},"additionalProperties":false},"example":{"match":"any","conditions":[{"field":"tag","op":"has","value":"VIP"},{"field":"clicked","op":"in_last_days","value":30}]}}}}}},"/segments/{id}":{"get":{"operationId":"get_segments_id","tags":["Campaigns"],"summary":"Retrieve a segment and its live count","description":"Retrieve a segment and its live count","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"match":{"type":"string"},"conditions":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string"},"value":{}},"required":["field","op","value"],"additionalProperties":false}},"count":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","match","conditions","count","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"seg_…","name":"Engaged pro customers","match":"all","conditions":[{"field":"name","op":"is_set","value":null},{"field":"fields.plan","op":"equals","value":"pro"},{"field":"opened","op":"in_last_days","value":90}],"count":120,"createdAt":"2026-11-01T12:00:00.000Z","updatedAt":"2026-11-01T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patch_segments_id","tags":["Campaigns"],"summary":"Rename a segment or change its conditions","description":"Change `name`, `match`, or `conditions` (which replaces the whole list). Broadcasts that use the segment pick up the change when they start sending.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"match":{"type":"string"},"conditions":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string"},"value":{}},"required":["field","op","value"],"additionalProperties":false}},"count":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","match","conditions","count","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"seg_…","name":"Engaged pro customers","match":"all","conditions":[{"field":"name","op":"is_set","value":null},{"field":"fields.plan","op":"equals","value":"pro"},{"field":"opened","op":"in_last_days","value":90}],"count":120,"createdAt":"2026-11-01T12:00:00.000Z","updatedAt":"2026-11-01T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"match":{"type":"string","enum":["all","any"],"default":"all"},"conditions":{"type":"array","maxItems":20,"items":{"type":"object","required":["field","op"],"properties":{"field":{"type":"string","description":"One of tag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as `fields.<key>` (or `field` with `key`)."},"key":{"type":"string","description":"Custom field key when `field` is `field`."},"op":{"type":"string","description":"Operator allowed for the field (see `fields` in GET /segments)."},"value":{"type":["string","number","null"],"description":"Required except for is_set, not_set, ever, and never. Day counts and numbers for in_last_days, not_in_last_days, gte, lte, gt, and lt; YYYY-MM-DD for before and after."}},"additionalProperties":false}}},"additionalProperties":false},"example":{"conditions":[{"field":"fields.plan","op":"equals","value":"pro"},{"field":"opened","op":"in_last_days","value":60}]}}}}},"delete":{"operationId":"delete_segments_id","tags":["Campaigns"],"summary":"Delete a segment","description":"Returns 409 while a sending or scheduled broadcast uses the segment. Contacts are not affected.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists":{"get":{"operationId":"get_lists","tags":["Campaigns"],"summary":"List contact lists with member counts","description":"List contact lists with member counts","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"form":{"type":"object","properties":{"enabled":{"type":"boolean"},"from":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri"}},"required":["enabled","from","redirectUrl","url"],"additionalProperties":false},"counts":{"type":"object","properties":{"subscribed":{"type":"integer"},"pending":{"type":"integer"},"unsubscribed":{"type":"integer"}},"required":["subscribed","pending","unsubscribed"],"additionalProperties":false},"welcome":{"type":"object","properties":{"enabled":{"type":"boolean"},"subject":{"type":"string"},"html":{"type":"string"},"content":{}},"required":["enabled","subject","html","content"],"additionalProperties":false},"site":{"type":"object","properties":{"enabled":{"type":"boolean"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"accent":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["enabled","slug","title","description","accent","url"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","form","counts","welcome","site","createdAt","updatedAt"],"additionalProperties":false}},"count":{"type":"integer"}},"required":["data","count"],"additionalProperties":false},"example":{"data":[{"id":"lst_…","name":"Product updates","description":"Monthly news from Acme","form":{"enabled":true,"from":"Acme <news@example.com>","redirectUrl":"https://example.com/thanks","url":"https://sendhq.cc/subscribe/lst_…"},"counts":{"subscribed":0,"pending":0,"unsubscribed":0},"welcome":{"enabled":true,"subject":"Welcome to Product updates, {{first_name | friend}}","html":"<p>Thanks for subscribing.</p>","content":null},"site":{"enabled":true,"slug":"acme-updates","title":"Acme product updates","description":"Monthly news from Acme","accent":"#0a7d4f","url":"https://sendhq.cc/n/acme-updates"},"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}],"count":1}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"post_lists","tags":["Campaigns"],"summary":"Create a list with an optional signup form, welcome email, and newsletter site","description":"Create a list. Set `form_enabled` to publish a hosted double opt-in signup form at `form.url`; `form_from` is the sender (on a verified domain) of the confirmation email, and `redirect_url` is an optional https page to show after confirming. `welcome` ({ enabled, subject, and html, markdown, or a block document in content }) sends one welcome email, from `form_from`, when someone confirms. `site` ({ enabled, slug, title, description, accent }) publishes a public newsletter site at `https://sendhq.cc/n/<slug>` with a signup form, every issue sent with `web.enabled`, and an RSS feed at `/n/<slug>/feed.xml`; it needs the signup form on, and a slug that is reserved or taken returns 409. A workspace may have 100 lists.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"form":{"type":"object","properties":{"enabled":{"type":"boolean"},"from":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri"}},"required":["enabled","from","redirectUrl","url"],"additionalProperties":false},"counts":{"type":"object","properties":{"subscribed":{"type":"integer"},"pending":{"type":"integer"},"unsubscribed":{"type":"integer"}},"required":["subscribed","pending","unsubscribed"],"additionalProperties":false},"welcome":{"type":"object","properties":{"enabled":{"type":"boolean"},"subject":{"type":"string"},"html":{"type":"string"},"content":{}},"required":["enabled","subject","html","content"],"additionalProperties":false},"site":{"type":"object","properties":{"enabled":{"type":"boolean"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"accent":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["enabled","slug","title","description","accent","url"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","form","counts","welcome","site","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"lst_…","name":"Product updates","description":"Monthly news from Acme","form":{"enabled":true,"from":"Acme <news@example.com>","redirectUrl":"https://example.com/thanks","url":"https://sendhq.cc/subscribe/lst_…"},"counts":{"subscribed":0,"pending":0,"unsubscribed":0},"welcome":{"enabled":true,"subject":"Welcome to Product updates, {{first_name | friend}}","html":"<p>Thanks for subscribing.</p>","content":null},"site":{"enabled":true,"slug":"acme-updates","title":"Acme product updates","description":"Monthly news from Acme","accent":"#0a7d4f","url":"https://sendhq.cc/n/acme-updates"},"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":500},"form_enabled":{"type":"boolean"},"form_from":{"type":"string","description":"Sender of confirmation and welcome emails, on a verified domain."},"redirect_url":{"type":["string","null"],"format":"uri"},"welcome":{"type":"object","description":"Welcome email sent once when someone confirms a signup. Needs `form_from`.","properties":{"enabled":{"type":"boolean"},"subject":{"type":"string","maxLength":300},"html":{"type":"string"},"markdown":{"type":"string"},"content":{"type":["object","null"],"description":"Block document from the editor ({ type: 'doc', content: [...] }); rendered with the workspace design unless `html` is sent too."}},"additionalProperties":false},"site":{"type":"object","description":"Public newsletter site at https://sendhq.cc/n/<slug>. Needs the signup form on.","properties":{"enabled":{"type":"boolean"},"slug":{"type":["string","null"],"minLength":3,"maxLength":48},"title":{"type":["string","null"],"maxLength":120},"description":{"type":["string","null"],"maxLength":300},"accent":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$"}},"additionalProperties":false}},"additionalProperties":false,"required":["name"]},"example":{"name":"Product updates","description":"Monthly news from Acme","form_enabled":true,"form_from":"Acme <news@example.com>","redirect_url":"https://example.com/thanks","welcome":{"enabled":true,"subject":"Welcome to Product updates, {{first_name | friend}}","markdown":"Thanks for subscribing. Here is what to expect."},"site":{"enabled":true,"slug":"acme-updates","title":"Acme product updates","accent":"#0a7d4f"}}}}}}},"/lists/{id}":{"get":{"operationId":"get_lists_id","tags":["Campaigns"],"summary":"Retrieve a list","description":"Retrieve a list","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"form":{"type":"object","properties":{"enabled":{"type":"boolean"},"from":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri"}},"required":["enabled","from","redirectUrl","url"],"additionalProperties":false},"counts":{"type":"object","properties":{"subscribed":{"type":"integer"},"pending":{"type":"integer"},"unsubscribed":{"type":"integer"}},"required":["subscribed","pending","unsubscribed"],"additionalProperties":false},"welcome":{"type":"object","properties":{"enabled":{"type":"boolean"},"subject":{"type":"string"},"html":{"type":"string"},"content":{}},"required":["enabled","subject","html","content"],"additionalProperties":false},"site":{"type":"object","properties":{"enabled":{"type":"boolean"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"accent":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["enabled","slug","title","description","accent","url"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","form","counts","welcome","site","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"lst_…","name":"Product updates","description":"Monthly news from Acme","form":{"enabled":true,"from":"Acme <news@example.com>","redirectUrl":"https://example.com/thanks","url":"https://sendhq.cc/subscribe/lst_…"},"counts":{"subscribed":0,"pending":0,"unsubscribed":0},"welcome":{"enabled":true,"subject":"Welcome to Product updates, {{first_name | friend}}","html":"<p>Thanks for subscribing.</p>","content":null},"site":{"enabled":true,"slug":"acme-updates","title":"Acme product updates","description":"Monthly news from Acme","accent":"#0a7d4f","url":"https://sendhq.cc/n/acme-updates"},"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patch_lists_id","tags":["Campaigns"],"summary":"Rename a list or change its signup form, welcome email, or site","description":"Change any of the fields accepted when creating a list. Omitted fields, and omitted keys inside `welcome` and `site`, keep their current value.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"form":{"type":"object","properties":{"enabled":{"type":"boolean"},"from":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri"}},"required":["enabled","from","redirectUrl","url"],"additionalProperties":false},"counts":{"type":"object","properties":{"subscribed":{"type":"integer"},"pending":{"type":"integer"},"unsubscribed":{"type":"integer"}},"required":["subscribed","pending","unsubscribed"],"additionalProperties":false},"welcome":{"type":"object","properties":{"enabled":{"type":"boolean"},"subject":{"type":"string"},"html":{"type":"string"},"content":{}},"required":["enabled","subject","html","content"],"additionalProperties":false},"site":{"type":"object","properties":{"enabled":{"type":"boolean"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"accent":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["enabled","slug","title","description","accent","url"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","form","counts","welcome","site","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"lst_…","name":"Product updates","description":"Monthly news from Acme","form":{"enabled":true,"from":"Acme <news@example.com>","redirectUrl":"https://example.com/thanks","url":"https://sendhq.cc/subscribe/lst_…"},"counts":{"subscribed":0,"pending":0,"unsubscribed":0},"welcome":{"enabled":true,"subject":"Welcome to Product updates, {{first_name | friend}}","html":"<p>Thanks for subscribing.</p>","content":null},"site":{"enabled":true,"slug":"acme-updates","title":"Acme product updates","description":"Monthly news from Acme","accent":"#0a7d4f","url":"https://sendhq.cc/n/acme-updates"},"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":500},"form_enabled":{"type":"boolean"},"form_from":{"type":"string","description":"Sender of confirmation and welcome emails, on a verified domain."},"redirect_url":{"type":["string","null"],"format":"uri"},"welcome":{"type":"object","description":"Welcome email sent once when someone confirms a signup. Needs `form_from`.","properties":{"enabled":{"type":"boolean"},"subject":{"type":"string","maxLength":300},"html":{"type":"string"},"markdown":{"type":"string"},"content":{"type":["object","null"],"description":"Block document from the editor ({ type: 'doc', content: [...] }); rendered with the workspace design unless `html` is sent too."}},"additionalProperties":false},"site":{"type":"object","description":"Public newsletter site at https://sendhq.cc/n/<slug>. Needs the signup form on.","properties":{"enabled":{"type":"boolean"},"slug":{"type":["string","null"],"minLength":3,"maxLength":48},"title":{"type":["string","null"],"maxLength":120},"description":{"type":["string","null"],"maxLength":300},"accent":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$"}},"additionalProperties":false}},"additionalProperties":false},"example":{"name":"Product news","site":{"enabled":false}}}}}},"delete":{"operationId":"delete_lists_id","tags":["Campaigns"],"summary":"Delete a list without deleting its contacts","description":"Removes the list and its memberships. Returns 409 while a broadcast to the list is sending.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists/{id}/contacts":{"post":{"operationId":"post_lists_id_contacts","tags":["Campaigns"],"summary":"Add existing contacts to a list","description":"Add up to 500 existing contacts by `contact_ids` or `emails`. Each membership mirrors the contact: subscribed contacts join subscribed, others join in their current state. Unknown references are returned in `notFound`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"listId":{"type":"string"},"added":{"type":"integer"},"notFound":{"type":"array","items":{}},"list":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"form":{"type":"object","properties":{"enabled":{"type":"boolean"},"from":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri"}},"required":["enabled","from","redirectUrl","url"],"additionalProperties":false},"counts":{"type":"object","properties":{"subscribed":{"type":"integer"},"pending":{"type":"integer"},"unsubscribed":{"type":"integer"}},"required":["subscribed","pending","unsubscribed"],"additionalProperties":false},"welcome":{"type":"object","properties":{"enabled":{"type":"boolean"},"subject":{"type":"string"},"html":{"type":"string"},"content":{}},"required":["enabled","subject","html","content"],"additionalProperties":false},"site":{"type":"object","properties":{"enabled":{"type":"boolean"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"accent":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["enabled","slug","title","description","accent","url"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","form","counts","welcome","site","createdAt","updatedAt"],"additionalProperties":false}},"required":["listId","added","notFound","list"],"additionalProperties":false},"example":{"listId":"lst_…","added":1,"notFound":[],"list":{"id":"lst_…","name":"Product updates","description":"Monthly news from Acme","form":{"enabled":true,"from":"Acme <news@example.com>","redirectUrl":"https://example.com/thanks","url":"https://sendhq.cc/subscribe/lst_…"},"counts":{"subscribed":0,"pending":0,"unsubscribed":0},"welcome":{"enabled":true,"subject":"Welcome to Product updates, {{first_name | friend}}","html":"<p>Thanks for subscribing.</p>","content":null},"site":{"enabled":true,"slug":"acme-updates","title":"Acme product updates","description":"Monthly news from Acme","accent":"#0a7d4f","url":"https://sendhq.cc/n/acme-updates"},"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"emails":{"type":"array","items":{"type":"string","format":"email"}}},"required":["emails"],"additionalProperties":false},"example":{"emails":["ada@example.net"]}}}}}},"/lists/{id}/contacts/{contact_id}":{"delete":{"operationId":"delete_lists_id_contacts_contact_id","tags":["Campaigns"],"summary":"Remove a contact from a list","description":"Remove a contact from a list","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/broadcasts":{"get":{"operationId":"get_broadcasts","tags":["Campaigns"],"summary":"List broadcasts","description":"List broadcasts","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","sending","sent","cancelled","failed"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"listId":{"type":"string"},"from":{"type":"string"},"replyTo":{},"subject":{"type":"string"},"previewText":{"type":"string"},"html":{"type":"string"},"text":{},"template":{},"audience":{"type":"object","properties":{"segmentId":{},"order":{"type":"string"},"limit":{}},"required":["segmentId","order","limit"],"additionalProperties":false},"tracking":{"type":"object","properties":{"opens":{"type":"boolean"},"clicks":{"type":"boolean"}},"required":["opens","clicks"],"additionalProperties":false},"editor":{"type":"string"},"content":{},"testSentAt":{},"web":{"type":"object","properties":{"enabled":{"type":"boolean"},"slug":{},"pinned":{"type":"boolean"},"publishedAt":{}},"required":["enabled","slug","pinned","publishedAt"],"additionalProperties":false},"scheduledAt":{},"startedAt":{},"completedAt":{},"nextAttemptAt":{},"lastError":{},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","status","listId","from","replyTo","subject","previewText","html","text","template","audience","tracking","editor","content","testSentAt","web","scheduledAt","startedAt","completedAt","nextAttemptAt","lastError","createdAt","updatedAt"],"additionalProperties":false}},"count":{"type":"integer"}},"required":["data","count"],"additionalProperties":false},"example":{"data":[{"id":"bc_…","name":"October update","status":"draft","listId":"lst_…","from":"Acme <news@example.com>","replyTo":null,"subject":"What's new in October, {{first_name | friend}}","previewText":"Three new features and a roadmap peek","html":"<p>Hi {{first_name | there}},</p>","text":null,"template":null,"audience":{"segmentId":null,"order":"signup","limit":null},"tracking":{"opens":true,"clicks":true},"editor":"html","content":null,"testSentAt":null,"web":{"enabled":false,"slug":null,"pinned":false,"publishedAt":null},"scheduledAt":null,"startedAt":null,"completedAt":null,"nextAttemptAt":null,"lastError":null,"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}],"count":1}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"post_broadcasts","tags":["Campaigns"],"summary":"Create a broadcast draft","description":"Create a draft for one list: `from` on a verified domain, `subject`, optional `preview_text`, and content as `html` and/or `text`, `markdown`, a block document in `content`, or a published hosted `template` ({id or key, optional version_id}). Markdown and block content are rendered with the workspace design (newsletter settings). Raw content supports merge tags such as `{{first_name}}`, `{{fields.plan}}`, and fallbacks like `{{first_name | there}}`; HTML values are escaped. `audience` narrows who gets it: `segment_id` (only list members matching a segment), `limit` (at most this many people), and `order` (`signup`, or `engaged` for most engaged first). `tracking` turns open and click tracking on or off (both on by default). `web.enabled` publishes the issue on the list's newsletter site once it is sent. To send later, create the draft, then call POST /broadcasts/{id}/schedule; `scheduled_at` is not accepted here.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"listId":{"type":"string"},"from":{"type":"string"},"replyTo":{},"subject":{"type":"string"},"previewText":{"type":"string"},"html":{"type":"string"},"text":{},"template":{},"audience":{"type":"object","properties":{"segmentId":{},"order":{"type":"string"},"limit":{}},"required":["segmentId","order","limit"],"additionalProperties":false},"tracking":{"type":"object","properties":{"opens":{"type":"boolean"},"clicks":{"type":"boolean"}},"required":["opens","clicks"],"additionalProperties":false},"editor":{"type":"string"},"content":{},"testSentAt":{},"web":{"type":"object","properties":{"enabled":{"type":"boolean"},"slug":{},"pinned":{"type":"boolean"},"publishedAt":{}},"required":["enabled","slug","pinned","publishedAt"],"additionalProperties":false},"scheduledAt":{},"startedAt":{},"completedAt":{},"nextAttemptAt":{},"lastError":{},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","status","listId","from","replyTo","subject","previewText","html","text","template","audience","tracking","editor","content","testSentAt","web","scheduledAt","startedAt","completedAt","nextAttemptAt","lastError","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"bc_…","name":"October update","status":"draft","listId":"lst_…","from":"Acme <news@example.com>","replyTo":null,"subject":"What's new in October, {{first_name | friend}}","previewText":"Three new features and a roadmap peek","html":"<p>Hi {{first_name | there}},</p>","text":null,"template":null,"audience":{"segmentId":null,"order":"signup","limit":null},"tracking":{"opens":true,"clicks":true},"editor":"html","content":null,"testSentAt":null,"web":{"enabled":false,"slug":null,"pinned":false,"publishedAt":null},"scheduledAt":null,"startedAt":null,"completedAt":null,"nextAttemptAt":null,"lastError":null,"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"list_id":{"type":"string"},"from":{"type":"string","description":"Sender on a verified workspace domain."},"reply_to":{"type":"string"},"subject":{"type":"string","maxLength":998},"preview_text":{"type":"string","maxLength":300},"html":{"type":"string"},"text":{"type":"string"},"markdown":{"type":"string","description":"Markdown body, converted to a block document rendered with the workspace design. Not combinable with `html` or `content`."},"editor":{"type":"string","enum":["html","blocks"]},"content":{"type":["object","null"],"description":"Block document ({ type: 'doc', content: [...] }) as the dashboard editor stores it. Without `html`, it is rendered with the workspace design."},"template":{"type":["object","null"],"properties":{"id":{"type":"string"},"key":{"type":"string"},"version_id":{"type":"string"}},"additionalProperties":false},"audience":{"type":"object","properties":{"segment_id":{"type":["string","null"],"description":"Only list members matching this segment."},"order":{"type":"string","enum":["signup","engaged"],"default":"signup","description":"Who goes first when `limit` is set: signup order, or most engaged first."},"limit":{"type":["integer","null"],"minimum":1,"maximum":10000000,"description":"Send to at most this many people; null for everyone."}},"additionalProperties":false},"tracking":{"type":"object","properties":{"opens":{"type":"boolean","default":true},"clicks":{"type":"boolean","default":true}},"additionalProperties":false},"track_opens":{"type":"boolean"},"track_clicks":{"type":"boolean"},"web":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Publish this issue on the list's newsletter site once it is sent."},"slug":{"type":["string","null"],"description":"Issue address; defaults to the subject."},"pinned":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false},"example":{"name":"October update","list_id":"lst_…","from":"Acme <news@example.com>","subject":"What's new in October, {{first_name | friend}}","preview_text":"Three new features and a roadmap peek","html":"<p>Hi {{first_name | there}},</p><p>Here's what shipped.</p>","audience":{"segment_id":"seg_…","order":"engaged","limit":1000},"tracking":{"opens":true,"clicks":true}}}}}}},"/broadcasts/{id}":{"get":{"operationId":"get_broadcasts_id","tags":["Campaigns"],"summary":"Retrieve a broadcast and its delivery totals","description":"Retrieve a broadcast and its delivery totals","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"listId":{"type":"string"},"from":{"type":"string"},"replyTo":{},"subject":{"type":"string"},"previewText":{"type":"string"},"html":{"type":"string"},"text":{},"template":{},"audience":{"type":"object","properties":{"segmentId":{},"order":{"type":"string"},"limit":{}},"required":["segmentId","order","limit"],"additionalProperties":false},"tracking":{"type":"object","properties":{"opens":{"type":"boolean"},"clicks":{"type":"boolean"}},"required":["opens","clicks"],"additionalProperties":false},"editor":{"type":"string"},"content":{},"testSentAt":{},"web":{"type":"object","properties":{"enabled":{"type":"boolean"},"slug":{},"pinned":{"type":"boolean"},"publishedAt":{}},"required":["enabled","slug","pinned","publishedAt"],"additionalProperties":false},"scheduledAt":{},"startedAt":{},"completedAt":{},"nextAttemptAt":{},"lastError":{},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"totals":{"type":"object","properties":{"queued":{"type":"integer"},"sending":{"type":"integer"},"sent":{"type":"integer"},"held":{"type":"integer"},"skipped":{"type":"integer"},"failed":{"type":"integer"},"total":{"type":"integer"}},"required":["queued","sending","sent","held","skipped","failed","total"],"additionalProperties":false}},"required":["id","name","status","listId","from","replyTo","subject","previewText","html","text","template","audience","tracking","editor","content","testSentAt","web","scheduledAt","startedAt","completedAt","nextAttemptAt","lastError","createdAt","updatedAt","totals"],"additionalProperties":false},"example":{"id":"bc_…","name":"October update","status":"sending","listId":"lst_…","from":"Acme <news@example.com>","replyTo":null,"subject":"What's new in October, {{first_name | friend}}","previewText":"Three new features and a roadmap peek","html":"<p>Hi {{first_name | there}},</p>","text":null,"template":null,"audience":{"segmentId":null,"order":"signup","limit":null},"tracking":{"opens":true,"clicks":true},"editor":"html","content":null,"testSentAt":null,"web":{"enabled":false,"slug":null,"pinned":false,"publishedAt":null},"scheduledAt":null,"startedAt":null,"completedAt":null,"nextAttemptAt":null,"lastError":null,"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z","totals":{"queued":0,"sending":0,"sent":0,"held":0,"skipped":0,"failed":0,"total":0}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patch_broadcasts_id","tags":["Campaigns"],"summary":"Edit a draft broadcast","description":"Change any field accepted when creating a broadcast. Only unscheduled drafts can be edited: a scheduled draft returns 409 until it is unscheduled.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"listId":{"type":"string"},"from":{"type":"string"},"replyTo":{},"subject":{"type":"string"},"previewText":{"type":"string"},"html":{"type":"string"},"text":{},"template":{},"audience":{"type":"object","properties":{"segmentId":{},"order":{"type":"string"},"limit":{}},"required":["segmentId","order","limit"],"additionalProperties":false},"tracking":{"type":"object","properties":{"opens":{"type":"boolean"},"clicks":{"type":"boolean"}},"required":["opens","clicks"],"additionalProperties":false},"editor":{"type":"string"},"content":{},"testSentAt":{},"web":{"type":"object","properties":{"enabled":{"type":"boolean"},"slug":{},"pinned":{"type":"boolean"},"publishedAt":{}},"required":["enabled","slug","pinned","publishedAt"],"additionalProperties":false},"scheduledAt":{},"startedAt":{},"completedAt":{},"nextAttemptAt":{},"lastError":{},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","status","listId","from","replyTo","subject","previewText","html","text","template","audience","tracking","editor","content","testSentAt","web","scheduledAt","startedAt","completedAt","nextAttemptAt","lastError","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"bc_…","name":"October update","status":"draft","listId":"lst_…","from":"Acme <news@example.com>","replyTo":null,"subject":"What's new in October, {{first_name | friend}}","previewText":"Three new features and a roadmap peek","html":"<p>Hi {{first_name | there}},</p>","text":null,"template":null,"audience":{"segmentId":null,"order":"signup","limit":null},"tracking":{"opens":true,"clicks":true},"editor":"html","content":null,"testSentAt":null,"web":{"enabled":false,"slug":null,"pinned":false,"publishedAt":null},"scheduledAt":null,"startedAt":null,"completedAt":null,"nextAttemptAt":null,"lastError":null,"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"list_id":{"type":"string"},"from":{"type":"string","description":"Sender on a verified workspace domain."},"reply_to":{"type":"string"},"subject":{"type":"string","maxLength":998},"preview_text":{"type":"string","maxLength":300},"html":{"type":"string"},"text":{"type":"string"},"markdown":{"type":"string","description":"Markdown body, converted to a block document rendered with the workspace design. Not combinable with `html` or `content`."},"editor":{"type":"string","enum":["html","blocks"]},"content":{"type":["object","null"],"description":"Block document ({ type: 'doc', content: [...] }) as the dashboard editor stores it. Without `html`, it is rendered with the workspace design."},"template":{"type":["object","null"],"properties":{"id":{"type":"string"},"key":{"type":"string"},"version_id":{"type":"string"}},"additionalProperties":false},"audience":{"type":"object","properties":{"segment_id":{"type":["string","null"],"description":"Only list members matching this segment."},"order":{"type":"string","enum":["signup","engaged"],"default":"signup","description":"Who goes first when `limit` is set: signup order, or most engaged first."},"limit":{"type":["integer","null"],"minimum":1,"maximum":10000000,"description":"Send to at most this many people; null for everyone."}},"additionalProperties":false},"tracking":{"type":"object","properties":{"opens":{"type":"boolean","default":true},"clicks":{"type":"boolean","default":true}},"additionalProperties":false},"track_opens":{"type":"boolean"},"track_clicks":{"type":"boolean"},"web":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Publish this issue on the list's newsletter site once it is sent."},"slug":{"type":["string","null"],"description":"Issue address; defaults to the subject."},"pinned":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false},"example":{"subject":"October product update","audience":{"limit":null}}}}}},"delete":{"operationId":"delete_broadcasts_id","tags":["Campaigns"],"summary":"Delete a draft broadcast","description":"Deletes a draft, including a scheduled one. Sent and sending broadcasts cannot be deleted.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/broadcasts/{id}/checks":{"get":{"operationId":"get_broadcasts_id_checks","tags":["Campaigns"],"summary":"Run the pre-send checks for a broadcast","description":"The review list the dashboard shows before sending: sender verification, subject, preview text, content, audience size, email size against Gmail's 102 KB clipping limit, postal address, merge tags without data or fallback, empty or shortened links, missing image descriptions, leftover placeholder text, spam-prone wording, an active subscription, and whether a test was sent. Each check has a `level` (`ok`, `warn`, or `block`); `ready` is false while any check blocks. Scheduling runs the same checks.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ready":{"type":"boolean"},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"level":{"type":"string"},"label":{"type":"string"},"detail":{"type":"string"},"tab":{"type":"string"}},"required":["id","level","label","detail","tab"],"additionalProperties":false}},"audience":{"type":"object","properties":{"total":{"type":"integer"},"matching":{"type":"integer"}},"required":["total","matching"],"additionalProperties":false}},"required":["ready","checks","audience"],"additionalProperties":false},"example":{"ready":true,"checks":[{"id":"from","level":"ok","label":"From address","detail":"Acme <news@example.com>","tab":"content"}],"audience":{"total":1200,"matching":1200}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/broadcasts/{id}/test":{"post":{"operationId":"post_broadcasts_id_test","tags":["Campaigns"],"summary":"Send a test copy of a draft","description":"Sends a copy marked `[Test]` to up to 5 addresses in `to` (default: the saved test recipients, or the account email), with merge tags filled from `contact_id` or a sample contact. Test sends go through the normal send checks, never reach the list, and are limited to 100 a day per workspace. `remember: true` saves `to` as the default test recipients. Template broadcasts are tested from their template. Returns 201 with one result per address, or 422 when every address failed.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"to":{"type":"string","format":"email"},"id":{"type":"string"},"status":{"type":"string"}},"required":["to","id","status"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"example":{"data":[{"to":"owner@example.com","id":"em_…","status":"sent"}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string","format":"email"}},"contact_id":{"type":"string"},"remember":{"type":"boolean"}},"required":["to","contact_id","remember"],"additionalProperties":false},"example":{"to":["owner@example.com"],"contact_id":"ct_…","remember":true}}}}}},"/broadcasts/{id}/schedule":{"post":{"operationId":"post_broadcasts_id_schedule","tags":["Campaigns"],"summary":"Schedule a draft to send later","description":"Sets `scheduled_at` (ISO 8601, at least a minute and at most a year ahead) on a draft. The pre-send checks and plan rules run now: a blocking check returns 422 with `checks`. The broadcast starts within about a minute of its time; if it can no longer send then (for example the sender lost verification), it returns to an unscheduled draft with the reason in `lastError`. A scheduled draft cannot be edited or sent now until it is unscheduled.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"listId":{"type":"string"},"from":{"type":"string"},"replyTo":{},"subject":{"type":"string"},"previewText":{"type":"string"},"html":{"type":"string"},"text":{},"template":{},"audience":{"type":"object","properties":{"segmentId":{},"order":{"type":"string"},"limit":{}},"required":["segmentId","order","limit"],"additionalProperties":false},"tracking":{"type":"object","properties":{"opens":{"type":"boolean"},"clicks":{"type":"boolean"}},"required":["opens","clicks"],"additionalProperties":false},"editor":{"type":"string"},"content":{},"testSentAt":{},"web":{"type":"object","properties":{"enabled":{"type":"boolean"},"slug":{},"pinned":{"type":"boolean"},"publishedAt":{}},"required":["enabled","slug","pinned","publishedAt"],"additionalProperties":false},"scheduledAt":{"type":"string","format":"date-time"},"startedAt":{},"completedAt":{},"nextAttemptAt":{},"lastError":{},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","status","listId","from","replyTo","subject","previewText","html","text","template","audience","tracking","editor","content","testSentAt","web","scheduledAt","startedAt","completedAt","nextAttemptAt","lastError","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"bc_…","name":"October update","status":"draft","listId":"lst_…","from":"Acme <news@example.com>","replyTo":null,"subject":"What's new in October, {{first_name | friend}}","previewText":"Three new features and a roadmap peek","html":"<p>Hi {{first_name | there}},</p>","text":null,"template":null,"audience":{"segmentId":null,"order":"signup","limit":null},"tracking":{"opens":true,"clicks":true},"editor":"html","content":null,"testSentAt":null,"web":{"enabled":false,"slug":null,"pinned":false,"publishedAt":null},"scheduledAt":"2026-11-10T09:00:00.000Z","startedAt":null,"completedAt":null,"nextAttemptAt":null,"lastError":null,"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scheduled_at":{"type":"string","format":"date-time"}},"required":["scheduled_at"],"additionalProperties":false},"example":{"scheduled_at":"2026-11-10T09:00:00.000Z"}}}}}},"/broadcasts/{id}/unschedule":{"post":{"operationId":"post_broadcasts_id_unschedule","tags":["Campaigns"],"summary":"Unschedule a draft","description":"Returns a scheduled draft to an editable, unscheduled draft. Returns 409 when it is not scheduled.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"listId":{"type":"string"},"from":{"type":"string"},"replyTo":{},"subject":{"type":"string"},"previewText":{"type":"string"},"html":{"type":"string"},"text":{},"template":{},"audience":{"type":"object","properties":{"segmentId":{},"order":{"type":"string"},"limit":{}},"required":["segmentId","order","limit"],"additionalProperties":false},"tracking":{"type":"object","properties":{"opens":{"type":"boolean"},"clicks":{"type":"boolean"}},"required":["opens","clicks"],"additionalProperties":false},"editor":{"type":"string"},"content":{},"testSentAt":{},"web":{"type":"object","properties":{"enabled":{"type":"boolean"},"slug":{},"pinned":{"type":"boolean"},"publishedAt":{}},"required":["enabled","slug","pinned","publishedAt"],"additionalProperties":false},"scheduledAt":{},"startedAt":{},"completedAt":{},"nextAttemptAt":{},"lastError":{},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","status","listId","from","replyTo","subject","previewText","html","text","template","audience","tracking","editor","content","testSentAt","web","scheduledAt","startedAt","completedAt","nextAttemptAt","lastError","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"bc_…","name":"October update","status":"draft","listId":"lst_…","from":"Acme <news@example.com>","replyTo":null,"subject":"What's new in October, {{first_name | friend}}","previewText":"Three new features and a roadmap peek","html":"<p>Hi {{first_name | there}},</p>","text":null,"template":null,"audience":{"segmentId":null,"order":"signup","limit":null},"tracking":{"opens":true,"clicks":true},"editor":"html","content":null,"testSentAt":null,"web":{"enabled":false,"slug":null,"pinned":false,"publishedAt":null},"scheduledAt":null,"startedAt":null,"completedAt":null,"nextAttemptAt":null,"lastError":null,"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/broadcasts/{id}/duplicate":{"post":{"operationId":"post_broadcasts_id_duplicate","tags":["Campaigns"],"summary":"Copy a broadcast into a new draft","description":"Creates a new draft named `<name> (copy)` with the same list, sender, content, audience, and tracking settings. Works for a broadcast in any state.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"listId":{"type":"string"},"from":{"type":"string"},"replyTo":{},"subject":{"type":"string"},"previewText":{"type":"string"},"html":{"type":"string"},"text":{},"template":{},"audience":{"type":"object","properties":{"segmentId":{},"order":{"type":"string"},"limit":{}},"required":["segmentId","order","limit"],"additionalProperties":false},"tracking":{"type":"object","properties":{"opens":{"type":"boolean"},"clicks":{"type":"boolean"}},"required":["opens","clicks"],"additionalProperties":false},"editor":{"type":"string"},"content":{},"testSentAt":{},"web":{"type":"object","properties":{"enabled":{"type":"boolean"},"slug":{},"pinned":{"type":"boolean"},"publishedAt":{}},"required":["enabled","slug","pinned","publishedAt"],"additionalProperties":false},"scheduledAt":{},"startedAt":{},"completedAt":{},"nextAttemptAt":{},"lastError":{},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","status","listId","from","replyTo","subject","previewText","html","text","template","audience","tracking","editor","content","testSentAt","web","scheduledAt","startedAt","completedAt","nextAttemptAt","lastError","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"bc_…","name":"October update (copy)","status":"draft","listId":"lst_…","from":"Acme <news@example.com>","replyTo":null,"subject":"What's new in October, {{first_name | friend}}","previewText":"Three new features and a roadmap peek","html":"<p>Hi {{first_name | there}},</p>","text":null,"template":null,"audience":{"segmentId":null,"order":"signup","limit":null},"tracking":{"opens":true,"clicks":true},"editor":"html","content":null,"testSentAt":null,"web":{"enabled":false,"slug":null,"pinned":false,"publishedAt":null},"scheduledAt":null,"startedAt":null,"completedAt":null,"nextAttemptAt":null,"lastError":null,"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/broadcasts/{id}/send":{"post":{"operationId":"post_broadcasts_id_send","tags":["Campaigns"],"summary":"Send a broadcast to its audience","description":"Snapshot the broadcast's audience (the list's subscribed, non-dormant members, narrowed by its segment and limit, most engaged first when `audience.order` is `engaged`) and send one message to each in the background. Every message goes through the normal send checks: verified domain, an active subscription (an unpaid workspace cannot send, including to the account email or a mailbox simulator), suppressions, unsubscribes, sender reputation, and daily and monthly limits, and carries one-click List-Unsubscribe headers that remove the recipient from this list only (the unsubscribe page also offers leaving all marketing email; receipts and other transactional mail are never blocked) and the postal address from newsletter settings. With tracking on, links are rewritten to signed SendHQ redirects and an open pixel is added; the unsubscribe link is never rewritten. Members that cannot be mailed are recorded as skipped. Each contact is sent at most once per broadcast. When a limit or a reputation pause stops delivery, the broadcast keeps `sending` and resumes after `nextAttemptAt`. A scheduled draft returns 409 until it is unscheduled. Returns 202.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Stable for one logical request. Reuse with an identical JSON body; changed bodies return 409."}],"responses":{"202":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"listId":{"type":"string"},"from":{"type":"string"},"replyTo":{},"subject":{"type":"string"},"previewText":{"type":"string"},"html":{"type":"string"},"text":{},"template":{},"audience":{"type":"object","properties":{"segmentId":{},"order":{"type":"string"},"limit":{}},"required":["segmentId","order","limit"],"additionalProperties":false},"tracking":{"type":"object","properties":{"opens":{"type":"boolean"},"clicks":{"type":"boolean"}},"required":["opens","clicks"],"additionalProperties":false},"editor":{"type":"string"},"content":{},"testSentAt":{},"web":{"type":"object","properties":{"enabled":{"type":"boolean"},"slug":{},"pinned":{"type":"boolean"},"publishedAt":{}},"required":["enabled","slug","pinned","publishedAt"],"additionalProperties":false},"scheduledAt":{},"startedAt":{},"completedAt":{},"nextAttemptAt":{},"lastError":{},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"totals":{"type":"object","properties":{"queued":{"type":"integer"},"sending":{"type":"integer"},"sent":{"type":"integer"},"held":{"type":"integer"},"skipped":{"type":"integer"},"failed":{"type":"integer"},"total":{"type":"integer"}},"required":["queued","sending","sent","held","skipped","failed","total"],"additionalProperties":false}},"required":["id","name","status","listId","from","replyTo","subject","previewText","html","text","template","audience","tracking","editor","content","testSentAt","web","scheduledAt","startedAt","completedAt","nextAttemptAt","lastError","createdAt","updatedAt","totals"],"additionalProperties":false},"example":{"id":"bc_…","name":"October update","status":"sending","listId":"lst_…","from":"Acme <news@example.com>","replyTo":null,"subject":"What's new in October, {{first_name | friend}}","previewText":"Three new features and a roadmap peek","html":"<p>Hi {{first_name | there}},</p>","text":null,"template":null,"audience":{"segmentId":null,"order":"signup","limit":null},"tracking":{"opens":true,"clicks":true},"editor":"html","content":null,"testSentAt":null,"web":{"enabled":false,"slug":null,"pinned":false,"publishedAt":null},"scheduledAt":null,"startedAt":null,"completedAt":null,"nextAttemptAt":null,"lastError":null,"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z","totals":{"queued":0,"sending":0,"sent":0,"held":0,"skipped":0,"failed":0,"total":0}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/broadcasts/{id}/send-more":{"post":{"operationId":"post_broadcasts_id_send_more","tags":["Campaigns"],"summary":"Send a sent broadcast to more of its audience","description":"Sends a sent or sending broadcast to up to `limit` more people in its audience who have not received it yet, in the broadcast's audience order: the rest of a limited audience, or people who joined the list since. The same send checks apply, and each contact still gets it at most once. Returns 202 with how many were `added`, or 422 when everyone in the audience already got it.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Stable for one logical request. Reuse with an identical JSON body; changed bodies return 409."}],"responses":{"202":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"added":{"type":"integer"},"broadcast":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"listId":{"type":"string"},"from":{"type":"string"},"replyTo":{},"subject":{"type":"string"},"previewText":{"type":"string"},"html":{"type":"string"},"text":{},"template":{},"audience":{"type":"object","properties":{"segmentId":{},"order":{"type":"string"},"limit":{}},"required":["segmentId","order","limit"],"additionalProperties":false},"tracking":{"type":"object","properties":{"opens":{"type":"boolean"},"clicks":{"type":"boolean"}},"required":["opens","clicks"],"additionalProperties":false},"editor":{"type":"string"},"content":{},"testSentAt":{},"web":{"type":"object","properties":{"enabled":{"type":"boolean"},"slug":{},"pinned":{"type":"boolean"},"publishedAt":{}},"required":["enabled","slug","pinned","publishedAt"],"additionalProperties":false},"scheduledAt":{},"startedAt":{},"completedAt":{},"nextAttemptAt":{},"lastError":{},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"totals":{"type":"object","properties":{"queued":{"type":"integer"},"sending":{"type":"integer"},"sent":{"type":"integer"},"held":{"type":"integer"},"skipped":{"type":"integer"},"failed":{"type":"integer"},"total":{"type":"integer"}},"required":["queued","sending","sent","held","skipped","failed","total"],"additionalProperties":false}},"required":["id","name","status","listId","from","replyTo","subject","previewText","html","text","template","audience","tracking","editor","content","testSentAt","web","scheduledAt","startedAt","completedAt","nextAttemptAt","lastError","createdAt","updatedAt","totals"],"additionalProperties":false}},"required":["added","broadcast"],"additionalProperties":false},"example":{"added":500,"broadcast":{"id":"bc_…","name":"October update","status":"sending","listId":"lst_…","from":"Acme <news@example.com>","replyTo":null,"subject":"What's new in October, {{first_name | friend}}","previewText":"Three new features and a roadmap peek","html":"<p>Hi {{first_name | there}},</p>","text":null,"template":null,"audience":{"segmentId":null,"order":"signup","limit":null},"tracking":{"opens":true,"clicks":true},"editor":"html","content":null,"testSentAt":null,"web":{"enabled":false,"slug":null,"pinned":false,"publishedAt":null},"scheduledAt":null,"startedAt":null,"completedAt":null,"nextAttemptAt":null,"lastError":null,"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z","totals":{"queued":0,"sending":0,"sent":0,"held":0,"skipped":0,"failed":0,"total":0}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer"}},"required":["limit"],"additionalProperties":false},"example":{"limit":500}}}}}},"/broadcasts/{id}/cancel":{"post":{"operationId":"post_broadcasts_id_cancel","tags":["Campaigns"],"summary":"Cancel a draft or sending broadcast","description":"Stops a broadcast: recipients not yet sent are marked skipped (`cancelled`). Messages already handed to the provider are not recalled.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"listId":{"type":"string"},"from":{"type":"string"},"replyTo":{},"subject":{"type":"string"},"previewText":{"type":"string"},"html":{"type":"string"},"text":{},"template":{},"audience":{"type":"object","properties":{"segmentId":{},"order":{"type":"string"},"limit":{}},"required":["segmentId","order","limit"],"additionalProperties":false},"tracking":{"type":"object","properties":{"opens":{"type":"boolean"},"clicks":{"type":"boolean"}},"required":["opens","clicks"],"additionalProperties":false},"editor":{"type":"string"},"content":{},"testSentAt":{},"web":{"type":"object","properties":{"enabled":{"type":"boolean"},"slug":{},"pinned":{"type":"boolean"},"publishedAt":{}},"required":["enabled","slug","pinned","publishedAt"],"additionalProperties":false},"scheduledAt":{},"startedAt":{},"completedAt":{},"nextAttemptAt":{},"lastError":{},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"totals":{"type":"object","properties":{"queued":{"type":"integer"},"sending":{"type":"integer"},"sent":{"type":"integer"},"held":{"type":"integer"},"skipped":{"type":"integer"},"failed":{"type":"integer"},"total":{"type":"integer"}},"required":["queued","sending","sent","held","skipped","failed","total"],"additionalProperties":false}},"required":["id","name","status","listId","from","replyTo","subject","previewText","html","text","template","audience","tracking","editor","content","testSentAt","web","scheduledAt","startedAt","completedAt","nextAttemptAt","lastError","createdAt","updatedAt","totals"],"additionalProperties":false},"example":{"id":"bc_…","name":"October update","status":"cancelled","listId":"lst_…","from":"Acme <news@example.com>","replyTo":null,"subject":"What's new in October, {{first_name | friend}}","previewText":"Three new features and a roadmap peek","html":"<p>Hi {{first_name | there}},</p>","text":null,"template":null,"audience":{"segmentId":null,"order":"signup","limit":null},"tracking":{"opens":true,"clicks":true},"editor":"html","content":null,"testSentAt":null,"web":{"enabled":false,"slug":null,"pinned":false,"publishedAt":null},"scheduledAt":null,"startedAt":null,"completedAt":null,"nextAttemptAt":null,"lastError":null,"createdAt":"2026-10-25T12:00:00.000Z","updatedAt":"2026-10-25T12:00:00.000Z","totals":{"queued":0,"sending":0,"sent":0,"held":0,"skipped":0,"failed":0,"total":0}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/broadcasts/{id}/recipients":{"get":{"operationId":"get_broadcasts_id_recipients","tags":["Campaigns"],"summary":"List a broadcast's recipients, outcomes, and engagement","description":"Per-recipient outcome (`queued`, `sending`, `sent`, `held`, `skipped` with a reason, or `failed` with the error), the email ID for delivery events, the inbox provider, and delivery, open, click, bounce, complaint, and unsubscribe times. Filter by `status`, by `activity` (`opened`, `clicked`, `not_opened`, `not_delivered`, `bounced`, `complained`, `unsubscribed`), or by an email substring in `query`. `include=links` (implied by `activity=clicked`) adds the links each recipient clicked. Opens are estimates and bot-filtered; they never prove that someone read the message.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["queued","sending","sent","held","skipped","failed"]}},{"name":"activity","in":"query","required":false,"schema":{"type":"string","enum":["opened","clicked","not_opened","not_delivered","bounced","complained","unsubscribed"]}},{"name":"query","in":"query","required":false,"schema":{"type":"string"}},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["links"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"contactId":{"type":"string"},"email":{"type":"string","format":"email"},"status":{"type":"string"},"skipReason":{},"emailId":{"type":"string"},"error":{},"attempts":{"type":"integer"},"sentAt":{"type":"string","format":"date-time"},"provider":{"type":"string"},"deliveredAt":{"type":"string","format":"date-time"},"openedAt":{"type":"string","format":"date-time"},"clickedAt":{},"opens":{"type":"integer"},"clicks":{"type":"integer"},"bouncedAt":{},"complainedAt":{},"unsubscribedAt":{}},"required":["contactId","email","status","skipReason","emailId","error","attempts","sentAt","provider","deliveredAt","openedAt","clickedAt","opens","clicks","bouncedAt","complainedAt","unsubscribedAt"],"additionalProperties":false}},"count":{"type":"integer"},"totals":{"type":"object","properties":{"queued":{"type":"integer"},"sending":{"type":"integer"},"sent":{"type":"integer"},"held":{"type":"integer"},"skipped":{"type":"integer"},"failed":{"type":"integer"},"total":{"type":"integer"}},"required":["queued","sending","sent","held","skipped","failed","total"],"additionalProperties":false}},"required":["data","count","totals"],"additionalProperties":false},"example":{"data":[{"contactId":"ct_…","email":"ada@example.net","status":"sent","skipReason":null,"emailId":"em_…","error":null,"attempts":1,"sentAt":"2026-10-25T12:00:00.000Z","provider":"gmail","deliveredAt":"2026-10-25T12:00:02.000Z","openedAt":"2026-10-25T12:20:00.000Z","clickedAt":null,"opens":1,"clicks":0,"bouncedAt":null,"complainedAt":null,"unsubscribedAt":null}],"count":1,"totals":{"queued":0,"sending":0,"sent":0,"held":0,"skipped":0,"failed":0,"total":0}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/broadcasts/{id}/report":{"get":{"operationId":"get_broadcasts_id_report","tags":["Campaigns"],"summary":"Retrieve a broadcast's engagement report","description":"Delivery and engagement for a sending or sent broadcast: unique and total opens and clicks, bounces, complaints, and unsubscribes with rates in percent (open and click rates are over delivered messages), the same by inbox provider, clicks per link, first opens and clicks hour by hour, and the workspace's average over its previous five sent broadcasts. Opens and clicks that looked automated (security scanners, link previews, privacy prefetching, data-center networks) are counted in `machine` and left out of every other number, so opens remain an estimate. `remaining` is how many people in a limited audience have not been sent it yet. Returns 409 for a draft.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"stats":{"type":"object","properties":{"sent":{"type":"integer"},"delivered":{"type":"integer"},"opened":{"type":"integer"},"clicked":{"type":"integer"},"bounced":{"type":"integer"},"complained":{"type":"integer"},"unsubscribed":{"type":"integer"},"opens":{"type":"integer"},"clicks":{"type":"integer"},"rates":{"type":"object","properties":{"delivery":{"type":"integer"},"open":{"type":"number"},"click":{"type":"number"},"clickToOpen":{"type":"number"},"bounce":{"type":"number"},"complaint":{"type":"integer"},"unsubscribe":{"type":"number"}},"required":["delivery","open","click","clickToOpen","bounce","complaint","unsubscribe"],"additionalProperties":false}},"required":["sent","delivered","opened","clicked","bounced","complained","unsubscribed","opens","clicks","rates"],"additionalProperties":false},"providers":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"label":{"type":"string"},"sent":{"type":"integer"},"delivered":{"type":"integer"},"opened":{"type":"integer"},"clicked":{"type":"integer"},"bounced":{"type":"integer"},"complained":{"type":"integer"},"openRate":{"type":"number"},"clickRate":{"type":"number"}},"required":["provider","label","sent","delivered","opened","clicked","bounced","complained","openRate","clickRate"],"additionalProperties":false}},"links":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer"},"url":{"type":"string","format":"uri"},"uniqueClicks":{"type":"integer"},"clicks":{"type":"integer"},"share":{"type":"number"}},"required":["position","url","uniqueClicks","clicks","share"],"additionalProperties":false}},"timeline":{"type":"array","items":{"type":"object","properties":{"hour":{"type":"string","format":"date-time"},"opened":{"type":"integer"},"clicked":{"type":"integer"}},"required":["hour","opened","clicked"],"additionalProperties":false}},"average":{"type":"object","properties":{"basedOn":{"type":"integer"},"open":{"type":"number"},"click":{"type":"number"},"bounce":{"type":"number"},"unsubscribe":{"type":"number"},"delivery":{"type":"number"}},"required":["basedOn","open","click","bounce","unsubscribe","delivery"],"additionalProperties":false},"machine":{"type":"object","properties":{"opens":{"type":"integer"},"clicks":{"type":"integer"}},"required":["opens","clicks"],"additionalProperties":false},"tracking":{"type":"object","properties":{"opens":{"type":"boolean"},"clicks":{"type":"boolean"}},"required":["opens","clicks"],"additionalProperties":false},"totals":{"type":"object","properties":{"queued":{"type":"integer"},"sending":{"type":"integer"},"sent":{"type":"integer"},"held":{"type":"integer"},"skipped":{"type":"integer"},"failed":{"type":"integer"},"total":{"type":"integer"}},"required":["queued","sending","sent","held","skipped","failed","total"],"additionalProperties":false},"remaining":{"type":"integer"}},"required":["stats","providers","links","timeline","average","machine","tracking","totals","remaining"],"additionalProperties":false},"example":{"stats":{"sent":1200,"delivered":1188,"opened":520,"clicked":140,"bounced":9,"complained":0,"unsubscribed":4,"opens":760,"clicks":210,"rates":{"delivery":99,"open":43.77,"click":11.78,"clickToOpen":26.92,"bounce":0.75,"complaint":0,"unsubscribe":0.34}},"providers":[{"provider":"gmail","label":"Gmail","sent":700,"delivered":696,"opened":320,"clicked":90,"bounced":2,"complained":0,"openRate":45.98,"clickRate":12.93}],"links":[{"position":0,"url":"https://example.com/changelog","uniqueClicks":120,"clicks":180,"share":85.71}],"timeline":[{"hour":"2026-10-30T09:00:00.000Z","opened":210,"clicked":60}],"average":{"basedOn":5,"open":41.2,"click":10.4,"bounce":0.8,"unsubscribe":0.3,"delivery":98.9},"machine":{"opens":310,"clicks":45},"tracking":{"opens":true,"clicks":true},"totals":{"queued":0,"sending":0,"sent":1200,"held":0,"skipped":0,"failed":0,"total":1200},"remaining":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/campaigns/overview":{"get":{"operationId":"get_campaigns_overview","tags":["Campaigns"],"summary":"Retrieve subscriber growth and recent broadcast performance","description":"For the last `days` (7 to 365, default 30): active, dormant, and pending subscribers, how many joined and left, a daily subscriber series, and the six most recent sending or sent broadcasts with their open and click rates and the average of both.","security":[{"bearerAuth":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":7,"maximum":365,"default":30}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"subscribers":{"type":"object","properties":{"active":{"type":"integer"},"dormant":{"type":"integer"},"pending":{"type":"integer"},"joined":{"type":"integer"},"left":{"type":"integer"}},"required":["active","dormant","pending","joined","left"],"additionalProperties":false},"series":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"subscribers":{"type":"integer"},"joined":{"type":"integer"},"left":{"type":"integer"}},"required":["day","subscribers","joined","left"],"additionalProperties":false}},"recent":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"subject":{"type":"string"},"status":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"sent":{"type":"integer"},"openRate":{"type":"number"},"clickRate":{"type":"number"}},"required":["id","name","subject","status","startedAt","sent","openRate","clickRate"],"additionalProperties":false}},"averages":{"type":"object","properties":{"openRate":{"type":"number"},"clickRate":{"type":"number"}},"required":["openRate","clickRate"],"additionalProperties":false}},"required":["subscribers","series","recent","averages"],"additionalProperties":false},"example":{"subscribers":{"active":1180,"dormant":20,"pending":6,"joined":140,"left":9},"series":[{"day":"2026-11-01","subscribers":1175,"joined":6,"left":1}],"recent":[{"id":"bc_…","name":"October update","subject":"What's new in October","status":"sent","startedAt":"2026-10-30T09:00:00.000Z","sent":1200,"openRate":43.77,"clickRate":11.78}],"averages":{"openRate":43.77,"clickRate":11.78}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/newsletter-settings":{"get":{"operationId":"get_newsletter_settings","tags":["Campaigns"],"summary":"Retrieve newsletter settings","description":"Workspace settings for broadcasts: the postal address added to every marketing email footer, the design (accent color, font, alignment) used to render Markdown and block content, list cleanup, and the default test recipients.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"postalAddress":{"type":"string"},"design":{"type":"object","properties":{"accentColor":{"type":"string"},"font":{"type":"string"},"align":{"type":"string"}},"required":["accentColor","font","align"],"additionalProperties":false},"cleanup":{"type":"object","properties":{"enabled":{"type":"boolean"},"afterSends":{"type":"integer"},"quietDays":{"type":"integer"},"subject":{"type":"string"},"body":{"type":"string"},"from":{}},"required":["enabled","afterSends","quietDays","subject","body","from"],"additionalProperties":false},"testRecipients":{"type":"array","items":{"type":"string","format":"email"}}},"required":["postalAddress","design","cleanup","testRecipients"],"additionalProperties":false},"example":{"postalAddress":"Acme Inc., 1 Main St, Springfield","design":{"accentColor":"#0a7d4f","font":"sans","align":"left"},"cleanup":{"enabled":true,"afterSends":6,"quietDays":90,"subject":"Do you still want these emails?","body":"You haven't opened our emails in a while. If you'd still like to hear from us, click the button below. Otherwise we'll stop emailing you, no hard feelings.","from":null},"testRecipients":["owner@example.com"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patch_newsletter_settings","tags":["Campaigns"],"summary":"Change newsletter settings","description":"Change `postalAddress`, `design` ({ accentColor, font: sans, serif, or mono, align: left or center }), `cleanup`, or `testRecipients` (up to 5). Keys are camelCase. List cleanup is on by default: a subscriber who received `afterSends` broadcasts in a row without opening or clicking, and has not engaged for `quietDays`, gets one email asking whether to stay subscribed (`subject`, `body`, sent from `from` or the last broadcast's sender, paid plans only). A week later, anyone who did not click to stay becomes dormant: still on the list, but left out of broadcasts until they open or click again.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"postalAddress":{"type":"string"},"design":{"type":"object","properties":{"accentColor":{"type":"string"},"font":{"type":"string"},"align":{"type":"string"}},"required":["accentColor","font","align"],"additionalProperties":false},"cleanup":{"type":"object","properties":{"enabled":{"type":"boolean"},"afterSends":{"type":"integer"},"quietDays":{"type":"integer"},"subject":{"type":"string"},"body":{"type":"string"},"from":{}},"required":["enabled","afterSends","quietDays","subject","body","from"],"additionalProperties":false},"testRecipients":{"type":"array","items":{"type":"string","format":"email"}}},"required":["postalAddress","design","cleanup","testRecipients"],"additionalProperties":false},"example":{"postalAddress":"Acme Inc., 1 Main St, Springfield","design":{"accentColor":"#0a7d4f","font":"sans","align":"left"},"cleanup":{"enabled":true,"afterSends":6,"quietDays":90,"subject":"Do you still want these emails?","body":"You haven't opened our emails in a while. If you'd still like to hear from us, click the button below. Otherwise we'll stop emailing you, no hard feelings.","from":null},"testRecipients":["owner@example.com"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Keys are camelCase. Omitted keys keep their value.","properties":{"postalAddress":{"type":["string","null"],"maxLength":300,"description":"Shown in every marketing email footer (CAN-SPAM, CASL)."},"design":{"type":"object","properties":{"accentColor":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$"},"font":{"type":"string","enum":["sans","serif","mono"]},"align":{"type":"string","enum":["left","center"]}},"additionalProperties":false},"cleanup":{"type":"object","properties":{"enabled":{"type":"boolean"},"afterSends":{"type":"integer","minimum":3,"maximum":50},"quietDays":{"type":"integer","minimum":30,"maximum":730},"subject":{"type":["string","null"],"maxLength":200},"body":{"type":["string","null"],"maxLength":2000},"from":{"type":["string","null"],"description":"Sender on a verified domain; defaults to the last sent broadcast's sender."}},"additionalProperties":false},"testRecipients":{"type":"array","maxItems":5,"items":{"type":"string","format":"email"}}},"additionalProperties":false},"example":{"postalAddress":"Acme Inc., 1 Main St, Springfield","design":{"accentColor":"#0a7d4f"},"cleanup":{"afterSends":8}}}}}}},"/uploads/images":{"post":{"operationId":"post_uploads_images","tags":["Campaigns"],"summary":"Upload an image for email content","description":"Upload one PNG, JPEG, GIF, or WebP image (up to 5 MB) as the raw request body with its `Content-Type`. Optional `filename` query parameter. The image is served publicly, with a long cache, from the returned `url` (`https://sendhq.cc/i/<id>`), so it keeps working in sent email; anyone with the URL can view it. 300 uploads or 300 MB per day.","security":[{"bearerAuth":[]}],"parameters":[{"name":"filename","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"width":{"type":"integer"},"height":{"type":"integer"},"size":{"type":"integer"}},"required":["id","url","width","height","size"],"additionalProperties":false},"example":{"id":"img_….png","url":"https://sendhq.cc/i/img_….png","width":1200,"height":630,"size":48231}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"image/png":{"schema":{"type":"string","contentEncoding":"binary"}},"image/jpeg":{"schema":{"type":"string","contentEncoding":"binary"}},"image/gif":{"schema":{"type":"string","contentEncoding":"binary"}},"image/webp":{"schema":{"type":"string","contentEncoding":"binary"}}}}},"get":{"operationId":"get_uploads_images","tags":["Campaigns"],"summary":"List recently uploaded images","description":"The workspace's 60 most recent image uploads, newest first.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"width":{"type":"integer"},"height":{"type":"integer"},"size":{"type":"integer"},"filename":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","url","width","height","size","filename","createdAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"example":{"data":[{"id":"img_….png","url":"https://sendhq.cc/i/img_….png","width":1200,"height":630,"size":48231,"filename":"header.png","createdAt":"2026-11-01T12:00:00.000Z"}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account":{"get":{"operationId":"get_account","tags":["Account and billing"],"summary":"Retrieve account, usage, billing state, and workspace counts with an API key","description":"API-key equivalent of the dashboard profile: the account owner, current-period recipient and attachment usage against plan limits, access tier, sender reputation summary, subscription state, published plans, and workspace counts. Read-only; billing changes remain session-only.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{},"required":[],"additionalProperties":false},"usage":{"type":"object","properties":{},"required":[],"additionalProperties":false},"access":{"type":"object","properties":{},"required":[],"additionalProperties":false},"reputation":{"type":"object","properties":{},"required":[],"additionalProperties":false},"infrastructure":{"type":"object","properties":{},"required":[],"additionalProperties":false},"billing":{"type":"object","properties":{},"required":[],"additionalProperties":false},"plans":{"type":"array","items":{}},"workspace":{"type":"object","properties":{"mailer":{"type":"string"},"stats":{"type":"object","properties":{},"required":[],"additionalProperties":false}},"required":["mailer","stats"],"additionalProperties":false}},"required":["user","usage","access","reputation","infrastructure","billing","plans","workspace"],"additionalProperties":false},"example":{"user":{},"usage":{},"access":{},"reputation":{},"infrastructure":{},"billing":{},"plans":[],"workspace":{"mailer":"ses","stats":{}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account/diagnostics":{"get":{"operationId":"get_account_diagnostics","tags":["Account and billing"],"summary":"Diagnose sending and receiving problems in the workspace","description":"Read-only troubleshooting snapshot from stored state: an `issues` list in plain language, plan and usage against limits, each domain's DKIM and inbound state, sending identities, 30-day deliverability and sender reputation, suppressions and unsubscribes, the last 30 days of messages that were not sent with their reasons, bounce, complaint and reject events, and webhook delivery health. Never returns message bodies, API keys or webhook secrets.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"generatedAt":{"type":"string","format":"date-time"},"windowDays":{"type":"integer"},"issues":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["severity","code","message"],"additionalProperties":false}},"plan":{"type":"object","properties":{},"required":[],"additionalProperties":false},"domains":{"type":"array","items":{}},"sendingIdentities":{"type":"object","properties":{"domains":{"type":"array","items":{}},"addresses":{"type":"array","items":{}}},"required":["domains","addresses"],"additionalProperties":false},"inbound":{"type":"object","properties":{},"required":[],"additionalProperties":false},"deliverability":{"type":"object","properties":{},"required":[],"additionalProperties":false},"suppressions":{"type":"object","properties":{},"required":[],"additionalProperties":false},"failures":{"type":"object","properties":{"notSent":{"type":"array","items":{}},"recentNotSent":{"type":"array","items":{}},"recentProviderEvents":{"type":"array","items":{}}},"required":["notSent","recentNotSent","recentProviderEvents"],"additionalProperties":false},"webhooks":{"type":"array","items":{}}},"required":["generatedAt","windowDays","issues","plan","domains","sendingIdentities","inbound","deliverability","suppressions","failures","webhooks"],"additionalProperties":false},"example":{"generatedAt":"2026-10-30T12:00:00.000Z","windowDays":30,"issues":[{"severity":"action","code":"domain_unverified","message":"example.com is not verified (pending); 2 of 3 DKIM records are not visible in DNS yet."}],"plan":{},"domains":[],"sendingIdentities":{"domains":[],"addresses":[]},"inbound":{},"deliverability":{},"suppressions":{},"failures":{"notSent":[],"recentNotSent":[],"recentProviderEvents":[]},"webhooks":[]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analytics":{"get":{"operationId":"get_analytics","tags":["Account and billing"],"summary":"Retrieve dashboard sending analytics for 7, 30, or 90 days","description":"Sent, received, delivered, bounced, blocked, opened, clicked, and complaint totals for the window, a per-day sent/received timeline, the top sending domains, and the best-performing subjects.","security":[{"bearerAuth":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","enum":[7,30,90]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"window":{"type":"string"},"days":{"type":"integer"},"metrics":{"type":"object","properties":{"sent":{"type":"integer"},"received":{"type":"integer"},"bounced":{"type":"integer"},"blocked":{"type":"integer"},"delivered":{"type":"integer"},"opened":{"type":"integer"},"clicks":{"type":"integer"},"complaints":{"type":"integer"}},"required":["sent","received","bounced","blocked","delivered","opened","clicks","complaints"],"additionalProperties":false},"timeline":{"type":"array","items":{}},"domains":{"type":"array","items":{}},"topContent":{"type":"array","items":{}}},"required":["window","days","metrics","timeline","domains","topContent"],"additionalProperties":false},"example":{"window":"30d","days":30,"metrics":{"sent":0,"received":0,"bounced":0,"blocked":0,"delivered":0,"opened":0,"clicks":0,"complaints":0},"timeline":[],"domains":[],"topContent":[]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/profile":{"get":{"operationId":"get_profile","tags":["Account and billing"],"summary":"Retrieve account, usage, and stacked subscription state","description":"Retrieve account, usage, and stacked subscription state","security":[{"sessionCookie":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{},"required":[],"additionalProperties":false},"usage":{"type":"object","properties":{},"required":[],"additionalProperties":false},"access":{"type":"object","properties":{},"required":[],"additionalProperties":false},"reputation":{"type":"object","properties":{},"required":[],"additionalProperties":false},"billing":{"type":"object","properties":{},"required":[],"additionalProperties":false},"plans":{"type":"array","items":{}}},"required":["user","usage","access","reputation","billing","plans"],"additionalProperties":false},"example":{"user":{},"usage":{},"access":{},"reputation":{},"billing":{},"plans":[]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/checkout":{"post":{"operationId":"post_billing_checkout","tags":["Account and billing"],"summary":"Start a hosted checkout for a plan not already held (tier, message class, and billing interval)","description":"Start a hosted checkout for a plan not already held (tier, message class, and billing interval)","security":[{"sessionCookie":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"session_id":{"type":"string"}},"required":["url","session_id"],"additionalProperties":false},"example":{"url":"https://checkout.example/…","session_id":"…"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan_key":{"type":"string"}},"required":["plan_key"],"additionalProperties":false},"example":{"plan_key":"scaleup_marketing_annual"}}}}}},"/billing/cancel":{"post":{"operationId":"post_billing_cancel","tags":["Account and billing"],"summary":"Cancel the current subscription in-app without touching the provider","description":"Cancel the current subscription in-app without touching the provider","security":[{"sessionCookie":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keys":{"post":{"operationId":"post_keys","tags":["Account and billing"],"summary":"Create an API key","description":"Create an API key","security":[{"sessionCookie":[]}],"parameters":[],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"prefix":{"type":"string"}},"required":["id","name","key","prefix"],"additionalProperties":false},"example":{"id":"key_…","name":"Production","key":"re_…","prefix":"re_…"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false},"example":{"name":"Production"}}}}},"get":{"operationId":"get_keys","tags":["Account and billing"],"summary":"List API-key metadata","description":"List key names, non-secret prefixes, and last-used timestamps. Full key values are never returned. Creating and revoking keys requires a dashboard session.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}},"count":{"type":"integer"}},"required":["data","count"],"additionalProperties":false},"example":{"data":[],"count":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keys/{id}":{"delete":{"operationId":"delete_keys_id","tags":["Account and billing"],"summary":"Revoke an API key","description":"Revoke an API key","security":[{"sessionCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Sending requires an active subscription (subscription_required). There is no free allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace, domain, policy, or suppression state forbids the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource state or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Attachment count or bytes exceed the accepted limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request validation or suppression check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"account_paused for a deliverability review includes bounce_rate and complaint_rate against their limits. Other workspace pauses return their own reason without those limits. sender_paused is the per-sender circuit breaker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, or quota_exhausted. Daily, hourly, and Gmail refusals include resets_at and are not queued. Retry-After is the seconds until that reset, not a short backoff. When the hour and the day are both exhausted, the code is daily_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the refused limit resets.","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"An upstream provider operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required provider or signing configuration is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"re_…","description":"Workspace API key. Keep it server-side."},"sessionCookie":{"type":"apiKey","in":"cookie","name":"sendhq_session_v2","description":"Browser session used for account administration."}},"schemas":{"SendEmailRequest":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","description":"Email address, optionally with a display name, on a verified workspace domain."},"to":{"oneOf":[{"type":"string","description":"Email address, optionally with a display name."},{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","description":"Email address, optionally with a display name."}}]},"cc":{"oneOf":[{"type":"string","description":"Email address, optionally with a display name."},{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","description":"Email address, optionally with a display name."}}]},"bcc":{"oneOf":[{"type":"string","description":"Email address, optionally with a display name."},{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","description":"Email address, optionally with a display name."}}]},"subject":{"type":"string","description":"Optional for raw-content sends; an omitted subject is sent empty. Hosted templates supply their published subject."},"html":{"type":"string"},"text":{"type":"string"},"reply_to":{"type":"string","format":"email"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"message_class":{"type":"string","enum":["transactional","marketing"],"default":"transactional"},"draft_id":{"type":"string"},"reply_to_email_id":{"type":"string"},"thread_id":{"type":"string"},"labels":{"type":"array","maxItems":10,"items":{"type":"string","minLength":1,"maxLength":64},"description":"Label names or lbl_ IDs to file the message under. Unknown names are created; replies in the conversation inherit them."},"template":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"version_id":{"type":"string"},"versionId":{"type":"string"},"data":{"type":"object","additionalProperties":true}},"anyOf":[{"required":["id"]},{"required":["key"]}],"additionalProperties":false}},"anyOf":[{"required":["html"]},{"required":["text"]},{"required":["template"]}],"additionalProperties":true},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","status"],"additionalProperties":false,"properties":{"message":{"type":"string","description":"Human-readable explanation."},"status":{"type":"integer","minimum":400,"maximum":599,"description":"HTTP status repeated for machine consumers."},"code":{"type":["string","null"],"description":"Stable machine code when the route defines one. Sending refusals include subscription_required, daily_limit_reached, hourly_limit_reached, gmail_recipient_limit, gmail_rate_limited, account_paused, and quota_exhausted."},"pricing_url":{"type":"string"},"billing_url":{"type":"string"},"daily_limit":{"type":"integer"},"sent_today":{"type":"integer"},"remaining":{"type":"integer"},"ladder_day":{"type":"integer"},"ladder_days":{"type":"integer"},"next_limit":{"type":["integer","null"]},"next_rung":{"type":"string"},"resets_at":{"type":"string","format":"date-time"},"queued":{"type":"boolean","description":"False when the refused message was not queued."},"hourly_limit":{"type":"integer"},"sent_this_hour":{"type":"integer"},"gmail_limit":{"type":"integer"},"gmail_sent_today":{"type":"integer"},"bounce_rate":{"type":"number"},"bounce_limit":{"type":"number"},"complaint_rate":{"type":"number"},"complaint_limit":{"type":"number"},"reason":{"type":"string"}}}}}},"responses":{"BadRequest":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SenderPaused":{"description":"The exact sender identity is paused by its rolling reputation policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"A monthly, daily, or trial usage limit was reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnexpectedError":{"description":"An error response using SendHQ's standard JSON envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}