API docs

Messages and batches

Look up the status of a message or a batch by its id.

GET/v1/messages/{id}

The status of one message. The message body is never returned.

curl https://api.wesend.mn/v1/messages/0b9c1a52-6f0e-4d8b-9a3c-2f1e5d7c8a90 \
  -H "Authorization: Bearer $WESEND_API_KEY"
Response200 OK
{
  "id": "0b9c1a52-6f0e-4d8b-9a3c-2f1e5d7c8a90",
  "status": "sent",
  "channel": "sms",
  "to": "99112233",
  "parts": 1,
  "rate_multiplier": 1,
  "credits": 80,
  "batch_id": null,
  "error": null,
  "sandbox": false,
  "created_at": "2026-10-06T08:15:30.000Z",
  "sent_at": "2026-10-06T08:15:31.000Z"
}

Response fields

idstring
The message id (UUID).
statusstring
queued, processing, sent or failed.
channelstring
sms or email.
tostring
The recipient: an 8-digit number or an email address.
partsinteger
Number of SMS parts. SMS only.
rate_multiplierinteger
The holiday rate multiplier. SMS only.
creditsinteger
Credits charged.
batch_idstring | null
The batch, if the message was part of one.
errorobject | null
For a failed message, an object with code and message.
sandboxboolean
true when it was sent with a sandbox key: nothing was delivered or charged.
created_atstring
When it was created, ISO 8601 (UTC).
sent_atstring | null
When it was sent.
deliveryobject | null
Email only. The latest report from the recipient's mail server: status, detail, refunded and updated_at. null until a report arrives.
delivered_atstring | null
Email only. When the recipient's mail server accepted it.
StatusMeaning
queuedWaiting in the queue.
processingBeing sent.
sentHanded to the operator or the email provider.
failedNot sent. The credits were refunded.

For SMS, sent means the operator accepted the message. Delivery reports from the handset are not available for SMS yet.

Email delivery

After an email is sent, the delivery field is updated as reports arrive from the recipient's mail server, usually within seconds. status stays sent.

Response200 OK
{
  "id": "0b9c1a52-6f0e-4d8b-9a3c-2f1e5d7c8a90",
  "status": "sent",
  "channel": "email",
  "to": "[email protected]",
  "credits": 10,
  "batch_id": null,
  "error": null,
  "sandbox": false,
  "created_at": "2026-10-06T08:15:30.000Z",
  "sent_at": "2026-10-06T08:15:31.000Z",
  "delivery": {
    "status": "delivered",
    "detail": null,
    "refunded": false,
    "updated_at": "2026-10-06T08:15:33.000Z"
  },
  "delivered_at": "2026-10-06T08:15:33.000Z"
}
`delivery.status`Meaning
deliveredThe recipient's mail server accepted it.
delayedThe server is not accepting it for now; delivery is being retried.
bouncedThe server refused it. The address may be wrong or inactive. detail gives the reason.
complainedThe recipient marked it as spam. We recommend not emailing this address again.
suppressedNot sent, because the address bounced or complained before. The credits are refunded.
failedThe email provider could not deliver it. The credits are refunded.
  • Reports can arrive out of order. delayed never replaces delivered, while a bounced or complained that follows a delivery replaces it.
  • A failed or suppressed email is refunded automatically and delivery.refunded becomes true. A bounced or complained email was sent, so it is not refunded.
  • No report says an email landed in the spam folder: one delivered there still reports delivered. complained means the recipient marked it as spam themselves.
  • An address that bounced for good (Permanent) or is suppressed is left out of promotions automatically.
  • When a project that sent over 200 emails in the last 7 days has 5% permanent bounces, or 0.1% marked as spam (at least 3), its sending pauses until WeSend staff review it, and sends answer 403 sending_paused.
  • Each message's delivery timeline is shown in the dashboard under Messages.

Batches

GET/v1/batches/{id}

The progress of a bulk send.

curl https://api.wesend.mn/v1/batches/5d2a7c1e-93b4-4f6a-8e0d-b1c2d3e4f5a6 \
  -H "Authorization: Bearer $WESEND_API_KEY"
Response200 OK
{
  "id": "5d2a7c1e-93b4-4f6a-8e0d-b1c2d3e4f5a6",
  "status": "completed",
  "channel": "sms",
  "total": 500,
  "sent": 497,
  "failed": 3,
  "credits": 40000,
  "sandbox": false,
  "created_at": "2026-10-06T08:15:30.000Z",
  "completed_at": "2026-10-06T08:19:02.000Z"
}

status is processing or completed. credits is the amount charged up front; each failed message has been refunded.