Mail API reference

Mail API · Received

get/v1/workspaces/{workspace_id}/receivedAuth

List received email across every mailbox in the workspace

Newest first, cursor-paged, deleted email excluded. Filters combine with AND: `q` (sender, subject, envelope recipient or To address as a substring; or an exact id or Message-ID), `mailbox_id`, `domain_id`, `received_after` / `received_before` (at most 30 days apart), `spam`, `unread`. `GET /received/export` takes exactly the same filters and returns the same rows. No body content.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Query parameters

qstring

Free-text search, case-insensitive. Matches a substring of the sender, the subject, the envelope recipient or a To address, or exactly a received email id (uuid) or its RFC 822 Message-ID (with or without the angle brackets).

mailbox_idstring · uuid

Only email received by this mailbox.

domain_idstring · uuid

Only email received by mailboxes on this domain (`domain.id`).

received_afterstring · date-time

Only email received at or after this instant. With `received_before`, the window may span at most 30 days.

received_beforestring · date-time

Only email received before this instant. Without `received_after`, the window is the 30 days before it.

spamboolean

`true`: only email the spam filter quarantined (verdict `junk` or `reject`). `false`: only email it did not. Omit for both.

unreadboolean

`true`: only unread email. `false`: only email already marked read. Omit for both.

limitinteger

Page size, 1–100

cursorstring

Opaque cursor from the previous page's `pagination.next_cursor`. Omit for the first page.

Response · 200

data*array

The received emails on this page, newest first.

pagination*object
next_cursor*string

Opaque cursor for the next page. `null` when no more pages are available.

Example: "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0wMVQwMDowMDowMFoifQ"

has_more*boolean

True iff another page exists; if true, pass `next_cursor` on the next request.

Example: false

Example

Request

GET https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/received
Authorization: Bearer YOUR_TOKEN

Response

{
  "data": [
    {
      "id": "7d9c1e2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a",
      "mailbox_id": "00000000-0000-0000-0000-000000000000",
      "mailbox_address": "support@in.example.com",
      "from": "jane@example.org",
      "to": [
        "support@in.example.com"
      ],
      "cc": [],
      "subject": "Invoice #42",
      "rfc822_message_id": "<CAF1234@mail.gmail.com>",
      "received_at": "2026-01-01T00:00:00.000Z",
      "read_at": "2026-01-01T00:00:00.000Z",
      "spam_verdict": "ham",
      "spam": false,
      "spf_result": "pass",
      "dkim_result": "pass",
      "dmarc_result": "pass",
      "size_bytes": 5120,
      "attachment_count": 1
    }
  ],
  "pagination": {
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0wMVQwMDowMDowMFoifQ",
    "has_more": false
  }
}