{"openapi":"3.1.0","info":{"title":"COSS API","version":"2026-10-10","description":"One API key for every COSS product. Errors share one envelope: `Error`. Every request is scoped to the environment the key belongs to; domains and the audit log are organization-wide."},"servers":[{"url":"https://api.coss.com"}],"tags":[{"name":"Emails","description":"Send transactional email and follow its delivery."},{"name":"Suppressions","description":"Addresses that sends skip, added by bounces, complaints or you."},{"name":"Tracking","description":"Which emails of the environment have their opens and clicks tracked."},{"name":"Domains","description":"The organization's verified sending domains."},{"name":"Webhook endpoints","description":"URLs that receive the environment's delivery events, signed."},{"name":"Logs","description":"The environment's API requests, email events and webhook attempts."},{"name":"Audit log","description":"Changes to the organization, by members, API keys and COSS support."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A secret API key from the dashboard: `coss_live_…` for production environments, `coss_test_…` for sandbox environments."}},"schemas":{"Email":{"type":"object","properties":{"object":{"type":"string","enum":["email"]},"id":{"type":"string","examples":["email_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"from":{"type":"string"},"to":{"type":"array","items":{"type":"string"}},"cc":{"type":"array","items":{"type":"string"}},"bcc":{"type":"array","items":{"type":"string"}},"reply_to":{"type":"array","items":{"type":"string"}},"subject":{"type":"string"},"html":{"type":["string","null"]},"text":{"type":["string","null"]},"headers":{"type":"object","additionalProperties":{"type":"string"}},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}},"required":["name","value"]}},"category":{"type":["string","null"]},"status":{"type":"string","enum":["queued","sent","failed","scheduled","canceled"],"description":"Whether the email was handed to the delivery provider. `scheduled` emails wait for `scheduled_at`; `canceled` ones were canceled before that. Per-recipient delivery is in `recipients`."},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/EmailRecipient"}},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/EmailAttachment"},"description":"Attachment metadata. Content is never returned, and is discarded once sent."},"sandbox":{"type":"boolean","description":"True when sent from a sandbox environment (never delivered)."},"tracking":{"$ref":"#/components/schemas/EmailTracking"},"created_at":{"type":"string","format":"date-time"},"sent_at":{"type":["string","null"],"format":"date-time"},"scheduled_at":{"type":["string","null"],"format":"date-time","description":"When the email was scheduled to be sent; `null` if it was not."},"batch_id":{"type":["string","null"],"description":"The batch that sent the email; `null` if it was sent on its own."}},"required":["object","id","from","to","cc","bcc","reply_to","subject","html","text","headers","tags","category","status","recipients","attachments","sandbox","tracking","created_at","sent_at","scheduled_at","batch_id"],"examples":[{"object":"email","id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","from":"Acme <onboarding@acme.com>","to":["user@example.com"],"cc":[],"bcc":[],"reply_to":[],"subject":"Welcome to Acme","html":"<p>Thanks for signing up!</p>","text":null,"headers":{},"tags":[{"name":"template","value":"welcome"}],"category":"onboarding","status":"sent","recipients":[{"address":"user@example.com","type":"to","status":"delivered","last_event_at":"2026-10-10T12:00:02.000Z"}],"sandbox":false,"tracking":{"opens":false,"clicks":false,"open_count":0,"first_opened_at":null,"last_opened_at":null,"click_count":0,"first_clicked_at":null,"last_clicked_at":null},"attachments":[],"created_at":"2026-10-10T12:00:00.000Z","sent_at":"2026-10-10T12:00:01.000Z","scheduled_at":null,"batch_id":null}]},"EmailRecipient":{"type":"object","properties":{"address":{"type":"string","description":"The bare, lower-cased address."},"type":{"type":"string","enum":["to","cc","bcc"]},"status":{"type":"string","enum":["queued","sent","delivery_delayed","delivered","bounced","suppressed","complained","failed","canceled"],"description":"Delivery status of this recipient. `suppressed` means the address is on the environment's suppression list (for every email or for this email's category), so it was skipped. `canceled` means the scheduled email was canceled before it was sent."},"last_event_at":{"type":["string","null"],"format":"date-time"}},"required":["address","type","status","last_event_at"],"examples":[{"address":"user@example.com","type":"to","status":"delivered","last_event_at":"2026-10-10T12:00:02.000Z"}]},"EmailAttachment":{"type":"object","properties":{"id":{"type":"string","example":"att_01k7c8m4q2f3e9v6t5r1n0p8yz"},"filename":{"type":"string"},"content_type":{"type":"string"},"content_id":{"type":["string","null"],"description":"Set for inline attachments (`cid:` references)."},"size":{"type":"integer","description":"Size in bytes."}},"required":["id","filename","content_type","content_id","size"]},"EmailTracking":{"type":"object","properties":{"opens":{"type":"boolean","description":"Whether opens are tracked for this email."},"clicks":{"type":"boolean","description":"Whether link clicks are tracked for this email."},"open_count":{"type":"integer"},"first_opened_at":{"type":["string","null"],"format":"date-time"},"last_opened_at":{"type":["string","null"],"format":"date-time"},"click_count":{"type":"integer"},"first_clicked_at":{"type":["string","null"],"format":"date-time"},"last_clicked_at":{"type":["string","null"],"format":"date-time"}},"required":["opens","clicks","open_count","first_opened_at","last_opened_at","click_count","first_clicked_at","last_clicked_at"],"examples":[{"opens":false,"clicks":false,"open_count":0,"first_opened_at":null,"last_opened_at":null,"click_count":0,"first_clicked_at":null,"last_clicked_at":null}],"description":"Open and click tracking, as resolved when the email was sent, with engagement so far. Opens can be inflated by mail clients that prefetch images, clicks by link scanners."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","idempotency_error","rate_limit_error","billing_error","api_error"]},"code":{"type":"string","description":"Machine-readable reason, e.g. `invalid_api_key`."},"message":{"type":"string","description":"Human-readable explanation. May change."},"param":{"type":"string","description":"The request field or header the error relates to."},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, e.g. `to.1`."},"message":{"type":"string"}},"required":["path","message"]},"description":"Every validation problem (`validation_error` only)."},"request_id":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"required":["type","code","message","request_id"]}},"required":["error"]},"SendEmailRequest":{"type":"object","properties":{"from":{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},"to":{"anyOf":[{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},{"type":"array","items":{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},"minItems":1,"maxItems":50}]},"cc":{"anyOf":[{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},{"type":"array","items":{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},"minItems":0,"maxItems":50}]},"bcc":{"anyOf":[{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},{"type":"array","items":{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},"minItems":0,"maxItems":50}]},"reply_to":{"anyOf":[{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},{"type":"array","items":{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},"minItems":0,"maxItems":50}]},"subject":{"type":"string","minLength":1,"maxLength":998},"html":{"type":"string","description":"HTML body. Provide `html`, `text`, or both."},"text":{"type":"string","description":"Plain-text body."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Up to 15 custom headers. Names are case-insensitive."},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$"},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$"}},"required":["name","value"],"additionalProperties":false},"maxItems":50},"category":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"What kind of email this is, e.g. \"marketing\". Recipients suppressed for this category (or for every email) are skipped."},"scheduled_at":{"type":"string","format":"date-time","description":"Send the email at this time instead of now (ISO 8601 with an offset, at most 30 days ahead). A time that is not in the future sends immediately. Scheduled emails can be rescheduled or canceled until they are sent.","example":"2026-10-11T09:00:00Z"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/SendEmailAttachment"},"maxItems":20,"description":"Up to 20 files, at most 25 MB combined."},"tracking":{"$ref":"#/components/schemas/TrackingOptions"}},"required":["from","to","subject"],"additionalProperties":false,"examples":[{"from":"Acme <onboarding@acme.com>","to":"user@example.com","subject":"Welcome to Acme","html":"<p>Thanks for signing up!</p>","tags":[{"name":"template","value":"welcome"}],"category":"onboarding"}]},"SendEmailAttachment":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"content":{"type":"string","minLength":1,"description":"The file's bytes, base64-encoded."},"content_type":{"type":"string","pattern":"^[!#$%&'*+.^_`|~0-9A-Za-z-]+\\/[!#$%&'*+.^_`|~0-9A-Za-z-]+$","description":"Defaults from the filename's extension."},"content_id":{"type":"string","pattern":"^[A-Za-z0-9!#$%&'*+\\-./=?^_`{|}~@]{1,100}$","description":"Makes the attachment inline: reference it from `html` as `<img src=\"cid:logo@acme\">`."}},"required":["filename","content"],"additionalProperties":false},"TrackingOptions":{"type":"object","properties":{"opens":{"type":"boolean","description":"Add an invisible pixel to the HTML body and record `email.opened` events."},"clicks":{"type":"boolean","description":"Send HTML links through a COSS redirect and record `email.clicked` events. Links with a `data-coss-no-track` attribute are left alone."}},"additionalProperties":false,"description":"Overrides the environment's tracking settings (its default, or the rule for this email's category) for this email. Omitted fields keep the configured setting."},"EmailBatch":{"type":"object","properties":{"object":{"type":"string","enum":["email_batch"]},"id":{"type":"string","examples":["batch_01k8d0n6x5f3w2e1r9t7y4u6i8"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Email"},"description":"The batch's emails, in the order of the request."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","data","created_at"],"examples":[{"object":"email_batch","id":"batch_01k8d0n6x5f3w2e1r9t7y4u6i8","data":[{"object":"email","id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","from":"Acme <notifications@acme.com>","to":["ada@example.com"],"cc":[],"bcc":[],"reply_to":[],"subject":"Your weekly summary","html":"<p>Hi Ada, here is your week.</p>","text":null,"headers":{},"tags":[],"category":"digest","status":"queued","recipients":[{"address":"ada@example.com","type":"to","status":"queued","last_event_at":null}],"sandbox":false,"tracking":{"opens":false,"clicks":false,"open_count":0,"first_opened_at":null,"last_opened_at":null,"click_count":0,"first_clicked_at":null,"last_clicked_at":null},"attachments":[],"created_at":"2026-10-10T12:00:00.000Z","sent_at":null,"scheduled_at":null,"batch_id":"batch_01k8d0n6x5f3w2e1r9t7y4u6i8"}],"created_at":"2026-10-10T12:00:00.000Z"}]},"SendEmailBatchRequest":{"type":"object","properties":{"emails":{"type":"array","items":{"$ref":"#/components/schemas/SendEmailRequest"},"minItems":1,"maxItems":100,"description":"Up to 100 emails, each accepted by `POST /v1/emails`. The batch is accepted or rejected as a whole."}},"required":["emails"],"additionalProperties":false,"examples":[{"emails":[{"from":"Acme <notifications@acme.com>","to":"ada@example.com","subject":"Your weekly summary","html":"<p>Hi Ada, here is your week.</p>","category":"digest"},{"from":"Acme <notifications@acme.com>","to":"grace@example.com","subject":"Your weekly summary","html":"<p>Hi Grace, here is your week.</p>","category":"digest"}]}]},"RescheduleEmailRequest":{"type":"object","properties":{"scheduled_at":{"type":"string","format":"date-time","description":"The new time to send the email at (ISO 8601 with an offset, at most 30 days ahead). A time that is not in the future sends it right away.","example":"2026-10-12T09:00:00Z"}},"required":["scheduled_at"],"additionalProperties":false,"examples":[{"scheduled_at":"2026-10-12T09:00:00Z"}]},"EmailEventList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailEvent"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"email_event","id":"evt_01k7c8m4r0c2b8w9y3d5f6g7h8","email_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","type":"email.sent","recipient":null,"occurred_at":"2026-10-10T12:00:01.000Z","data":{}},{"object":"email_event","id":"evt_01k7c8m4q2f3e9v6t5r1n0p8yz","email_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","type":"email.delivered","recipient":"user@example.com","occurred_at":"2026-10-10T12:00:02.000Z","data":{"delivery":{"smtp_response":"250 2.0.0 OK"}}}],"has_more":false}]},"EmailEvent":{"type":"object","properties":{"object":{"type":"string","enum":["email_event"]},"id":{"type":"string","examples":["evt_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"email_id":{"type":"string"},"type":{"type":"string","enum":["email.sent","email.delivered","email.delivery_delayed","email.bounced","email.complained","email.failed","email.suppressed","email.scheduled","email.canceled","email.opened","email.clicked","email.rescheduled"]},"recipient":{"type":["string","null"],"description":"The recipient this event is about; `null` for the whole email."},"occurred_at":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/EmailEventData"}},"required":["object","id","email_id","type","recipient","occurred_at","data"],"examples":[{"object":"email_event","id":"evt_01k7c8m4q2f3e9v6t5r1n0p8yz","email_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","type":"email.delivered","recipient":"user@example.com","occurred_at":"2026-10-10T12:00:02.000Z","data":{"delivery":{"smtp_response":"250 2.0.0 OK"}}}]},"EmailEventData":{"type":"object","properties":{"bounce":{"type":"object","properties":{"type":{"type":"string","enum":["permanent","transient","undetermined"]},"sub_type":{"type":"string"},"diagnostic_code":{"type":["string","null"]}},"required":["type","sub_type","diagnostic_code"]},"complaint":{"type":"object","properties":{"feedback_type":{"type":["string","null"]},"sub_type":{"type":["string","null"]}},"required":["feedback_type","sub_type"]},"delay":{"type":"object","properties":{"type":{"type":"string"},"expires_at":{"type":["string","null"],"format":"date-time"},"diagnostic_code":{"type":["string","null"]}},"required":["type","expires_at","diagnostic_code"]},"delivery":{"type":"object","properties":{"smtp_response":{"type":["string","null"]}},"required":["smtp_response"]},"failure":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"suppression":{"type":"object","properties":{"id":{"type":"string"},"scope":{"type":"string"},"reason":{"type":"string","enum":["bounce","complaint","manual","import"],"description":"`bounce`: added after a permanent bounce. `complaint`: added after a spam complaint. `manual`: added one by one through the API or dashboard. `import`: added by a bulk import."}},"required":["id","scope","reason"],"description":"Only for `email.suppressed`: the entry that matched the recipient."},"open":{"type":"object","properties":{"user_agent":{"type":["string","null"]}},"required":["user_agent"],"description":"Only for `email.opened`."},"click":{"type":"object","properties":{"url":{"type":"string","description":"The original link that was clicked."},"link_position":{"type":"integer","description":"Index of the link among the email's tracked links."},"user_agent":{"type":["string","null"]}},"required":["url","link_position","user_agent"],"description":"Only for `email.clicked`."},"reschedule":{"type":"object","properties":{"scheduled_at":{"type":"string","format":"date-time","description":"The new time."},"previous_scheduled_at":{"type":"string","format":"date-time","description":"The time it replaced."}},"required":["scheduled_at","previous_scheduled_at"],"description":"Only for `email.rescheduled`."}},"examples":[{"delivery":{"smtp_response":"250 2.0.0 OK"}}]},"EmailLinkList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailLink"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"email_link","id":"lnk_01k7c8m4q2f3e9v6t5r1n0p8yz","email_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","position":0,"url":"https://acme.com/start","click_count":0,"first_clicked_at":null,"last_clicked_at":null}],"has_more":false}]},"EmailLink":{"type":"object","properties":{"object":{"type":"string","enum":["email_link"]},"id":{"type":"string","examples":["lnk_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"email_id":{"type":"string"},"position":{"type":"integer","description":"Index of the link among the tracked links."},"url":{"type":"string"},"click_count":{"type":"integer"},"first_clicked_at":{"type":["string","null"],"format":"date-time"},"last_clicked_at":{"type":["string","null"],"format":"date-time"}},"required":["object","id","email_id","position","url","click_count","first_clicked_at","last_clicked_at"],"examples":[{"object":"email_link","id":"lnk_01k7c8m4q2f3e9v6t5r1n0p8yz","email_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","position":0,"url":"https://acme.com/start","click_count":0,"first_clicked_at":null,"last_clicked_at":null}]},"Domain":{"type":"object","properties":{"object":{"type":"string","enum":["domain"]},"id":{"type":"string","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"name":{"type":"string","description":"The domain, lower-cased.","examples":["acme.com"]},"status":{"type":"string","enum":["pending","verified","temporary_failure","failed","deleting"],"description":"`pending` while the records are being checked, `verified` once they are, `temporary_failure` after a transient DNS problem, and `failed` when verification gave up (72 hours) — restart it with the verify endpoint. `deleting` is a removal in progress."},"can_send":{"type":"boolean","description":"Whether live keys may send from this domain right now."},"region":{"type":["string","null"]},"mail_from_domain":{"type":"string","description":"The envelope sender subdomain bounces come back to."},"mail_from_status":{"type":"string","enum":["pending","success","temporary_failure","failed"]},"records":{"type":"array","items":{"$ref":"#/components/schemas/DomainRecord"},"description":"The DNS records to publish, with the result of the last check."},"created_at":{"type":"string","format":"date-time"},"last_checked_at":{"type":["string","null"],"format":"date-time"},"verified_at":{"type":["string","null"],"format":"date-time"},"failed_at":{"type":["string","null"],"format":"date-time"},"tracking":{"anyOf":[{"$ref":"#/components/schemas/TrackingDomain"},{"type":"null"}]}},"required":["object","id","name","status","can_send","region","mail_from_domain","mail_from_status","records","created_at","last_checked_at","verified_at","failed_at","tracking"],"examples":[{"object":"domain","id":"dom_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"acme.com","status":"verified","can_send":true,"region":"us-east-1","mail_from_domain":"send.acme.com","mail_from_status":"success","records":[{"priority":null,"required":true,"status":"verified","found":[],"purpose":"dkim","type":"CNAME","name":"x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e._domainkey.acme.com","value":"x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e.dkim.amazonses.com"},{"priority":10,"required":true,"status":"verified","found":[],"purpose":"mail_from_mx","type":"MX","name":"send.acme.com","value":"feedback-smtp.us-east-1.amazonses.com"},{"priority":null,"required":true,"status":"verified","found":[],"purpose":"mail_from_spf","type":"TXT","name":"send.acme.com","value":"v=spf1 include:amazonses.com ~all"},{"priority":null,"required":false,"status":"verified","found":[],"purpose":"dmarc","type":"TXT","name":"_dmarc.acme.com","value":"v=DMARC1; p=none;"}],"created_at":"2026-01-15T09:30:00.000Z","last_checked_at":"2026-01-15T09:42:10.000Z","verified_at":"2026-01-15T09:42:10.000Z","failed_at":null,"tracking":{"hostname":"links.acme.com","status":"active","record":{"type":"CNAME","name":"links.acme.com","value":"track.coss.com","status":"verified","found":[]},"message":null,"created_at":"2026-01-15T09:45:00.000Z","last_checked_at":"2026-01-15T09:52:00.000Z","activated_at":"2026-01-15T09:52:00.000Z","failed_at":null}}]},"DomainRecord":{"type":"object","properties":{"purpose":{"type":"string","enum":["dkim","mail_from_mx","mail_from_spf","dmarc"],"description":"What the record is for: `dkim` signs messages, `mail_from_mx` and `mail_from_spf` set up the bounce subdomain, `dmarc` is recommended but not required."},"type":{"type":"string","enum":["CNAME","MX","TXT"]},"name":{"type":"string","description":"The fully qualified record name to create."},"value":{"type":"string"},"priority":{"type":["integer","null"],"description":"`MX` records only."},"required":{"type":"boolean","description":"`false` for records that are only recommended."},"status":{"type":"string","enum":["verified","missing","mismatch","not_checked"],"description":"What the last DNS check saw. `not_checked` means DNS has not been consulted yet."},"found":{"type":"array","items":{"type":"string"},"description":"What DNS returned when it did not match."}},"required":["purpose","type","name","value","priority","required","status","found"],"examples":[{"priority":null,"required":true,"status":"verified","found":[],"purpose":"dkim","type":"CNAME","name":"x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e._domainkey.acme.com","value":"x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e.dkim.amazonses.com"}]},"TrackingDomain":{"type":"object","properties":{"hostname":{"type":"string","description":"The tracking hostname, a subdomain of the domain.","examples":["links.acme.com"]},"status":{"type":"string","enum":["pending","active","temporary_failure","failed","deleting"],"description":"`pending` until the CNAME points at COSS and its certificate is issued, `active` once links and open pixels of emails sent from the domain use it, `temporary_failure` when an active hostname stopped working (emails fall back to the default tracking host meanwhile), `failed` when setup gave up (72 hours) — restart it with the domain's verify endpoint. `deleting` is a removal in progress."},"record":{"type":"object","properties":{"type":{"type":"string","enum":["CNAME"]},"name":{"type":"string","description":"The fully qualified record name to create."},"value":{"type":"string","description":"The host the record must point at."},"status":{"type":"string","enum":["verified","missing","mismatch","not_checked"],"description":"What the last DNS check saw. `not_checked` means DNS has not been consulted yet."},"found":{"type":"array","items":{"type":"string"},"description":"What DNS returned when it did not match."}},"required":["type","name","value","status","found"],"description":"The DNS record to publish, with the result of the last check."},"message":{"type":["string","null"],"description":"What is holding the hostname up, when the certificate provider said."},"created_at":{"type":"string","format":"date-time"},"last_checked_at":{"type":["string","null"],"format":"date-time"},"activated_at":{"type":["string","null"],"format":"date-time"},"failed_at":{"type":["string","null"],"format":"date-time"}},"required":["hostname","status","record","message","created_at","last_checked_at","activated_at","failed_at"],"description":"A domain's custom tracking domain: open pixels and click redirects of emails sent from the domain use it while it is `active`.","examples":[{"hostname":"links.acme.com","status":"active","record":{"type":"CNAME","name":"links.acme.com","value":"track.coss.com","status":"verified","found":[]},"message":null,"created_at":"2026-01-15T09:45:00.000Z","last_checked_at":"2026-01-15T09:52:00.000Z","activated_at":"2026-01-15T09:52:00.000Z","failed_at":null}]},"CreateDomainRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"The domain to send from, without a scheme or path. Subdomains are allowed; internationalized domains must be punycode-encoded.","examples":["acme.com"]}},"required":["name"],"additionalProperties":false,"examples":[{"name":"acme.com"}]},"DomainList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"domain","id":"dom_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"acme.com","status":"verified","can_send":true,"region":"us-east-1","mail_from_domain":"send.acme.com","mail_from_status":"success","records":[{"priority":null,"required":true,"status":"verified","found":[],"purpose":"dkim","type":"CNAME","name":"x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e._domainkey.acme.com","value":"x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e.dkim.amazonses.com"},{"priority":10,"required":true,"status":"verified","found":[],"purpose":"mail_from_mx","type":"MX","name":"send.acme.com","value":"feedback-smtp.us-east-1.amazonses.com"},{"priority":null,"required":true,"status":"verified","found":[],"purpose":"mail_from_spf","type":"TXT","name":"send.acme.com","value":"v=spf1 include:amazonses.com ~all"},{"priority":null,"required":false,"status":"verified","found":[],"purpose":"dmarc","type":"TXT","name":"_dmarc.acme.com","value":"v=DMARC1; p=none;"}],"created_at":"2026-01-15T09:30:00.000Z","last_checked_at":"2026-01-15T09:42:10.000Z","verified_at":"2026-01-15T09:42:10.000Z","failed_at":null,"tracking":{"hostname":"links.acme.com","status":"active","record":{"type":"CNAME","name":"links.acme.com","value":"track.coss.com","status":"verified","found":[]},"message":null,"created_at":"2026-01-15T09:45:00.000Z","last_checked_at":"2026-01-15T09:52:00.000Z","activated_at":"2026-01-15T09:52:00.000Z","failed_at":null}}],"has_more":false}]},"DeletedDomain":{"type":"object","properties":{"object":{"type":"string","enum":["domain"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"domain","id":"dom_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"CreateTrackingDomainRequest":{"type":"object","properties":{"hostname":{"type":"string","minLength":1,"maxLength":200,"description":"A subdomain of the domain to serve tracking links from, without a scheme or path. Point it at COSS with the CNAME record the response lists.","examples":["links.acme.com"]}},"required":["hostname"],"additionalProperties":false,"examples":[{"hostname":"links.acme.com"}]},"WebhookEndpointWithSecret":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_endpoint"]},"id":{"type":"string","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"url":{"type":"string","examples":["https://example.com/webhooks/coss"]},"description":{"type":["string","null"]},"event_types":{"type":"array","items":{"type":"string"},"description":"Event types delivered to this endpoint. An empty array means every event type, including ones added later."},"api_version":{"type":"string","description":"The API version (`Coss-Version`) events are rendered in for this endpoint. Each event carries it as `api_version`.","examples":["2026-10-10"]},"enabled":{"type":"boolean","description":"A disabled endpoint receives nothing until it is enabled again."},"previous_secret_expires_at":{"type":["string","null"],"format":"date-time","description":"After a secret roll, deliveries are also signed with the previous secret until this time. `null` when only the current secret signs."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"The endpoint's `whsec_…` signing secret, used to verify the requests COSS sends. Returned only when the endpoint is created and when its secret is rolled — store it now; it cannot be read back through the API.","examples":["whsec_6Jk…"]}},"required":["object","id","url","description","event_types","api_version","enabled","previous_secret_expires_at","created_at","updated_at","secret"],"examples":[{"object":"webhook_endpoint","id":"whep_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://example.com/webhooks/coss","description":"Production receiver","event_types":["email.delivered","email.bounced"],"api_version":"2026-10-10","enabled":true,"previous_secret_expires_at":null,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z","secret":"whsec_6Jk…"}]},"CreateWebhookEndpointRequest":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"An `https://` URL COSS posts events to.","examples":["https://example.com/webhooks/coss"]},"description":{"type":["string","null"],"maxLength":256,"description":"A note for your own reference. `null` clears it."},"event_types":{"type":"array","items":{"type":"string","enum":["email.sent","email.delivered","email.delivery_delayed","email.bounced","email.complained","email.failed","email.suppressed","email.scheduled","email.canceled","email.opened","email.clicked","email.rescheduled","account.reputation_warning","account.reputation_recovered","account.suspended","account.reinstated","billing.invoice_finalized","billing.invoice_paid","billing.invoice_payment_failed","billing.invoice_voided","billing.plan_changed","billing.usage_threshold_reached","billing.hold_placed","billing.hold_lifted","billing.credit_granted"]},"maxItems":25,"description":"Event types delivered to this endpoint. An empty array means every event type, including ones added later. Defaults to every event type."},"api_version":{"type":"string","enum":["2026-10-10"],"description":"The API version (`Coss-Version`) events are rendered in for this endpoint. Each event carries it as `api_version`. Defaults to the version of the request that creates the endpoint."}},"required":["url"],"additionalProperties":false,"examples":[{"url":"https://example.com/webhooks/coss","description":"Production receiver","event_types":["email.sent","email.delivered"]}]},"WebhookEndpointList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"webhook_endpoint","id":"whep_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://example.com/webhooks/coss","description":"Production receiver","event_types":["email.delivered","email.bounced"],"api_version":"2026-10-10","enabled":true,"previous_secret_expires_at":null,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"WebhookEndpoint":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_endpoint"]},"id":{"type":"string","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"url":{"type":"string","examples":["https://example.com/webhooks/coss"]},"description":{"type":["string","null"]},"event_types":{"type":"array","items":{"type":"string"},"description":"Event types delivered to this endpoint. An empty array means every event type, including ones added later."},"api_version":{"type":"string","description":"The API version (`Coss-Version`) events are rendered in for this endpoint. Each event carries it as `api_version`.","examples":["2026-10-10"]},"enabled":{"type":"boolean","description":"A disabled endpoint receives nothing until it is enabled again."},"previous_secret_expires_at":{"type":["string","null"],"format":"date-time","description":"After a secret roll, deliveries are also signed with the previous secret until this time. `null` when only the current secret signs."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","url","description","event_types","api_version","enabled","previous_secret_expires_at","created_at","updated_at"],"examples":[{"object":"webhook_endpoint","id":"whep_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://example.com/webhooks/coss","description":"Production receiver","event_types":["email.delivered","email.bounced"],"api_version":"2026-10-10","enabled":true,"previous_secret_expires_at":null,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}]},"UpdateWebhookEndpointRequest":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"An `https://` URL COSS posts events to.","examples":["https://example.com/webhooks/coss"]},"description":{"type":["string","null"],"maxLength":256,"description":"A note for your own reference. `null` clears it."},"event_types":{"type":"array","items":{"type":"string","enum":["email.sent","email.delivered","email.delivery_delayed","email.bounced","email.complained","email.failed","email.suppressed","email.scheduled","email.canceled","email.opened","email.clicked","email.rescheduled","account.reputation_warning","account.reputation_recovered","account.suspended","account.reinstated","billing.invoice_finalized","billing.invoice_paid","billing.invoice_payment_failed","billing.invoice_voided","billing.plan_changed","billing.usage_threshold_reached","billing.hold_placed","billing.hold_lifted","billing.credit_granted"]},"maxItems":25,"description":"Event types delivered to this endpoint. An empty array means every event type, including ones added later."},"api_version":{"type":"string","enum":["2026-10-10"],"description":"The API version (`Coss-Version`) events are rendered in for this endpoint. Each event carries it as `api_version`."},"enabled":{"type":"boolean"}},"additionalProperties":false,"examples":[{"enabled":false}]},"RollWebhookEndpointSecretRequest":{"type":"object","properties":{"previous_secret_expires_in":{"type":"integer","minimum":0,"maximum":604800,"description":"Seconds the current secret keeps signing deliveries next to the new one, so receivers can switch without rejecting anything. Default 86400 (a day), at most 604800 (a week). `0` stops it immediately, e.g. after a leak."}},"additionalProperties":false,"examples":[{"previous_secret_expires_in":3600}]},"DeletedWebhookEndpoint":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_endpoint"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"webhook_endpoint","id":"whep_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"WebhookDeliveryList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"webhook_delivery","id":"whdel_01k7c8n2b5d7f9h1k3m5p7r9tv","endpoint_id":"whep_01k7c8m4q2f3e9v6t5r1n0p8yz","event_id":"evt_01k7c8n1z4c6e8g0j2l4n6q8sa","event_type":"email.delivered","status":"succeeded","attempt_count":1,"next_attempt_at":null,"last_status_code":200,"last_error":null,"payload":{"id":"evt_01k7c8n1z4c6e8g0j2l4n6q8sa","object":"event","type":"email.delivered","created_at":"2026-01-15T09:30:00.000Z","data":{"email_id":"email_01k7c8m9x3a5c7e9g1j3l5n7q9","recipient":"user@example.com"}},"attempts":[{"object":"webhook_attempt","id":"whatt_01k7c8n2c9e1g3j5l7n9q1s3uw","attempted_at":"2026-01-15T09:30:01.000Z","status_code":200,"duration_ms":182,"error":null,"response_excerpt":"ok"}],"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:01.000Z"}],"has_more":false}]},"WebhookDelivery":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_delivery"]},"id":{"type":"string","examples":["whdel_01k7c8n2b5d7f9h1k3m5p7r9tv"]},"endpoint_id":{"type":"string"},"event_id":{"type":"string","description":"The event's id: the `id` of the payload and the `webhook-id` header."},"event_type":{"type":"string","examples":["email.delivered"]},"status":{"$ref":"#/components/schemas/WebhookDeliveryStatus"},"attempt_count":{"type":"integer"},"next_attempt_at":{"type":["string","null"],"format":"date-time","description":"When the next attempt is due; `null` once the delivery is finished."},"last_status_code":{"type":["integer","null"]},"last_error":{"type":["string","null"]},"payload":{"type":"object","additionalProperties":{},"description":"The event body, exactly as posted to the endpoint."},"attempts":{"type":"array","items":{"$ref":"#/components/schemas/WebhookAttempt"},"description":"Every HTTP attempt of this delivery, oldest first."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","endpoint_id","event_id","event_type","status","attempt_count","next_attempt_at","last_status_code","last_error","payload","attempts","created_at","updated_at"],"examples":[{"object":"webhook_delivery","id":"whdel_01k7c8n2b5d7f9h1k3m5p7r9tv","endpoint_id":"whep_01k7c8m4q2f3e9v6t5r1n0p8yz","event_id":"evt_01k7c8n1z4c6e8g0j2l4n6q8sa","event_type":"email.delivered","status":"succeeded","attempt_count":1,"next_attempt_at":null,"last_status_code":200,"last_error":null,"payload":{"id":"evt_01k7c8n1z4c6e8g0j2l4n6q8sa","object":"event","type":"email.delivered","created_at":"2026-01-15T09:30:00.000Z","data":{"email_id":"email_01k7c8m9x3a5c7e9g1j3l5n7q9","recipient":"user@example.com"}},"attempts":[{"object":"webhook_attempt","id":"whatt_01k7c8n2c9e1g3j5l7n9q1s3uw","attempted_at":"2026-01-15T09:30:01.000Z","status_code":200,"duration_ms":182,"error":null,"response_excerpt":"ok"}],"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:01.000Z"}]},"WebhookDeliveryStatus":{"type":"string","enum":["pending","succeeded","failed"],"description":"`pending`: waiting for its next attempt. `succeeded`: the endpoint answered with a 2xx status. `failed`: every attempt failed, or the endpoint was disabled."},"WebhookAttempt":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_attempt"]},"id":{"type":"string"},"attempted_at":{"type":"string","format":"date-time"},"status_code":{"type":["integer","null"],"description":"The endpoint's HTTP status; `null` when no response arrived."},"duration_ms":{"type":"integer"},"error":{"type":["string","null"],"description":"Why the attempt failed (e.g. `HTTP 500`, a timeout); `null` on success."},"response_excerpt":{"type":["string","null"],"description":"At most 1 KB of the response body, as text."}},"required":["object","id","attempted_at","status_code","duration_ms","error","response_excerpt"],"examples":[{"object":"webhook_attempt","id":"whatt_01k7c8n2c9e1g3j5l7n9q1s3uw","attempted_at":"2026-01-15T09:30:01.000Z","status_code":200,"duration_ms":182,"error":null,"response_excerpt":"ok"}]},"Suppression":{"type":"object","properties":{"object":{"type":"string","enum":["suppression"]},"id":{"type":"string","examples":["sup_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"address":{"type":"string","description":"The bare, lower-cased address."},"scope":{"type":"string","description":"`*` (every email) or a category."},"reason":{"type":"string","enum":["bounce","complaint","manual","import"],"description":"`bounce`: added after a permanent bounce. `complaint`: added after a spam complaint. `manual`: added one by one through the API or dashboard. `import`: added by a bulk import."},"email_id":{"type":["string","null"],"description":"The email whose bounce or complaint added this entry."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","address","scope","reason","email_id","created_at"],"examples":[{"object":"suppression","id":"sup_01k7c8m4q2f3e9v6t5r1n0p8yz","address":"user@example.com","scope":"marketing","reason":"manual","email_id":null,"created_at":"2026-01-15T09:30:00.000Z"}]},"CreateSuppressionRequest":{"type":"object","properties":{"address":{"type":"string","description":"The address to suppress. Display names are ignored; matching is case-insensitive."},"scope":{"anyOf":[{"type":"string","enum":["*"]},{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$"}],"description":"Defaults to `*` (every email). Pass a category, e.g. \"marketing\", to only skip those."}},"required":["address"],"additionalProperties":false,"examples":[{"address":"user@example.com","scope":"marketing"}]},"SuppressionList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Suppression"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"suppression","id":"sup_01k7c8m4q2f3e9v6t5r1n0p8yz","address":"user@example.com","scope":"marketing","reason":"manual","email_id":null,"created_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"SuppressionCheck":{"type":"object","properties":{"object":{"type":"string","enum":["suppression_check"]},"address":{"type":"string"},"suppressed":{"type":"boolean","description":"Whether a send (with the given category) would skip this address."},"suppressions":{"type":"array","items":{"$ref":"#/components/schemas/Suppression"},"description":"The entries that match."}},"required":["object","address","suppressed","suppressions"],"examples":[{"object":"suppression_check","address":"user@example.com","suppressed":true,"suppressions":[{"object":"suppression","id":"sup_01k7c8m4q2f3e9v6t5r1n0p8yz","address":"user@example.com","scope":"marketing","reason":"manual","email_id":null,"created_at":"2026-01-15T09:30:00.000Z"}]}]},"SuppressionImport":{"type":"object","properties":{"object":{"type":"string","enum":["suppression_import"]},"created":{"type":"integer","description":"Entries added by this import."},"existing":{"type":"integer","description":"Valid entries that were already on the list (or repeated within this import); unchanged."},"invalid":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"Position of the entry in the request."},"address":{"type":"string"},"message":{"type":"string"}},"required":["index","address","message"]},"description":"Entries that were skipped, with the reason."}},"required":["object","created","existing","invalid"],"examples":[{"object":"suppression_import","created":2,"existing":0,"invalid":[]}]},"ImportSuppressionsRequest":{"type":"object","properties":{"suppressions":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string","description":"The address to suppress."},"scope":{"type":"string","description":"`*` (the default) or a category."}},"required":["address"],"additionalProperties":false},"minItems":1,"maxItems":1000,"description":"1-1000 entries. Each one is validated on its own: invalid entries are skipped and reported in `invalid`, the rest are imported."}},"required":["suppressions"],"additionalProperties":false,"examples":[{"suppressions":[{"address":"user@example.com"},{"address":"other@example.com","scope":"marketing"}]}]},"DeletedSuppression":{"type":"object","properties":{"object":{"type":"string","enum":["suppression"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"suppression","id":"sup_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"TrackingSettings":{"type":"object","properties":{"object":{"type":"string","enum":["tracking_settings"]},"default":{"anyOf":[{"$ref":"#/components/schemas/TrackingRule"},{"type":"null"}]},"categories":{"type":"array","items":{"$ref":"#/components/schemas/TrackingRule"},"description":"Category rules, by category name."}},"required":["object","default","categories"],"description":"Open and click tracking settings of the API key's environment. For each of `opens` and `clicks`, a send's own `tracking` wins, then its category's rule, then `default` (the environment default; `null` when none is set), then off.","examples":[{"object":"tracking_settings","default":{"object":"tracking_rule","id":"etr_01k7c8k1d9w4x2b7n3m5q6r8st","category":null,"opens":true,"clicks":true,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"},"categories":[{"object":"tracking_rule","id":"etr_01k7c8m4q2f3e9v6t5r1n0p8yz","category":"password-reset","opens":false,"clicks":false,"created_at":"2026-01-16T10:00:00.000Z","updated_at":"2026-01-16T10:00:00.000Z"}]}]},"TrackingRule":{"type":"object","properties":{"object":{"type":"string","enum":["tracking_rule"]},"id":{"type":"string","examples":["etr_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"category":{"type":["string","null"],"description":"The category the rule applies to; `null` for the environment default."},"opens":{"type":"boolean","description":"Whether opens are tracked."},"clicks":{"type":"boolean","description":"Whether clicks are tracked."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","category","opens","clicks","created_at","updated_at"],"description":"An environment's tracking default (`category: null`) or the rule for one category. Emails are fixed to the settings that applied when they were sent.","examples":[{"object":"tracking_rule","id":"etr_01k7c8m4q2f3e9v6t5r1n0p8yz","category":"password-reset","opens":false,"clicks":false,"created_at":"2026-01-16T10:00:00.000Z","updated_at":"2026-01-16T10:00:00.000Z"}]},"UpdateTrackingRuleRequest":{"type":"object","properties":{"opens":{"type":"boolean","description":"Track opens."},"clicks":{"type":"boolean","description":"Track clicks."}},"additionalProperties":false,"description":"Fields left out keep their current value; a new rule starts with both off. A send's own `tracking` option still wins over the rule.","examples":[{"opens":false,"clicks":false}]},"DeletedTrackingRule":{"type":"object","properties":{"object":{"type":"string","enum":["tracking_rule"]},"id":{"type":"string"},"category":{"type":["string","null"]},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","category","deleted"],"examples":[{"object":"tracking_rule","id":"etr_01k7c8m4q2f3e9v6t5r1n0p8yz","category":"password-reset","deleted":true}]},"Reputation":{"type":"object","properties":{"object":{"type":"string","enum":["reputation"]},"status":{"type":"string","enum":["good","warning","suspended"],"description":"`good`, `warning` (a rate is approaching the suspension threshold) or `suspended` (live sending is refused until COSS support reinstates the organization)."},"reason":{"type":["string","null"],"description":"The trigger behind a `warning` or `suspended` status.","example":"complaint_rate"},"status_changed_at":{"type":["string","null"],"format":"date-time"},"evaluated_at":{"type":["string","null"],"format":"date-time","description":"When the checks below were computed; `null` before the first evaluation."},"window":{"type":["object","null"],"properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"required":["start","end"],"description":"The period the checks cover (live environments only)."},"checks":{"type":"array","items":{"$ref":"#/components/schemas/ReputationCheck"}}},"required":["object","status","reason","status_changed_at","evaluated_at","window","checks"]},"ReputationCheck":{"type":"object","properties":{"trigger":{"type":"string","description":"What was measured, e.g. `bounce_rate` or `complaint_rate`.","example":"bounce_rate"},"severity":{"type":"string","enum":["ok","warning","suspend"],"description":"`ok`, `warning` (at or above the warning threshold) or `suspend` (at or above the suspension threshold)."},"message":{"type":"string"},"rate":{"type":["number","null"],"description":"`count / volume`; `null` with no volume."},"count":{"type":"integer","description":"Matching recipients, e.g. permanent bounces."},"volume":{"type":"integer","description":"Recipients sent to (live environments) in the window."},"warning_threshold":{"type":["number","null"]},"suspend_threshold":{"type":["number","null"]},"minimum_volume":{"type":["integer","null"],"description":"Below this volume the rate is reported but never acted on."}},"required":["trigger","severity","message","rate","count","volume","warning_threshold","suspend_threshold","minimum_volume"]},"LogList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Log"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"log","id":"log_01k7c8m4q2f3e9v6t5r1n0p8yz","occurred_at":"2026-01-15T09:30:00.000Z","source":"api","level":"info","type":"api.request","message":"POST /v1/emails 202","request_id":"req_01k7c8m4q2f3e9v6t5r1n0p8yz","api_key_id":"key_01k7c8m4q2f3e9v6t5r1n0p8yz","method":"POST","path":"/v1/emails","route":"/v1/emails","status_code":202,"duration_ms":48,"client_ip":"203.0.113.7","user_agent":"coss-node/0.1.0","error_code":null,"resource_type":"email","resource_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","recipient":null,"attributes":{"request":{"body":{"from":"hello@example.com","to":["user@example.com"],"subject":"Hi"}},"response":{"body":{"object":"email","id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz"}}}}],"has_more":false}]},"Log":{"type":"object","properties":{"object":{"type":"string","enum":["log"]},"id":{"type":"string","examples":["log_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"occurred_at":{"type":"string","format":"date-time"},"source":{"$ref":"#/components/schemas/LogSource"},"level":{"$ref":"#/components/schemas/LogLevel"},"type":{"type":"string","description":"`api.request`, `webhook.attempt`, or an email event type such as `email.delivered`."},"message":{"type":"string","description":"A one-line summary."},"request_id":{"type":["string","null"],"description":"The `X-Request-Id` of the API request this line belongs to."},"api_key_id":{"type":["string","null"]},"method":{"type":["string","null"]},"path":{"type":["string","null"]},"route":{"type":["string","null"],"description":"The matched route, e.g. `/v1/emails/:id`."},"status_code":{"type":["integer","null"],"description":"The API response status, or the webhook endpoint's response status."},"duration_ms":{"type":["integer","null"]},"client_ip":{"type":["string","null"]},"user_agent":{"type":["string","null"]},"error_code":{"type":["string","null"]},"resource_type":{"type":["string","null"],"description":"What the line is about: `email`, `domain`, `webhook_endpoint`…"},"resource_id":{"type":["string","null"]},"recipient":{"type":["string","null"]},"attributes":{"type":"object","additionalProperties":{},"description":"Details: redacted request and response bodies for API requests (secrets, attachment contents and long strings are never stored), event data for emails and webhooks."}},"required":["object","id","occurred_at","source","level","type","message","request_id","api_key_id","method","path","route","status_code","duration_ms","client_ip","user_agent","error_code","resource_type","resource_id","recipient","attributes"],"examples":[{"object":"log","id":"log_01k7c8m4q2f3e9v6t5r1n0p8yz","occurred_at":"2026-01-15T09:30:00.000Z","source":"api","level":"info","type":"api.request","message":"POST /v1/emails 202","request_id":"req_01k7c8m4q2f3e9v6t5r1n0p8yz","api_key_id":"key_01k7c8m4q2f3e9v6t5r1n0p8yz","method":"POST","path":"/v1/emails","route":"/v1/emails","status_code":202,"duration_ms":48,"client_ip":"203.0.113.7","user_agent":"coss-node/0.1.0","error_code":null,"resource_type":"email","resource_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","recipient":null,"attributes":{"request":{"body":{"from":"hello@example.com","to":["user@example.com"],"subject":"Hi"}},"response":{"body":{"object":"email","id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz"}}}}]},"LogSource":{"type":"string","enum":["api","email","webhook"],"description":"`api`: a request to the API. `email`: an email event. `webhook`: a delivery attempt."},"LogLevel":{"type":"string","enum":["info","warning","error"],"description":"`error`: 5xx responses, bounces, complaints, failures. `warning`: 4xx responses, delays, suppressions, failed webhook attempts that will be retried. `info`: everything else."},"AuditEventList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"audit_event","id":"oaudit_01k7c8m4q2f3e9v6t5r1n0p8yz","created_at":"2026-01-15T09:30:00.000Z","actor_type":"api_key","actor_id":"key_01k7c8m4q2f3e9v6t5r1n0p8yz","actor_label":"key_01k7c8m4q2f3e9v6t5r1n0p8yz","action":"suppression.created","target_type":"suppression","target_id":"sup_01k7c8m4q2f3e9v6t5r1n0p8yz","target_label":"user@example.com","project_id":"proj_01k7c8m4q2f3e9v6t5r1n0p8yz","environment_id":"env_01k7c8m4q2f3e9v6t5r1n0p8yz","metadata":{"scope":"*","request_id":"req_01k7c8m4q2f3e9v6t5r1n0p8yz"},"client_ip":"203.0.113.7","user_agent":"coss-node/0.1.0"}],"has_more":false}]},"AuditEvent":{"type":"object","properties":{"object":{"type":"string","enum":["audit_event"]},"id":{"type":"string","examples":["oaudit_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"created_at":{"type":"string","format":"date-time"},"actor_type":{"$ref":"#/components/schemas/AuditActorType"},"actor_id":{"type":["string","null"],"description":"The user's or API key's id; `null` for the system."},"actor_label":{"type":"string","description":"Who made the change, copied when it was recorded so it outlives them: the user's email, the API key's id, or `COSS support`."},"action":{"type":"string","description":"`<resource>.<verb>`, e.g. `api_key.created`, `domain.deleted`, `member.role_changed`."},"target_type":{"type":["string","null"],"description":"What was changed: `domain`, `api_key`, `member`…"},"target_id":{"type":["string","null"]},"target_label":{"type":["string","null"],"description":"A readable name for the target when it was changed."},"project_id":{"type":["string","null"],"description":"`null` for organization-wide changes (domains, members…)."},"environment_id":{"type":["string","null"],"description":"`null` for organization-wide changes (domains, members…)."},"metadata":{"type":"object","additionalProperties":{},"description":"Details of the change; API changes include their `request_id`."},"client_ip":{"type":["string","null"]},"user_agent":{"type":["string","null"]}},"required":["object","id","created_at","actor_type","actor_id","actor_label","action","target_type","target_id","target_label","project_id","environment_id","metadata","client_ip","user_agent"],"examples":[{"object":"audit_event","id":"oaudit_01k7c8m4q2f3e9v6t5r1n0p8yz","created_at":"2026-01-15T09:30:00.000Z","actor_type":"api_key","actor_id":"key_01k7c8m4q2f3e9v6t5r1n0p8yz","actor_label":"key_01k7c8m4q2f3e9v6t5r1n0p8yz","action":"suppression.created","target_type":"suppression","target_id":"sup_01k7c8m4q2f3e9v6t5r1n0p8yz","target_label":"user@example.com","project_id":"proj_01k7c8m4q2f3e9v6t5r1n0p8yz","environment_id":"env_01k7c8m4q2f3e9v6t5r1n0p8yz","metadata":{"scope":"*","request_id":"req_01k7c8m4q2f3e9v6t5r1n0p8yz"},"client_ip":"203.0.113.7","user_agent":"coss-node/0.1.0"}]},"AuditActorType":{"type":"string","enum":["user","api_key","system"],"description":"`user`: a member, in the dashboard (`actor_id` is the user's id, `actor_label` their email). `api_key`: a request made with an API key (`actor_id` is the key's id). `system`: COSS itself, including COSS support."},"Billing":{"type":"object","properties":{"object":{"type":"string","enum":["billing"]},"organization_id":{"type":"string"},"plan":{"type":"string","enum":["free","pro","scale","enterprise"],"description":"The plan in effect now (`free` without a contract)."},"contract":{"type":["object","null"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["self_serve","sales","internal"]},"effective_from":{"type":"string","format":"date-time"},"effective_until":{"type":["string","null"],"format":"date-time"},"term_end":{"type":["string","null"],"format":"date-time","description":"End of a committed term."},"auto_renew":{"type":"boolean"}},"required":["id","kind","effective_from","effective_until","term_end","auto_renew"],"description":"The contract in effect; `null` on the Free plan."},"scheduled_change":{"type":["object","null"],"properties":{"effective_at":{"type":"string","format":"date-time"},"plan":{"type":"string","enum":["free","pro","scale","enterprise"]}},"required":["effective_at","plan"],"description":"A plan change that takes effect later (a downgrade, a cancellation)."},"status":{"type":"string","enum":["active","past_due","delinquent"],"description":"`past_due`: an invoice is overdue; `delinquent`: past its grace period, and live sending is held."},"holds":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","enum":["delinquent","spend_limit","admin"]},"since":{"type":"string","format":"date-time"}},"required":["reason","since"]},"description":"Billing holds on live sending (sandbox keys keep working)."},"currency":{"type":"string","enum":["usd"]},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"required":["start","end"],"description":"The current billing month (UTC)."},"usage":{"type":"array","items":{"type":"object","properties":{"meter":{"type":"string","enum":["email.recipients","sms.segments","video.participant_minutes","scheduling.bookings"],"description":"What is counted, e.g. `email.recipients`."},"quantity":{"type":"integer","minimum":0},"included":{"type":["integer","null"],"minimum":0,"description":"The plan's monthly allowance where usage stops (Free), else `null`."}},"required":["meter","quantity","included"]}},"estimate":{"type":"object","properties":{"usage":{"type":"integer","description":"Usage this month at your rates."},"discount":{"type":"integer","description":"An amount in cents (USD)."},"credit":{"type":"integer","description":"Credit applied to this estimate (your plan's fee is credit)."},"total":{"type":"integer","description":"Estimated total including usage and fees billed in arrears, after discounts and credits."}},"required":["usage","discount","credit","total"],"description":"This month so far, as it would be invoiced if it ended now."},"credit_remaining":{"type":"integer","description":"Unused credit usable this month."},"spend_limit":{"type":["integer","null"],"description":"Usage beyond the credit past which live sending is held; `null`: none."},"payment_method":{"type":["object","null"],"properties":{"type":{"type":"string"},"brand":{"type":["string","null"]},"last4":{"type":["string","null"]}},"required":["type","brand","last4"]},"features":{"type":"object","properties":{"tracking_domains":{"type":"boolean"},"audit_log":{"type":"boolean"},"log_drains":{"type":"boolean"},"sso":{"type":"boolean"},"scim":{"type":"boolean"}},"required":["tracking_domains","audit_log","log_drains","sso","scim"]},"limits":{"type":"object","properties":{"domains":{"type":["integer","null"]},"members":{"type":["integer","null"]},"webhook_endpoints_per_environment":{"type":["integer","null"]}},"required":["domains","members","webhook_endpoints_per_environment"],"description":"Resource limits (`null`: unlimited)."}},"required":["object","organization_id","plan","contract","scheduled_change","status","holds","currency","period","usage","estimate","credit_remaining","spend_limit","payment_method","features","limits"],"examples":[{"object":"billing","organization_id":"org_01k7c8m4q2f3e9v6t5r1n0p8yz","plan":"pro","contract":{"id":"bcon_01k7c8m4q2f3e9v6t5r1n0p8yz","kind":"self_serve","effective_from":"2026-10-01T00:00:00.000Z","effective_until":null,"term_end":null,"auto_renew":false},"scheduled_change":null,"status":"active","holds":[],"currency":"usd","period":{"start":"2026-10-01T00:00:00.000Z","end":"2026-11-01T00:00:00.000Z"},"usage":[{"meter":"email.recipients","quantity":120000,"included":null}],"estimate":{"usage":4800,"discount":0,"credit":2500,"total":2300},"credit_remaining":0,"spend_limit":null,"payment_method":{"type":"card","brand":"visa","last4":"4242"},"features":{"tracking_domains":true,"audit_log":true,"log_drains":false,"sso":false,"scim":false},"limits":{"domains":10,"members":10,"webhook_endpoints_per_environment":10}}]},"UsageList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Usage"}},"has_more":{"type":"boolean","enum":[false]}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"usage","meter":"email.recipients","dimension":null,"environment_id":null,"start":"2026-10-12T00:00:00.000Z","end":"2026-10-13T00:00:00.000Z","quantity":4200}],"has_more":false}]},"Usage":{"type":"object","properties":{"object":{"type":"string","enum":["usage"]},"meter":{"type":"string","enum":["email.recipients","sms.segments","video.participant_minutes","scheduling.bookings"],"description":"What is counted, e.g. `email.recipients`."},"dimension":{"type":["string","null"],"description":"e.g. `country=US` for SMS; `null` for none."},"environment_id":{"type":["string","null"],"description":"Set with `group_by=environment`."},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"quantity":{"type":"integer","minimum":0}},"required":["object","meter","dimension","environment_id","start","end","quantity"],"examples":[{"object":"usage","meter":"email.recipients","dimension":null,"environment_id":null,"start":"2026-10-12T00:00:00.000Z","end":"2026-10-13T00:00:00.000Z","quantity":4200}]},"InvoiceList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceSummary"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"invoice","id":"inv_01k7c8m4q2f3e9v6t5r1n0p8yz","number":"COSS-000042","kind":"period","status":"paid","currency":"usd","period":{"start":"2026-10-01T00:00:00.000Z","end":"2026-11-01T00:00:00.000Z"},"subtotal":7300,"discount":0,"credit":2500,"tax":0,"total":4800,"amount_paid":4800,"amount_due":0,"collection_method":"charge_automatically","due_at":"2026-11-01T00:20:00.000Z","finalized_at":"2026-11-01T00:20:00.000Z","paid_at":"2026-11-01T00:21:00.000Z","voided_at":null,"hosted_url":"https://invoice.stripe.com/i/acct_123/test_YWNjdF8x","pdf_url":"https://pay.stripe.com/invoice/acct_123/test_YWNjdF8x/pdf"}],"has_more":false}]},"InvoiceSummary":{"type":"object","properties":{"object":{"type":"string","enum":["invoice"]},"id":{"type":"string"},"number":{"type":["string","null"]},"kind":{"type":"string","enum":["period","plan_change","one_off","final"]},"status":{"type":"string","enum":["open","paid","void","uncollectible"]},"currency":{"type":"string","enum":["usd"]},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"required":["start","end"]},"subtotal":{"type":"integer","description":"An amount in cents (USD)."},"discount":{"type":"integer","description":"An amount in cents (USD)."},"credit":{"type":"integer","description":"An amount in cents (USD)."},"tax":{"type":"integer","description":"An amount in cents (USD)."},"total":{"type":"integer","description":"An amount in cents (USD)."},"amount_paid":{"type":"integer","description":"An amount in cents (USD)."},"amount_due":{"type":"integer","description":"An amount in cents (USD)."},"collection_method":{"type":"string","enum":["charge_automatically","send_invoice"]},"due_at":{"type":["string","null"],"format":"date-time"},"finalized_at":{"type":["string","null"],"format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"voided_at":{"type":["string","null"],"format":"date-time"},"hosted_url":{"type":["string","null"],"description":"A page to view (and pay) the invoice."},"pdf_url":{"type":["string","null"]}},"required":["object","id","number","kind","status","currency","period","subtotal","discount","credit","tax","total","amount_paid","amount_due","collection_method","due_at","finalized_at","paid_at","voided_at","hosted_url","pdf_url"],"examples":[{"object":"invoice","id":"inv_01k7c8m4q2f3e9v6t5r1n0p8yz","number":"COSS-000042","kind":"period","status":"paid","currency":"usd","period":{"start":"2026-10-01T00:00:00.000Z","end":"2026-11-01T00:00:00.000Z"},"subtotal":7300,"discount":0,"credit":2500,"tax":0,"total":4800,"amount_paid":4800,"amount_due":0,"collection_method":"charge_automatically","due_at":"2026-11-01T00:20:00.000Z","finalized_at":"2026-11-01T00:20:00.000Z","paid_at":"2026-11-01T00:21:00.000Z","voided_at":null,"hosted_url":"https://invoice.stripe.com/i/acct_123/test_YWNjdF8x","pdf_url":"https://pay.stripe.com/invoice/acct_123/test_YWNjdF8x/pdf"}]},"Invoice":{"type":"object","properties":{"object":{"type":"string","enum":["invoice"]},"id":{"type":"string"},"number":{"type":["string","null"]},"kind":{"type":"string","enum":["period","plan_change","one_off","final"]},"status":{"type":"string","enum":["open","paid","void","uncollectible"]},"currency":{"type":"string","enum":["usd"]},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"required":["start","end"]},"subtotal":{"type":"integer","description":"An amount in cents (USD)."},"discount":{"type":"integer","description":"An amount in cents (USD)."},"credit":{"type":"integer","description":"An amount in cents (USD)."},"tax":{"type":"integer","description":"An amount in cents (USD)."},"total":{"type":"integer","description":"An amount in cents (USD)."},"amount_paid":{"type":"integer","description":"An amount in cents (USD)."},"amount_due":{"type":"integer","description":"An amount in cents (USD)."},"collection_method":{"type":"string","enum":["charge_automatically","send_invoice"]},"due_at":{"type":["string","null"],"format":"date-time"},"finalized_at":{"type":["string","null"],"format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"voided_at":{"type":["string","null"],"format":"date-time"},"hosted_url":{"type":["string","null"],"description":"A page to view (and pay) the invoice."},"pdf_url":{"type":["string","null"]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLine"}}},"required":["object","id","number","kind","status","currency","period","subtotal","discount","credit","tax","total","amount_paid","amount_due","collection_method","due_at","finalized_at","paid_at","voided_at","hosted_url","pdf_url","lines"],"examples":[{"object":"invoice","id":"inv_01k7c8m4q2f3e9v6t5r1n0p8yz","number":"COSS-000042","kind":"period","status":"paid","currency":"usd","period":{"start":"2026-10-01T00:00:00.000Z","end":"2026-11-01T00:00:00.000Z"},"subtotal":7300,"discount":0,"credit":2500,"tax":0,"total":4800,"amount_paid":4800,"amount_due":0,"collection_method":"charge_automatically","due_at":"2026-11-01T00:20:00.000Z","finalized_at":"2026-11-01T00:20:00.000Z","paid_at":"2026-11-01T00:21:00.000Z","voided_at":null,"hosted_url":"https://invoice.stripe.com/i/acct_123/test_YWNjdF8x","pdf_url":"https://pay.stripe.com/invoice/acct_123/test_YWNjdF8x/pdf","lines":[{"object":"invoice_line","id":"invl_01k7c8m4q2f3e9v6t5r1n0p8yz","kind":"usage","description":"Email: 120,000 recipients","meter":"email.recipients","dimension":null,"quantity":120000,"included_quantity":0,"unit_price":"0.0004","amount":4800,"period":{"start":"2026-10-01T00:00:00.000Z","end":"2026-11-01T00:00:00.000Z"}}]}]},"InvoiceLine":{"type":"object","properties":{"object":{"type":"string","enum":["invoice_line"]},"id":{"type":"string"},"kind":{"type":"string","enum":["plan_fee","proration","usage","credit","discount","commitment_fee","commitment_shortfall","add_on","adjustment","write_off"]},"description":{"type":"string"},"meter":{"type":["string","null"],"enum":["email.recipients","sms.segments","video.participant_minutes","scheduling.bookings",null],"description":"What is counted, e.g. `email.recipients`."},"dimension":{"type":["string","null"]},"quantity":{"type":["integer","null"]},"included_quantity":{"type":["integer","null"],"description":"Units covered by an allowance or committed volume (not charged)."},"unit_price":{"type":["string","null"],"description":"Dollars per unit, e.g. `0.0004`; `null` when the price varies by volume."},"amount":{"type":"integer","description":"An amount in cents (USD)."},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"required":["start","end"]}},"required":["object","id","kind","description","meter","dimension","quantity","included_quantity","unit_price","amount","period"],"examples":[{"object":"invoice_line","id":"invl_01k7c8m4q2f3e9v6t5r1n0p8yz","kind":"usage","description":"Email: 120,000 recipients","meter":"email.recipients","dimension":null,"quantity":120000,"included_quantity":0,"unit_price":"0.0004","amount":4800,"period":{"start":"2026-10-01T00:00:00.000Z","end":"2026-11-01T00:00:00.000Z"}}]},"CreditList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Credit"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"credit","id":"bcg_01k7c8m4q2f3e9v6t5r1n0p8yz","kind":"units","amount":50000,"remaining":12000,"meter":"email.recipients","meters":null,"applies_to":"usage","source":"support","description":"Migration credit","effective_at":"2026-10-01T00:00:00.000Z","expires_at":"2027-01-01T00:00:00.000Z","voided_at":null,"created_at":"2026-10-01T09:30:00.000Z"}],"has_more":false}]},"Credit":{"type":"object","properties":{"object":{"type":"string","enum":["credit"]},"id":{"type":"string"},"kind":{"type":"string","enum":["amount","units"],"description":"`amount`: dollars (`amount` and `remaining` in cents); `units`: free units of `meter`."},"amount":{"type":"integer"},"remaining":{"type":"integer"},"meter":{"type":["string","null"],"enum":["email.recipients","sms.segments","video.participant_minutes","scheduling.bookings",null],"description":"What a `units` credit covers."},"meters":{"type":["array","null"],"items":{"type":"string","enum":["email.recipients","sms.segments","video.participant_minutes","scheduling.bookings"],"description":"What is counted, e.g. `email.recipients`."},"description":"What an `amount` credit pays for (`null`: any usage)."},"applies_to":{"type":"string","enum":["usage","any"],"description":"`any`: also fees and other charges."},"source":{"type":"string","enum":["fee","commitment","support","promotion","refund","sla"]},"description":{"type":"string"},"effective_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"voided_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","kind","amount","remaining","meter","meters","applies_to","source","description","effective_at","expires_at","voided_at","created_at"],"examples":[{"object":"credit","id":"bcg_01k7c8m4q2f3e9v6t5r1n0p8yz","kind":"units","amount":50000,"remaining":12000,"meter":"email.recipients","meters":null,"applies_to":"usage","source":"support","description":"Migration credit","effective_at":"2026-10-01T00:00:00.000Z","expires_at":"2027-01-01T00:00:00.000Z","voided_at":null,"created_at":"2026-10-01T09:30:00.000Z"}]},"LogDrainWithSecret":{"type":"object","properties":{"object":{"type":"string","enum":["log_drain"]},"id":{"type":"string","examples":["drain_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"url":{"type":"string","examples":["https://logs.example.com/coss"]},"description":{"type":["string","null"]},"sources":{"type":"array","items":{"$ref":"#/components/schemas/LogDrainSource"},"description":"What the drain forwards: `api` (requests made with the environment's API keys), `email` (email events), `webhook` (webhook delivery attempts) and `audit` (changes to the environment, from the organization's audit log). An empty array means every source, including ones added later."},"enabled":{"type":"boolean","description":"A disabled drain receives nothing, and lines logged while it is disabled are not kept for it."},"disabled_reason":{"type":["string","null"],"enum":["manual","failing",null],"description":"`manual`: someone disabled it. `failing`: a batch failed every attempt, so COSS disabled it. `null` while enabled."},"disabled_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"The drain's `whsec_…` signing secret, used to verify the batches COSS sends. Returned only when the drain is created — store it now; it cannot be read back through the API.","examples":["whsec_6Jk…"]}},"required":["object","id","url","description","sources","enabled","disabled_reason","disabled_at","created_at","updated_at","secret"],"examples":[{"object":"log_drain","id":"drain_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://logs.example.com/coss","description":"Production logs","sources":["api","email"],"enabled":true,"disabled_reason":null,"disabled_at":null,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z","secret":"whsec_6Jk…"}]},"LogDrainSource":{"type":"string","enum":["api","email","webhook","audit"],"description":"What the drain forwards: `api` (requests made with the environment's API keys), `email` (email events), `webhook` (webhook delivery attempts) and `audit` (changes to the environment, from the organization's audit log). An empty array means every source, including ones added later."},"CreateLogDrainRequest":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"An `https://` URL COSS posts batches of log lines to.","examples":["https://logs.example.com/coss"]},"description":{"type":["string","null"],"maxLength":256,"description":"A note for your own reference. `null` clears it."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/LogDrainSource"},"maxItems":4,"description":"What the drain forwards: `api` (requests made with the environment's API keys), `email` (email events), `webhook` (webhook delivery attempts) and `audit` (changes to the environment, from the organization's audit log). An empty array means every source, including ones added later. Defaults to every source."}},"required":["url"],"additionalProperties":false,"examples":[{"url":"https://logs.example.com/coss","description":"Production logs","sources":["api","email"]}]},"LogDrainList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/LogDrain"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"log_drain","id":"drain_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://logs.example.com/coss","description":"Production logs","sources":["api","email"],"enabled":true,"disabled_reason":null,"disabled_at":null,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"LogDrain":{"type":"object","properties":{"object":{"type":"string","enum":["log_drain"]},"id":{"type":"string","examples":["drain_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"url":{"type":"string","examples":["https://logs.example.com/coss"]},"description":{"type":["string","null"]},"sources":{"type":"array","items":{"$ref":"#/components/schemas/LogDrainSource"},"description":"What the drain forwards: `api` (requests made with the environment's API keys), `email` (email events), `webhook` (webhook delivery attempts) and `audit` (changes to the environment, from the organization's audit log). An empty array means every source, including ones added later."},"enabled":{"type":"boolean","description":"A disabled drain receives nothing, and lines logged while it is disabled are not kept for it."},"disabled_reason":{"type":["string","null"],"enum":["manual","failing",null],"description":"`manual`: someone disabled it. `failing`: a batch failed every attempt, so COSS disabled it. `null` while enabled."},"disabled_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","url","description","sources","enabled","disabled_reason","disabled_at","created_at","updated_at"],"examples":[{"object":"log_drain","id":"drain_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://logs.example.com/coss","description":"Production logs","sources":["api","email"],"enabled":true,"disabled_reason":null,"disabled_at":null,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}]},"UpdateLogDrainRequest":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"An `https://` URL COSS posts batches of log lines to.","examples":["https://logs.example.com/coss"]},"description":{"type":["string","null"],"maxLength":256,"description":"A note for your own reference. `null` clears it."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/LogDrainSource"},"maxItems":4,"description":"What the drain forwards: `api` (requests made with the environment's API keys), `email` (email events), `webhook` (webhook delivery attempts) and `audit` (changes to the environment, from the organization's audit log). An empty array means every source, including ones added later."},"enabled":{"type":"boolean"}},"additionalProperties":false,"examples":[{"enabled":false}]},"DeletedLogDrain":{"type":"object","properties":{"object":{"type":"string","enum":["log_drain"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"log_drain","id":"drain_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"LogDrainBatchList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/LogDrainBatch"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"log_drain_batch","id":"drainbat_01k7c8n2b5d7f9h1k3m5p7r9tv","drain_id":"drain_01k7c8m4q2f3e9v6t5r1n0p8yz","status":"succeeded","line_count":42,"byte_size":31870,"attempt_count":1,"next_attempt_at":null,"last_status_code":200,"last_error":null,"attempts":[{"object":"log_drain_attempt","id":"drainatt_01k7c8n2c9e1g3j5l7n9q1s3uw","attempted_at":"2026-01-15T09:30:01.000Z","status_code":200,"duration_ms":182,"error":null,"response_excerpt":"ok"}],"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:01.000Z"}],"has_more":false}]},"LogDrainBatch":{"type":"object","properties":{"object":{"type":"string","enum":["log_drain_batch"]},"id":{"type":"string","description":"The batch's id: the `webhook-id` header, the same on every attempt.","examples":["drainbat_01k7c8n2b5d7f9h1k3m5p7r9tv"]},"drain_id":{"type":"string"},"status":{"$ref":"#/components/schemas/LogDrainBatchStatus"},"line_count":{"type":"integer","description":"Lines in the batch (one per NDJSON line)."},"byte_size":{"type":"integer","description":"Size of the request body in bytes."},"attempt_count":{"type":"integer"},"next_attempt_at":{"type":["string","null"],"format":"date-time","description":"When the next attempt is due; `null` once the batch is finished."},"last_status_code":{"type":["integer","null"]},"last_error":{"type":["string","null"]},"attempts":{"type":"array","items":{"$ref":"#/components/schemas/LogDrainAttempt"},"description":"Every HTTP attempt of this batch, oldest first."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","drain_id","status","line_count","byte_size","attempt_count","next_attempt_at","last_status_code","last_error","attempts","created_at","updated_at"],"examples":[{"object":"log_drain_batch","id":"drainbat_01k7c8n2b5d7f9h1k3m5p7r9tv","drain_id":"drain_01k7c8m4q2f3e9v6t5r1n0p8yz","status":"succeeded","line_count":42,"byte_size":31870,"attempt_count":1,"next_attempt_at":null,"last_status_code":200,"last_error":null,"attempts":[{"object":"log_drain_attempt","id":"drainatt_01k7c8n2c9e1g3j5l7n9q1s3uw","attempted_at":"2026-01-15T09:30:01.000Z","status_code":200,"duration_ms":182,"error":null,"response_excerpt":"ok"}],"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:01.000Z"}]},"LogDrainBatchStatus":{"type":"string","enum":["pending","succeeded","failed"],"description":"`pending`: waiting for its next attempt. `succeeded`: the drain answered with a 2xx status. `failed`: every attempt failed, or the drain was disabled."},"LogDrainAttempt":{"type":"object","properties":{"object":{"type":"string","enum":["log_drain_attempt"]},"id":{"type":"string"},"attempted_at":{"type":"string","format":"date-time"},"status_code":{"type":["integer","null"],"description":"The drain's HTTP status; `null` when no response arrived."},"duration_ms":{"type":"integer"},"error":{"type":["string","null"],"description":"Why the attempt failed (e.g. `HTTP 500`, a timeout); `null` on success."},"response_excerpt":{"type":["string","null"],"description":"At most 1 KB of the response body, as text."}},"required":["object","id","attempted_at","status_code","duration_ms","error","response_excerpt"],"examples":[{"object":"log_drain_attempt","id":"drainatt_01k7c8n2c9e1g3j5l7n9q1s3uw","attempted_at":"2026-01-15T09:30:01.000Z","status_code":200,"duration_ms":182,"error":null,"response_excerpt":"ok"}]}},"parameters":{"CossVersion":{"in":"header","name":"Coss-Version","required":false,"description":"The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.","schema":{"type":"string","enum":["2026-10-10"],"examples":["2026-10-10"]}}}},"paths":{"/v1/emails":{"post":{"operationId":"sendEmail","tags":["Emails"],"summary":"Send an email","description":"Queues an email from the API key's environment and returns it with `status: \"queued\"`; it is handed to the delivery provider moments later. Follow it with `GET /v1/emails/{id}` or the `email.sent` / `email.failed` webhooks. Live (`coss_live_…`) keys must send from a verified domain of the organization. Sandbox (`coss_test_…`) keys accept any `from` and never deliver anything; the response has `sandbox: true`. Recipients on the environment's suppression list (for every email, or for the email's `category`) are skipped and get the status `suppressed`. With a future `scheduled_at` the email is stored with the status `scheduled` and sent at that time; the domain and the suppression list are checked again then. Attachments are base64-encoded; only metadata is kept after sending. Recipients count against the organization's send quota (per second and per day; sandbox environments have their own daily quota). With open or click tracking on (the environment's settings, or `tracking`), the HTML body is delivered with a tracking pixel and/or links rewritten to COSS redirects; the stored `html` stays as sent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated request with the same key and body returns the original email (with its current status) instead of sending again, for 24 hours. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated request with the same key and body returns the original email (with its current status) instead of sending again, for 24 hours. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEmailRequest"}}}},"responses":{"202":{"description":"The email, accepted for delivery (`queued` or `scheduled`). A replay returns the original email with its current status.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Email"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`) or the `Idempotency-Key` header is invalid (`invalid_idempotency_key`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Live sending is paused for an overdue invoice or the spend limit (`billing_hold`), or the send would go past the plan's monthly allowance (`usage_limit_exceeded`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`insufficient_permissions`), its organization is suspended (`organization_suspended`), live sending is suspended (`account_suspended`), or sending is paused for the organization because of its sending reputation (`sending_paused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Requests with this `Idempotency-Key` are racing for an expired key (`request_in_progress`). Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 40 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`), the `from` domain is not a verified domain of the organization (`domain_not_verified`, live keys only), or the `Idempotency-Key` was already used with a different body (`idempotency_key_reused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or the email's recipients exceed the send quota (`quota_exceeded`). Retry after `Retry-After` seconds; without `Retry-After` the email has more recipients than the quota allows at once.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/batch":{"post":{"operationId":"sendEmailBatch","tags":["Emails"],"summary":"Send a batch of emails","description":"Queues up to 100 emails in one request. Each email is handled exactly as by `POST /v1/emails` (sender checks, suppressions, scheduling, attachments, tracking), but the batch is all or nothing: if any email is invalid, or any `from` is not a verified domain (live keys), nothing is stored and the error names the email (e.g. `emails.3.to`). One `Idempotency-Key` covers the whole batch. The emails' recipients are charged against the send quota together, so a batch with more recipients than the quota allows at once is refused (`quota_exceeded` without `Retry-After`): split it. The request body shares the 40 MB limit of a single send.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated request with the same key and body returns the original email (with its current status) instead of sending again, for 24 hours. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated request with the same key and body returns the original email (with its current status) instead of sending again, for 24 hours. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEmailBatchRequest"}}}},"responses":{"202":{"description":"The batch, accepted for delivery, with its emails in request order. A replay returns the original batch with the emails' current statuses.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailBatch"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`) or the `Idempotency-Key` header is invalid (`invalid_idempotency_key`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Live sending is paused for an overdue invoice or the spend limit (`billing_hold`), or the send would go past the plan's monthly allowance (`usage_limit_exceeded`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`insufficient_permissions`), its organization is suspended (`organization_suspended`), live sending is suspended (`account_suspended`), or sending is paused for the organization because of its sending reputation (`sending_paused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Requests with this `Idempotency-Key` are racing for an expired key (`request_in_progress`). Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 40 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`), a `from` domain is not a verified domain of the organization (`domain_not_verified`, live keys only; `param` names the email), or the `Idempotency-Key` was already used with a different body (`idempotency_key_reused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or the batch's recipients exceed the send quota (`quota_exceeded`). Retry after `Retry-After` seconds; without `Retry-After` the batch has more recipients than the quota allows at once.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/{id}":{"get":{"operationId":"getEmail","tags":["Emails"],"summary":"Retrieve an email","description":"Only emails sent from the API key's own environment can be retrieved.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The email's id.","examples":["email_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The email's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The email.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Email"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No email with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/{id}/cancel":{"post":{"operationId":"cancelEmail","tags":["Emails"],"summary":"Cancel a scheduled email","description":"Cancels an email sent with a future `scheduled_at` before it is sent. Canceling an already canceled email returns it unchanged. To send it at another time, reschedule it instead.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The email's id.","examples":["email_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The email's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The canceled email.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Email"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No email with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The email is not scheduled (it is being sent, was sent or failed): `email_not_cancelable`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/{id}/reschedule":{"post":{"operationId":"rescheduleEmail","tags":["Emails"],"summary":"Reschedule a scheduled email","description":"Moves an email sent with a future `scheduled_at` to a new time, at most 30 days from now, and records an `email.rescheduled` event. A time that is not in the future sends it within seconds. Rescheduling to the time it already has returns it unchanged. The domain and the suppression list are still checked when it is sent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The email's id.","examples":["email_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The email's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RescheduleEmailRequest"}}}},"responses":{"200":{"description":"The rescheduled email.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Email"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No email with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`), or the email is not scheduled (it is being sent, was sent, failed or was canceled): `email_not_reschedulable`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/{id}/events":{"get":{"operationId":"listEmailEvents","tags":["Emails"],"summary":"List an email's delivery events","description":"Every delivery event of the email, oldest first: `email.scheduled`, `email.rescheduled`, `email.canceled`, `email.sent` and `email.failed` for the whole email, and `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained` and `email.suppressed` (skipped because of the suppression list) per recipient, plus `email.opened` and `email.clicked` when tracking is on (attributed to a recipient only when the email had a single one).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The email's id.","examples":["email_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The email's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The email's events.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailEventList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No email with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/{id}/links":{"get":{"operationId":"listEmailLinks","tags":["Emails"],"summary":"List an email's tracked links","description":"The links COSS rewrote for click tracking, in the order they appear in the HTML, with their click counts. Empty unless the email was sent with click tracking.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The email's id.","examples":["email_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The email's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The email's tracked links.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailLinkList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No email with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains":{"post":{"operationId":"createDomain","tags":["Domains"],"summary":"Add a sending domain","description":"Claims the domain for the organization and returns the DNS records to publish. Domains belong to the organization, not to one environment, so every API key of the organization sees the same domains. The records are checked repeatedly in the background and verification gives up after 72 hours; until the domain is `verified`, live keys cannot send from it.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDomainRequest"}}}},"responses":{"200":{"description":"The domain, with the DNS records to publish.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The organization's plan allows no more domains (`plan_limit_reached`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the name is not a usable domain (`invalid_domain`), it is already in use here or by another account (`domain_taken`), or The organization already has 5 domains awaiting verification (`too_many_pending_domains`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The delivery provider could not set the domain up; retry (`provider_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listDomains","tags":["Domains"],"summary":"List sending domains","description":"Every domain of the organization, ordered by name. Domains belong to the organization, not to one environment, so every API key of the organization sees the same domains.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The organization's domains.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/domains/{id}":{"get":{"operationId":"getDomain","tags":["Domains"],"summary":"Retrieve a sending domain","description":"The domain with the result of the last DNS check, so you can show which records are still missing or mismatched.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The domain.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No domain with this id exists in this organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteDomain","tags":["Domains"],"summary":"Remove a sending domain","description":"Removes the domain and its provider identity. Emails already sent are unaffected, but live keys can no longer send from it and the name becomes available again.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The domain was removed.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDomain"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No domain with this id exists in this organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The organization's single sign-on uses the domain (`domain_in_use_by_sso`): remove it from the SSO provider in the dashboard first.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The delivery provider could not remove the domain; retry (`provider_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{id}/verify":{"post":{"operationId":"verifyDomain","tags":["Domains"],"summary":"Check a domain's DNS records now","description":"Asks the delivery provider and DNS about the domain immediately instead of waiting for the next background check, and returns the updated domain. A `failed` domain starts verification over with fresh DKIM records, which have to be published again. Its tracking domain, if any, is checked too (and set up again if it `failed`).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The domain, as the check left it.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No domain with this id exists in this organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The organization already has 5 domains awaiting verification, so a `failed` one cannot restart (`too_many_pending_domains`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The domain was checked moments ago (`domain_recently_checked`), or too many requests with this API key (`rate_limited`). Retry after `Retry-After` seconds, or just read the domain.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The delivery provider could not be reached; retry (`provider_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{id}/tracking":{"post":{"operationId":"createTrackingDomain","tags":["Domains"],"summary":"Add a custom tracking domain","description":"Sets up a subdomain of the domain (e.g. `links.acme.com`) to serve open and click tracking. Publish the CNAME record in `tracking.record`; COSS then issues its certificate and checks it in the background, giving up after 72 hours. Open pixels and click redirects of emails sent from the domain (or its subdomains without a domain of their own) use the tracking domain while it is `active`, and the default tracking host otherwise. A domain has at most one tracking domain: remove it to use another hostname.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTrackingDomainRequest"}}}},"responses":{"200":{"description":"The domain, with its tracking domain and the CNAME to publish.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The organization's plan doesn't include custom tracking domains (`plan_feature_unavailable`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No domain with this id exists in this organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the hostname is not a subdomain of the domain it can use (`invalid_tracking_hostname`), the domain already has a tracking domain (`tracking_domain_exists`), or the hostname is already in use (`tracking_domain_taken`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The certificate provider could not set the hostname up; retry (`provider_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteTrackingDomain","tags":["Domains"],"summary":"Remove a custom tracking domain","description":"Removes the domain's tracking domain. Later emails use the default tracking host, but links and open pixels in emails already sent through the tracking domain stop working.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The domain, without a tracking domain.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No domain with this id exists in this organization, or it has no tracking domain (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The certificate provider could not remove the hostname; retry (`provider_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook_endpoints":{"post":{"operationId":"createWebhookEndpoint","tags":["Webhook endpoints"],"summary":"Create a webhook endpoint","description":"Registers a URL that receives signed event notifications. Webhook endpoints belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox endpoints, and a `coss_live_…` key only production ones. The response carries the signing secret, which is returned only here and when it is rolled: store it, and verify every delivery with it (`verifyWebhook` in the SDK).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookEndpointRequest"}}}},"responses":{"200":{"description":"The endpoint and its signing secret.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointWithSecret"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, including an unknown `api_version`), the URL is not a usable https:// URL (`invalid_url`), or the environment already has 10 endpoints (`too_many_endpoints`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listWebhookEndpoints","tags":["Webhook endpoints"],"summary":"List webhook endpoints","description":"Every endpoint of the API key's environment, oldest first. Webhook endpoints belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox endpoints, and a `coss_live_…` key only production ones.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The environment's webhook endpoints.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/webhook_endpoints/{id}":{"get":{"operationId":"getWebhookEndpoint","tags":["Webhook endpoints"],"summary":"Retrieve a webhook endpoint","description":"The endpoint without its signing secret, which is only returned when created or rolled.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook endpoint's id.","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook endpoint's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The webhook endpoint.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No webhook endpoint with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateWebhookEndpoint","tags":["Webhook endpoints"],"summary":"Update a webhook endpoint","description":"Changes the URL, description, subscribed event types, API version or `enabled` flag. Omitted fields keep their current value, and the signing secret stays the same (see Roll a signing secret), so receivers keep verifying deliveries. Disabling an endpoint stops deliveries without losing its configuration.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook endpoint's id.","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook endpoint's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookEndpointRequest"}}}},"responses":{"200":{"description":"The updated endpoint.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No webhook endpoint with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`) or the URL is not a usable https:// URL (`invalid_url`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteWebhookEndpoint","tags":["Webhook endpoints"],"summary":"Delete a webhook endpoint","description":"Removes the endpoint and its delivery log. Deliveries already queued for it are dropped. To stop deliveries temporarily, set `enabled` to `false` instead.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook endpoint's id.","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook endpoint's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The endpoint was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedWebhookEndpoint"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No webhook endpoint with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook_endpoints/{id}/roll_secret":{"post":{"operationId":"rollWebhookEndpointSecret","tags":["Webhook endpoints"],"summary":"Roll a signing secret","description":"Replaces the endpoint's signing secret with a new one, returned in the response (the only time it is). Until `previous_secret_expires_at`, every delivery is signed with both secrets (`webhook-signature` lists two signatures), so receivers verifying with either one accept it: deploy the new secret, then let the old one expire. Rolling again in that time stops the older secret at once. Not idempotent: after a lost response, roll again.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook endpoint's id.","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook endpoint's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RollWebhookEndpointSecretRequest"}}}},"responses":{"200":{"description":"The endpoint and its new signing secret.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointWithSecret"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No webhook endpoint with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook_endpoints/{id}/deliveries":{"get":{"operationId":"listWebhookDeliveries","tags":["Webhook endpoints"],"summary":"List an endpoint's deliveries","description":"The endpoint's delivery log, newest first: one delivery per event sent to it, with every HTTP attempt and the payload as sent. Pass the last `id` as `after` to get the next page while `has_more` is true. Deleting the endpoint deletes its log.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook endpoint's id.","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook endpoint's id.","name":"id","in":"path"},{"schema":{"type":"string","enum":["pending","succeeded","failed"],"description":"Only deliveries with this status."},"required":false,"description":"Only deliveries with this status.","name":"status","in":"query"},{"schema":{"type":"string","description":"Only the delivery of this event."},"required":false,"description":"Only the delivery of this event.","name":"event_id","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last delivery of the previous page."},"required":false,"description":"Cursor: the `id` of the last delivery of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of deliveries.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No webhook endpoint with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook_endpoints/{id}/deliveries/{delivery_id}":{"get":{"operationId":"getWebhookDelivery","tags":["Webhook endpoints"],"summary":"Retrieve a delivery","description":"One delivery of the endpoint, with every HTTP attempt and the payload as sent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook endpoint's id.","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook endpoint's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"The delivery's id.","examples":["whdel_01k7c8n2b5d7f9h1k3m5p7r9tv"]},"required":true,"description":"The delivery's id.","name":"delivery_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The delivery.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No webhook endpoint with this id exists in the API key's environment, or the endpoint has no delivery with this id (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook_endpoints/{id}/deliveries/{delivery_id}/retry":{"post":{"operationId":"retryWebhookDelivery","tags":["Webhook endpoints"],"summary":"Retry a delivery","description":"Queues a finished delivery (`succeeded` or `failed`) for one more attempt, made within seconds, signed with the endpoint's current secret and sent to its current URL. A delivery that is still `pending` is returned unchanged: it is already scheduled for `next_attempt_at` (automatic retries stop after 8 attempts).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook endpoint's id.","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook endpoint's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"The delivery's id.","examples":["whdel_01k7c8n2b5d7f9h1k3m5p7r9tv"]},"required":true,"description":"The delivery's id.","name":"delivery_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The delivery, now `pending`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No webhook endpoint with this id exists in the API key's environment, or the endpoint has no delivery with this id (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/suppressions":{"post":{"operationId":"createSuppression","tags":["Suppressions"],"summary":"Add an address to the suppression list","description":"Suppresses an address in the API key's environment: later sends skip it, either for every email (`scope: \"*\"`, the default) or only for emails with the given `category` (e.g. to back an unsubscribe link). Adding an address that is already suppressed with the same scope returns the existing entry with status 200.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSuppressionRequest"}}}},"responses":{"200":{"description":"The address already had an entry with this scope.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suppression"}}}},"201":{"description":"The new entry.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suppression"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listSuppressions","tags":["Suppressions"],"summary":"List suppressed addresses","description":"The suppression list of the API key's environment, newest first. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Only entries for this address."},"required":false,"description":"Only entries for this address.","name":"address","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["*"]},{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$"}],"description":"Only entries with this scope."},"required":false,"description":"Only entries with this scope.","name":"scope","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last entry of the previous page."},"required":false,"description":"Cursor: the `id` of the last entry of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of entries.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuppressionList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/suppressions/check":{"get":{"operationId":"checkSuppression","tags":["Suppressions"],"summary":"Check whether an address is suppressed","description":"Whether a send to `address` (with `category`, if given) would skip it, and the entries that match: those with scope `*` and, with a `category`, those for that category.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The address to check.","examples":["user@example.com"]},"required":true,"description":"The address to check.","name":"address","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The category of the email you plan to send. Without it, only `*` entries count."},"required":false,"description":"The category of the email you plan to send. Without it, only `*` entries count.","name":"category","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The result.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuppressionCheck"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/suppressions/import":{"post":{"operationId":"importSuppressions","tags":["Suppressions"],"summary":"Import suppressions in bulk","description":"Adds up to 1000 entries at once, with reason `import`. Each entry is validated on its own: invalid ones are skipped and listed in `invalid`, entries already on the list are left unchanged and counted in `existing`. Importing again is safe.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportSuppressionsRequest"}}}},"responses":{"200":{"description":"What the import did.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuppressionImport"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body is not a list of 1-1000 `{ address, scope? }` objects (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/suppressions/export":{"get":{"operationId":"exportSuppressions","tags":["Suppressions"],"summary":"Export the suppression list as CSV","description":"The whole suppression list of the API key's environment (optionally filtered), oldest first, as CSV with the columns `address,scope,reason,created_at,email_id,id`. The file can be imported again as is. Values a spreadsheet would run as a formula are prefixed with `'`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"anyOf":[{"type":"string","enum":["*"]},{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$"}],"description":"Only entries with this scope."},"required":false,"description":"Only entries with this scope.","name":"scope","in":"query"},{"schema":{"type":"string","enum":["bounce","complaint","manual","import"],"description":"Only entries with this reason.","examples":["bounce"]},"required":false,"description":"Only entries with this reason.","name":"reason","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The CSV file.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/suppressions/{id}":{"get":{"operationId":"getSuppression","tags":["Suppressions"],"summary":"Retrieve a suppression","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The suppression's id.","examples":["sup_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The suppression's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The entry.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suppression"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No suppression with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSuppression","tags":["Suppressions"],"summary":"Remove a suppression","description":"Removes the entry, so later sends reach the address again (unless another entry still matches). Entries added for bounces and complaints can be removed too.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The suppression's id.","examples":["sup_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The suppression's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The entry was removed.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSuppression"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No suppression with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tracking_settings":{"get":{"operationId":"getTrackingSettings","tags":["Tracking"],"summary":"Retrieve tracking settings","description":"The environment's open and click tracking default and its category rules. For each of `opens` and `clicks`, a send's own `tracking` wins, then the rule for its `category`, then the default, then off. Settings belong to the API key's own environment: a `coss_test_…` key only ever changes sandbox settings. Emails keep the settings that applied when they were sent.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The environment's tracking settings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackingSettings"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/tracking_settings/default":{"patch":{"operationId":"updateTrackingDefault","tags":["Tracking"],"summary":"Update the tracking default","description":"Sets the environment default, which applies to emails without a rule for their category. Fields left out keep their value; if there is no default yet, it is created with them off. Settings belong to the API key's own environment: a `coss_test_…` key only ever changes sandbox settings. Emails keep the settings that applied when they were sent.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTrackingRuleRequest"}}}},"responses":{"200":{"description":"The environment default.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackingRule"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"delete":{"operationId":"deleteTrackingDefault","tags":["Tracking"],"summary":"Remove the tracking default","description":"Removes the environment default: emails without a rule for their category are then not tracked unless the send asks. Settings belong to the API key's own environment: a `coss_test_…` key only ever changes sandbox settings. Emails keep the settings that applied when they were sent.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The default was removed.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedTrackingRule"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The environment has no default (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/tracking_settings/categories/{category}":{"patch":{"operationId":"updateTrackingCategory","tags":["Tracking"],"summary":"Update a category's tracking rule","description":"Sets the rule for emails sent with this `category`, which wins over the environment default, e.g. to track `marketing` but never `password-reset`. Fields left out keep their value; a new rule is created with them off. Settings belong to the API key's own environment: a `coss_test_…` key only ever changes sandbox settings. Emails keep the settings that applied when they were sent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The category, as sent in `category`.","examples":["password-reset"]},"required":true,"description":"The category, as sent in `category`.","name":"category","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTrackingRuleRequest"}}}},"responses":{"200":{"description":"The category's rule.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackingRule"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The category or the body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteTrackingCategory","tags":["Tracking"],"summary":"Remove a category's tracking rule","description":"Removes the rule: emails of this category follow the environment default again. Settings belong to the API key's own environment: a `coss_test_…` key only ever changes sandbox settings. Emails keep the settings that applied when they were sent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The category, as sent in `category`.","examples":["password-reset"]},"required":true,"description":"The category, as sent in `category`.","name":"category","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The rule was removed.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedTrackingRule"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The environment has no rule for this category (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The category failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/reputation":{"get":{"operationId":"getReputation","tags":["Reputation"],"summary":"Retrieve the organization's sending reputation","description":"The organization's standing with the COSS reputation guard and the latest rates it measured over live environments. When a rate reaches its suspension threshold, live sending is suspended automatically (`account_suspended`) until COSS support reinstates the organization; sandbox keys keep working. Subscribe to the `account.*` webhook events to be notified of changes.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The organization's reputation.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reputation"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/logs":{"get":{"operationId":"listLogs","tags":["Logs"],"summary":"List log lines","description":"The API key's environment log, newest first: every API request made with one of its keys (`source: api`), every email event (`email`) and every webhook delivery attempt (`webhook`). Filter by time range (an hour by default, at most 31 days), source, level, type, status, method, route, key, request, resource or free text. Pass the last `id` as `after` to get the next page while `has_more` is true. Reading logs is not itself logged.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time","description":"Start of the range (inclusive). Defaults to an hour before `to`."},"required":false,"description":"Start of the range (inclusive). Defaults to an hour before `to`.","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of the range (exclusive). Defaults to now. At most 31 days."},"required":false,"description":"End of the range (exclusive). Defaults to now. At most 31 days.","name":"to","in":"query"},{"schema":{"type":"string","description":"Only these sources, comma-separated: `api,email,webhook`."},"required":false,"description":"Only these sources, comma-separated: `api,email,webhook`.","name":"source","in":"query"},{"schema":{"type":"string","description":"Only these levels, comma-separated: `warning,error`."},"required":false,"description":"Only these levels, comma-separated: `warning,error`.","name":"level","in":"query"},{"schema":{"type":"string","description":"Only these types, e.g. `email.bounced,email.complained`."},"required":false,"description":"Only these types, e.g. `email.bounced,email.complained`.","name":"type","in":"query"},{"schema":{"type":"string","description":"Only these status codes or classes, e.g. `4xx,503`."},"required":false,"description":"Only these status codes or classes, e.g. `4xx,503`.","name":"status","in":"query"},{"schema":{"type":"string","description":"Only these HTTP methods, e.g. `POST`."},"required":false,"description":"Only these HTTP methods, e.g. `POST`.","name":"method","in":"query"},{"schema":{"type":"string","description":"Only these routes, e.g. `/v1/emails/:id`."},"required":false,"description":"Only these routes, e.g. `/v1/emails/:id`.","name":"route","in":"query"},{"schema":{"type":"string","description":"Only requests made with these API keys."},"required":false,"description":"Only requests made with these API keys.","name":"api_key_id","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Only this request's lines."},"required":false,"description":"Only this request's lines.","name":"request_id","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Only lines about this resource, e.g. an `email_…` id."},"required":false,"description":"Only lines about this resource, e.g. an `email_…` id.","name":"resource_id","in":"query"},{"schema":{"type":"string","maxLength":256,"description":"Free text, matched against the message, path, ids and recipient."},"required":false,"description":"Free text, matched against the message, path, ids and recipient.","name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last line of the previous page."},"required":false,"description":"Cursor: the `id` of the last line of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of log lines.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`), or the range is empty or longer than 31 days (`invalid_range`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/logs/{id}":{"get":{"operationId":"getLog","tags":["Logs"],"summary":"Retrieve a log line","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The log line's id.","examples":["log_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The log line's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The log line.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Log"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No log line with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audit_events":{"get":{"operationId":"listAuditEvents","tags":["Audit log"],"summary":"List audit events","description":"The organization's audit log, newest first: changes made by members in the dashboard, by API keys (from any environment) and by COSS support. The audit log is organization-wide, so every key of the organization reads the same events. Filter by action (an entry ending in `.` matches a whole resource, e.g. `domain.`), actor, target, environment or time. Pass the last `id` as `after` to get the next page while `has_more` is true. Reading the audit log is not itself logged.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Only these actions, comma-separated. An entry ending in `.` matches every action of that resource: `domain.,api_key.created`."},"required":false,"description":"Only these actions, comma-separated. An entry ending in `.` matches every action of that resource: `domain.,api_key.created`.","name":"action","in":"query"},{"schema":{"type":"string","description":"Only these actor types, e.g. `user,api_key`."},"required":false,"description":"Only these actor types, e.g. `user,api_key`.","name":"actor_type","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Only changes made by this user or API key."},"required":false,"description":"Only changes made by this user or API key.","name":"actor_id","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Only changes to this resource, e.g. a `dom_…` id."},"required":false,"description":"Only changes to this resource, e.g. a `dom_…` id.","name":"target_id","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Only changes in this environment."},"required":false,"description":"Only changes in this environment.","name":"environment_id","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only events at or after this time."},"required":false,"description":"Only events at or after this time.","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only events before this time."},"required":false,"description":"Only events before this time.","name":"to","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last event of the previous page."},"required":false,"description":"Cursor: the `id` of the last event of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of audit events.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEventList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The organization's plan doesn't include the audit log (`plan_feature_unavailable`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audit_events/{id}":{"get":{"operationId":"getAuditEvent","tags":["Audit log"],"summary":"Retrieve an audit event","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The audit event's id.","examples":["oaudit_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The audit event's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The audit event.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEvent"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The organization's plan doesn't include the audit log (`plan_feature_unavailable`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No audit event with this id exists in the organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing":{"get":{"operationId":"getBilling","tags":["Billing"],"summary":"Retrieve the organization's billing","description":"The organization's plan (and contract), the current billing month's usage and what it would add to the next invoice so far, its standing (`past_due`, billing holds), payment method, and what the plan includes. Organization-wide: every environment's key sees the same. Plan changes are made in the dashboard; subscribe to the `billing.*` webhook events to follow them.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The organization's billing.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Billing"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/billing/usage":{"get":{"operationId":"listBillingUsage","tags":["Billing"],"summary":"List usage","description":"Billable usage over a range (the current billing month by default), per meter, dimension and bucket (`hour`, `day` or `month`, UTC), oldest first; with `group_by=environment`, per environment too. Only live environments are billed, so only they appear. Usage counts when it becomes billable (an email when the provider accepts it) and is kept for 400 days.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time","description":"Start (inclusive). Defaults to the start of the current billing month."},"required":false,"description":"Start (inclusive). Defaults to the start of the current billing month.","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End (exclusive). Defaults to now. At most 400 days after `from` (7 by hour)."},"required":false,"description":"End (exclusive). Defaults to now. At most 400 days after `from` (7 by hour).","name":"to","in":"query"},{"schema":{"type":"string","enum":["hour","day","month"],"description":"Bucket size (UTC). Defaults to `day`."},"required":false,"description":"Bucket size (UTC). Defaults to `day`.","name":"granularity","in":"query"},{"schema":{"type":"string","enum":["environment"],"description":"Split each bucket per environment."},"required":false,"description":"Split each bucket per environment.","name":"group_by","in":"query"},{"schema":{"type":"string","enum":["email.recipients","sms.segments","video.participant_minutes","scheduling.bookings"],"description":"Only this meter."},"required":false,"description":"Only this meter.","name":"meter","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"Usage, oldest first.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`), or the range is empty or too long (`invalid_range`: at most 400 days, 7 by hour).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/invoices":{"get":{"operationId":"listInvoices","tags":["Billing"],"summary":"List invoices","description":"The organization's invoices, newest first, without their lines. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["open","paid","void","uncollectible"],"description":"Only invoices in this status."},"required":false,"description":"Only invoices in this status.","name":"status","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Continue after this id (the last of the previous page)."},"required":false,"description":"Continue after this id (the last of the previous page).","name":"after","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many (default 20)."},"required":false,"description":"At most this many (default 20).","name":"limit","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of invoices.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/invoices/{id}":{"get":{"operationId":"getInvoice","tags":["Billing"],"summary":"Retrieve an invoice","description":"One invoice with its lines.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The invoice's id.","examples":["inv_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The invoice's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The invoice.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No invoice with this id exists in the organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/credits":{"get":{"operationId":"listCredits","tags":["Billing"],"summary":"List credits","description":"The organization's credits, newest first: each month's plan credit, prepaid commitments and credits from COSS support (in dollars, or free units of a product), with what's left. Only usable ones by default (`status=all` for every one). Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["active","all"],"description":"`active` (default): usable now or later, with something left; `all`: every credit, newest first."},"required":false,"description":"`active` (default): usable now or later, with something left; `all`: every credit, newest first.","name":"status","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Continue after this id (the last of the previous page)."},"required":false,"description":"Continue after this id (the last of the previous page).","name":"after","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many (default 20)."},"required":false,"description":"At most this many (default 20).","name":"limit","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of credits.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/log_drains":{"post":{"operationId":"createLogDrain","tags":["Log drains"],"summary":"Create a log drain","description":"Streams the environment's logs to a URL: every line `GET /v1/logs` returns (API requests, email events, webhook attempts) and the environment's audit events, posted as signed NDJSON batches of up to 500 lines or 1 MB, usually within seconds. Log drains belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox drains, and a `coss_live_…` key only production ones. The response carries the signing secret, which is returned only here: store it, and verify every batch with it (`verifyLogDrainBatch` in the SDK).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLogDrainRequest"}}}},"responses":{"200":{"description":"The drain and its signing secret.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDrainWithSecret"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The organization's plan doesn't include log drains (`plan_feature_unavailable`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the URL is not a usable https:// URL (`invalid_url`), or the environment already has 5 drains (`too_many_log_drains`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listLogDrains","tags":["Log drains"],"summary":"List log drains","description":"Every drain of the API key's environment, oldest first. Log drains belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox drains, and a `coss_live_…` key only production ones.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The environment's log drains.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDrainList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/log_drains/{id}":{"get":{"operationId":"getLogDrain","tags":["Log drains"],"summary":"Retrieve a log drain","description":"The drain without its signing secret, which is only returned when created.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The log drain's id.","examples":["drain_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The log drain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The log drain.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDrain"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No log drain with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateLogDrain","tags":["Log drains"],"summary":"Update a log drain","description":"Changes the URL, description, sources or `enabled` flag. Omitted fields keep their current value, and the signing secret stays the same. Disabling a drain drops the lines still waiting for it, and nothing is kept for it while it is disabled; enabling it again (also after COSS disabled it for failing) sends lines logged from then on.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The log drain's id.","examples":["drain_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The log drain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLogDrainRequest"}}}},"responses":{"200":{"description":"The updated drain.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDrain"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Re-enabling the drain needs a plan with log drains (`plan_feature_unavailable`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No log drain with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`) or the URL is not a usable https:// URL (`invalid_url`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteLogDrain","tags":["Log drains"],"summary":"Delete a log drain","description":"Removes the drain and its batch log. Lines still waiting for it are dropped. To stop it temporarily, set `enabled` to `false` instead.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The log drain's id.","examples":["drain_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The log drain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The drain was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedLogDrain"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No log drain with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/log_drains/{id}/batches":{"get":{"operationId":"listLogDrainBatches","tags":["Log drains"],"summary":"List a drain's batches","description":"The drain's delivery log, newest first: one batch per NDJSON request, with every HTTP attempt. A failing batch is retried with backoff for about a day (10 attempts); if every attempt fails, the drain is disabled. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The log drain's id.","examples":["drain_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The log drain's id.","name":"id","in":"path"},{"schema":{"type":"string","enum":["pending","succeeded","failed"],"description":"Only batches with this status."},"required":false,"description":"Only batches with this status.","name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last batch of the previous page."},"required":false,"description":"Cursor: the `id` of the last batch of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of batches.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDrainBatchList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No log drain with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/log_drains/{id}/batches/{batch_id}":{"get":{"operationId":"getLogDrainBatch","tags":["Log drains"],"summary":"Retrieve a batch","description":"One batch of the drain, with every HTTP attempt.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The log drain's id.","examples":["drain_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The log drain's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"The batch's id.","examples":["drainbat_01k7c8n2b5d7f9h1k3m5p7r9tv"]},"required":true,"description":"The batch's id.","name":"batch_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The batch.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDrainBatch"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No log drain with this id exists in the API key's environment, or the drain has no batch with this id (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}