Skip to main content

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

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.

FieldWhat to send
toThe one address to send to.
templateThe template's handle, such as verification-code.
valuesA value for each of the template's {{variables}}, by name, as text. Leave it out if the template has none.
fromThe address of one of your senders, such as billing@mail.example.com. Leave it out to send from your default sender.
externalIdYour 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 cost says 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, and refunded is true.
  • An email that was sent and then BOUNCED isn'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​

StatusWhyFix
400A field is missing or invalid (E01001). The body has details, one per problem.Fix the request, and send it with the same externalId.
400A variable the template uses has no value, such as Give a value for {{code}}. (E01002)Add it to values.
400You 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.
400Your balance can't cover the email (E03001).Add funds under Billing. In the sandbox, set your test balance.
401The key is wrong, or it doesn't match the base URL.See API keys and base URLs.
403The Messaging API isn't turned on, or your team isn't approved (E02010).Check Subscribed APIs and Settings › Compliance.
403Your team's email sending is paused (E02017).See When sending is paused.
404No 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.
429Too many requests in a minute (E01011).Wait, then send it again with the same externalId. See Rate limits.
503Email 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.