Email Activity

Query your sent email history programmatically. List messages with filtering, search, pagination, and delivery events.

Retrieve and inspect your sent email history, including delivery and engagement events.

Authentication

All requests require an API key passed as a Bearer token.

Authorization: Bearer pm_live_xxxxx

List Messages

GET https://api.xmit.sh/api/messages
Authorization: Bearer YOUR_API_KEY

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Results per page (1-1000)
`offset`	integer	0	Number of results to skip
`type`	string	-	Filter by `transactional` or `campaign`
`status`	string	-	Filter by status (see below)
`q`	string	-	Search by recipient email or subject
`includeEvents`	boolean	false	Attach delivery/engagement events to each message

Status values: queued, sent, delivered, bounced, complained, failed

Example Request

curl https://api.xmit.sh/api/messages?type=transactional&limit=25&includeEvents=true \
  -H "Authorization: Bearer pm_live_xxxxx"

Response

{
  "messages": [
    {
      "id": "msg_1a2b3c4d5e6f",
      "type": "transactional",
      "status": "delivered",
      "recipientEmail": "user@example.com",
      "subject": "Welcome to YourApp",
      "senderId": "snd_xxxxx",
      "campaignId": null,
      "contactId": null,
      "errorMessage": null,
      "metadata": { "userId": "usr_123" },
      "recipientCount": 1,
      "queuedAt": "1708905600000",
      "sentAt": "1708905601000",
      "deliveredAt": "1708905602000",
      "bouncedAt": null,
      "events": [
        {
          "id": "evt_yyyyy",
          "eventType": "delivered",
          "metadata": null,
          "createdAt": "1708905602000",
          "recipientId": null,
          "recipientEmail": null
        },
        {
          "id": "evt_zzzzz",
          "eventType": "open",
          "metadata": { "userAgent": "Mozilla/5.0..." },
          "createdAt": "1708906200000",
          "recipientId": null,
          "recipientEmail": null
        }
      ]
    }
  ],
  "totalCount": 142,
  "limit": 25,
  "offset": 0
}

Field	Description
`recipientCount`	Total number of recipients (to + cc + bcc). `1` for single-recipient sends.
`events[].recipientId`	ID of the specific recipient this event applies to. `null` for single-recipient sends and for open/click events.
`events[].recipientEmail`	Email of the specific recipient. `null` when `recipientId` is null.

The events array is only included when includeEvents=true. Event types include: delivered, bounce, complaint, open, click, reject. The metadata field contains only the custom metadata you passed when sending the email.

Pagination

Use totalCount with limit and offset to paginate through results.

# Page 1
curl "https://api.xmit.sh/api/messages?limit=25&offset=0" \
  -H "Authorization: Bearer pm_live_xxxxx"

# Page 2
curl "https://api.xmit.sh/api/messages?limit=25&offset=25" \
  -H "Authorization: Bearer pm_live_xxxxx"

Search and Filter

Combine q, type, and status to narrow results.

# Find failed transactional emails to a specific domain
curl "https://api.xmit.sh/api/messages?type=transactional&status=failed&q=example.com" \
  -H "Authorization: Bearer pm_live_xxxxx"

Get Message

Retrieve a single message by ID.

GET https://api.xmit.sh/api/messages/:id
Authorization: Bearer YOUR_API_KEY

Example Request

curl https://api.xmit.sh/api/messages/msg_1a2b3c4d5e6f \
  -H "Authorization: Bearer pm_live_xxxxx"

Response

Returns the full message object with events and per-recipient breakdown.

{
  "id": "msg_1a2b3c4d5e6f",
  "type": "transactional",
  "status": "delivered",
  "recipientEmail": "user@example.com",
  "subject": "Welcome to YourApp",
  "senderId": "snd_xxxxx",
  "campaignId": null,
  "contactId": null,
  "errorMessage": null,
  "metadata": { "userId": "usr_123" },
  "recipientCount": 3,
  "queuedAt": "1708905600000",
  "sentAt": "1708905601000",
  "deliveredAt": "1708905602000",
  "bouncedAt": null,
  "events": [
    {
      "id": "evt_xxxxx",
      "eventType": "delivered",
      "metadata": null,
      "createdAt": "1708905602000",
      "recipientId": "mrc_aaaaa",
      "recipientEmail": "user@example.com"
    },
    {
      "id": "evt_yyyyy",
      "eventType": "bounce",
      "metadata": null,
      "createdAt": "1708905603000",
      "recipientId": "mrc_bbbbb",
      "recipientEmail": "cc-user@example.com"
    }
  ],
  "recipients": [
    {
      "id": "mrc_aaaaa",
      "email": "user@example.com",
      "type": "to",
      "status": "delivered",
      "deliveredAt": "1708905602000",
      "bouncedAt": null
    },
    {
      "id": "mrc_bbbbb",
      "email": "cc-user@example.com",
      "type": "cc",
      "status": "bounced",
      "deliveredAt": null,
      "bouncedAt": "1708905603000"
    },
    {
      "id": "mrc_ccccc",
      "email": "bcc-user@example.com",
      "type": "bcc",
      "status": "delivered",
      "deliveredAt": "1708905602500",
      "bouncedAt": null
    }
  ]
}

Multi-Recipient Tracking

When you send an email with cc or bcc recipients, the single message response includes a recipients array with per-recipient delivery status.

Field	Type	Description
`recipients[].id`	string	Unique recipient tracking ID (`mrc_xxxxx`)
`recipients[].email`	string	Recipient email address
`recipients[].type`	string	`to`, `cc`, or `bcc`
`recipients[].status`	string	`sent`, `delivered`, `bounced`, or `complained`
`recipients[].deliveredAt`	string\|null	Delivery timestamp
`recipients[].bouncedAt`	string\|null	Bounce timestamp

The parent message status reflects the worst status across all recipients: complained > bounced > delivered > sent.

The recipients array is only present for multi-recipient sends. Single-recipient messages skip this table entirely for zero overhead.

Tracking limitations: Delivery, bounce, complaint, and reject events are tracked per-recipient. Open and click events are tracked at the message level only, because SES uses a shared tracking pixel and shared link rewrites across all recipients of the same send.

Error Codes

Status	Meaning
200	Success
401	Invalid or missing API key
403	Endpoint not accessible with this API key
404	Message not found

Send Email - Send transactional emails via API
Webhooks - Receive real-time delivery notifications
Campaigns - Send marketing emails

On this page