{"openapi":"3.1.0","info":{"title":"Smartletter API","version":"1.0.0","description":"Newsletters, contacts, signups and transactional email. Every action of the dashboard and of the Smartletter MCP server. Docs: https://smartletter.ai/docs","contact":{"name":"Smartletter","url":"https://smartletter.ai/docs"}},"servers":[{"url":"https://api.smartletter.ai"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Emails","description":"Transactional email, compatible with the Resend API and SDKs."},{"name":"Newsletters","description":"Newsletter issues (campaigns): write, review, test, send, schedule, pause, report."},{"name":"Contacts","description":"Subscribers of your newsletters: add, import with cleaning, export, unsubscribe."},{"name":"Signups","description":"Double opt-in signups from your own site, with a key that is safe in public code."},{"name":"Segments","description":"Your newsletters (segments) and their topics."},{"name":"Archive","description":"Public archive of a newsletter's sent issues, and its custom subdomain (tracked links, preferences, archive)."},{"name":"Suppressions","description":"Addresses that never receive anything from your workspace."},{"name":"Images","description":"Images for your newsletters, hosted on the Smartletter CDN."},{"name":"Stats","description":"Audience growth and sending volume."},{"name":"Domains","description":"Custom sending domains (DKIM, SPF, MX)."},{"name":"API keys","description":"Create, list, rename and revoke API keys."},{"name":"Logs","description":"The last API requests of your workspace."},{"name":"Usage","description":"Plan limits and what you used."},{"name":"Meta","description":"This API's own description."}],"paths":{"/emails":{"post":{"operationId":"postEmails","summary":"Send an email","tags":["Emails"],"description":"Sends one transactional email, like Resend's `POST /emails`. Works with the official Resend SDKs: point them at `https://api.smartletter.ai`. The `from` domain must be verified in your workspace.","x-permissions":["full_access","sending_access"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replays the first answer for 24 h when the same key is sent again (1–256 characters).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string"},"to":{"anyOf":[{"type":"string"},{"maxItems":50,"type":"array","items":{"type":"string"}}]},"subject":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"cc":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"bcc":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"reply_to":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}},"required":["name","value"]}}},"required":["from","to","subject"]},"example":{"from":"Acme ","to":["jane@example.com"],"subject":"Welcome","html":"

Hi Jane

"}}}},"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"id":"4ef9a417-02e9-4d39-ad75-9611e0fcc33c"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/emails/{id}":{"get":{"operationId":"getEmailsById","summary":"Retrieve an email","tags":["Emails"],"x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"email","id":"4ef9a417-02e9-4d39-ad75-9611e0fcc33c","last_event":"delivered"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/newsletters":{"get":{"operationId":"getNewsletters","summary":"List newsletters","tags":["Newsletters"],"x-permissions":["full_access"],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","scheduled","sending","paused","sent","failed","held"]}},{"name":"limit","in":"query","required":false,"description":"1–100, default 20.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"after","in":"query","required":false,"description":"Id of the last item of the previous page (older items).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"before","in":"query","required":false,"description":"Id of the first item of the previous page (newer items).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"list","has_more":false,"data":[{"object":"newsletter","id":"7c3e1a52-0000-4000-8000-000000000001","segment_id":"2d9e4b11-0000-4000-8000-000000000003","topic_id":null,"subject":"This week in AI","preheader":"Three tools worth your time","status":"draft","body":{"format":"markdown","content":"# Hello\n\nThree tools this week…"},"audience_limit":null,"scheduled_for":null,"pause_reason":null,"recipient_estimate":null,"created_at":"2026-10-17T09:00:00.000Z","updated_at":"2026-10-17T09:00:00.000Z"}]}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}},"post":{"operationId":"postNewsletters","summary":"Create a draft","tags":["Newsletters"],"description":"Creates a draft from a Markdown or HTML body. The platform adds the footer (unsubscribe link, postal address) when the issue is sent.","x-permissions":["full_access"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","minLength":1,"maxLength":200,"description":"Subject line."},"preheader":{"description":"Preview text shown after the subject.","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"segment_id":{"description":"Newsletter (segment) to send from. Optional when the workspace has a single active newsletter.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"topic_id":{"description":"Topic of that newsletter; its subscribers receive the issue.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"markdown":{"description":"Body in Markdown. Give `markdown` or `html`.","type":"string","maxLength":100000},"html":{"description":"Body in HTML. The platform footer is added around it.","type":"string","maxLength":200000}},"required":["subject"]},"example":{"subject":"This week in AI","preheader":"Three tools worth your time","markdown":"# Hello\n\nThree tools this week…"}}}},"responses":{"201":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"newsletter","id":"7c3e1a52-0000-4000-8000-000000000001","segment_id":"2d9e4b11-0000-4000-8000-000000000003","topic_id":null,"subject":"This week in AI","preheader":"Three tools worth your time","status":"draft","body":{"format":"markdown","content":"# Hello\n\nThree tools this week…"},"audience_limit":null,"scheduled_for":null,"pause_reason":null,"recipient_estimate":null,"created_at":"2026-10-17T09:00:00.000Z","updated_at":"2026-10-17T09:00:00.000Z"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/newsletters/{id}":{"get":{"operationId":"getNewslettersById","summary":"Retrieve a newsletter","tags":["Newsletters"],"x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"newsletter","id":"7c3e1a52-0000-4000-8000-000000000001","segment_id":"2d9e4b11-0000-4000-8000-000000000003","topic_id":null,"subject":"This week in AI","preheader":"Three tools worth your time","status":"draft","body":{"format":"markdown","content":"# Hello\n\nThree tools this week…"},"audience_limit":null,"scheduled_for":null,"pause_reason":null,"recipient_estimate":null,"created_at":"2026-10-17T09:00:00.000Z","updated_at":"2026-10-17T09:00:00.000Z"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}},"patch":{"operationId":"patchNewslettersById","summary":"Update a draft","tags":["Newsletters"],"x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","minLength":1,"maxLength":200},"preheader":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"topic_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"markdown":{"type":"string","maxLength":100000},"html":{"type":"string","maxLength":200000}}},"example":{"subject":"This week in AI (updated)"}}}},"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"newsletter","id":"7c3e1a52-0000-4000-8000-000000000001","segment_id":"2d9e4b11-0000-4000-8000-000000000003","topic_id":null,"subject":"This week in AI","preheader":"Three tools worth your time","status":"draft","body":{"format":"markdown","content":"# Hello\n\nThree tools this week…"},"audience_limit":null,"scheduled_for":null,"pause_reason":null,"recipient_estimate":null,"created_at":"2026-10-17T09:00:00.000Z","updated_at":"2026-10-17T09:00:00.000Z"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}},"delete":{"operationId":"deleteNewslettersById","summary":"Delete a draft","tags":["Newsletters"],"description":"Only drafts can be deleted. Unschedule a scheduled issue first.","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"newsletter","id":"7c3e1a52-0000-4000-8000-000000000001","deleted":true}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"429":{"$ref":"#/components/responses/E429"}}}},"/newsletters/{id}/duplicate":{"post":{"operationId":"postNewslettersByIdDuplicate","summary":"Duplicate","tags":["Newsletters"],"description":"Copies subject, preheader, body and targeting into a new draft. Never the sending state or the stats.","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"newsletter","id":"9a0d2f3e-0000-4000-8000-000000000004","segment_id":"2d9e4b11-0000-4000-8000-000000000003","topic_id":null,"subject":"This week in AI","preheader":"Three tools worth your time","status":"draft","body":{"format":"markdown","content":"# Hello\n\nThree tools this week…"},"audience_limit":null,"scheduled_for":null,"pause_reason":null,"recipient_estimate":null,"created_at":"2026-10-17T09:00:00.000Z","updated_at":"2026-10-17T09:00:00.000Z"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/newsletters/{id}/review":{"get":{"operationId":"getNewslettersByIdReview","summary":"Pre-send review","tags":["Newsletters"],"description":"Runs the checks a send runs (subject, unsubscribe link, Gmail clipping at ~102 KB, postal address, sending domain) without sending. Blocking items make `send` and `schedule` fail with 422.","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"review","blocking":false,"items":[{"id":"subject","level":"ok"},{"id":"gmail_clip","level":"ok","values":{"kb":18}}]}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/newsletters/{id}/test":{"post":{"operationId":"postNewslettersByIdTest","summary":"Send a test email","tags":["Newsletters"],"description":"Sends the issue to the workspace owner only, subject prefixed with [Test]. 10 per hour; counts in the monthly quota.","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"test_email","to":"owner@acme.com"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/newsletters/{id}/send":{"post":{"operationId":"postNewslettersByIdSend","summary":"Send now","tags":["Newsletters"],"description":"Locks the rendered issue and starts sending. Warm-up, test batch and automatic pauses apply. `audience_limit` sends to the N most engaged contacts first. A blocking pre-send item answers 422 `presend_blocked` with the items in `details`.","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Replays the first answer for 24 h when the same key is sent again (1–256 characters).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"audience_limit":{"type":"integer","minimum":1,"maximum":10000000,"description":"Send only to the N most engaged contacts now; the rest can follow with send-more."}}},"example":{"audience_limit":500}}}},"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"newsletter","id":"7c3e1a52-0000-4000-8000-000000000001","status":"sending"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/newsletters/{id}/schedule":{"post":{"operationId":"postNewslettersByIdSchedule","summary":"Schedule","tags":["Newsletters"],"description":"Schedules a draft up to one year ahead. Same checks as a send.","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Replays the first answer for 24 h when the same key is sent again (1–256 characters).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scheduled_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 date, in the future, at most one year ahead."},"audience_limit":{"type":"integer","minimum":1,"maximum":10000000,"description":"Send only to the N most engaged contacts now; the rest can follow with send-more."}},"required":["scheduled_at"]},"example":{"scheduled_at":"2026-10-20T08:00:00Z"}}}},"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"newsletter","id":"7c3e1a52-0000-4000-8000-000000000001","status":"scheduled","scheduled_for":"2026-10-20T08:00:00.000Z"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/newsletters/{id}/unschedule":{"post":{"operationId":"postNewslettersByIdUnschedule","summary":"Unschedule","tags":["Newsletters"],"x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"newsletter","id":"7c3e1a52-0000-4000-8000-000000000001","status":"draft"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"429":{"$ref":"#/components/responses/E429"}}}},"/newsletters/{id}/pause":{"post":{"operationId":"postNewslettersByIdPause","summary":"Pause sending","tags":["Newsletters"],"x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"newsletter","id":"7c3e1a52-0000-4000-8000-000000000001","status":"paused"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"429":{"$ref":"#/components/responses/E429"}}}},"/newsletters/{id}/resume":{"post":{"operationId":"postNewslettersByIdResume","summary":"Resume sending","tags":["Newsletters"],"description":"Resumes a manual pause (or a quota / suspension pause once lifted). A pause for bounces, complaints or a failed test batch needs our team: 409.","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"newsletter","id":"7c3e1a52-0000-4000-8000-000000000001","status":"sending"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"429":{"$ref":"#/components/responses/E429"}}}},"/newsletters/{id}/send-more":{"post":{"operationId":"postNewslettersByIdSendMore","summary":"Send to the next N","tags":["Newsletters"],"description":"For an issue sent with an `audience_limit`: sends to the next `count` most engaged contacts. Nobody gets it twice.","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Replays the first answer for 24 h when the same key is sent again (1–256 characters).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","minimum":1,"maximum":10000000,"description":"How many of the next most engaged contacts to add."}},"required":["count"]},"example":{"count":1000}}}},"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"newsletter","id":"7c3e1a52-0000-4000-8000-000000000001","status":"sending"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"429":{"$ref":"#/components/responses/E429"}}}},"/newsletters/{id}/report":{"get":{"operationId":"getNewslettersByIdReport","summary":"Report","tags":["Newsletters"],"description":"Opens, clicks, bounces, complaints and unsubscribes, sending progress, and results per mailbox provider.","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"report","id":"7c3e1a52-0000-4000-8000-000000000001","status":"sent","totals":{"sent":1200,"delivered":1188,"opened":540,"clicked":96,"bounced":12,"complained":0,"unsubscribed":4},"rates":{"delivery":0.99,"open":0.4545,"click":0.0808,"bounce":0.01,"complaint":0,"unsubscribe":0.0034},"progress":{"attempted":1200,"recipient_estimate":1200,"audience_limit":null},"providers":[{"provider":"gmail","sent":700,"delivered":698,"opened":330,"clicked":60,"bounced":2,"complained":0}]}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/contacts":{"get":{"operationId":"getContacts","summary":"List contacts","tags":["Contacts"],"x-permissions":["full_access"],"parameters":[{"name":"segment_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","pending","unsubscribed","bounced","complained","dormant"]}},{"name":"search","in":"query","required":false,"description":"Substring of the email address.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"description":"1–100, default 20.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"after","in":"query","required":false,"description":"Id of the last item of the previous page (older items).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"before","in":"query","required":false,"description":"Id of the first item of the previous page (newer items).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"list","has_more":false,"data":[{"object":"contact","id":"5b1f2c90-0000-4000-8000-000000000002","email":"jane@example.com","status":"active","segment_id":"2d9e4b11-0000-4000-8000-000000000003"}]}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}},"post":{"operationId":"postContacts","summary":"Add a contact","tags":["Contacts"],"description":"Adds one contact as imported (the same cleaning as an import: invalid syntax, typos, spam traps, role and disposable addresses, suppressions). A refused address answers 422 with the reason. Returns the existing contact when the address is already there.","x-permissions":["full_access"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replays the first answer for 24 h when the same key is sent again (1–256 characters).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"segment_id":{"description":"Optional when the workspace has a single active newsletter.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","maxLength":200},"language":{"type":"string","minLength":2,"maxLength":5}},"required":["email"]},"example":{"email":"jane@example.com","name":"Jane"}}}},"responses":{"201":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"contact","id":"5b1f2c90-0000-4000-8000-000000000002","email":"jane@example.com","status":"active","existed":false}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/contacts/import":{"post":{"operationId":"postContactsImport","summary":"Import contacts","tags":["Contacts"],"description":"Up to 1000 rows per call, `consent: true` required. Rows are cleaned like a CSV import and the answer reports every rejected row with its reason. New accounts' large imports may be held for a quick review.","x-permissions":["full_access"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replays the first answer for 24 h when the same key is sent again (1–256 characters).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"segment_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"consent":{"type":"boolean","const":true,"description":"You confirm every contact opted in to receive this newsletter (no bought, rented or scraped list)."},"contacts":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"description":"Checked by the import cleaning; an invalid address is reported, not an error."},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"language":{"anyOf":[{"type":"string","minLength":2,"maxLength":5},{"type":"null"}]},"open_rate":{"description":"Open rate on your previous platform (0–1).","anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"null"}]},"click_rate":{"description":"Click rate on your previous platform (0–1).","anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"null"}]},"last_activity_at":{"description":"Last open or click on your previous platform.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["email"]}}},"required":["consent","contacts"]},"example":{"consent":true,"contacts":[{"email":"jane@example.com","name":"Jane","open_rate":0.42}]}}}},"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"import","total":3,"inserted":1,"rejected":2,"reasons":{"invalid":0,"typo":1,"spam_trap":0,"role":1,"disposable":0,"no_mx":0,"duplicate":0,"suppressed":0,"capped":0},"rejected_rows":[{"line":2,"email":"bob@gmial.com","reason":"typo","suggestion":"bob@gmail.com"},{"line":3,"email":"info@acme.com","reason":"role"}],"pending_review":false}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/contacts/export":{"get":{"operationId":"getContactsExport","summary":"Export contacts (CSV)","tags":["Contacts"],"x-permissions":["full_access"],"parameters":[{"name":"segment_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","pending","unsubscribed","bounced","complained","dormant"]}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/contacts/{id}":{"get":{"operationId":"getContactsById","summary":"Retrieve a contact","tags":["Contacts"],"x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"contact","id":"5b1f2c90-0000-4000-8000-000000000002","email":"jane@example.com","status":"active","engagement":{"emails_sent":12,"emails_opened":7,"emails_clicked":2}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}},"delete":{"operationId":"deleteContactsById","summary":"Delete a contact","tags":["Contacts"],"x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"contact","id":"5b1f2c90-0000-4000-8000-000000000002","deleted":true}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/contacts/{id}/unsubscribe":{"post":{"operationId":"postContactsByIdUnsubscribe","summary":"Unsubscribe","tags":["Contacts"],"x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"contact","id":"5b1f2c90-0000-4000-8000-000000000002","status":"unsubscribed"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/contacts/{id}/reactivate":{"post":{"operationId":"postContactsByIdReactivate","summary":"Reactivate a dormant contact","tags":["Contacts"],"description":"Only for contacts put to sleep by the inactive cleanup. An unsubscribed contact can only come back through their own link.","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"contact","id":"5b1f2c90-0000-4000-8000-000000000002","status":"active"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"429":{"$ref":"#/components/responses/E429"}}}},"/signups":{"post":{"operationId":"postSignups","summary":"Sign up a subscriber","tags":["Signups"],"description":"For your site's signup form. Use a `signups` key: it can do nothing else, so it is safe in public code. The contact stays pending until they click the confirmation email (double opt-in). The answer is the same for every address. Limited to 5 signups per IP per 10 minutes.","x-permissions":["signups","full_access"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replays the first answer for 24 h when the same key is sent again (1–256 characters).","schema":{"type":"string","minLength":1,"maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"name":{"type":"string","maxLength":120},"segment_id":{"description":"Optional when the workspace has a single active newsletter.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"language":{"type":"string","minLength":2,"maxLength":5},"source_url":{"description":"Page the form was on (attribution).","type":"string","maxLength":2000,"format":"uri"}},"required":["email"]},"example":{"email":"jane@example.com","name":"Jane","source_url":"https://acme.com/blog"}}}},"responses":{"202":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"signup","status":"pending"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/segments":{"get":{"operationId":"getSegments","summary":"List newsletters (segments)","tags":["Segments"],"x-permissions":["full_access"],"parameters":[{"name":"limit","in":"query","required":false,"description":"1–100, default 20.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"after","in":"query","required":false,"description":"Id of the last item of the previous page (older items).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"before","in":"query","required":false,"description":"Id of the first item of the previous page (newer items).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"list","has_more":false,"data":[{"object":"segment","id":"2d9e4b11-0000-4000-8000-000000000003","name":"Acme Weekly","slug":"acme-weekly"}]}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}},"post":{"operationId":"postSegments","summary":"Create a newsletter (segment)","tags":["Segments"],"x-permissions":["full_access"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"slug":{"type":"string","minLength":1,"maxLength":60,"pattern":"^[a-z0-9-]+$"},"language":{"type":"string","minLength":2,"maxLength":5},"description":{"type":"string","maxLength":500},"themes":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":60}}},"required":["name","slug"]},"example":{"name":"Acme Weekly","slug":"acme-weekly","language":"en"}}}},"responses":{"201":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"segment","id":"2d9e4b11-0000-4000-8000-000000000003","name":"Acme Weekly","slug":"acme-weekly"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/topics":{"get":{"operationId":"getTopics","summary":"List topics","tags":["Segments"],"x-permissions":["full_access"],"parameters":[{"name":"segment_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"list","has_more":false,"data":[{"object":"topic","id":"5b1f2c90-0000-4000-8000-000000000002","segment_id":"2d9e4b11-0000-4000-8000-000000000003","name":"AI tools"}]}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/segments/{id}/archive":{"get":{"operationId":"getSegmentsByIdArchive","summary":"Retrieve a newsletter's archive settings","tags":["Archive"],"description":"Settings of the public archive and its URL (on the custom subdomain once verified).","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"archive","segment_id":"2d9e4b11-0000-4000-8000-000000000003","enabled":true,"slug":"acme-weekly","url":"https://news.acme.com/","custom_domain":"news.acme.com","description":"Three AI tools every Tuesday","author":"Jane Doe","about":null,"avatar_url":null,"links":{"x":"https://x.com/acme"}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}},"patch":{"operationId":"patchSegmentsByIdArchive","summary":"Update a newsletter's archive settings","tags":["Archive"],"description":"Only sent issues are public, never hidden ones nor issues reserved to a plan. The archive is indexed by search engines (sitemap, RSS at `/rss.xml`).","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"description":"Publish the sent issues of this newsletter on its public archive.","type":"boolean"},"slug":{"description":"Archive address: `smartletter.ai//n/`. Unique across Smartletter.","type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9-]+$"},"description":{"description":"One-line description (also the meta description).","anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"author":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"about":{"description":"Text of the About page (plain text, blank lines between paragraphs).","anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"avatar_url":{"description":"https URL of an avatar or logo.","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"links":{"description":"Social links (https). Replaces the whole set.","type":"object","properties":{"website":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"x":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"linkedin":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"youtube":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"instagram":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"github":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"bluesky":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]}}}}},"example":{"enabled":true,"description":"Three AI tools every Tuesday","links":{"x":"https://x.com/acme"}}}}},"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"archive","segment_id":"2d9e4b11-0000-4000-8000-000000000003","enabled":true,"slug":"acme-weekly","url":"https://news.acme.com/","custom_domain":"news.acme.com","description":"Three AI tools every Tuesday","author":"Jane Doe","about":null,"avatar_url":null,"links":{"x":"https://x.com/acme"}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/newsletters/{id}/archive":{"patch":{"operationId":"patchNewslettersByIdArchive","summary":"Pin or hide an issue in the archive","tags":["Archive"],"description":"Sent issues only. At most 3 pinned issues per newsletter (409 beyond).","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pinned":{"description":"Pin at the top of the archive (3 pinned issues max per newsletter).","type":"boolean"},"hidden":{"description":"Hide this issue from the public archive.","type":"boolean"}}},"example":{"pinned":true}}}},"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"newsletter_archive","id":"7c3e1a52-0000-4000-8000-000000000001","pinned":true,"hidden":false}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/segments/{id}/domain":{"get":{"operationId":"getSegmentsByIdDomain","summary":"Retrieve a newsletter's custom subdomain","tags":["Archive"],"description":"Status and the DNS record to add. Links of new emails use the subdomain once it is verified.","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"custom_domain","id":"5b1f2c90-0000-4000-8000-000000000002","segment_id":"2d9e4b11-0000-4000-8000-000000000003","domain":"news.acme.com","status":"pending","uses":["tracking","preferences","archive"],"records":[{"type":"CNAME","name":"news.acme.com","value":"abc123.vercel-dns-017.com"}],"last_checked_at":null,"verified_at":null,"last_error":null,"created_at":"2026-10-17T09:00:00.000Z"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}},"post":{"operationId":"postSegmentsByIdDomain","summary":"Add a custom subdomain","tags":["Archive"],"description":"One subdomain per newsletter (`news.acme.com` by default in the dashboard) for tracked links, the preference and unsubscribe pages and the public archive. Pro plan or higher. Add the returned CNAME (DNS only, not proxied); verification runs every 15 minutes.","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":4,"maxLength":253,"description":"Subdomain you own, e.g. `news.acme.com` (a CNAME to Vercel)."}},"required":["domain"]},"example":{"domain":"news.acme.com"}}}},"responses":{"201":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"custom_domain","id":"5b1f2c90-0000-4000-8000-000000000002","segment_id":"2d9e4b11-0000-4000-8000-000000000003","domain":"news.acme.com","status":"pending","uses":["tracking","preferences","archive"],"records":[{"type":"CNAME","name":"news.acme.com","value":"abc123.vercel-dns-017.com"}],"last_checked_at":null,"verified_at":null,"last_error":null,"created_at":"2026-10-17T09:00:00.000Z"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}},"delete":{"operationId":"deleteSegmentsByIdDomain","summary":"Remove the custom subdomain","tags":["Archive"],"description":"New emails go back to smartletter.ai links at once. Remove the CNAME too.","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"custom_domain","segment_id":"2d9e4b11-0000-4000-8000-000000000003","deleted":true}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/suppressions":{"get":{"operationId":"getSuppressions","summary":"List suppressions","tags":["Suppressions"],"x-permissions":["full_access"],"parameters":[{"name":"reason","in":"query","required":false,"schema":{"type":"string","enum":["bounced","complained","user_unsub","admin","gdpr"]}},{"name":"limit","in":"query","required":false,"description":"1–100, default 20.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"after","in":"query","required":false,"description":"Id of the last item of the previous page (older items).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"before","in":"query","required":false,"description":"Id of the first item of the previous page (newer items).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"list","has_more":false,"data":[{"object":"suppression","id":"5b1f2c90-0000-4000-8000-000000000002","email":"old@example.com","reason":"admin"}]}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}},"post":{"operationId":"postSuppressions","summary":"Suppress an address","tags":["Suppressions"],"x-permissions":["full_access"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"reason":{"default":"admin","type":"string","enum":["bounced","complained","user_unsub","admin","gdpr"]},"notes":{"type":"string","maxLength":500}},"required":["email"]},"example":{"email":"old@example.com","reason":"gdpr"}}}},"responses":{"201":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"suppression","id":"5b1f2c90-0000-4000-8000-000000000002","email":"old@example.com","reason":"gdpr"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/suppressions/{id}":{"delete":{"operationId":"deleteSuppressionsById","summary":"Lift a suppression","tags":["Suppressions"],"description":"Bounces and spam complaints can never be lifted (409).","x-permissions":["full_access"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"suppression","id":"5b1f2c90-0000-4000-8000-000000000002","deleted":true}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"429":{"$ref":"#/components/responses/E429"}}}},"/images":{"get":{"operationId":"getImages","summary":"List images","tags":["Images"],"x-permissions":["full_access"],"parameters":[{"name":"limit","in":"query","required":false,"description":"1–100, default 20.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"after","in":"query","required":false,"description":"Id of the last item of the previous page (older items).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"before","in":"query","required":false,"description":"Id of the first item of the previous page (newer items).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"list","has_more":false,"data":[{"object":"image","id":"5b1f2c90-0000-4000-8000-000000000002","url":"https://assets.smartletter.ai/…/x.png"}]}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}},"post":{"operationId":"postImages","summary":"Upload an image","tags":["Images"],"description":"PNG, JPEG, GIF or WebP, 4 MB max. Send the file as the raw body (`Content-Type: image/png`…) or as multipart field `file`. The type is read from the bytes.","x-permissions":["full_access"],"requestBody":{"required":true,"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/gif":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"201":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"image","id":"5b1f2c90-0000-4000-8000-000000000002","url":"https://assets.smartletter.ai/ws/5b1f2c90.png","content_type":"image/png","size_bytes":48213}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"413":{"$ref":"#/components/responses/E413"},"415":{"$ref":"#/components/responses/E415"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/stats/overview":{"get":{"operationId":"getStatsOverview","summary":"Overview","tags":["Stats"],"description":"Active subscribers, new subscribers and unsubscribes per day over the last 30 days, and emails sent.","x-permissions":["full_access"],"responses":{"200":{"description":"Success","headers":{"ratelimit-limit":{"$ref":"#/components/headers/RateLimitLimit"},"ratelimit-remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"ratelimit-reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"example":{"object":"overview","subscribers":{"active":1520,"new_last_30_days":210,"unsubscribed_last_30_days":12},"daily":[{"date":"2026-10-17","new_subscribers":9,"unsubscribed":0,"emails_sent":0}],"emails":{"sent_this_month":4800,"sent_last_30_days":6100,"newsletters_sent_last_30_days":4}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/domains":{"post":{"operationId":"postDomains","summary":"Add a domain","tags":["Domains"],"description":"`tracking_subdomain` (a label, e.g. `news`) also makes `