Inbound

Search received messages

POST/v1/inbound/search

TypeScript sendora.inbound.search(filters)

Python sendora.inbound.search(**filters)

Key sk_… a server key

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.

Request body

Every filter is optional; the page is newest first.

streamIdstring (uuid)
Messages received on this inbound stream of the server.
fromstring (email)
Messages from this address, in the envelope or the From header.
recipientstring (email)
Messages sent to this address of yours, the envelope recipient.
mailboxHashstring (at most 255 characters)
Messages whose address carried this text after the plus sign.
receivedFromstring (date-time)
Accepted at or after this time.
receivedTostring (date-time)
Accepted before this time.
limitinteger (1 to 100)default 50
Page size, 1 to 100.
afterstring (uuid)
The next value of the previous page.

{
  "from": "anna@example.com",
  "receivedFrom": "2026-09-15T00:00:00+02:00",
  "limit": 20
}

Responses

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

messagesarray of objectrequired
- inboundMessageIdstring (uuid)required
- streamIdstring (uuid)required
  The inbound stream that received it.
- receivedAtstring (date-time)required
  When the message was accepted from the sending server.
- envelopeRecipientstringrequired
  The address of yours the message was sent to.
- mailboxHashstring or nullrequired
  The text after the plus sign in that address, when the sender used one.
- sizeBytesintegerrequired
- attachmentCountintegerrequired
- hasTextbooleanrequired
- hasHtmlbooleanrequired
- parseIssuestring or nullrequired
  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.
- authenticationobjectrequired
  What Sendora found when it checked the message; unchecked until the checks have run.
  - spf"pass" | "fail" | "softfail" | "neutral" | "none" | "temperror" | "permerror" | "unchecked"required
    SPF for the address in MAIL FROM.
  - spfHelo"pass" | "fail" | "softfail" | "neutral" | "none" | "temperror" | "permerror" | "unchecked"required
    SPF for the name the sending server gave in HELO.
  - dkim"pass" | "fail" | "none" | "temperror" | "permerror" | "unchecked"required
  - dmarc"pass" | "fail" | "none" | "temperror" | "permerror" | "unchecked"required
  - dmarcPolicy"none" | "quarantine" | "reject" or nullrequired
    What the sender’s domain asks for; told only when DMARC failed.
  - arc"none" | "pass" | "fail" | "unchecked"required
  - checkedAtstring (date-time) or nullrequired
    When the checks ran; null until they have.
- contentAvailablebooleanrequired
  False once the stream’s content window has passed; only the reference remains.
- contentExpiresAtstring (date-time)required
  When the content goes.
- fromobject or nullrequired
  The From header; null without it or once the content is gone.
  - addressstringrequired
  - namestring or nullrequired
- subjectstring or nullrequired
- datestring (date-time) or nullrequired
  The sender’s Date header as ISO 8601, when it was a real moment.
nextstring (uuid) or nullrequired
Pass as after for the next page; null on the last.

Example (34 lines)

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

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.
`stream_not_found`	422	The streamId names no stream of this server.

`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"
    }
  ]
}