Messages

Search the message log

POST/v1/messages/search

TypeScript sendora.messages.search(filters)

Python sendora.messages.search(**filters)

Key sk_… a server key

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.

Request body

Every filter is optional; the page is newest first.

recipientstring (email)
Messages to this address, in to, cc or bcc.
streamIdstring (uuid)
Messages on this stream of the server.
broadcastIdstring (uuid)
Messages of this broadcast.
tagstring (at least 1, at most 100 characters)
status"queued" | "delivered" | "deferred" | "bounced" | "expired"
Messages with at least one recipient in this state.
fromstring (date-time)
Submitted at or after this time.
tostring (date-time)
Submitted before this time.
limitinteger (1 to 100)default 50
Page size, 1 to 100.
afterstring (uuid)
The next value of the previous page.

{
  "recipient": "anna@example.com",
  "status": "bounced",
  "limit": 20
}

Responses

`200`A page of the messages that match, newest first.

messagesarray of objectrequired
- messageIdstring (uuid)required
- streamIdstring (uuid)required
  The stream the message went on.
- broadcastIdstring (uuid) or nullrequired
  The broadcast the message belongs to; null for a message sent on its own.
- status"accepted" | "injected" | "failed"required
  accepted until handed to the mail server, injected after; failed if that never worked.
- fromstringrequired
- subjectstringrequired
- tagstring or nullrequired
- metadatamap of string to stringrequired
- submittedAtstring (date-time)required
- testbooleanrequired
  True when the message went through a test server: its events were simulated and nobody received it.
- recipientsarray of objectrequired
  - addressstringrequired
  - kind"to" | "cc" | "bcc"required
  - status"queued" | "delivered" | "deferred" | "bounced" | "expired"required
    queued until the receiver answers; deferred while it keeps saying try later.
nextstring (uuid) or nullrequired
Pass as after for the next page; null on the last.

Example (26 lines)

{
  "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
}

Errors

Every error answers error, the code, and message, a sentence for a person. A code that adds fields is shown in full below the table.

Code	Status	Meaning
`invalid_request`	400	The body, the query or a header does not match what the route takes.
`unauthorized`	401	The key is missing, malformed or revoked.
`wrong_token_kind`	403	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.

`invalid_request`

issuesarray of object
One entry per invalid field; absent when a header is wrong.
- pathstringrequired
  The field, dotted, such as to.0.email; empty when the whole body is wrong.
- messagestringrequired

Example

{
  "error": "invalid_request",
  "message": "The request is invalid: to.0: Invalid email address",
  "issues": [
    {
      "path": "to.0",
      "message": "Invalid email address"
    }
  ]
}