List Received Emails

List inbound email rows stored for the authenticated OpenSend tenant.

GET /emails/receiving

Compatibility note: GET /api/emails/receiving remains available for existing OpenSend integrations; new API clients can use the root compatibility path above. Browser dashboard navigation is preserved for page routes that share these names.

Authentication

Use an OpenSend API key in the Authorization header. The API key must belong to a tenant; dashboard session cookies are not API credentials for public API calls.

http

Authorization: Bearer os_YOUR_API_KEY

Query parameters

Name	Type	Description
`limit`	number	Number of rows to return. Values are clamped from `1` to `100`; default is `20`.
`after`	string	Cursor for older rows. OpenSend compares against received-email IDs and returns rows after that cursor in descending order.
`to`	string	Optional recipient address filter. OpenSend normalizes whitespace and case before querying the recipient array.

Response

json

{
  "object": "list",
  "data": [
    {
      "id": "6f6f8b7e-534f-4b62-b0c1-64b79e45f3c2",
      "from": "support@example.com",
      "to": ["agent@inbound.example.com"],
      "subject": "New support request",
      "route_decisions": [
        {
          "recipient": "agent@inbound.example.com",
          "status": "exact",
          "routeId": "22222222-2222-4222-8222-222222222222",
          "routeType": "exact",
          "targetAddress": "agent@inbound.example.com"
        }
      ],
      "reply_match_status": "unmatched",
      "thread_id": null,
      "reply_to_email_id": null,
      "contact_id": null,
      "created_at": "2026-05-10T00:00:00.000Z"
    }
  ],
  "has_more": false
}

Rows are scoped to the owner of the API key. route_decisions is an empty array for legacy rows inserted before route audit metadata existed. reply_match_status is matched when the ingester validated a tenant/domain-scoped reply token and linked the message to an outbound email thread; otherwise it is unmatched. Empty lists are returned as 200 responses with data: [].

Self-hosting notes

Hosted OpenSend provisions SES receipt rules when receiving is enabled for a domain, then writes received_emails after the ingester resolves the recipient to one tenant and stores attachments through the storage abstraction. Self-hosted deployments should set SES_INBOUND_SNS_TOPIC_ARN and S3_BUCKET_NAME or SES_INBOUND_BUCKET_NAME, subscribe the inbound SNS topic to /events/inbound/ses-s3, and add the MX records shown in the dashboard.