Sending email
Send an email with one POST to /emails. Ponitor answers straight away with the email, already charged and queued. What happens to it next comes by webhook, or when you look it up.
You need
- An API key with the Messaging API turned on. See API keys and base URLs.
- A verified domain with a sender on it. See Connecting a domain.
- A template, and its handle. See Templates.
Send the email
curl -X POST $PONITOR_BASE_URL/messaging/v1/emails \
-H "apiKey: $PONITOR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "ada@example.com",
"template": "verification-code",
"values": { "first_name": "Ada", "code": "482913", "expires_in": "10 minutes" },
"externalId": "signup-8812"
}'
For a template whose subject is {{code}} is your {{brand_name}} code, Ada's inbox shows 482913 is your Acme code. {{brand_name}} is your brand's name, so you don't send it.
| Field | What to send |
|---|---|
to | The one address to send to. |
template | The template's handle, such as verification-code. |
values | A value for each of the template's {{variables}}, by name, as text. Leave it out if the template has none. |
from | The address of one of your senders, such as billing@mail.example.com. Leave it out to send from your default sender. |
externalId | Your own reference, such as a sign-up number. Up to 64 characters, unique among your team's emails. See Retries and externalId. |
Every field is described in Send an email.
Read the response
201 Created means the email is charged and queued:
{
"email": {
"id": "3f0e8a52-6f4b-4d0e-9b8a-2c1d0e9f8a7b",
"externalId": "signup-8812",
"from": "\"Acme\" <hello@mail.example.com>",
"to": "ada@example.com",
"subject": "482913 is your Acme code",
"templateName": "Verification Code",
"status": "QUEUED",
"cost": 0.002,
"refunded": false,
"failureReason": null,
"createdAt": "2026-11-07T09:30:00.112Z",
"sentAt": null
}
}
Store the id. Webhooks and Get an email use it. Most emails are SENT within seconds and DELIVERED within a minute. See Delivery statuses.
200 OK instead means you already used this externalId. The body is the first email, with its status now. Nothing new was sent or charged, even if the rest of the request is different.
Emails keep their own list of externalIds, apart from SMS and WhatsApp messages. An externalId you used on an SMS can be used again on an email.
Look an email up
curl $PONITOR_BASE_URL/messaging/v1/emails/3f0e8a52-6f4b-4d0e-9b8a-2c1d0e9f8a7b \
-H "apiKey: $PONITOR_API_KEY"
You get the email with its status now, and its events: everything that happened to it, oldest first. A bounce or a failure says why in its event's detail. See Get an email.
Use it for a one-off check, not in a loop. A webhook tells you as each thing happens.
Charges and refunds
- Ponitor charges your team's price for an email when it accepts the request. The email's
costsays what it was. A refused request is never charged. - If an email can't go out, Ponitor tries again for about five minutes. If it still can't, the email ends as
FAILED, its cost goes back to your balance, andrefundedistrue. - An email that was sent and then
BOUNCEDisn't refunded. The address doesn't exist or wouldn't take it. - Emails are paid from your team's balance, never a workspace's.
When a send is refused
| Status | Why | Fix |
|---|---|---|
400 | A field is missing or invalid (E01001). The body has details, one per problem. | Fix the request, and send it with the same externalId. |
400 | A variable the template uses has no value, such as Give a value for {{code}}. (E01002) | Add it to values. |
400 | You have no default sender, the sender's domain isn't verified, or the request names a workspace (E01002). The message says which. | Check your senders under Email › Domains. Leave out workspace. |
400 | Your balance can't cover the email (E03001). | Add funds under Billing. In the sandbox, set your test balance. |
401 | The key is wrong, or it doesn't match the base URL. | See API keys and base URLs. |
403 | The Messaging API isn't turned on, or your team isn't approved (E02010). | Check Subscribed APIs and Settings › Compliance. |
403 | Your team's email sending is paused (E02017). | See When sending is paused. |
404 | No template has that handle, or from isn't one of your senders (E01005). | Check the handle under Email › Templates, and the sender under Email › Domains. |
429 | Too many requests in a minute (E01011). | Wait, then send it again with the same externalId. See Rate limits. |
503 | Email isn't available for a moment (E01012). | Try again later with the same externalId. |
Nothing is charged for a refused send. Each message is listed in Refused emails.
Send to more than one person
Each request sends one email to one address. To send a template to up to five people at once, use Email › Send in the app. Each person gets their own email, charged on its own.