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

API basics

Base URL, authentication, errors, limits, idempotency and pagination.

The endpoint pages in the API reference are generated from the API itself, so they are always current. The raw spec is at /api.openapi.json (OpenAPI 3.1).

The API is compatible with the Resend API: same paths, request shapes and error format. Call it from the BillionSend SDKs or over plain HTTP.

Base URL

https://api.billionsend.com

Authentication

Send an API key from API keys in the dashboard on every request:

Authorization: Bearer bs_...

A missing or malformed key answers 401 missing_api_key, a wrong one 401 invalid_api_key.

A key has a permission level:

  • Full access can use every endpoint.
  • Sending only can only send. Everything outside /emails answers 403 restricted_api_key, and so do GET /emails, GET /emails/{id}, GET /emails/metrics, DELETE /emails/{id} and every /emails/receiving endpoint, because they return stored content.

A key can also be limited to one domain or to one inbox. A key limited to a domain works inside that domain: it sends only from it, reads only its mail, sees and changes only it under /domains, and answers 403 restricted_api_key on everything that belongs to the whole team (webhooks, suppressions, templates, contact properties, /usage, /deliverability, verifications, POST /domains); see API keys. A key you create with the API is never broader than the key that created it.

A team can have 25 active keys. Which actions need a key made by an owner or admin is listed under Team roles.

Errors

Every error has this shape:

{ "statusCode": 422, "name": "validation_error", "message": "..." }
Status and name Meaning
400 invalid_parameter The body is not valid JSON.
401 missing_api_key / invalid_api_key No key, or a wrong one.
403 restricted_api_key The key’s permission or scope does not allow this.
403 forbidden Your role or key does not allow this action.
403 plan_limit_reached You reached a limit of your plan. See Plans and limits.
403 sending_paused Sending is paused because your bounce or complaint rate is too high.
404 not_found The endpoint, or the thing you asked for, does not exist.
409 invalid_idempotent_request The idempotency key was used with a different payload.
415 The body is not application/json.
422 validation_error The request is invalid. The message says why.
422 all_recipients_suppressed Every recipient is suppressed or opted out. See Suppressions.
429 rate_limit_exceeded Too many requests.
429 daily_quota_exceeded / monthly_quota_exceeded Your plan’s sending quota is used. See Plans and limits.
503 service_unavailable The statistics store did not answer. Sending is not affected.

Every 429 carries a retry-after header: the seconds to wait.

Every answer, an error or not, carries an x-request-id header: the request’s id, the same id the request has on the dashboard’s Logs page. Quote it when you ask us about a request.

A recipient whose domain can never receive mail, such as x@example.com, x@foo.test or x@gmail.con, is refused with 422 validation_error. The same goes for a new contact at such an address. To test without emailing anyone, send to success@simulator.amazonses.com.

Receiving, inboxes and agent safety add their own errors, which those pages list.

Rate limits

Each API key can make 600 requests per minute, and a team’s keys together 3,000. Over the limit you get 429 rate_limit_exceeded and a retry-after header. More than 20 failed authentications per minute from one IP address are refused the same way.

Idempotency

POST /emails and POST /emails/batch accept an Idempotency-Key header of 1 to 256 characters. So do inbox replies, forwards and draft sends, and replies and forwards of received mail. Retry with the same key and the same payload and you get the original response instead of a second email. The same key with a different payload answers 409.

Pagination

List endpoints take limit (1 to 100, default 20) and the cursors after and before, each an item id from a previous page. The response has has_more. Lists run newest first:

  • after takes the last id of a page and returns older items.
  • before takes the first id and returns newer items.

To catch up on what is new, pass the newest id you stored as before.

A few lists run in another order, which their reference pages state: inbox threads (latest activity first), thread emails (oldest first), and topics and labels (oldest first, all at once). A cursor that matches no item answers 422 validation_error (404 under /inboxes).

Rules worth knowing

  • Attachments take inline base64 content only. A remote path URL answers 422. Attachments total up to 10 MiB per email, and the whole email must stay under 40 MB. Programs and scripts (.exe, .js, .bat and similar, also inside a ZIP) are always refused. On a new team, some risky types, such as archives, web pages and macro-enabled Office files, are accepted but wait for review before they are sent.
  • Contacts belong to the team. There are no audiences: audience endpoints work as aliases of segments.
  • Unsubscribes belong to the sending domain. See Unsubscribes.
  • Recipients: to, cc and bcc together take up to 50 addresses, each a single mailbox. A send where every to address is suppressed answers 422 all_recipients_suppressed.
  • Headers are allowlisted: any X-* name (except X-SES-* and X-BillionSend-*), threading and priority headers, and the List-Unsubscribe pair. Anything else answers 422.
  • Subjects can be up to 998 characters.
  • Extra endpoints: GET /usage (plan, limits and usage), DELETE /emails/{id}, and GET /emails/metrics (Analytics).
  • Bulk contacts: POST /contacts/batch creates and POST /contacts/batch/remove deletes up to 1,000 contacts in one request. include=properties,topics on the contact lists adds each contact’s properties and topics.
  • Bulk suppressions take up to 1,000 addresses per request.
  • Extra statuses: broadcasts can be canceled.
  • Receiving and inboxes are in beta, with long-polling and a live event stream for new mail. See Receiving and Inboxes.
  • Unsupported settings are rejected with 422 instead of being silently ignored.

Received mail carries download links for the raw message and its attachments. They are plain GET URLs that need no API key, work for one hour and answer 403 once expired. Ask the API again for a fresh link. See Receiving.

Was this page helpful?