Mail API reference

Mail API · Outbound-Messages

get/v1/workspaces/{workspace_id}/messagesAuth

List outbound messages with cursor pagination

One row per recipient delivery, newest first. Filters combine with AND: `q` (free text over recipient, from, subject, message id and Message-ID), `status` (any of, repeatable), `domain_id`, `api_key_id`, `source`, `template`, `created_after` / `created_before` (at most 30 days apart), plus the legacy `recipient` and `subject_contains`. `GET /messages/export` takes exactly the same filters and returns the same rows.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Query parameters

qstring

Free-text search, case-insensitive. Matches a substring of the recipient, the from address or the subject, or exactly a message id (uuid) or a Message-ID (the provider message id, with or without its `<…@…>` domain).

statusarray

Only messages in any of these statuses. Repeat the parameter (`status=bounced&status=complained`), use the bracket form (`status[]=bounced&status[]=complained`) or comma-separate the values (`status=bounced,complained`); a single value is the original single-status filter.

domain_idstring · uuid

Only messages sent from this domain (`domain.id`).

api_key_idstring · uuid

Only messages sent with this Platform API Key. Recorded from 2026-10-12; older messages have no key.

sourceenum (4)

How the message was sent: `api_key` (a Platform API Key), `dashboard` (a signed-in person, in the console or through MCP), `platform` (in-cluster product mail), `test_send` (a template test send). Recorded from 2026-10-12; older messages all read `platform`.

templatestring

Filter by template name.

created_afterstring · date-time

Only messages created at or after this instant. With `created_before`, the window may span at most 30 days (the log retention).

created_beforestring · date-time

Only messages created before this instant. Without `created_after`, the window is the 30 days before it.

recipientstring

Legacy: filter by exact recipient address. Prefer `q`.

subject_containsstring

Legacy: substring filter on subject (case-insensitive, max 200 chars). Prefer `q`.

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 messages on this page, newest first.

pagination*object
has_more*boolean

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

next_cursor*string

Opaque cursor for the next page; null when no more pages.

Example

Request

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

Response

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "workspace_id": "00000000-0000-0000-0000-000000000000",
      "domain_id": "00000000-0000-0000-0000-000000000000",
      "api_key_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "source": "api_key",
      "from_address": "string",
      "to_address": "string",
      "subject": "string",
      "template_name": "string",
      "status": {},
      "smtp_transcript": "string",
      "spf_result": "string",
      "dkim_result": "string",
      "dmarc_result": "string",
      "bounce_code": "string",
      "bounce_detail": "string",
      "bounce_type": "Permanent",
      "bounce_subtype": "General",
      "transport": "ses",
      "created_at": "2026-01-01T00:00:00.000Z",
      "sent_at": "2026-01-01T00:00:00.000Z",
      "delivered_at": "2026-01-01T00:00:00.000Z",
      "deferred_at": "2026-01-01T00:00:00.000Z",
      "deferral_count": 0,
      "email_id": "00000000-0000-0000-0000-000000000000",
      "cc": [
        "string"
      ],
      "bcc": [
        "string"
      ],
      "reply_to": [
        "string"
      ],
      "tags": [
        {
          "name": "category",
          "value": "confirm_email"
        }
      ]
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": "string"
  }
}