{"openapi":"3.1.0","info":{"title":"Noosletter API","version":"1.0.0","description":"Manage subscribers, tags, segments, newsletters and emails, and read anonymous per-email stats. Every response is scoped to the account the key belongs to. There is no per-person open, click or view data anywhere in the API."},"servers":[{"url":"https://app.noosletter.com"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key from Settings → Developers, e.g. `Authorization: Bearer noos_…`"}},"schemas":{"Newsletter":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"privacy":{"type":"string","enum":["public","private"]},"cadence":{"type":"string","enum":["weekly","fortnightly","monthly"]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"subscriber_count":{"description":"People with an active subscription","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"description":"ISO 8601, UTC","type":"string"}},"required":["id","name","description","privacy","cadence","category","subscriber_count","created_at"],"additionalProperties":false},"Subscriber":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email_verification_status":{"type":"string","enum":["verified","risky","invalid","unverified"]},"archived":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"object","properties":{"newsletter_id":{"type":"string","minLength":1,"maxLength":100},"status":{"type":"string","enum":["subscribed","unsubscribed"]}},"required":["newsletter_id","status"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"created_at":{"description":"ISO 8601, UTC","type":"string"}},"required":["id","email","first_name","last_name","email_verification_status","archived","subscriptions","tags","created_at"],"additionalProperties":false},"SubscriberCreate":{"type":"object","properties":{"email":{"type":"string","minLength":3,"maxLength":320},"first_name":{"type":"string","maxLength":200},"last_name":{"type":"string","maxLength":200},"newsletter_ids":{"description":"Subscribe them to these newsletters. Needs `consent`.","maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}},"consent":{"type":"object","properties":{"basis":{"description":"How this person agreed to hear from you, in your words, e.g. \"Ticked the newsletter box at checkout\"","type":"string","minLength":1,"maxLength":200}},"required":["basis"]},"tag_ids":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}}},"required":["email"]},"SubscriberUpdate":{"type":"object","properties":{"first_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}}},"SubscribeRequest":{"type":"object","properties":{"newsletter_id":{"type":"string","minLength":1,"maxLength":100},"consent":{"type":"object","properties":{"basis":{"description":"How this person agreed to hear from you, in your words, e.g. \"Ticked the newsletter box at checkout\"","type":"string","minLength":1,"maxLength":200}},"required":["basis"]}},"required":["newsletter_id","consent"]},"Tag":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"name":{"type":"string"},"color":{"type":"string"}},"required":["id","name","color"],"additionalProperties":false},"TagCreate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100}},"required":["name"]},"TagApply":{"type":"object","properties":{"tag_id":{"type":"string","minLength":1,"maxLength":100}},"required":["tag_id"]},"Segment":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"name":{"type":"string"},"rule":{"description":"The segment's filter, as built in the app"},"contact_count":{"description":"Only on GET /v1/segments/{id}","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"description":"ISO 8601, UTC","type":"string"}},"required":["id","name","rule","created_at"],"additionalProperties":false},"Email":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"name":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","sending","sent","failed","cancelled"]},"newsletter_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"subject":{"type":"string"},"preview_text":{"anyOf":[{"type":"string"},{"type":"null"}]},"body_markdown":{"description":"Only on GET /v1/emails/{id}","type":"string"},"scheduled_at":{"anyOf":[{"description":"ISO 8601, UTC","type":"string"},{"type":"null"}]},"sent_at":{"anyOf":[{"description":"ISO 8601, UTC","type":"string"},{"type":"null"}]},"created_at":{"description":"ISO 8601, UTC","type":"string"}},"required":["id","name","status","newsletter_id","subject","preview_text","scheduled_at","sent_at","created_at"],"additionalProperties":false},"EmailCreate":{"type":"object","properties":{"newsletter_id":{"description":"Needed when the account has more than one newsletter","type":"string","minLength":1,"maxLength":100},"name":{"description":"Defaults to the subject","type":"string","minLength":1,"maxLength":200},"subject":{"type":"string","maxLength":500},"preview_text":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"body_markdown":{"description":"The email, in Markdown","type":"string","maxLength":200000}}},"EmailUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"newsletter_id":{"type":"string","minLength":1,"maxLength":100},"subject":{"type":"string","maxLength":500},"preview_text":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"body_markdown":{"type":"string","maxLength":200000}}},"ScheduleRequest":{"type":"object","properties":{"send_at":{"description":"When to send, ISO 8601 with a time zone offset","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|([+-]\\d{2}:\\d{2})))$"},"timezone":{"description":"IANA time zone to show it in, e.g. Europe/London. Defaults to the account's.","type":"string","maxLength":100}},"required":["send_at"]},"EmailStats":{"description":"Anonymous totals for one email. Never who opened or clicked.","type":"object","properties":{"email_id":{"type":"string","minLength":1,"maxLength":100},"status":{"type":"string"},"sent_at":{"anyOf":[{"description":"ISO 8601, UTC","type":"string"},{"type":"null"}]},"sends":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"delivered":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"opened":{"description":"Unique opens, approximate (privacy features in mail apps affect it)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clicked":{"description":"Unique clickers","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unsubscribes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"complaints":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bounces":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"new_subscribers":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"web_views":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"web_unique_views":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rates":{"type":"object","properties":{"delivery":{"anyOf":[{"type":"number"},{"type":"null"}]},"open":{"anyOf":[{"type":"number"},{"type":"null"}]},"click":{"anyOf":[{"type":"number"},{"type":"null"}]},"unsubscribe":{"anyOf":[{"type":"number"},{"type":"null"}]},"complaint":{"anyOf":[{"type":"number"},{"type":"null"}]},"bounce":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["delivery","open","click","unsubscribe","complaint","bounce"],"additionalProperties":false}},"required":["email_id","status","sent_at","sends","delivered","opened","clicked","unsubscribes","complaints","bounces","new_subscribers","web_views","web_unique_views","rates"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/newsletters":{"get":{"summary":"List your newsletters","tags":["Newsletters"],"x-scope":"read","security":[{"apiKey":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Newsletter"}}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/newsletters/{id}":{"get":{"summary":"Get a newsletter","tags":["Newsletters"],"x-scope":"read","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Newsletter"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/subscribers":{"get":{"summary":"List subscribers","description":"Newest first.","tags":["Subscribers"],"x-scope":"read","security":[{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"1 to 100, default 25","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page","schema":{"type":"string"}},{"name":"email","in":"query","required":false,"description":"Find one address","schema":{"type":"string"}},{"name":"newsletter_id","in":"query","required":false,"description":"Only people subscribed to this newsletter","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"With newsletter_id: `subscribed` (default) or `unsubscribed`","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Subscriber"}},"next_cursor":{"type":["string","null"]}},"required":["items","next_cursor"]}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Add a subscriber","description":"Runs your Blocklist and address verification; an address that can't receive email is refused. To subscribe them to newsletters, say how they agreed in `consent.basis`: it's kept with the subscription. Adding someone without newsletters creates a contact who gets nothing until they're subscribed.","tags":["Subscribers"],"x-scope":"write","security":[{"apiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string. Repeating it within 24 hours returns the first response instead of repeating the action.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriberCreate"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Subscriber"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/subscribers/{id}":{"get":{"summary":"Get a subscriber","tags":["Subscribers"],"x-scope":"read","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Subscriber"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a subscriber's name","tags":["Subscribers"],"x-scope":"write","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriberUpdate"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Subscriber"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/subscribers/{id}/subscriptions":{"post":{"summary":"Subscribe to a newsletter","description":"Needs a consent basis. Someone who unsubscribed themselves can only come back themselves, so that's refused with `unsubscribed_by_reader`.","tags":["Subscribers"],"x-scope":"write","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string. Repeating it within 24 hours returns the first response instead of repeating the action.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Subscriber"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/subscribers/{id}/subscriptions/{newsletter_id}":{"delete":{"summary":"Unsubscribe from a newsletter","tags":["Subscribers"],"x-scope":"write","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"newsletter_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Subscriber"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/subscribers/{id}/tags":{"post":{"summary":"Tag a subscriber","tags":["Subscribers"],"x-scope":"write","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagApply"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Subscriber"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/subscribers/{id}/tags/{tag_id}":{"delete":{"summary":"Remove a tag","tags":["Subscribers"],"x-scope":"write","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"tag_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Subscriber"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tags":{"get":{"summary":"List tags","tags":["Tags"],"x-scope":"read","security":[{"apiKey":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a tag","tags":["Tags"],"x-scope":"write","security":[{"apiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string. Repeating it within 24 hours returns the first response instead of repeating the action.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagCreate"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tag"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/segments":{"get":{"summary":"List segments","tags":["Segments"],"x-scope":"read","security":[{"apiKey":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/segments/{id}":{"get":{"summary":"Get a segment and how many people are in it","tags":["Segments"],"x-scope":"read","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Segment"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails":{"get":{"summary":"List emails","tags":["Emails"],"x-scope":"read","security":[{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"1 to 100, default 25","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"draft, scheduled, sending, sent, failed or cancelled","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Email"}},"next_cursor":{"type":["string","null"]}},"required":["items","next_cursor"]}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a draft","description":"Written in Markdown, the same as the editor. It's sent from your default verified sender.","tags":["Emails"],"x-scope":"write","security":[{"apiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string. Repeating it within 24 hours returns the first response instead of repeating the action.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailCreate"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Email"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/{id}":{"get":{"summary":"Get an email","tags":["Emails"],"x-scope":"read","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Email"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Edit a draft","tags":["Emails"],"x-scope":"write","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailUpdate"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Email"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/{id}/schedule":{"post":{"summary":"Schedule","description":"Checks there's a subject, a body, a verified sender and your postal address first.","tags":["Emails"],"x-scope":"write","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string. Repeating it within 24 hours returns the first response instead of repeating the action.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Email"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/{id}/cancel":{"post":{"summary":"Cancel a schedule","description":"It goes back to being a draft.","tags":["Emails"],"x-scope":"write","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Email"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/{id}/send":{"post":{"summary":"Send now","description":"Sends to everyone subscribed to the email's newsletter who can receive it. Pass an `Idempotency-Key` so a retry can never send twice; without one, a second send is refused.","tags":["Emails"],"x-scope":"write","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string. Repeating it within 24 hours returns the first response instead of repeating the action.","schema":{"type":"string","maxLength":200}}],"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","const":"sending"},"recipients":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","status","recipients"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/{id}/stats":{"get":{"summary":"Stats","description":"Anonymous totals. Never who opened or clicked.","tags":["Emails"],"x-scope":"read","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmailStats"}},"required":["data"]}}}},"400":{"description":"The request isn't valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key can't do this (read-only key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Can't be done as asked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit (120 requests a minute per key); see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"x-webhook-events":["subscriber.created","subscriber.resubscribed","subscriber.unsubscribed","email.scheduled","email.sent"]}