Email API
Send transactional emails (password reset, notices, confirmations) through Sendeasy from your own application, authenticated by the token of the email itself — every email configured in the project has its own.
Messages go out from the email that owns the token and consume 1 email credit of the project. You never pass the sender: it is the token's email. Have more than one email? Use the token of the one you want to send from.
Prerequisites
- Email token — in Channels → Email (or on the email card in Channels) → Settings → Sending API section. Each email has its own token; you can also generate a new one there (the previous one stops working immediately).
- The email with status Verified (same place). Without it the route answers
503 ERR_EMAIL_SENDER_NOT_CONFIGUREDand nothing is sent, even with credits. - Email credits available in the project plan.
Use GET /api/v1/email/health to check items 1 and 2 without spending credits.
Authentication
Required header, with the sender email's token:
Authorization: Bearer <email_token>
The token identifies the sender email and, through it, the project — there is no whatsappId/emailId in the URL.
Compatibility: the project API Token (the WABA API one) is also accepted in this header. In that case the sender is the project's first verified email — handy for integrations built before per-email tokens, but to choose the sender use the email token.
Endpoints
| Method | Endpoint | Purpose | Credit |
|---|---|---|---|
POST | /api/v1/email/send | Send a transactional email | 1 per send |
GET | /api/v1/email/health | Diagnostics: is the token's email verified? | none |
GET | /api/v1/email/sends/:id | Status of a send | none |
GET | /api/v1/email/sends | Recent sends | none |
Rate limit: 20 sends per minute per origin (429 ERR_PUBLIC_EMAIL_RATE_LIMIT). Status lookups have their own limit of 120 per minute.
Sending an email
POST /api/v1/email/send
Payload
| Field | Type | Required | Notes |
|---|---|---|---|
to | string or string[] | Yes | up to 10 recipients per send |
subject | string | Yes | up to 200 characters |
html | string | One of the two | HTML body, up to 200,000 characters |
text | string | One of the two | plain-text body, up to 20,000 characters |
fromName | string | No | sender display name (up to 80 characters). The address is always the email that owns the token |
The sender address (fromEmail) is not accepted in the payload: the route always uses the email that owns the token. This prevents a token from sending on behalf of an email that is not yours.
Example
curl --location 'https://backend.sendeasy.app/api/v1/email/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer EMAIL_TOKEN' \
--data '{
"to": "customer@example.com",
"subject": "Password reset",
"fromName": "My Platform",
"html": "<p>Hi! Click the link below to create a new password.</p>"
}'
Success response:
{
"success": true,
"id": "9fbbb3a9-4c1e-4b1a-9d1e-0c2b7e3f5a61"
}
Keep the id: it is how you follow delivery in GET /api/v1/email/sends/:id. The response confirms the email was accepted for delivery; final delivery depends on the recipient's mail server.
Integration diagnostics
GET /api/v1/email/health
Does not consume credits. Tells whether the token's email is already verified — the most common reason a send fails even with credits available.
curl --location 'https://backend.sendeasy.app/api/v1/email/health' \
--header 'Authorization: Bearer EMAIL_TOKEN'
{
"ok": true,
"senderConfigured": true,
"sender": "no-reply@yourcompany.com",
"domain": "yourcompany.com",
"channelId": 12
}
With senderConfigured: false, finish verifying the email in Channels → Email before sending. (With the project API Token the response has no channelId and tells whether the project has any verified email.)
Send status
Every accepted send is recorded with its current status and the timeline of delivery events. Look it up by the id returned when sending, or list recent sends. Lookups do not consume credits.
| Method | Endpoint | Purpose |
|---|---|---|
GET | /api/v1/email/sends/:id | Status and timeline of one send |
GET | /api/v1/email/sends | Recent sends, newest first |
With an email token you see the sends of that email; with the project API Token, those of every email in the project. Lookup limit: 120 requests per minute per origin, separate from the sending limit.
Statuses
status | Meaning |
|---|---|
accepted | accepted by Sendeasy, no delivery event yet |
sent | handed to the recipient's mail server |
delivery_delayed | the recipient's server deferred delivery (retried automatically) |
delivered | delivered to the recipient's mail server |
opened | opened by the recipient |
clicked | the recipient clicked a link |
bounced | bounced (no such mailbox, full mailbox, blocked); the reason is in detail |
complained | the recipient marked it as spam |
failed | the send failed before leaving |
suppressed | not sent: the address is blocked after previous bounces or complaints |
canceled | send canceled |
The status only moves forward: events that arrive out of order (opened before delivered) never move it back, and bounced/complained take precedence over the others.
opened and clicked require open and click tracking to be enabled for the domain. Without it, the last status of a delivered email is delivered.
Look up a send
curl --location 'https://backend.sendeasy.app/api/v1/email/sends/9fbbb3a9-4c1e-4b1a-9d1e-0c2b7e3f5a61' \
--header 'Authorization: Bearer EMAIL_TOKEN'
{
"id": "9fbbb3a9-4c1e-4b1a-9d1e-0c2b7e3f5a61",
"status": "bounced",
"from": "no-reply@yourcompany.com",
"to": ["customer@example.com"],
"subject": "Password reset",
"createdAt": "2026-11-17T14:02:11.000Z",
"lastEventAt": "2026-11-17T14:02:14.000Z",
"events": [
{ "status": "sent", "at": "2026-11-17T14:02:12.000Z", "detail": null },
{
"status": "bounced",
"at": "2026-11-17T14:02:14.000Z",
"detail": { "type": "Permanent", "subType": "General", "message": "The recipient's mailbox does not exist." }
}
]
}
Sends made before this record existed can also be looked up by id: the response then carries the current status, without the timeline.
List sends
curl --location 'https://backend.sendeasy.app/api/v1/email/sends?status=bounced&since=2026-11-01' \
--header 'Authorization: Bearer EMAIL_TOKEN'
| Parameter | Notes |
|---|---|
status | one of the statuses in the table above |
to | only sends to this recipient |
since / until | range by send date (ISO 8601) |
page | page, starting at 1 |
limit | items per page, up to 100 (default 50) |
{ "sends": [ { "id": "9fbbb3a9-...", "status": "bounced", "...": "..." } ], "count": 1, "page": 1, "hasMore": false }
In the console
The same sends show up in Channels → Email → Settings → Sending API → API sends, with a status filter and each send's timeline.
Status webhook
If the project has a webhook configured (under Integrations), every event of an API send arrives as the message_status event, with channel: "email":
{
"event": "message_status",
"channel": "email",
"channelId": "email-channel-uuid",
"data": {
"messageId": "9fbbb3a9-4c1e-4b1a-9d1e-0c2b7e3f5a61",
"status": "delivered",
"currentStatus": "delivered",
"timestamp": "2026-11-17T14:02:13.000Z",
"to": ["customer@example.com"],
"subject": "Password reset",
"detail": null
}
}
status is the event that just arrived; currentStatus is the send's status after it.
Credits and refunds
- Every accepted send debits 1 email credit from the project.
- With no credits, the route answers
402 ERR_NO_EMAIL_CREDITSbefore any debit. - If the send fails after the debit (sender not configured, provider unavailable), the credit is refunded automatically and the route answers
502/503.
Error codes
| HTTP | error | When it happens |
|---|---|---|
| 400 | ERR_EMAIL_INVALID_BODY | invalid payload (missing to/subject, neither html nor text, no valid recipient) |
| 400 | ERR_EMAIL_TOO_MANY_RECIPIENTS | more than 10 recipients in one send |
| 401 | ERR_API_TOKEN_NOT_PROVIDED / ERR_API_TOKEN_INVALID | header missing or token invalid/inactive |
| 402 | ERR_NO_EMAIL_CREDITS | project has no email credits |
| 400 | ERR_VALIDATION | invalid filter when listing sends (the field is in params.field) |
| 404 | ERR_EMAIL_SEND_NOT_FOUND | unknown send id, or one from another email/project |
| 429 | ERR_PUBLIC_EMAIL_RATE_LIMIT | more than 20 sends or 120 lookups per minute |
| 502 | ERR_EMAIL_SEND_FAILED | provider failure while sending (credit refunded) |
| 502 | ERR_EMAIL_STATUS_UNAVAILABLE | the status of an older send could not be checked right now; try again |
| 503 | ERR_EMAIL_SENDER_NOT_CONFIGURED | the token's email is not verified yet (with an email token, before any debit) |
Email API vs. Custom integration
Sendeasy offers two ways to send email by API — pick by the kind of token you have:
Email API (/api/v1/email/send) | Custom (/api/integration/generic) | |
|---|---|---|
| Token | email token (Channels → Email → Sending API) | integration token bound to one email channel |
| Sender | the email that owns the token | the token's channel |
| Typical use | transactional emails from your own application | per-channel integrations with bcc, inReplyTo, etc. |
Custom integration details at /en/server/integracoes.
Security: treat the token like a password. Never embed it in browser JavaScript, public repositories or logs — keep it in environment variables or a secret manager on your server.