Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

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, cc and bcc together hold at most 50 recipients.
  • html and text: 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.

Was this page helpful?