Delivery, History & Stats

Track the lifecycle of individual emails, search your send history, and pull aggregate delivery/engagement stats — three related endpoints under /v1/email.

GET

/v1/email/status/:messageId

Request Parameters

Parameter	Type	Description
messageId	Path	The unique ID returned when the email was sent

Response

JSON

{
  "success": true,
  "data": {
    "messageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "from": "noreply@yourdomain.com",
    "to": ["user@example.com"],
    "subject": "Welcome to Sendexa!",
    "status": "DELIVERED",
    "provider": "postfix",
    "providerMessageId": "<a1b2c3d4-e5f6@sendexa.co>",
    "sentAt": "2026-07-18T10:30:00.000Z",
    "deliveredAt": "2026-07-18T10:30:02.000Z",
    "openedAt": null,
    "clickedAt": null,
    "bouncedAt": null,
    "bounceType": null,
    "errorCode": null,
    "errorMessage": null,
    "cost": 0.0001,
    "tags": ["onboarding"],
    "createdAt": "2026-07-18T10:30:00.000Z"
  }
}

provider reflects how the message was actually delivered: postfix(Sendexa's own mail node) or postfix-smtp if it was submitted via SMTP relay rather than this REST API.

Status Types

queued

Email is in our processing queue

delivered

Successfully delivered to recipient's inbox

bounced

Hard bounce (invalid address or rejected)

deferred

Soft bounce, retrying delivery

opened

Recipient opened the email

clicked

Recipient clicked a link in the email

spam

Recipient marked email as spam

Pro Tip: Webhooks

While you can poll this endpoint to check status, we highly recommend using Webhooks to receive real-time updates when an email's status changes.

GET

/v1/email/history

Search and paginate your full send history. All query parameters are optional.

Query param	Type	Description
status	string	Filter by status, e.g. DELIVERED, BOUNCED, FAILED
from	string	Filter by sender address (partial match)
to	string	Filter by exact recipient address
search	string	Matches subject, sender, message ID, or recipient
startDate / endDate	ISO date	Filter by createdAt range
limit	number	Max 100, default 50
offset	number	Pagination offset, default 0

JSON

{
  "success": true,
  "data": {
    "messages": [ /* array of message summaries, same shape as status above */ ],
    "total": 1842,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

GET

/v1/email/stats

All-time aggregate counters and computed rates for your account.

JSON

{
  "success": true,
  "data": {
    "total": 1842,
    "queued": 3,
    "sent": 1810,
    "delivered": 1795,
    "opened": 940,
    "clicked": 210,
    "bounced": 22,
    "failed": 7,
    "spam": 3,
    "deliveryRate": 99.17,
    "openRate": 52.36,
    "clickRate": 11.7,
    "bounceRate": 1.21,
    "complainRate": 0.17,
    "totalCost": 0.1842
  }
}

GET

/v1/email/metrics

Daily time-series for the last days (query param, default 15, max 90) — powers dashboard charts, but available to your own integrations too.

JSON

{
  "success": true,
  "data": {
    "days": 15,
    "series": [
      { "date": "2026-07-20", "sent": 120, "delivered": 118, "opened": 61, "clicked": 14, "bounced": 2, "failed": 0, "spam": 0 }
      /* ...one entry per day */
    ],
    "totals": {
      "sent": 1810, "delivered": 1795, "opened": 940, "clicked": 210,
      "bounced": 22, "failed": 7, "spam": 3,
      "deliveryRate": 99.17, "openRate": 52.36, "clickRate": 11.7,
      "bounceRate": 1.21, "complainRate": 0.17
    },
    "updatedAt": "2026-08-04T00:00:00.000Z"
  }
}