{"openapi":"3.1.0","info":{"title":"Aiosis Emails API","version":"1.0.0","description":"Multi-tenant email marketing API.\n\nAuthenticate with `Authorization: Bearer sk_live_…`. Every key belongs to exactly one tenant, and every response is scoped to that tenant.\n\nCollections are cursor-paged: follow `nextCursor` until it is null. Rate limits are 600 requests per minute **per key**, reported on every response in `X-RateLimit-Limit` and `X-RateLimit-Remaining`."},"servers":[{"url":"https://emails.aiosis.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API keys carry a subset of: contacts:read, contacts:write, campaigns:read, campaigns:write, messages:send, stats:read, messages:read, templates:read, templates:write, events:write, domains:read, webhooks:manage, mail:read, mail:send."}},"schemas":{"Contact":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["pending","subscribed","unsubscribed","bounced","complained"]},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"fields":{"type":"object","additionalProperties":true},"source":{"type":["string","null"]},"createdAt":{"type":["integer","null"],"description":"Epoch milliseconds"},"updatedAt":{"type":["integer","null"],"description":"Epoch milliseconds"}},"required":["id","email","status"]},"List":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"doubleOptin":{"type":"boolean"},"createdAt":{"type":["integer","null"]}},"required":["id","name","doubleOptin"]},"Campaign":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","materializing","queued","sending","paused","sent","cancelled","failed"]},"subject":{"type":["string","null"]},"preheader":{"type":["string","null"]},"fromName":{"type":["string","null"]},"fromEmail":{"type":["string","null"]},"replyTo":{"type":["string","null"]},"audience":{"type":"object","additionalProperties":true},"scheduleAt":{"type":["integer","null"]},"timezone":{"type":"string"},"sentAt":{"type":["integer","null"]},"cancelledAt":{"type":["integer","null"]},"createdAt":{"type":["integer","null"]}},"required":["id","name","status"]},"Suppression":{"type":"object","description":"Suppressions expose the address hash, never the plaintext address.","properties":{"emailHash":{"type":"string"},"reason":{"type":"string","enum":["unsubscribe","hard_bounce","complaint","manual","global_block"]},"scope":{"type":"string","enum":["global","list"]},"listId":{"type":["string","null"]},"source":{"type":["string","null"]},"note":{"type":["string","null"]},"createdAt":{"type":["integer","null"]}},"required":["emailHash","reason","scope"]},"CampaignStats":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"recipients":{"type":"integer"},"totals":{"type":"object","additionalProperties":{"type":"integer"}},"rates":{"type":"object","description":"Percentages of the recipient count, to one decimal place.","additionalProperties":{"type":"number"}},"daily":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["contact.subscribed","contact.unsubscribed","message.delivered","message.opened","message.clicked","message.bounced","message.complained","campaign.completed"]}},"description":{"type":["string","null"]},"status":{"type":"string","enum":["active","disabled"]},"secretHint":{"type":"string","description":"First few characters of the signing secret, for identification only."},"secret":{"type":"string","description":"The signing secret in full. Returned ONLY by create and rotate — store it now, it cannot be read back."},"consecutiveFailures":{"type":"integer"},"lastSuccessAt":{"type":["integer","null"]},"lastFailureAt":{"type":["integer","null"]},"lastError":{"type":["string","null"]},"createdAt":{"type":["integer","null"]}},"required":["id","url","events","status"]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"endpointId":{"type":"string"},"type":{"type":"string","enum":["contact.subscribed","contact.unsubscribed","message.delivered","message.opened","message.clicked","message.bounced","message.complained","campaign.completed"]},"attempt":{"type":"integer"},"lastStatus":{"type":["integer","null"]},"lastError":{"type":["string","null"]},"createdAt":{"type":["integer","null"]}},"required":["id","endpointId","type"]},"Message":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string","description":"queued, sent, failed, suppressed, delivered, soft_bounce, hard_bounce, complaint"},"to":{"type":"string"},"subject":{"type":["string","null"]},"category":{"type":["string","null"]},"sendingDomain":{"type":["string","null"]},"templateVersionId":{"type":["string","null"]},"error":{"type":["string","null"],"description":"Why a failed message failed, verbatim from the transport."},"sentAt":{"type":["integer","null"]},"events":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"occurredAt":{"type":"integer"},"machine":{"type":"boolean"}}}}},"required":["id","status","to"]},"SendResult":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"category":{"type":["string","null"]},"template":{"type":["string","null"]},"version":{"type":["integer","null"]},"duplicate":{"type":"boolean","description":"True when the idempotency key matched an earlier send; nothing new was queued."}},"required":["id","status"]},"Template":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":["string","null"]},"locale":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"category":{"type":["string","null"]},"status":{"type":"string","enum":["draft","published","changed"]},"publishedVersion":{"type":["integer","null"]},"hasUnpublishedChanges":{"type":"boolean"},"subject":{"type":["string","null"]},"preheader":{"type":["string","null"]},"variables":{"type":"array","items":{"type":"object","additionalProperties":true}},"fromEmail":{"type":["string","null"]},"system":{"type":"boolean","description":"Built in: called by name from integrations, so it can be edited or reset but not deleted."}},"required":["id","locale","name","status"]},"Category":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"required":{"type":"boolean","description":"Sign-in and security: cannot be unsubscribed from."},"legalBasis":{"type":"string","enum":["consent","contract","legitimate_interest"]},"defaultOptIn":{"type":"boolean"}},"required":["key","name","required"]},"Subscription":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"required":{"type":"boolean"},"subscribed":{"type":"boolean"}},"required":["key","subscribed"]},"Error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable reason, e.g. recipient_unsubscribed, template_not_published, domain_not_allowed."},"errors":{"type":"array","items":{}},"issues":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["message"]}}},"paths":{"/v1/contacts":{"get":{"operationId":"listContacts","summary":"List contacts","tags":["contacts"],"security":[{"bearerAuth":["contacts:read"]}],"responses":{"200":{"description":"A page of contacts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page, or null when this was the last one."}},"required":["data"]}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:read\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"cursor","in":"query","required":false,"description":"Id of the last item from the previous page. Omit for the first page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200. Values above the ceiling are clamped, not rejected.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"list","in":"query","required":false,"description":"Only contacts subscribed to this list id.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","subscribed","unsubscribed","bounced","complained"]}}]},"post":{"operationId":"upsertContact","summary":"Create or update a contact","tags":["contacts"],"security":[{"bearerAuth":["contacts:write"]}],"responses":{"200":{"description":"The stored contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Idempotent on the email address: posting a known address updates it rather than failing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"firstName":{"type":"string","maxLength":120},"lastName":{"type":"string","maxLength":120},"fields":{"type":"object","additionalProperties":{}},"listIds":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":"string"},"domain":{"type":"string"},"domains":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"required":["email"]}}}}}},"/v1/contacts/{id}":{"get":{"operationId":"getContact","summary":"Fetch one contact","tags":["contacts"],"security":[{"bearerAuth":["contacts:read"]}],"responses":{"200":{"description":"The contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:read\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Contact id","schema":{"type":"string"}}]},"patch":{"operationId":"updateContact","summary":"Update a contact","tags":["contacts"],"security":[{"bearerAuth":["contacts:write"]}],"responses":{"200":{"description":"The updated contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"The email address is immutable; create a new contact to change it.","parameters":[{"name":"id","in":"path","required":true,"description":"Contact id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","maxLength":120},"lastName":{"type":"string","maxLength":120},"fields":{"type":"object","additionalProperties":{}},"listIds":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}}}}},"delete":{"operationId":"eraseContact","summary":"Erase a contact (GDPR)","tags":["contacts"],"security":[{"bearerAuth":["contacts:write"]}],"responses":{"200":{"description":"Erasure confirmation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"erased":{"type":"boolean"}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Nulls the personal data but keeps the address hash, so a later import cannot resurrect someone who asked to be forgotten.","parameters":[{"name":"id","in":"path","required":true,"description":"Contact id","schema":{"type":"string"}}]}},"/v1/contacts/{id}/unsubscribe":{"post":{"operationId":"unsubscribeContact","summary":"Unsubscribe a contact","tags":["contacts"],"security":[{"bearerAuth":["contacts:write"]}],"responses":{"200":{"description":"Unsubscribe confirmation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"unsubscribed":{"type":"boolean"},"scope":{"type":"string","enum":["global","list"]}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"With no body, unsubscribes globally. Supply a listId to unsubscribe from one list only.","parameters":[{"name":"id","in":"path","required":true,"description":"Contact id","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"listId":{"type":"string"}},"additionalProperties":false}}}}}},"/v1/lists":{"get":{"operationId":"listLists","summary":"List mailing lists","tags":["lists"],"security":[{"bearerAuth":["contacts:read"]}],"responses":{"200":{"description":"Every list for the tenant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/List"}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page, or null when this was the last one."}},"required":["data"]}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:read\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createList","summary":"Create a mailing list","tags":["lists"],"security":[{"bearerAuth":["contacts:write"]}],"responses":{"200":{"description":"The created list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","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},"description":{"type":"string","maxLength":500},"doubleOptin":{"type":"boolean"}},"additionalProperties":false,"required":["name"]}}}}}},"/v1/lists/{id}/contacts":{"get":{"operationId":"listListContacts","summary":"List the subscribed contacts of a list","tags":["lists"],"security":[{"bearerAuth":["contacts:read"]}],"responses":{"200":{"description":"A page of contacts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page, or null when this was the last one."}},"required":["data"]}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:read\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"List id","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Id of the last item from the previous page. Omit for the first page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200. Values above the ceiling are clamped, not rejected.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}]}},"/v1/campaigns":{"get":{"operationId":"listCampaigns","summary":"List campaigns","tags":["campaigns"],"security":[{"bearerAuth":["campaigns:read"]}],"responses":{"200":{"description":"A page of campaigns","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page, or null when this was the last one."}},"required":["data"]}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"campaigns:read\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200. Values above the ceiling are clamped, not rejected.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}]},"post":{"operationId":"createCampaign","summary":"Create a campaign","tags":["campaigns"],"security":[{"bearerAuth":["campaigns:write"]}],"responses":{"200":{"description":"The created campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"campaigns:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Campaigns are created as drafts. Use the send or schedule action to start them.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"subject":{"type":"string","maxLength":300},"preheader":{"type":"string","maxLength":300},"templateId":{"type":"string"},"fromName":{"type":"string","maxLength":120},"fromEmail":{"type":"string","format":"email"},"replyTo":{"type":"string","format":"email"},"audience":{"type":"object","properties":{"kind":{"type":"string","enum":["all","list","segment"]},"listId":{"type":"string"},"segmentId":{"type":"string"},"domains":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"required":["kind"]},"scheduleAt":{"type":"number"},"timezone":{"type":"string"},"category":{"type":"string"},"newsletterId":{"type":"string"},"tracking":{"type":"object","properties":{"opens":{"type":"boolean"},"clicks":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false,"required":["name"]}}}}}},"/v1/campaigns/{id}":{"get":{"operationId":"getCampaign","summary":"Fetch one campaign","tags":["campaigns"],"security":[{"bearerAuth":["campaigns:read"]}],"responses":{"200":{"description":"The campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"campaigns:read\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Campaign id","schema":{"type":"string"}}]}},"/v1/campaigns/{id}/send":{"post":{"operationId":"sendCampaign","summary":"Send a campaign now","tags":["campaigns"],"security":[{"bearerAuth":["campaigns:write"]}],"responses":{"200":{"description":"The send was accepted and is materialising","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"campaigns:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Preflight failed. `errors` lists every unmet requirement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Runs preflight first. A campaign that fails preflight is not queued, and every reason is returned at once.","parameters":[{"name":"id","in":"path","required":true,"description":"Campaign id","schema":{"type":"string"}}]}},"/v1/campaigns/{id}/schedule":{"post":{"operationId":"scheduleCampaign","summary":"Schedule a campaign","tags":["campaigns"],"security":[{"bearerAuth":["campaigns:write"]}],"responses":{"200":{"description":"The campaign is scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"scheduleAt":{"type":"integer"}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"campaigns:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The requested time is in the past.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Campaign id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"at":{"type":"integer"}},"additionalProperties":false,"required":["at"]}}}}}},"/v1/campaigns/{id}/pause":{"post":{"operationId":"pauseCampaign","summary":"Pause a sending campaign","tags":["campaigns"],"security":[{"bearerAuth":["campaigns:write"]}],"responses":{"200":{"description":"The campaign is paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"campaigns:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Campaign id","schema":{"type":"string"}}]}},"/v1/campaigns/{id}/cancel":{"post":{"operationId":"cancelCampaign","summary":"Cancel a campaign","tags":["campaigns"],"security":[{"bearerAuth":["campaigns:write"]}],"responses":{"200":{"description":"The campaign is cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"campaigns:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Campaign id","schema":{"type":"string"}}]}},"/v1/campaigns/{id}/stats":{"get":{"operationId":"getCampaignStats","summary":"Campaign performance","tags":["campaigns"],"security":[{"bearerAuth":["stats:read"]}],"responses":{"200":{"description":"Totals, rates and the daily series","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignStats"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"stats:read\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Campaign id","schema":{"type":"string"}}]}},"/v1/messages":{"post":{"operationId":"sendMessage","summary":"Send an email","tags":["messages"],"security":[{"bearerAuth":["messages:send"]}],"responses":{"200":{"description":"The message was accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The recipient is suppressed for a hard bounce or a complaint, or the key may not send from this domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The data does not match the template variables (`errors` lists them), or the category does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Two forms. With `template` (e.g. `signin-code`) and `data`, the template's published version is rendered, the recipient's consent for its category is checked, and the legal footer, List-Unsubscribe headers and tracking are added; a recipient who unsubscribed from that category is refused with 409 `recipient_unsubscribed`. Sign-in and security templates always go, except to addresses that bounced or complained. Without a template, `subject` + `html`/`text` is wrapped in the account's `default` template and filed under its plain-email type (`notifications` unless changed), so it carries the same footer and checks; the response says `\"template\": \"default\"`. A plain send in a required type such as `security` is refused with 422 `template_required`, and `template` with `html`/`text` together with 400 `template_and_content`. See docs/API-SENDING-GUIDE.md. Send `idempotencyKey` to make retries safe. Queued on a path separate from campaigns, so a large campaign cannot delay a password reset.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","format":"email"},"template":{"type":"string"},"data":{"type":"object","additionalProperties":{}},"locale":{"type":"string"},"category":{"type":"string"},"subject":{"type":"string","minLength":1},"html":{"type":"string"},"text":{"type":"string"},"templateId":{"type":"string"},"fromEmail":{"type":"string","format":"email"},"fromName":{"type":"string"},"replyTo":{"type":"string"},"idempotencyKey":{"type":"string","maxLength":200},"tags":{"type":"array","items":{"type":"string"}},"contact":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"locale":{"type":"string"}},"additionalProperties":false},"consent":{"type":"object","additionalProperties":{"type":"boolean"}}},"additionalProperties":false,"required":["to"]}}}}}},"/v1/messages/batch":{"post":{"operationId":"sendBatch","summary":"Send one template to many recipients","tags":["messages"],"security":[{"bearerAuth":["messages:send"]}],"responses":{"200":{"description":"Per-recipient results","content":{"application/json":{"schema":{"type":"object","properties":{"queued":{"type":"integer"},"refused":{"type":"integer"},"results":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"messages:send\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Up to 100 recipients. Each is checked and queued on its own: a refused recipient is reported in `results` and does not fail the batch.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"string"},"fromEmail":{"type":"string","format":"email"},"fromName":{"type":"string"},"replyTo":{"type":"string"},"messages":{"type":"array","items":{"type":"object","properties":{"to":{"type":"string","format":"email"},"data":{"type":"object","additionalProperties":{}},"locale":{"type":"string"},"idempotencyKey":{"type":"string","maxLength":200}},"additionalProperties":false,"required":["to"]}}},"additionalProperties":false,"required":["template","messages"]}}}}}},"/v1/messages/{id}":{"get":{"operationId":"getMessage","summary":"Fetch one message, its events and its failure reason","tags":["messages"],"security":[{"bearerAuth":["messages:read"]},{"bearerAuth":["messages:send"]}],"responses":{"200":{"description":"The message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"messages:read\" or \"messages:send\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Message id returned by a send","schema":{"type":"string"}}]}},"/v1/templates":{"get":{"operationId":"listTemplates","summary":"List templates, every locale","tags":["templates"],"security":[{"bearerAuth":["templates:read"]}],"responses":{"200":{"description":"Templates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"templates:read\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createTemplate","summary":"Create a template, or a new locale of a key","tags":["templates"],"security":[{"bearerAuth":["templates:write"]}],"responses":{"200":{"description":"The template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"templates:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Give `blocks` (the editor's block model) or a whole `html` body. Created as a draft unless `publish` is true; only a published version is ever sent.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,62}$"},"locale":{"type":"string"},"kind":{"type":"string","enum":["transactional","campaign","automation","system"]},"publish":{"type":"boolean"},"name":{"type":"string","maxLength":120},"category":{"type":"string"},"subject":{"type":"string","maxLength":250},"preheader":{"type":"string","maxLength":250},"blocks":{"type":"array","items":{"type":"object","additionalProperties":{}}},"html":{"type":"string"},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-zA-Z_][a-zA-Z0-9_]{0,62}$"},"type":{"type":"string","enum":["string","number","boolean","url","email"]},"required":{"type":"boolean"},"sample":{},"description":{"type":"string"}},"additionalProperties":false,"required":["name"]}},"fromEmail":{"type":"string","format":"email"},"fromName":{"type":"string"},"replyTo":{"type":"string"},"domain":{"type":"string"},"tracking":{"type":"object","properties":{"opens":{"type":"boolean"},"clicks":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false,"required":["key"]}}}}}},"/v1/templates/{key}":{"get":{"operationId":"getTemplate","summary":"Every locale of one template key","tags":["templates"],"security":[{"bearerAuth":["templates:read"]}],"responses":{"200":{"description":"The key and its locales","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"locales":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"templates:read\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"key","in":"path","required":true,"description":"Template key, e.g. signin-code","schema":{"type":"string"}}]},"patch":{"operationId":"updateTemplate","summary":"Edit one locale of a template","tags":["templates"],"security":[{"bearerAuth":["templates:write"]}],"responses":{"200":{"description":"The template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"templates:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Edits the draft. Sends keep using the published version until `publish` is true or the publish action is called.","parameters":[{"name":"key","in":"path","required":true,"description":"Template key, e.g. signin-code","schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Locale of the template (en, ro). English when omitted.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"publish":{"type":"boolean"},"name":{"type":"string","maxLength":120},"category":{"type":"string"},"subject":{"type":"string","maxLength":250},"preheader":{"type":"string","maxLength":250},"blocks":{"type":"array","items":{"type":"object","additionalProperties":{}}},"html":{"type":"string"},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-zA-Z_][a-zA-Z0-9_]{0,62}$"},"type":{"type":"string","enum":["string","number","boolean","url","email"]},"required":{"type":"boolean"},"sample":{},"description":{"type":"string"}},"additionalProperties":false,"required":["name"]}},"fromEmail":{"type":"string","format":"email"},"fromName":{"type":"string"},"replyTo":{"type":"string"},"domain":{"type":"string"},"tracking":{"type":"object","properties":{"opens":{"type":"boolean"},"clicks":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}},"delete":{"operationId":"deleteTemplate","summary":"Delete a template (one locale, or all)","tags":["templates"],"security":[{"bearerAuth":["templates:write"]}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"templates:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Built-in templates cannot be deleted; they are called by name.","parameters":[{"name":"key","in":"path","required":true,"description":"Template key, e.g. signin-code","schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Locale of the template (en, ro). English when omitted.","schema":{"type":"string"}}]}},"/v1/templates/{key}/publish":{"post":{"operationId":"publishTemplate","summary":"Publish the current draft","tags":["templates"],"security":[{"bearerAuth":["templates:write"]}],"responses":{"200":{"description":"The new version","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"locale":{"type":"string"},"version":{"type":"integer"}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"templates:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"key","in":"path","required":true,"description":"Template key, e.g. signin-code","schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Locale of the template (en, ro). English when omitted.","schema":{"type":"string"}}]}},"/v1/templates/{key}/preview":{"post":{"operationId":"previewTemplate","summary":"Render a template without sending","tags":["templates"],"security":[{"bearerAuth":["templates:read"]}],"responses":{"200":{"description":"Subject, HTML and text","content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"errors":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"templates:read\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"The published version, or the draft with `draft: true`. Without `data`, the template's sample values are used. `errors` lists data that would be refused by a send.","parameters":[{"name":"key","in":"path","required":true,"description":"Template key, e.g. signin-code","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string"},"data":{"type":"object","additionalProperties":{}},"draft":{"type":"boolean"},"to":{"type":"string","format":"email"},"fromEmail":{"type":"string","format":"email"}},"additionalProperties":false}}}}}},"/v1/templates/{key}/test":{"post":{"operationId":"testTemplate","summary":"Send the draft to one address","tags":["templates"],"security":[{"bearerAuth":["templates:write"]}],"responses":{"200":{"description":"The test message was accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"templates:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"key","in":"path","required":true,"description":"Template key, e.g. signin-code","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string"},"data":{"type":"object","additionalProperties":{}},"draft":{"type":"boolean"},"to":{"type":"string","format":"email"},"fromEmail":{"type":"string","format":"email"}},"additionalProperties":false}}}}}},"/v1/categories":{"get":{"operationId":"listCategories","summary":"Email categories a recipient can opt into or out of","tags":["categories"],"security":[{"bearerAuth":["contacts:read"]},{"bearerAuth":["templates:read"]},{"bearerAuth":["messages:send"]}],"responses":{"200":{"description":"Categories","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:read\" or \"templates:read\" or \"messages:send\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contacts/{id}/subscriptions":{"get":{"operationId":"getSubscriptions","summary":"A contact's subscription to every category","tags":["contacts"],"security":[{"bearerAuth":["contacts:read"]}],"responses":{"200":{"description":"Subscriptions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:read\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Contact id","schema":{"type":"string"}}]},"put":{"operationId":"setSubscriptions","summary":"Record subscription choices made in your own UI","tags":["contacts"],"security":[{"bearerAuth":["contacts:write"]}],"responses":{"200":{"description":"Subscriptions after the change","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Each change is stored with consent evidence. The required (sign-in and security) category ignores this.","parameters":[{"name":"id","in":"path","required":true,"description":"Contact id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"choices":{"type":"object","additionalProperties":{"type":"boolean"}}},"additionalProperties":false,"required":["choices"]}}}}}},"/v1/suppressions":{"get":{"operationId":"listSuppressions","summary":"List suppressions","tags":["suppressions"],"security":[{"bearerAuth":["contacts:read"]}],"responses":{"200":{"description":"Suppressed address hashes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Suppression"}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page, or null when this was the last one."}},"required":["data"]}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:read\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200. Values above the ceiling are clamped, not rejected.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}]},"post":{"operationId":"addSuppression","summary":"Suppress an address","tags":["suppressions"],"security":[{"bearerAuth":["contacts:write"]}],"responses":{"200":{"description":"The address is suppressed","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"suppressed":{"type":"boolean"},"reason":{"type":"string"}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"There is deliberately no delete: lifting a suppression re-enables mail to someone who unsubscribed, bounced or complained, and that stays a console action attributable to a person.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"note":{"type":"string","maxLength":500}},"additionalProperties":false,"required":["email"]}}}}}},"/v1/imports":{"post":{"operationId":"createImport","summary":"Import contacts from CSV","tags":["imports"],"security":[{"bearerAuth":["contacts:write"]}],"responses":{"200":{"description":"The import is queued","content":{"application/json":{"schema":{"type":"object","properties":{"r2Key":{"type":"string"},"status":{"type":"string"}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Enqueues the import and returns immediately. Supply the CSV inline or the key of an object already staged in storage.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"csv":{"type":"string"},"r2Key":{"type":"string"},"listIds":{"type":"array","items":{"type":"string"}},"consentSource":{"type":"string","minLength":3},"mapping":{"type":"object","additionalProperties":{"type":"string"}}},"additionalProperties":false,"required":["listIds","consentSource"]}}}}}},"/v1/webhooks":{"get":{"operationId":"listWebhooks","summary":"List webhook endpoints","tags":["webhooks"],"security":[{"bearerAuth":["campaigns:read"]}],"responses":{"200":{"description":"Configured endpoints","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page, or null when this was the last one."}},"required":["data"]}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"campaigns:read\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createWebhook","summary":"Register a webhook endpoint","tags":["webhooks"],"security":[{"bearerAuth":["campaigns:write"]}],"responses":{"200":{"description":"The endpoint, including its signing secret (shown once)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"campaigns:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Deliveries are POSTed as JSON and signed `t=<unix>,v1=<hex>` in `X-Aiosis-Signature`, where the HMAC-SHA256 is taken over `<unix>.<raw body>` with the endpoint secret. Reject anything older than 300s. Delivery is at-least-once: deduplicate on the payload `id`. A failing endpoint is retried with exponential backoff for 24 hours and then dead-lettered.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["contact.subscribed","contact.unsubscribed","message.delivered","message.opened","message.clicked","message.bounced","message.complained","campaign.completed"]}},"description":{"type":"string","maxLength":200}},"additionalProperties":false,"required":["url","events"]}}}}}},"/v1/webhooks/{id}":{"patch":{"operationId":"updateWebhook","summary":"Update a webhook endpoint","tags":["webhooks"],"security":[{"bearerAuth":["campaigns:write"]}],"responses":{"200":{"description":"The updated endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"campaigns:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Setting status back to active also clears the failure streak, so a repaired endpoint is not immediately auto-disabled again.","parameters":[{"name":"id","in":"path","required":true,"description":"Endpoint id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["contact.subscribed","contact.unsubscribed","message.delivered","message.opened","message.clicked","message.bounced","message.complained","campaign.completed"]}},"description":{"type":"string","maxLength":200},"status":{"type":"string","enum":["active","disabled"]}},"additionalProperties":false}}}}},"delete":{"operationId":"deleteWebhook","summary":"Delete a webhook endpoint","tags":["webhooks"],"security":[{"bearerAuth":["campaigns:write"]}],"responses":{"200":{"description":"Deletion confirmation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"campaigns:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Endpoint id","schema":{"type":"string"}}]}},"/v1/webhooks/{id}/rotate":{"post":{"operationId":"rotateWebhookSecret","summary":"Rotate an endpoint signing secret","tags":["webhooks"],"security":[{"bearerAuth":["campaigns:write"]}],"responses":{"200":{"description":"The endpoint with its new secret (shown once)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"campaigns:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Secrets are per endpoint, so this invalidates one integration rather than all of them.","parameters":[{"name":"id","in":"path","required":true,"description":"Endpoint id","schema":{"type":"string"}}]}},"/v1/webhooks/deliveries":{"get":{"operationId":"listDeadLetters","summary":"List dead-lettered deliveries","tags":["webhooks"],"security":[{"bearerAuth":["campaigns:read"]}],"responses":{"200":{"description":"Dead deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page, or null when this was the last one."}},"required":["data"]}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"campaigns:read\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Deliveries that exhausted 24 hours of retries.","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–200. Values above the ceiling are clamped, not rejected.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}]}},"/v1/webhooks/deliveries/{id}/replay":{"post":{"operationId":"replayDelivery","summary":"Replay a dead-lettered delivery","tags":["webhooks"],"security":[{"bearerAuth":["campaigns:write"]}],"responses":{"200":{"description":"The delivery is queued again","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"campaigns:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Delivery id","schema":{"type":"string"}}]}},"/v1/events":{"post":{"operationId":"recordEvent","summary":"Record a custom event","tags":["events"],"security":[{"bearerAuth":["contacts:write"]},{"bearerAuth":["events:write"]}],"responses":{"200":{"description":"Automations started, if any matched","content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"string"},"name":{"type":"string"},"started":{"type":"integer"},"runIds":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the \"contacts:write\" or \"events:write\" scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such object for this tenant. Objects owned by another tenant are reported as missing rather than forbidden, so ids stay unenumerable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Fires any active automation with a matching api.event trigger. The lifecycle events `user.signed_up`, `user.verified`, `user.signed_in` and `user.deleted` also maintain the contact: a sign-up is collected as a pending contact, verification or sign-in makes it reachable, deletion erases it. Pass `consent` with the categories the person ticked in your own form; collecting a contact never subscribes them to marketing by itself.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"email":{"type":"string","format":"email"},"contactId":{"type":"string"},"context":{"type":"object","additionalProperties":{}},"contact":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"locale":{"type":"string"}},"additionalProperties":false},"consent":{"type":"object","additionalProperties":{"type":"boolean"}}},"additionalProperties":false,"required":["name"]}}}}}}}}