Hi!
Here is the news for October.
", "tag": "newsletter-2026-10", "messages": [ { "to": [ "anna@example.com" ], "metadata": { "customer": "1042" } }, { "to": [ { "email": "bo@example.com", "name": "Bo Berg" } ] } ] } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[^\\p{Cc}]{1,255}$" }, "in": "header", "name": "idempotency-key", "required": true, "description": "Any text of 1 to 255 printable characters that identifies this broadcast; the same key with a different body is refused." } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "The broadcast was stored; Sendora sends its messages from here.", "headers": { "Idempotent-Replayed": { "schema": { "type": "string", "enum": [ "true" ] }, "description": "true when this is the first answer again, to a request sent before under the same Idempotency-Key; absent otherwise." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "broadcastId": { "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)$", "description": "The id the messages, the progress and the cancel refer to." }, "status": { "type": "string", "enum": [ "accepted" ] }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Messages stored; each is a message in the log." }, "suppressed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Addresses dropped for standing on the stream’s suppression list." }, "submittedAt": { "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))$" }, "test": { "type": "boolean", "description": "True when the server is a test server: the messages go through everything but delivery, and nobody receives them." } }, "required": [ "broadcastId", "status", "total", "suppressed", "submittedAt", "test" ], "additionalProperties": false, "description": "The broadcast was stored; Sendora sends its messages from here." }, "examples": { "example": { "summary": "Accepted", "value": { "broadcastId": "2f1c8a4e-3b6d-4f0a-9c21-7d5e6a8b9c01", "status": "accepted", "total": 2, "suppressed": 0, "submittedAt": "2026-10-01T08:00:00.000Z", "test": false } } } } } }, "400": { "description": "The body, the query or a header does not match what the route takes, or the Idempotency-Key header is missing.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." }, "issues": { "description": "One entry per invalid field; absent when a header is wrong.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The field, dotted, such as to.0.email; empty when the whole body is wrong." }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The body, the query or a header does not match what the route takes.", "examples": [ { "error": "invalid_request", "message": "The request is invalid: to.0: Invalid email address", "issues": [ { "path": "to.0", "message": "Invalid email address" } ] } ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "idempotency_key_required" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "Batch sends need an Idempotency-Key header." } ], "description": "The body, the query or a header does not match what the route takes, or the Idempotency-Key header is missing." } } } }, "401": { "description": "The key is missing, malformed or revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The key is missing, malformed or revoked." } } } }, "402": { "description": "The account has no active subscription.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "payment_required" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The account has no active subscription." } } } }, "403": { "description": "The key is of the other kind, or the account is paused, closed or not yet approved for a live server's sends.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "enum": [ "wrong_token_kind" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The key is of the other kind: a server key (sk_) where an account key (ak_) is needed, or the reverse. The message names the kind the operation takes." }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "account_paused" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The account is paused by Sendora." }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "account_not_active" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The account is closed, or not yet approved for a live server's sends or an inbound stream." } ], "description": "The key is of the other kind, or the account is paused, closed or not yet approved for a live server's sends." } } } }, "413": { "description": "The body exceeds 10 MB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "request_too_large" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The body exceeds 10 MB." } } } }, "422": { "description": "The broadcast cannot be sent as it stands; the code says why.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "enum": [ "from_domain_not_verified" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The From domain is not a verified sending domain of this server." }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "stream_not_found" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The streamId names no stream of this server." }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "stream_archived" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The stream is archived and takes no new messages." }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "stream_paused" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "Sendora has paused the stream after complaints; it takes no messages until support has resumed it." }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "stream_not_broadcast" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "A broadcast goes on a broadcast stream; the streamId names a transactional one." }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unsubscribe_placeholder_missing" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "A message on a broadcast stream must carry {{ unsubscribe_url }} in every part it has." }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "list_unsubscribe_reserved" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "On a broadcast stream Sendora writes the List-Unsubscribe pair itself, so a message may not carry one." }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "substitution_missing" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." }, "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the message in `messages`." }, "keys": { "type": "array", "items": { "type": "string" }, "description": "The keys the content names that the message lacks." } }, "required": [ "error", "message", "index", "keys" ], "additionalProperties": false, "description": "The subject, text or HTML names a {{ key }} that a message does not give.", "examples": [ { "error": "substitution_missing", "message": "The content names {{ firstName }}, which message 1 does not give.", "index": 1, "keys": [ "firstName" ] } ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "recipient_suppressed" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." }, "streamId": { "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)$", "description": "The stream whose suppression list refused the send." }, "suppressed": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "reason": { "type": "string", "enum": [ "hard_bounce", "spam_complaint", "manual", "unsubscribe" ] } }, "required": [ "address", "reason" ], "additionalProperties": false }, "description": "Each refused address, lower-cased, with the reason it is on the list." } }, "required": [ "error", "message", "streamId", "suppressed" ], "additionalProperties": false, "description": "One or more recipients are on the suppression list of the stream.", "examples": [ { "error": "recipient_suppressed", "message": "One or more recipients are on the suppression list of this stream; suppressed says which and why.", "streamId": "3d1a2b4c-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "suppressed": [ { "address": "anna@example.com", "reason": "hard_bounce" } ] } ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "test_address_on_live_server" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." }, "addresses": { "type": "array", "items": { "type": "string" }, "description": "The recipients at simulator.sendora.se, each once." } }, "required": [ "error", "message", "addresses" ], "additionalProperties": false, "description": "Addresses at simulator.sendora.se act out an outcome on a test server; a live server never sends to them.", "examples": [ { "error": "test_address_on_live_server", "message": "Addresses at simulator.sendora.se act out an outcome on a test server and are never sent to from a live one. Send them from a test server.", "addresses": [ "hardbounce@simulator.sendora.se" ] } ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "idempotency_key_mismatch" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The Idempotency-Key was already used for a different request." } ], "description": "The broadcast cannot be sent as it stands; the code says why." } } } }, "429": { "description": "The monthly cap of the account, the server or the test servers is used up.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "monthly_cap_reached" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." }, "scope": { "type": "string", "enum": [ "account", "server", "test" ], "description": "Whose limit it is: `account` for the account's, `server` for the server's own, `test` for the cap the account's test servers share." }, "cap": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Emails the scope may send in a calendar month, in UTC." }, "used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Emails sent this month, the refused send not counted." }, "resetsAt": { "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))$", "description": "When the month counter resets." } }, "required": [ "error", "message", "scope", "cap", "used", "resetsAt" ], "additionalProperties": false, "description": "The monthly cap of the account, the server or the test servers is used up." }, "example": { "error": "monthly_cap_reached", "message": "This account has used 50000 of 50000 emails this month. The cap resets at 2026-11-01T00:00:00.000Z.", "scope": "account", "cap": 50000, "used": 50000, "resetsAt": "2026-11-01T00:00:00.000Z" } } } }, "503": { "description": "Sending is disabled for everyone for the moment; retry after the seconds in Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before trying again." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "sending_disabled" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "Sending is disabled for everyone for the moment; retry after the seconds in Retry-After." } } } } } }, "get": { "summary": "List the broadcasts", "tags": [ "Broadcasts" ], "description": "The broadcasts of this server, newest first, a page at a time.", "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Page size, 1 to 100." }, { "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)$" }, "in": "query", "name": "after", "required": false, "description": "The `next` value of the previous page." } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "A page of the broadcasts, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "broadcasts": { "type": "array", "items": { "type": "object", "properties": { "broadcastId": { "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)$" }, "streamId": { "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)$", "description": "The broadcast stream the messages go on." }, "status": { "type": "string", "enum": [ "accepted", "processing", "completed", "cancelled" ], "description": "accepted until the first message leaves, processing while messages are leaving, completed when every message has left or failed, cancelled once cancelled." }, "from": { "type": "string" }, "subject": { "type": "string" }, "tag": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Messages stored, after suppressed addresses were dropped." }, "released": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Messages handed to the mail server so far." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Messages that could not be handed over, cancelled ones included." }, "suppressed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Addresses dropped from the list for standing on the stream’s suppression list." }, "submittedAt": { "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))$" }, "completedAt": { "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))$" }, { "type": "null" } ], "description": "Set once nothing is left to send, or on cancel." } }, "required": [ "broadcastId", "streamId", "status", "from", "subject", "tag", "metadata", "total", "released", "failed", "suppressed", "submittedAt", "completedAt" ], "additionalProperties": false, "description": "A broadcast and how far it has come." } }, "next": { "anyOf": [ { "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)$" }, { "type": "null" } ], "description": "Pass as `after` for the next page; null on the last." } }, "required": [ "broadcasts", "next" ], "additionalProperties": false, "description": "A page of the broadcasts, newest first." }, "examples": { "example": { "summary": "One broadcast under way", "value": { "broadcasts": [ { "broadcastId": "2f1c8a4e-3b6d-4f0a-9c21-7d5e6a8b9c01", "streamId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "processing", "from": "news@acme.se", "subject": "News from Acme in October", "tag": "newsletter-2026-10", "metadata": {}, "total": 2, "released": 1, "failed": 0, "suppressed": 0, "submittedAt": "2026-10-01T08:00:00.000Z", "completedAt": null } ], "next": null } } } } } }, "400": { "description": "The body, the query or a header does not match what the route takes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." }, "issues": { "description": "One entry per invalid field; absent when a header is wrong.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The field, dotted, such as to.0.email; empty when the whole body is wrong." }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The body, the query or a header does not match what the route takes." }, "example": { "error": "invalid_request", "message": "The request is invalid: to.0: Invalid email address", "issues": [ { "path": "to.0", "message": "Invalid email address" } ] } } } }, "401": { "description": "The key is missing, malformed or revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The key is missing, malformed or revoked." } } } }, "403": { "description": "The key is of the other kind: a server key (sk_) where an account key (ak_) is needed, or the reverse. The message names the kind the operation takes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "wrong_token_kind" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The key is of the other kind: a server key (sk_) where an account key (ak_) is needed, or the reverse. The message names the kind the operation takes." } } } } } } }, "/v1/broadcasts/{id}": { "get": { "summary": "Get a broadcast", "tags": [ "Broadcasts" ], "description": "The broadcast and how far it has come: its status and the counts of messages released and failed.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "The broadcast id." } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "A broadcast and how far it has come.", "content": { "application/json": { "schema": { "type": "object", "properties": { "broadcastId": { "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)$" }, "streamId": { "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)$", "description": "The broadcast stream the messages go on." }, "status": { "type": "string", "enum": [ "accepted", "processing", "completed", "cancelled" ], "description": "accepted until the first message leaves, processing while messages are leaving, completed when every message has left or failed, cancelled once cancelled." }, "from": { "type": "string" }, "subject": { "type": "string" }, "tag": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Messages stored, after suppressed addresses were dropped." }, "released": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Messages handed to the mail server so far." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Messages that could not be handed over, cancelled ones included." }, "suppressed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Addresses dropped from the list for standing on the stream’s suppression list." }, "submittedAt": { "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))$" }, "completedAt": { "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))$" }, { "type": "null" } ], "description": "Set once nothing is left to send, or on cancel." } }, "required": [ "broadcastId", "streamId", "status", "from", "subject", "tag", "metadata", "total", "released", "failed", "suppressed", "submittedAt", "completedAt" ], "additionalProperties": false, "description": "A broadcast and how far it has come." }, "examples": { "example": { "summary": "Under way", "value": { "broadcastId": "2f1c8a4e-3b6d-4f0a-9c21-7d5e6a8b9c01", "streamId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "processing", "from": "news@acme.se", "subject": "News from Acme in October", "tag": "newsletter-2026-10", "metadata": {}, "total": 2, "released": 1, "failed": 0, "suppressed": 0, "submittedAt": "2026-10-01T08:00:00.000Z", "completedAt": null } } } } } }, "401": { "description": "The key is missing, malformed or revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The key is missing, malformed or revoked." } } } }, "403": { "description": "The key is of the other kind: a server key (sk_) where an account key (ak_) is needed, or the reverse. The message names the kind the operation takes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "wrong_token_kind" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The key is of the other kind: a server key (sk_) where an account key (ak_) is needed, or the reverse. The message names the kind the operation takes." } } } }, "404": { "description": "No such broadcast of this server.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "No such broadcast of this server." } } } } } } }, "/v1/broadcasts/{id}/cancel": { "post": { "summary": "Cancel a broadcast", "tags": [ "Broadcasts" ], "description": "Holds every message of the broadcast that has not been handed to the mail server yet; those count as failed. A message already on its way is delivered. A completed or cancelled broadcast answers 409.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "The broadcast id." } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "A broadcast and how far it has come.", "content": { "application/json": { "schema": { "type": "object", "properties": { "broadcastId": { "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)$" }, "streamId": { "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)$", "description": "The broadcast stream the messages go on." }, "status": { "type": "string", "enum": [ "accepted", "processing", "completed", "cancelled" ], "description": "accepted until the first message leaves, processing while messages are leaving, completed when every message has left or failed, cancelled once cancelled." }, "from": { "type": "string" }, "subject": { "type": "string" }, "tag": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Messages stored, after suppressed addresses were dropped." }, "released": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Messages handed to the mail server so far." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Messages that could not be handed over, cancelled ones included." }, "suppressed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Addresses dropped from the list for standing on the stream’s suppression list." }, "submittedAt": { "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))$" }, "completedAt": { "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))$" }, { "type": "null" } ], "description": "Set once nothing is left to send, or on cancel." } }, "required": [ "broadcastId", "streamId", "status", "from", "subject", "tag", "metadata", "total", "released", "failed", "suppressed", "submittedAt", "completedAt" ], "additionalProperties": false, "description": "A broadcast and how far it has come." }, "examples": { "example": { "summary": "Cancelled", "value": { "broadcastId": "2f1c8a4e-3b6d-4f0a-9c21-7d5e6a8b9c01", "streamId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "cancelled", "from": "news@acme.se", "subject": "News from Acme in October", "tag": "newsletter-2026-10", "metadata": {}, "total": 2, "released": 1, "failed": 1, "suppressed": 0, "submittedAt": "2026-10-01T08:00:00.000Z", "completedAt": "2026-10-01T08:05:00.000Z" } } } } } }, "401": { "description": "The key is missing, malformed or revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The key is missing, malformed or revoked." } } } }, "403": { "description": "The key is of the other kind: a server key (sk_) where an account key (ak_) is needed, or the reverse. The message names the kind the operation takes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "wrong_token_kind" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The key is of the other kind: a server key (sk_) where an account key (ak_) is needed, or the reverse. The message names the kind the operation takes." } } } }, "404": { "description": "No such broadcast of this server.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "No such broadcast of this server." } } } }, "409": { "description": "The broadcast is completed or cancelled already; nothing is left to cancel.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "broadcast_not_open" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The broadcast is completed or cancelled already; nothing is left to cancel." } } } } } } }, "/v1/messages/{id}": { "get": { "summary": "Read a message", "tags": [ "Messages" ], "description": "The message as the log holds it, its attachments described but not returned, and every event on its timeline. Bodies are never returned.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "The message id." } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "The message with its attachments described and its timeline.", "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "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)$" }, "streamId": { "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)$", "description": "The stream the message went on." }, "broadcastId": { "anyOf": [ { "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)$" }, { "type": "null" } ], "description": "The broadcast the message belongs to; null for a message sent on its own." }, "status": { "type": "string", "enum": [ "accepted", "injected", "failed" ], "description": "`accepted` until handed to the mail server, `injected` after; `failed` if that never worked." }, "from": { "type": "string" }, "subject": { "type": "string" }, "tag": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "submittedAt": { "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))$" }, "test": { "type": "boolean", "description": "True when the message went through a test server: its events were simulated and nobody received it." }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "kind": { "type": "string", "enum": [ "to", "cc", "bcc" ] }, "status": { "type": "string", "enum": [ "queued", "delivered", "deferred", "bounced", "expired" ], "description": "queued until the receiver answers; deferred while it keeps saying try later." } }, "required": [ "address", "kind", "status" ], "additionalProperties": false } }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "contentType": { "type": "string" }, "contentId": { "type": [ "string", "null" ] }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Bytes before encoding." } }, "required": [ "name", "contentType", "contentId", "size" ], "additionalProperties": false } }, "events": { "type": "array", "items": { "type": "object", "properties": { "recipient": { "description": "The recipient the event is about; null when it concerns the message as a whole.", "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "Reception", "Delivery", "Bounce", "TransientFailure", "Expiration", "AdminBounce", "OOB", "Feedback", "AdminRebind", "DeferredInjectionRebind", "Rejection", "Delayed" ], "description": "Reception when the mail server took it, Delivery, TransientFailure, Bounce, OOB for a bounce report received by mail, Feedback for a spam complaint." }, "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))$" }, "code": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The SMTP status code the receiver answered." }, "details": { "description": "The receiver’s response text.", "type": [ "string", "null" ] }, "classification": { "description": "How a bounce was classified, such as InvalidRecipient.", "type": [ "string", "null" ] } }, "required": [ "recipient", "type", "at", "code", "details", "classification" ], "additionalProperties": false, "description": "One step of the message’s timeline." }, "description": "Oldest first." } }, "required": [ "messageId", "streamId", "broadcastId", "status", "from", "subject", "tag", "metadata", "submittedAt", "test", "recipients", "attachments", "events" ], "additionalProperties": false, "description": "The message with its attachments described and its timeline." }, "examples": { "example": { "summary": "A delivered message", "value": { "messageId": "5f432ffd-c005-499b-aa3a-5b8a088ea20e", "streamId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "broadcastId": null, "status": "injected", "from": "no-reply@example.se", "subject": "Your invoice for September", "tag": "invoice", "metadata": { "invoiceId": "2026-0912" }, "submittedAt": "2026-09-15T12:00:00.000Z", "test": false, "recipients": [ { "address": "anna@example.com", "kind": "to", "status": "delivered" } ], "attachments": [ { "name": "invoice.pdf", "contentType": "application/pdf", "contentId": null, "size": 48213 } ], "events": [ { "recipient": "anna@example.com", "type": "Reception", "at": "2026-09-15T12:00:00.000Z", "code": 250, "details": null, "classification": null }, { "recipient": "anna@example.com", "type": "Delivery", "at": "2026-09-15T12:00:02.000Z", "code": 250, "details": "2.0.0 OK", "classification": null } ] } } } } } }, "401": { "description": "The key is missing, malformed or revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The key is missing, malformed or revoked." } } } }, "403": { "description": "The key is of the other kind: a server key (sk_) where an account key (ak_) is needed, or the reverse. The message names the kind the operation takes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "wrong_token_kind" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The key is of the other kind: a server key (sk_) where an account key (ak_) is needed, or the reverse. The message names the kind the operation takes." } } } }, "404": { "description": "No such message of this server.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "No such message of this server." } } } } } } }, "/v1/messages/search": { "post": { "summary": "Search the message log", "tags": [ "Messages" ], "description": "The messages of the server, newest first, one page at a time. A POST so that an address travels in the body and never in a URL. Messages older than the retention window are gone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "description": "Messages to this address, in to, cc or bcc.", "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "streamId": { "description": "Messages on this stream of the server.", "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)$" }, "broadcastId": { "description": "Messages of this broadcast.", "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)$" }, "tag": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "description": "Messages with at least one recipient in this state.", "type": "string", "enum": [ "queued", "delivered", "deferred", "bounced", "expired" ] }, "from": { "description": "Submitted at or after this time.", "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)))$" }, "to": { "description": "Submitted before this time.", "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)))$" }, "limit": { "default": 50, "description": "Page size, 1 to 100.", "type": "integer", "minimum": 1, "maximum": 100 }, "after": { "description": "The `next` value of the previous page.", "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)$" } }, "additionalProperties": false, "description": "Every filter is optional; the page is newest first." }, "examples": { "example": { "summary": "Bounced messages to one address", "value": { "recipient": "anna@example.com", "status": "bounced", "limit": 20 } } } } }, "description": "Every filter is optional; the page is newest first." }, "security": [ { "bearer": [] } ], "responses": { "200": { "description": "A page of the messages that match, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "messageId": { "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)$" }, "streamId": { "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)$", "description": "The stream the message went on." }, "broadcastId": { "anyOf": [ { "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)$" }, { "type": "null" } ], "description": "The broadcast the message belongs to; null for a message sent on its own." }, "status": { "type": "string", "enum": [ "accepted", "injected", "failed" ], "description": "`accepted` until handed to the mail server, `injected` after; `failed` if that never worked." }, "from": { "type": "string" }, "subject": { "type": "string" }, "tag": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "submittedAt": { "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))$" }, "test": { "type": "boolean", "description": "True when the message went through a test server: its events were simulated and nobody received it." }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "kind": { "type": "string", "enum": [ "to", "cc", "bcc" ] }, "status": { "type": "string", "enum": [ "queued", "delivered", "deferred", "bounced", "expired" ], "description": "queued until the receiver answers; deferred while it keeps saying try later." } }, "required": [ "address", "kind", "status" ], "additionalProperties": false } } }, "required": [ "messageId", "streamId", "broadcastId", "status", "from", "subject", "tag", "metadata", "submittedAt", "test", "recipients" ], "additionalProperties": false, "description": "A message as the log lists it." } }, "next": { "anyOf": [ { "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)$" }, { "type": "null" } ], "description": "Pass as `after` for the next page; null on the last." } }, "required": [ "messages", "next" ], "additionalProperties": false, "description": "A page of the messages that match, newest first." }, "examples": { "example": { "summary": "One message", "value": { "messages": [ { "messageId": "5f432ffd-c005-499b-aa3a-5b8a088ea20e", "streamId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "broadcastId": null, "status": "injected", "from": "no-reply@example.se", "subject": "Your invoice for September", "tag": "invoice", "metadata": { "invoiceId": "2026-0912" }, "submittedAt": "2026-09-15T12:00:00.000Z", "test": false, "recipients": [ { "address": "anna@example.com", "kind": "to", "status": "delivered" } ] } ], "next": null } } } } } }, "400": { "description": "The body, the query or a header does not match what the route takes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." }, "issues": { "description": "One entry per invalid field; absent when a header is wrong.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The field, dotted, such as to.0.email; empty when the whole body is wrong." }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The body, the query or a header does not match what the route takes." }, "example": { "error": "invalid_request", "message": "The request is invalid: to.0: Invalid email address", "issues": [ { "path": "to.0", "message": "Invalid email address" } ] } } } }, "401": { "description": "The key is missing, malformed or revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The key is missing, malformed or revoked." } } } }, "403": { "description": "The key is of the other kind: a server key (sk_) where an account key (ak_) is needed, or the reverse. The message names the kind the operation takes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "wrong_token_kind" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The key is of the other kind: a server key (sk_) where an account key (ak_) is needed, or the reverse. The message names the kind the operation takes." } } } } } } }, "/v1/inbound/search": { "post": { "summary": "Search received messages", "tags": [ "Inbound" ], "description": "The messages the server has received, newest first, one page at a time. A POST so that an address travels in the body and never in a URL. The sender is matched by keyed hash, so the search itself stores no address. Messages older than 13 months are gone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "streamId": { "description": "Messages received on this inbound stream of the server.", "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)$" }, "from": { "description": "Messages from this address, in the envelope or the From header.", "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "recipient": { "description": "Messages sent to this address of yours, the envelope recipient.", "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "mailboxHash": { "description": "Messages whose address carried this text after the plus sign.", "type": "string", "maxLength": 255 }, "receivedFrom": { "description": "Accepted at or after this time.", "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)))$" }, "receivedTo": { "description": "Accepted before this time.", "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)))$" }, "limit": { "default": 50, "description": "Page size, 1 to 100.", "type": "integer", "minimum": 1, "maximum": 100 }, "after": { "description": "The `next` value of the previous page.", "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)$" } }, "additionalProperties": false, "description": "Every filter is optional; the page is newest first." }, "examples": { "example": { "summary": "Messages from one sender this week", "value": { "from": "anna@example.com", "receivedFrom": "2026-09-15T00:00:00+02:00", "limit": 20 } } } } }, "description": "Every filter is optional; the page is newest first." }, "security": [ { "bearer": [] } ], "responses": { "200": { "description": "A page of the received messages that match, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "inboundMessageId": { "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)$" }, "streamId": { "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)$", "description": "The inbound stream that received it." }, "receivedAt": { "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))$", "description": "When the message was accepted from the sending server." }, "envelopeRecipient": { "type": "string", "description": "The address of yours the message was sent to." }, "mailboxHash": { "description": "The text after the plus sign in that address, when the sender used one.", "type": [ "string", "null" ] }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "attachmentCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasText": { "type": "boolean" }, "hasHtml": { "type": "boolean" }, "parseIssue": { "description": "What the parser met; null when the message parsed clean. A hard issue empties the parsed parts, and the raw message stays: `no_headers`, `header_block_too_large`, `too_many_headers`, `too_many_parts`, `nesting_too_deep`, `missing_boundary`, `decoded_too_large`, `parse_timeout`, `parser_error`. A soft issue keeps them and says what was changed or dropped: `truncated_multipart`, `too_many_attachments`, `unknown_transfer_encoding`, `undecodable_container`, `filename_sanitised`, `control_chars_stripped`, `multiple_from`, `duplicate_header`, `malformed_header_dropped`, `address_list_truncated`, `header_value_truncated`. A message with several names the hard one, or the first soft one in this order.", "type": [ "string", "null" ] }, "authentication": { "type": "object", "properties": { "spf": { "type": "string", "enum": [ "pass", "fail", "softfail", "neutral", "none", "temperror", "permerror", "unchecked" ], "description": "SPF for the address in MAIL FROM." }, "spfHelo": { "type": "string", "enum": [ "pass", "fail", "softfail", "neutral", "none", "temperror", "permerror", "unchecked" ], "description": "SPF for the name the sending server gave in HELO." }, "dkim": { "type": "string", "enum": [ "pass", "fail", "none", "temperror", "permerror", "unchecked" ] }, "dmarc": { "type": "string", "enum": [ "pass", "fail", "none", "temperror", "permerror", "unchecked" ] }, "dmarcPolicy": { "anyOf": [ { "type": "string", "enum": [ "none", "quarantine", "reject" ] }, { "type": "null" } ], "description": "What the sender’s domain asks for; told only when DMARC failed." }, "arc": { "type": "string", "enum": [ "none", "pass", "fail", "unchecked" ] }, "checkedAt": { "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))$" }, { "type": "null" } ], "description": "When the checks ran; null until they have." } }, "required": [ "spf", "spfHelo", "dkim", "dmarc", "dmarcPolicy", "arc", "checkedAt" ], "additionalProperties": false, "description": "What Sendora found when it checked the message; unchecked until the checks have run." }, "contentAvailable": { "type": "boolean", "description": "False once the stream’s content window has passed; only the reference remains." }, "contentExpiresAt": { "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))$", "description": "When the content goes." }, "from": { "anyOf": [ { "type": "object", "properties": { "address": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "address", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The From header; null without it or once the content is gone." }, "subject": { "type": [ "string", "null" ] }, "date": { "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))$" }, { "type": "null" } ], "description": "The sender’s Date header as ISO 8601, when it was a real moment." } }, "required": [ "inboundMessageId", "streamId", "receivedAt", "envelopeRecipient", "mailboxHash", "sizeBytes", "attachmentCount", "hasText", "hasHtml", "parseIssue", "authentication", "contentAvailable", "contentExpiresAt", "from", "subject", "date" ], "additionalProperties": false, "description": "A received message as the list shows it." } }, "next": { "anyOf": [ { "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)$" }, { "type": "null" } ], "description": "Pass as `after` for the next page; null on the last." } }, "required": [ "messages", "next" ], "additionalProperties": false, "description": "A page of the received messages that match, newest first." }, "examples": { "example": { "summary": "One received message", "value": { "messages": [ { "inboundMessageId": "4d1f8b2e-9c3a-4e7b-8f21-6a5d0c9e7b31", "streamId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "receivedAt": "2026-09-19T08:00:02.000Z", "envelopeRecipient": "7c9e6679742540de944be07fc1f90ae7@inbound.sendora.se", "mailboxHash": null, "sizeBytes": 48213, "attachmentCount": 1, "hasText": true, "hasHtml": false, "parseIssue": null, "authentication": { "spf": "pass", "spfHelo": "pass", "dkim": "pass", "dmarc": "pass", "dmarcPolicy": null, "arc": "none", "checkedAt": "2026-09-19T08:00:03.000Z" }, "contentAvailable": true, "contentExpiresAt": "2026-10-19T08:00:02.000Z", "from": { "address": "anna@example.com", "name": "Anna Andersson" }, "subject": "A question about my order", "date": "2026-09-19T08:00:00.000Z" } ], "next": null } } } } } }, "400": { "description": "The body, the query or a header does not match what the route takes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." }, "issues": { "description": "One entry per invalid field; absent when a header is wrong.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The field, dotted, such as to.0.email; empty when the whole body is wrong." }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The body, the query or a header does not match what the route takes." }, "example": { "error": "invalid_request", "message": "The request is invalid: to.0: Invalid email address", "issues": [ { "path": "to.0", "message": "Invalid email address" } ] } } } }, "401": { "description": "The key is missing, malformed or revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The key is missing, malformed or revoked." } } } }, "403": { "description": "The key is of the other kind: a server key (sk_) where an account key (ak_) is needed, or the reverse. The message names the kind the operation takes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "wrong_token_kind" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The key is of the other kind: a server key (sk_) where an account key (ak_) is needed, or the reverse. The message names the kind the operation takes." } } } }, "422": { "description": "The streamId names no stream of this server.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "stream_not_found" ] }, "message": { "type": "string", "description": "What went wrong, for a person to read." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "The streamId names no stream of this server." } } } } } } }, "/v1/inbound/{id}": { "get": { "summary": "Read a received message", "tags": [ "Inbound" ], "description": "The message with its envelope, parties, headers, text, HTML and attachment descriptors; the attachment bytes and the raw message are downloads of their own. Once the stream’s content window has passed, the content fields are null and contentAvailable is false.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "The inbound message id." } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "The received message with everything but the attachment bytes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "inboundMessageId": { "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)$" }, "streamId": { "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)$", "description": "The inbound stream that received it." }, "receivedAt": { "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))$", "description": "When the message was accepted from the sending server." }, "envelopeRecipient": { "type": "string", "description": "The address of yours the message was sent to." }, "mailboxHash": { "description": "The text after the plus sign in that address, when the sender used one.", "type": [ "string", "null" ] }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "attachmentCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasText": { "type": "boolean" }, "hasHtml": { "type": "boolean" }, "parseIssue": { "description": "What the parser met; null when the message parsed clean. A hard issue empties the parsed parts, and the raw message stays: `no_headers`, `header_block_too_large`, `too_many_headers`, `too_many_parts`, `nesting_too_deep`, `missing_boundary`, `decoded_too_large`, `parse_timeout`, `parser_error`. A soft issue keeps them and says what was changed or dropped: `truncated_multipart`, `too_many_attachments`, `unknown_transfer_encoding`, `undecodable_container`, `filename_sanitised`, `control_chars_stripped`, `multiple_from`, `duplicate_header`, `malformed_header_dropped`, `address_list_truncated`, `header_value_truncated`. A message with several names the hard one, or the first soft one in this order.", "type": [ "string", "null" ] }, "authentication": { "type": "object", "properties": { "spf": { "type": "string", "enum": [ "pass", "fail", "softfail", "neutral", "none", "temperror", "permerror", "unchecked" ], "description": "SPF for the address in MAIL FROM." }, "spfHelo": { "type": "string", "enum": [ "pass", "fail", "softfail", "neutral", "none", "temperror", "permerror", "unchecked" ], "description": "SPF for the name the sending server gave in HELO." }, "dkim": { "type": "string", "enum": [ "pass", "fail", "none", "temperror", "permerror", "unchecked" ] }, "dmarc": { "type": "string", "enum": [ "pass", "fail", "none", "temperror", "permerror", "unchecked" ] }, "dmarcPolicy": { "anyOf": [ { "type": "string", "enum": [ "none", "quarantine", "reject" ] }, { "type": "null" } ], "description": "What the sender’s domain asks for; told only when DMARC failed." }, "arc": { "type": "string", "enum": [ "none", "pass", "fail", "unchecked" ] }, "checkedAt": { "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))$" }, { "type": "null" } ], "description": "When the checks ran; null until they have." } }, "required": [ "spf", "spfHelo", "dkim", "dmarc", "dmarcPolicy", "arc", "checkedAt" ], "additionalProperties": false, "description": "What Sendora found when it checked the message; unchecked until the checks have run." }, "contentAvailable": { "type": "boolean", "description": "False once the stream’s content window has passed; only the reference remains." }, "contentExpiresAt": { "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))$", "description": "When the content goes." }, "from": { "anyOf": [ { "type": "object", "properties": { "address": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "address", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The From header; null without it or once the content is gone." }, "subject": { "type": [ "string", "null" ] }, "date": { "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))$" }, { "type": "null" } ], "description": "The sender’s Date header as ISO 8601, when it was a real moment." }, "envelope": { "anyOf": [ { "type": "object", "properties": { "sender": { "description": "The MAIL FROM address; null for a bounce.", "type": [ "string", "null" ] } }, "required": [ "sender" ], "additionalProperties": false }, { "type": "null" } ], "description": "Null once the content is gone." }, "replyTo": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "address", "name" ], "additionalProperties": false } }, "to": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "address", "name" ], "additionalProperties": false }, "description": "Up to 100 entries; toCount is the whole number." }, "toCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "cc": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "address", "name" ], "additionalProperties": false }, "description": "Up to 100 entries; ccCount is the whole number." }, "ccCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "messageIdHeader": { "type": [ "string", "null" ] }, "inReplyTo": { "type": [ "string", "null" ] }, "references": { "type": "array", "items": { "type": "string" } }, "headers": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ], "additionalProperties": false } }, { "type": "null" } ], "description": "Every header in order; null once the content is gone." }, "text": { "description": "The plain-text body; null without one or once the content is gone.", "type": [ "string", "null" ] }, "html": { "description": "The HTML body as received; null without one or once the content is gone.", "type": [ "string", "null" ] }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "attachmentId": { "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)$" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Its place among the message’s attachments, from 0." }, "name": { "description": "The filename, sanitised; null once the content is gone.", "type": [ "string", "null" ] }, "contentType": { "description": "The type the sender declared; every download is served as application/octet-stream.", "type": [ "string", "null" ] }, "contentId": { "description": "The Content-ID an HTML body refers to with cid:.", "type": [ "string", "null" ] }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Bytes." }, "inline": { "type": "boolean", "description": "True for a part shown in the body rather than offered as a file." } }, "required": [ "attachmentId", "position", "name", "contentType", "contentId", "size", "inline" ], "additionalProperties": false, "description": "An attachment of a received message; its bytes are a download of their own." } } }, "required": [ "inboundMessageId", "streamId", "receivedAt", "envelopeRecipient", "mailboxHash", "sizeBytes", "attachmentCount", "hasText", "hasHtml", "parseIssue", "authentication", "contentAvailable", "contentExpiresAt", "from", "subject", "date", "envelope", "replyTo", "to", "toCount", "cc", "ccCount", "messageIdHeader", "inReplyTo", "references", "headers", "text", "html", "attachments" ], "additionalProperties": false, "description": "The received message with everything but the attachment bytes." }, "examples": { "example": { "summary": "A received message", "value": { "inboundMessageId": "4d1f8b2e-9c3a-4e7b-8f21-6a5d0c9e7b31", "streamId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "receivedAt": "2026-09-19T08:00:02.000Z", "envelopeRecipient": "7c9e6679742540de944be07fc1f90ae7@inbound.sendora.se", "mailboxHash": null, "sizeBytes": 48213, "attachmentCount": 1, "hasText": true, "hasHtml": false, "parseIssue": null, "authentication": { "spf": "pass", "spfHelo": "pass", "dkim": "pass", "dmarc": "pass", "dmarcPolicy": null, "arc": "none", "checkedAt": "2026-09-19T08:00:03.000Z" }, "contentAvailable": true, "contentExpiresAt": "2026-10-19T08:00:02.000Z", "from": { "address": "anna@example.com", "name": "Anna Andersson" }, "subject": "A question about my order", "date": "2026-09-19T08:00:00.000Z", "envelope": { "sender": "anna@example.com" }, "replyTo": [], "to": [ { "address": "7c9e6679742540de944be07fc1f90ae7@inbound.sendora.se", "name": null } ], "toCount": 1, "cc": [], "ccCount": 0, "messageIdHeader": "Hi! I have a question about the invoice for September.
", "attachments": [ { "position": 0, "name": "invoice.pdf", "contentType": "application/pdf", "contentId": null, "size": 15360, "inline": false } ], "contentOmitted": null } ] } ], "description": "A message was received on an inbound stream: the reference, or the reference and the message itself, as the webhook asks." } } } }, "responses": { "2XX": { "description": "Acknowledges the delivery. Any other answer, or none within 10 seconds, is retried." } } } } }, "tags": [ { "name": "Sending", "description": "Hand messages over for delivery." }, { "name": "Broadcasts", "description": "One message to many, sent as a broadcast." }, { "name": "Messages", "description": "The message log and each message’s timeline." }, { "name": "Inbound", "description": "The mail the server has received: the messages, their raw form and their attachments." }, { "name": "Streams", "description": "The streams of the server: transactional, broadcast, and at most one inbound." }, { "name": "Servers", "description": "The account’s servers and each one’s keys, under an account key: a server is created with its first key and holds up to two. GET /v1/server takes a server key and reads that key’s own server." }, { "name": "Domains", "description": "Sending domains and their two DNS records, under an account key." }, { "name": "Erasures", "description": "A person's data erased from every server of the account, under an account key." }, { "name": "Suppressions", "description": "Addresses the server no longer sends to." }, { "name": "Webhooks", "description": "Where events are posted, signed with each of the webhook’s live secrets, and every delivery of them." }, { "name": "Keys", "description": "A server's own keys under one of them, up to two live at once; an account key manages them under /v1/servers/{id}/tokens, and the account's own keys are created in the dashboard." } ] }