Pular para o conteúdo
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

Básico da API

URL base, autenticação, erros, limites, idempotência e paginação.

As páginas de endpoints da Referência da API são geradas a partir da própria API, então estão sempre atuais. A especificação bruta está em /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 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. 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. 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.

Erros

Todo erro tem este formato:

{ "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.
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.
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.
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, caixas de entrada e segurança de agentes 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.
  • Os descadastros pertencem ao domínio remetente. Veja Marcas e descadastros.
  • 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).
  • 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 e Caixas de entrada.
  • Configurações sem suporte são rejeitadas com 422 em vez de ignoradas em silêncio.

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.

Esta página foi útil?