Emails
Send one email or a batch, schedule it, and follow it from accepted to delivered.
An email is one POST /emails request, or one message over the SMTP relay. BillionSend checks it, stores it and returns an id right away. The sending happens in the background, so a 200 means the email is accepted, not delivered.
Send an email
import { BillionSend } from "@billionsend/node";
const bs = new BillionSend(); // reads BILLIONSEND_API_KEY
const { data, error } = await bs.emails.send({
from: "Acme <hello@mail.example.com>",
to: ["user@example.org"],
subject: "Welcome",
html: "<p>Thanks for signing up.</p>",
});
The same call with curl:
curl -X POST https://api.billionsend.com/emails \
-H "Authorization: Bearer $BILLIONSEND_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "Acme <hello@mail.example.com>",
"to": ["user@example.org"],
"subject": "Welcome",
"html": "<p>Thanks for signing up.</p>"
}'
from: must be on a verified domain of your team.to,cc,bcc,reply_to: an address or a list.to,ccandbcctogether hold at most 50 recipients.htmlandtext: at least one is required. Sending with a template id is not supported. A template is content you copy into a broadcast.tags,headers,attachments: see API basics for the rules, the attachment limits and idempotency.topic_id: recipients who opted out of that topic are skipped.
To test without emailing anyone, send to success@simulator.amazonses.com.
Send a batch
POST /emails/batch takes an array of up to 100 emails. By default one invalid email fails the whole batch. Add the header x-batch-validation: permissive to accept the valid ones: data lists their ids, and errors lists the others by position.
Schedule, change, cancel
Add scheduled_at to send later, up to 30 days ahead. It takes an ISO 8601 time with an offset, or a relative time such as in 2 hours. While an email is scheduled, PATCH /emails/{id} changes its time and POST /emails/{id}/cancel cancels it.
Follow an email
GET /emails/{id} returns the email with last_event, its newest outcome, and a score from Deliverability Insights. In the dashboard, Emails lists every email and shows its events in order. Bodies and history are kept for 30 days.
| Event | Meaning |
|---|---|
email.scheduled |
Accepted, and waiting for its time. |
email.sent |
Handed over for delivery. |
email.delivered |
The recipient’s server accepted it. |
email.delivery_delayed |
Delivery is delayed and will be retried. |
email.bounced |
The recipient’s server refused it. |
email.complained |
The recipient marked it as spam. |
email.failed |
It could not be sent. The event says why. |
email.suppressed |
It was not sent because every recipient is suppressed or unsubscribed. |
email.opened, email.clicked |
The recipient opened it or clicked a link, if tracking is on. |
Each event can also be sent to you as a webhook.
What stops or holds a send
A send is refused with a 4xx error that names the reason when:
- the sender domain is not verified (
422); - every recipient is suppressed (
422 all_recipients_suppressed); - you are past your plan’s volume (
429); - your bounce or complaint rate has paused sending (
403 sending_paused).
Some mail is accepted but held, and goes out later: a new domain over its daily cap, or mail waiting for a limit to reset. See Sending limits. The API and the SMTP relay apply the same rules.