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

Quickstart

Send your first email in a few minutes.

1. Sign up

Create an account at billionsend.com. The dashboard is there; the API is at https://api.billionsend.com.

2. Verify a domain

You can only send from domains you have verified.

  1. Open Domains and add a domain you own, for example acme.dev.
  2. Add the DNS records shown (DKIM and MAIL FROM) at your DNS provider.
  3. Click Verify domain. The page shows which records are still missing.

See Domains.

3. Create an API key

Open API keys and create one. The bs_ key is shown once, so copy it. A key can be full access or sending only, and can be limited to one domain.

4. Send an email

With curl:

curl -X POST https://api.billionsend.com/emails \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <onboarding@acme.dev>",
    "to": ["success@simulator.amazonses.com"],
    "subject": "Hello from BillionSend",
    "html": "<strong>It works!</strong>"
  }'

Or with the Node.js SDK (npm install @billionsend/node):

import { BillionSend } from "@billionsend/node";

const bs = new BillionSend("bs_..."); // or new BillionSend() with BILLIONSEND_API_KEY set

const { data, error } = await bs.emails.send({
  from: "Acme <onboarding@acme.dev>",
  to: ["success@simulator.amazonses.com"],
  subject: "Hello from BillionSend",
  html: "<strong>It works!</strong>",
});

if (error) console.error(error.name, error.message);
else console.log("sent", data.id);

Both return { "id": "..." }. Watch the email go from queued to delivered on the Emails page. Other languages: see SDKs.

Testing

  • success@simulator.amazonses.com simulates a delivery without emailing anyone. Add a label for variety: success+signup@simulator.amazonses.com.
  • Simulator mail still counts toward your plan’s quota.
  • bounce@, complaint@ and suppressionlist@ at the simulator produce real bounces and complaints: the address is added to your suppression list and counts toward your bounce and complaint rates. Use them by hand, not in automated tests. Each address works once, so add a label for a fresh one: bounce+2@simulator.amazonses.com.
  • Addresses at example.com, or under .test or .invalid, cannot receive mail. A send to one is refused with 422 (see API basics).

Next steps

Was this page helpful?