Mail API reference

Mail API · Outbound-Messages

get/v1/workspaces/{workspace_id}/messages/{id}Auth

Get a single outbound message (metadata + delivery verdicts; body not included) with its event timeline: `events[]` oldest first, `last_event`, `transport`, `bounce_type`, `bounce_subtype`. Use /:id/body for cleartext content.

Path parameters

workspace_id*string · uuid

Id of the workspace.

id*string · uuid

Id of the message.

Response · 200

id*string · uuid

The message id.

workspace_id*string · uuid

The workspace that sent the message.

domain_id*string · uuid

The sending domain (`domain.id`). Null for rows whose domain was deleted.

api_key_id*string · uuid

The Platform API Key that sent the message. Null for console, platform, MCP and test sends without a key, and unknown (null) for messages created before 2026-10-12.

Example: "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"

source*object

How the message was sent: `api_key`, `dashboard`, `platform` or `test_send`. Unknown for messages created before 2026-10-12, which all read `platform`.

Example: "api_key"

from_address*string

The sender address.

to_address*string

The recipient address.

subject*string

Subject line; null when the message has none.

template_name*string

Template the message was rendered from; null for a raw send.

status*object

Delivery status of the message.

smtp_transcript*string

SMTP conversation with the receiving server; null when not recorded.

spf_result*string

SPF result reported for the delivery; null when unknown.

dkim_result*string

DKIM result reported for the delivery; null when unknown.

dmarc_result*string

DMARC result reported for the delivery; null when unknown.

bounce_code*string

SMTP status code of a bounce; null when the message did not bounce.

bounce_detail*string

Diagnostic text of a bounce; null when the message did not bounce.

bounce_type*object

Bounce type, when the message bounced or was deferred: `Permanent`, `Transient` or `Undetermined`. `Permanent` adds the recipient to the suppression list.

Example: "Permanent"

bounce_subtype*string

Bounce subtype, e.g. `General`, `NoEmail`, `Suppressed`, `MailboxFull`.

Example: "General"

transport*object

How the message was sent: `ses` (delivery tracking: delivery, bounces and complaints reported) or `smtp` (sent before delivery tracking started or through a custom SMTP relay: hand-off confirmed, delivery not measurable). Null until the send is acknowledged.

Example: "ses"

created_at*string · date-time

When the message was accepted for delivery.

sent_at*string · date-time

When the message was handed off for delivery. This is the fact the send path actually establishes.

delivered_at*string · date-time

When the message was confirmed delivered to the recipient. Null unless there is recipient-side evidence — a hand-off is not delivery.

deferred_at*string · date-time

Most recent deferral. Set when the destination refused to take the message for now and delivery is still being retried.

deferral_count*number

How many times a destination has refused to take this message. The count is the operator-legible number, not the flag: one greylist is noise, a dozen on the same recipient is a reputation block.

Example: 0

email_id*string · uuid

The email (`POST /emails` or a template send) this message belongs to: one email, one message per recipient (`GET /emails/{id}`). Null for messages sent before 2026-11-06.

cc*array

The email's Cc list, as sent; null when none.

bcc*array

The email's Bcc list, as sent; null when none.

reply_to*array

The email's Reply-To list, as sent; null when none.

tags*array

The email's tags (`[{ name, value }]`); null when none.

events*array

Every recorded transition, oldest first (at most 200).

last_event*object

The most recent event, or null for a row that predates event recording.

Example

Request

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

Response

{
  "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"
    }
  ],
  "events": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "delivered",
      "occurred_at": "2026-01-01T00:00:00.000Z",
      "detail": {
        "source": "ses",
        "smtp_response": "250 2.0.0 OK",
        "remote_mta": "203.0.113.7"
      }
    }
  ],
  "last_event": {}
}