Inbound

List and read mail received at your own domain, with its authentication verdict, and manage the addresses that accept it.

Every endpoint here needs a full-access API key. A sending key is for putting mail on the wire; reading a mailbox is a different power.

List received messages

GET /v1/inbound

Newest first. Metadata only - fetch one message for its body.

curl "https://api.sendpository.com/v1/inbound?limit=20&status=received" \
  -H "Authorization: Bearer $SENDPOSITORY_API_KEY"

Parameter	Meaning
`limit`, `offset`	Page through the list.
`status`	`received` or `spam`.
`address`	Only mail to this receiving address.
`received_after`, `received_before`	ISO 8601 timestamps.

{
  "data": [
    {
      "id": "9f1c7d4e-2b1a-4f3c-9d55-0a1b2c3d4e5f",
      "from": "customer@example.com",
      "to": "support@sp.yourdomain.com",
      "subject": "Invoice question",
      "status": "received",
      "spam_score": 0.1,
      "size_bytes": 18422,
      "received_at": "2026-09-16T09:12:03.000Z"
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 1
}

Read one message

GET /v1/inbound/:id

The whole message, with both bodies.

{
  "id": "9f1c7d4e-2b1a-4f3c-9d55-0a1b2c3d4e5f",
  "from": "customer@example.com",
  "from_name": "Priya",
  "to": ["support@sp.yourdomain.com"],
  "cc": [],
  "recipient": "support@sp.yourdomain.com",
  "subject": "Invoice question",
  "text": "Hi - could you resend invoice SENT/2026-27/0184?",
  "html": "<p>Hi - could you resend invoice SENT/2026-27/0184?</p>",
  "attachments": [{ "filename": "invoice.pdf", "contentType": "application/pdf", "size": 48122 }],
  "status": "received",
  "spam_status": "NotSpam",
  "sender_verdict": "verified",
  "auth": { "spf": "pass", "dkim": "pass", "dmarc": "pass", "spf_domain": "example.com", "dkim_domain": "example.com" },
  "size_bytes": 18422,
  "message_id": "<CAJ8s...@mail.example.com>",
  "received_at": "2026-09-16T09:12:03.000Z"
}

sender_verdict is verified, failed, unverified or unchecked - see Is the sender real?. auth is absent when the message was not checked.

An id from another account returns not_found, never somebody else's mail.

List receiving addresses

GET /v1/inbound/addresses

{
  "data": [
    {
      "id": "6d1f...",
      "address": "support@sp.yourdomain.com",
      "domain": "yourdomain.com",
      "host": "sp.yourdomain.com",
      "local_part": "support",
      "status": "active",
      "created_at": "2026-09-16T08:00:00.000Z"
    }
  ]
}

Add a receiving address

POST /v1/inbound/addresses

host defaults to the domain's receiving host.

curl -X POST https://api.sendpository.com/v1/inbound/addresses \
  -H "Authorization: Bearer $SENDPOSITORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain_id": "d0e78a7b-...", "local_part": "support" }'

{
  "id": "6d1f...",
  "address": "support@sp.yourdomain.com",
  "status": "active"
}

A pending status comes back with the dns_record to publish, and the reason it is not receiving yet. local_part may be * for a catch-all.

Once the account has as many receiving addresses as its plan allows, this returns permission_denied. Remove an address, or upgrade, to add another.

Remove a receiving address

DELETE /v1/inbound/addresses/:id

Stops accepting mail. Messages already received are kept.

{ "id": "6d1f...", "address": "support@sp.yourdomain.com", "deleted": true }