---
title: Básico da API
description: URL base, autenticação, erros, limites, idempotência e paginação.
ai:
  exclude: true
---

As páginas de endpoints da [Referência da API](/docs/pt-br/api-reference) são geradas a partir da própria API, então estão sempre atuais. A especificação bruta está em [/api.openapi.json](/docs/api.openapi.json) (OpenAPI 3.1).

A API é compatível com a API do Resend: mesmos caminhos, formatos de requisição e de erro. Chame-a pelos [SDKs](/docs/pt-br/sdks) do BillionSend ou por HTTP simples.

## URL base

`https://api.billionsend.com`

## Autenticação

Envie em toda requisição uma chave de API de **Chaves de API** no painel:

```
Authorization: Bearer bs_...
```

Uma chave ausente ou malformada responde `401 missing_api_key`, e uma errada `401 invalid_api_key`.

Uma chave tem um nível de permissão:

- **Acesso total** pode usar todos os endpoints.
- **Somente envio** só pode enviar. Tudo fora de `/emails` responde `403 restricted_api_key`, e o mesmo vale para `GET /emails`, `GET /emails/{id}`, `GET /emails/metrics`, `DELETE /emails/{id}` e todos os endpoints de `/emails/receiving`, porque eles devolvem conteúdo armazenado.

Uma chave também pode ser limitada a **um domínio** ou a **uma [caixa de entrada](/docs/pt-br/inboxes)**. Uma chave restrita a um domínio trabalha dentro dele: só envia desse domínio, só lê os e-mails dele, vê e altera só ele em `/domains`, e responde `403 restricted_api_key` em tudo o que pertence à equipe inteira (webhooks, supressões, templates, propriedades de contato, `/usage`, `/deliverability`, verificações, `POST /domains`); veja [chaves de API](/docs/pt-br/api-keys). Uma chave criada pela API nunca é mais ampla que a chave que a criou.

Uma equipe pode ter 25 chaves ativas. As ações que exigem uma chave criada por um proprietário ou administrador estão listadas em [Funções da equipe](/docs/pt-br/team-roles).

## Erros

Todo erro tem este formato:

```json
{ "statusCode": 422, "name": "validation_error", "message": "..." }
```

| Status e nome | Significado |
| --- | --- |
| `400 invalid_parameter` | O corpo não é um JSON válido. |
| `401 missing_api_key` / `invalid_api_key` | Sem chave, ou chave errada. |
| `403 restricted_api_key` | A permissão ou o escopo da chave não permite isso. |
| `403 forbidden` | Sua função ou chave não permite esta ação. |
| `403 plan_limit_reached` | Você atingiu um limite do seu plano. Veja [Planos e limites](/docs/pt-br/billing). |
| `403 sending_paused` | O envio está pausado porque sua taxa de rejeição ou de reclamação está alta demais. |
| `404 not_found` | O endpoint, ou o que você pediu, não existe. |
| `409 invalid_idempotent_request` | A chave de idempotência foi usada com outro conteúdo. |
| `415` | O corpo não é `application/json`. |
| `422 validation_error` | A requisição é inválida. A mensagem diz o motivo. |
| `422 all_recipients_suppressed` | Todos os destinatários estão suprimidos ou descadastrados. Veja [Supressões](/docs/pt-br/concepts/suppressions). |
| `429 rate_limit_exceeded` | Requisições demais. |
| `429 daily_quota_exceeded` / `monthly_quota_exceeded` | A cota de envio do seu plano acabou. Veja [Planos e limites](/docs/pt-br/billing). |
| `503 service_unavailable` | O armazenamento de estatísticas não respondeu. O envio não é afetado. |

Todo `429` traz um cabeçalho `retry-after`: os segundos de espera.

Toda resposta, de erro ou não, traz um cabeçalho `x-request-id`: o id da requisição, o mesmo que ela tem na página Logs do painel. Informe-o quando nos perguntar sobre uma requisição.

Um destinatário cujo domínio nunca pode receber e-mail, como `x@example.com`, `x@foo.test` ou `x@gmail.con`, é recusado com `422 validation_error`. O mesmo vale para um novo contato nesse endereço. Para testar sem enviar e-mail a ninguém, envie para `success@simulator.amazonses.com`.

[Recebimento](/docs/pt-br/receiving), [caixas de entrada](/docs/pt-br/inboxes) e [segurança de agentes](/docs/pt-br/agent-safety) acrescentam erros próprios, que essas páginas listam.

## Limites de taxa

Cada chave de API pode fazer 600 requisições por minuto, e as chaves de uma equipe juntas 3.000. Acima do limite você recebe `429 rate_limit_exceeded` e um cabeçalho `retry-after`. Mais de 20 autenticações com falha por minuto vindas de um mesmo endereço IP são recusadas do mesmo modo.

## Idempotência

`POST /emails` e `POST /emails/batch` aceitam um cabeçalho `Idempotency-Key` de 1 a 256 caracteres. As respostas, os encaminhamentos e os envios de rascunho das caixas de entrada, e as respostas e os encaminhamentos de e-mail recebido, também. Tente de novo com a mesma chave e o mesmo conteúdo e você recebe a resposta original, em vez de um segundo e-mail. A mesma chave com outro conteúdo responde `409`.

## Paginação

Os endpoints de lista aceitam `limit` (1 a 100, padrão 20) e os cursores `after` e `before`, cada um um id de item de uma página anterior. A resposta traz `has_more`. As listas vão do mais novo para o mais antigo:

- `after` recebe o último id de uma página e retorna itens mais antigos.
- `before` recebe o primeiro id e retorna itens mais novos.

Para se atualizar com o que é novo, passe como `before` o id mais novo que você guardou.

Algumas listas seguem outra ordem, que as suas páginas de referência indicam: as conversas de uma caixa (atividade mais recente primeiro), os e-mails de uma conversa (mais antigos primeiro), e os tópicos e rótulos (mais antigos primeiro, todos de uma vez). Um cursor que não corresponde a nenhum item responde `422 validation_error` (`404` em `/inboxes`).

## Regras que vale conhecer

- **Anexos** aceitam apenas `content` em base64 embutido. Uma URL `path` remota responde `422`. Os anexos somam até 10 MiB por e-mail, e o e-mail inteiro precisa ficar abaixo de 40 MB. Programas e scripts (`.exe`, `.js`, `.bat` e semelhantes, também dentro de um ZIP) são sempre recusados. Em uma equipe nova, alguns tipos de risco, como arquivos compactados, páginas web e arquivos do Office com macros, são aceitos mas esperam uma revisão antes de serem enviados.
- **Os contatos** pertencem à equipe. Não há audiências: os endpoints de audiência funcionam como aliases de [segmentos](/docs/pt-br/concepts/segments).
- **Os descadastros** pertencem ao domínio remetente. Veja [Marcas e descadastros](/docs/pt-br/concepts/unsubscribes).
- **Destinatários**: `to`, `cc` e `bcc` juntos aceitam até 50 endereços, cada um uma única caixa. Um envio em que todos os endereços de `to` estão suprimidos responde `422 all_recipients_suppressed`.
- **Os cabeçalhos** têm lista permitida: qualquer nome `X-*` (exceto `X-SES-*` e `X-BillionSend-*`), cabeçalhos de encadeamento e prioridade, e o par `List-Unsubscribe`. Qualquer outro responde `422`.
- **Os assuntos** podem ter até 998 caracteres.
- **Endpoints extras**: `GET /usage` (plano, limites e uso), `DELETE /emails/{id}` e `GET /emails/metrics` ([Análises e métricas](/docs/pt-br/concepts/analytics)).
- **Contatos em lote**: `POST /contacts/batch` cria e `POST /contacts/batch/remove` exclui até 1.000 contatos numa requisição. `include=properties,topics` nas listas de contatos acrescenta as propriedades e os tópicos de cada contato.
- **Supressões em lote** aceitam até 1.000 endereços por requisição.
- **Status extras**: as transmissões podem ficar `canceled`.
- **Recebimento e caixas de entrada** estão em beta, com long-polling e um fluxo de eventos em tempo real para e-mails novos. Veja [Recebimento](/docs/pt-br/receiving) e [Caixas de entrada](/docs/pt-br/inboxes).
- **Configurações sem suporte** são rejeitadas com `422` em vez de ignoradas em silêncio.

## Links de download assinados

O e-mail recebido traz links de download da mensagem bruta e dos seus anexos. São URLs `GET` simples que não precisam de chave de API, valem por uma hora e respondem `403` depois de expirar. Peça um link novo à API. Veja [Recebimento](/docs/pt-br/receiving).
