---
title: API basics
description: Base URL, authentication, errors, limits, idempotency and pagination.
---

The endpoint pages in the [API reference](/docs/api-reference) are generated from the API itself, so they are always current. The raw spec is at [/api.openapi.json](/docs/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](/docs/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](/docs/inboxes)**. 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](/docs/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](/docs/team-roles).

## Errors

Every error has this shape:

```json
{ "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](/docs/billing). |
| `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](/docs/concepts/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](/docs/billing). |
| `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](/docs/receiving), [inboxes](/docs/inboxes) and [agent safety](/docs/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](/docs/concepts/segments).
- **Unsubscribes** belong to the sending domain. See [Unsubscribes](/docs/concepts/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](/docs/concepts/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](/docs/receiving) and [Inboxes](/docs/inboxes).
- **Unsupported** settings are rejected with `422` instead of being silently ignored.

## Signed download links

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](/docs/receiving).
