Skip to content
Esc
↑↓navigate↵open⌘Jpreview

Send an email

POST/emails
Authorization
AuthorizationBearer token · headerrequired

A BillionSend API key (bs_…).

Header parameters
Idempotency-Keystring

1 to 256 characters. A retry with the same key and the same body answers the original response instead of sending again; the same key with a different body answers 409 invalid_idempotent_request.

min length 1 · max length 256
Request body
requiredapplication/json
fromstringrequired

Sender, "Name <user@domain>" or bare address; the domain must be verified for the team

tostring | string[]required

Recipient address or list of up to 50

Show properties
Any of:
string
string
string[]
Array of string
string
subjectstringrequired

Subject line

min length 1 · max length 998
htmlstring

HTML body; at least one of html/text is required

textstring

Plain-text body; at least one of html/text is required

ccstring | string[]

Cc address or list

Show properties
Any of:
string
string
string[]
Array of string
string
bccstring | string[]

Bcc address or list

Show properties
Any of:
string
string
string[]
Array of string
string
reply_tostring | string[]

Reply-To address or list

Show properties
Any of:
string
string
string[]
Array of string
string
scheduled_atstring

Deliver later: ISO 8601 with offset, or relative like "in 2 hours" (an ISO 8601 datetime with offset (e.g. "2026-09-01T12:00:00Z") or a relative time like "in 5 mins", "in 2 hours", or "in 1 day"); max 30 days ahead

tagsobject[]

Key/value labels attached to the email for filtering; names starting with billionsend_, in any letter case, are reserved

Show properties
Array of object
namestringrequired
min length 1
valuestringrequired
topic_idstring<uuid> | null

Topic id: recipients opted out of the topic are skipped; a send to one address that is a contact also gets that contact's unsubscribe link. A topic bound to a domain (domain_id) can be sent only from that domain (422 otherwise)

attachmentsobject[]

Attachments with base64 content (no remote paths)

Show properties
Array of object
filenamestring | boolean | null
Show properties
Any of:
string
string
boolean
boolean
null
null
contentstring
content_typestring
content_idstring

Inline part: the HTML shows it with <img src="cid:<content_id>">

min length 1 · max length 255
pathstring
headersobject

Extra message headers (transport headers are rejected)

templateany

Not supported: any value is a 422; an email takes html and/or text

Responses
200

Email accepted

idstring<uuid>required
400

Idempotency-Key is not 1 to 256 characters

statusCodenumberrequired
namestringrequired
messagestringrequired
401

Missing, malformed, unknown or revoked API key

statusCodenumberrequired
namestringrequired
messagestringrequired
403

Restricted API key

statusCodenumberrequired
namestringrequired
messagestringrequired
404

Not found

statusCodenumberrequired
namestringrequired
messagestringrequired
409

Idempotency conflict

statusCodenumberrequired
namestringrequired
messagestringrequired
422

Validation error

statusCodenumberrequired
namestringrequired
messagestringrequired
429

Sending quota exceeded, or the rate limit (rate_limit_exceeded, with Retry-After)

statusCodenumberrequired
namestringrequired
messagestringrequired
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST 'https://api.billionsend.com/emails' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <onboarding@acme.dev>",
  "to": [
    "success@simulator.amazonses.com"
  ],
  "subject": "string",
  "html": "string",
  "text": "string",
  "cc": "string",
  "bcc": "string",
  "reply_to": "string",
  "scheduled_at": "string",
  "tags": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "topic_id": "646807af-5da6-43aa-83d3-8ac1d15ab4e5",
  "attachments": [
    {
      "filename": "string",
      "content": "string",
      "content_type": "string",
      "content_id": "string",
      "path": "string"
    }
  ],
  "headers": {
    "property1": "string",
    "property2": "string"
  },
  "template": null
}'
Response
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Was this page helpful?