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" },
      "queuedAt": "1708905600000",
      "sentAt": "1708905601000",
      "deliveredAt": "1708905602000",
      "bouncedAt": null,
      "events": [
        {
          "id": "evt_yyyyy",
          "eventType": "delivered",
          "metadata": null,
          "createdAt": "1708905602000"
        },
        {
          "id": "evt_zzzzz",
          "eventType": "open",
          "metadata": { "userAgent": "Mozilla/5.0..." },
          "createdAt": "1708906200000"
        }
      ]
    }
  ],
  "totalCount": 142,
  "limit": 25,
  "offset": 0
}

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 always included.

{
  "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" },
  "queuedAt": "1708905600000",
  "sentAt": "1708905601000",
  "deliveredAt": "1708905602000",
  "bouncedAt": null,
  "events": [
    {
      "id": "evt_xxxxx",
      "eventType": "delivered",
      "metadata": null,
      "createdAt": "1708905602000"
    }
  ]
}

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

Email Activity

On this page