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

  1. 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).
  2. The email with status Verified (same place). Without it the route answers 503 ERR_EMAIL_SENDER_NOT_CONFIGURED and nothing is sent, even with credits.
  3. 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.

Endpoints

MethodEndpointPurposeCredit
POST/api/v1/email/sendSend a transactional email1 per send
GET/api/v1/email/healthDiagnostics: is the token's email verified?none
GET/api/v1/email/sends/:idStatus of a sendnone
GET/api/v1/email/sendsRecent sendsnone

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

FieldTypeRequiredNotes
tostring or string[]Yesup to 10 recipients per send
subjectstringYesup to 200 characters
htmlstringOne of the twoHTML body, up to 200,000 characters
textstringOne of the twoplain-text body, up to 20,000 characters
fromNamestringNosender display name (up to 80 characters). The address is always the email that owns the token

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.

MethodEndpointPurpose
GET/api/v1/email/sends/:idStatus and timeline of one send
GET/api/v1/email/sendsRecent 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

statusMeaning
acceptedaccepted by Sendeasy, no delivery event yet
senthanded to the recipient's mail server
delivery_delayedthe recipient's server deferred delivery (retried automatically)
delivereddelivered to the recipient's mail server
openedopened by the recipient
clickedthe recipient clicked a link
bouncedbounced (no such mailbox, full mailbox, blocked); the reason is in detail
complainedthe recipient marked it as spam
failedthe send failed before leaving
suppressednot sent: the address is blocked after previous bounces or complaints
canceledsend 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.

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'
ParameterNotes
statusone of the statuses in the table above
toonly sends to this recipient
since / untilrange by send date (ISO 8601)
pagepage, starting at 1
limititems 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_CREDITS before 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

HTTPerrorWhen it happens
400ERR_EMAIL_INVALID_BODYinvalid payload (missing to/subject, neither html nor text, no valid recipient)
400ERR_EMAIL_TOO_MANY_RECIPIENTSmore than 10 recipients in one send
401ERR_API_TOKEN_NOT_PROVIDED / ERR_API_TOKEN_INVALIDheader missing or token invalid/inactive
402ERR_NO_EMAIL_CREDITSproject has no email credits
400ERR_VALIDATIONinvalid filter when listing sends (the field is in params.field)
404ERR_EMAIL_SEND_NOT_FOUNDunknown send id, or one from another email/project
429ERR_PUBLIC_EMAIL_RATE_LIMITmore than 20 sends or 120 lookups per minute
502ERR_EMAIL_SEND_FAILEDprovider failure while sending (credit refunded)
502ERR_EMAIL_STATUS_UNAVAILABLEthe status of an older send could not be checked right now; try again
503ERR_EMAIL_SENDER_NOT_CONFIGUREDthe 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)
Tokenemail token (Channels → Email → Sending API)integration token bound to one email channel
Senderthe email that owns the tokenthe token's channel
Typical usetransactional emails from your own applicationper-channel integrations with bcc, inReplyTo, etc.

Custom integration details at /en/server/integracoes.

Essa informação foi útil?