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

Caixas de entrada

Endereços de e-mail que guardam as mensagens em conversas e respondem pelo mesmo endereço, para um agente de IA ou para pessoas.

Uma caixa de entrada é um endereço de e-mail que recebe mensagens em conversas e envia pelo mesmo endereço. Dê uma para um agente de IA, que lê pela API, por webhooks ou pelo servidor MCP, ou para pessoas, que leem pelo painel. Uma caixa é um endereço de um dos seus domínios de recebimento, ou um endereço no domínio compartilhado do BillionSend, que não precisa de DNS.

Os SDKs cobrem todos os endpoints de caixas de entrada como inboxes.*, incluindo as regras de segurança, a quarentena, as aprovações e o fluxo de eventos em tempo real.

Agente ou pessoas

Toda caixa tem um kind, escolhido na criação e que nunca muda. O tipo define os padrões das configurações de segurança.

Configuração Agente Pessoas
accept_from verified anyone
screening ligada desligada
extract_codes ligada ligada
send_policy reply_only open (reply_only no domínio compartilhado)
require_approval desligada desligada
private_codes ligada desligada
send_cap 200 (50 no domínio compartilhado) sem limite (50 no domínio compartilhado)
  • agent é o padrão quando kind é omitido. E-mails de remetentes cujo domínio não os garante esperam na quarentena, e-mails dos demais remetentes externos passam pela análise de injeção de prompt, e o agente responde dentro das conversas existentes: uma conversa nova que ele começa vira um rascunho que espera uma pessoa. Veja Segurança do agente.
  • human é para pessoas que leem pelo painel: o e-mail de todos é entregue (uma autenticação reprovada cai na pasta spam) e nada passa pela análise.

E-mail com vírus vai para a quarentena em toda caixa.

Criar uma caixa de entrada

No painel, abra Caixas de entrada e escolha Criar caixa de entrada. Ou chame a API:

curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "orders@inbound.example.com",
    "name": "Agente de pedidos",
    "kind": "agent"
  }'

Com o SDK para Node.js:

import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // reads BILLIONSEND_API_KEY

const { data, error } = await bs.inboxes.create({
  email_address: "orders@inbound.example.com",
  name: "Orders agent",
  kind: "agent",
});

A resposta (201) é a caixa inteira: id, name, email_address, domain_id, kind, shared, expires_at, unread (conversas com mensagem não lida), drafts, quarantined, pending_approval e mais.

Campo Regras
email_address Um endereço de um domínio verificado da sua equipe que recebe e-mails. Em minúsculas; a parte antes do @ aceita até 64 letras, dígitos e . _ % + -. Não pode mudar depois. Omita para um endereço no domínio compartilhado.
username Com email_address omitido, a parte antes do @ no domínio compartilhado; omitido, o endereço é aleatório. Com o domain_id de um dos seus domínios, é a parte antes do @ nele.
domain_id Uma linha de GET /domains: o subdomínio compartilhado da sua equipe (shared: true) ou um dos seus domínios verificados.
name 1 a 320 caracteres; o endereço, quando omitido.
from_name Nome de exibição dos e-mails que a caixa envia, até 78 caracteres: um nome simples, sem @, :, <, >, quebras de linha, links nem telefones.
kind agent (padrão) ou human.
expires_in Quando a caixa expira, como 1h, 24h ou 7d; omitido, nunca.
safety Qualquer uma das configurações de segurança.
forwarding true acrescenta um receiving_address no domínio compartilhado, para encaminhar para a caixa uma conta de e-mail que você mantém em outro lugar.
Resposta Quando
409 validation_error Outra caixa já usa o endereço. Nenhum outro nome é escolhido por você.
403 validation_error O limite de caixas do seu plano foi atingido.
429 rate_limit_exceeded Caixas demais criadas na última hora, ou a análise de nomes do domínio compartilhado atingiu o limite de hoje. retry-after diz quando tentar de novo.
422 validation_error O domínio não está verificado ou não recebe e-mails, um username quebra uma regra ou é reservado, ou uma configuração quebra uma regra.
503 name_review_unavailable Não foi possível analisar agora um nome do domínio compartilhado. Tente de novo em instantes.

As outras chamadas:

  • GET /inboxes lista as caixas, da mais nova à mais antiga (?kind=agent ou ?kind=human restringe).
  • GET /inboxes/{id} lê uma. Todo {id} de um caminho /inboxes/{id}/… aceita o id da caixa ou o endereço de e-mail dela.
  • PATCH /inboxes/{id} altera name, from_name ou expires_in.
  • DELETE /inboxes/{id} exclui a caixa com suas conversas, rascunhos e etiquetas, e revoga as chaves de API dela. Uma mensagem que também chegou a outra caixa ou a um endereço do pega-tudo continua lá.

Endereços

No seu domínio

Uma caixa no seu domínio exige que o domínio receba e-mails: verificado, com o recebimento ligado e o registro MX publicado. Cada mensagem segue o endereço para o qual o servidor do remetente a entregou:

  1. para a caixa com exatamente esse endereço;
  2. senão, para name+tag@, para a caixa de name@;
  3. senão, quando o pega-tudo do domínio está ligado, para Todos os recebidos sem caixa; com o pega-tudo desligado, o endereço é recusado (550 5.1.1).

O e-mail enviado do endereço de uma caixa segue as regras da caixa em todas as vias: POST /emails, o endpoint em lote, o relay SMTP e o MCP. Dê à caixa um endereço que o seu app ainda não use para enviar.

Domínio compartilhado

Uma caixa no domínio compartilhado não precisa de DNS. Cada equipe tem um subdomínio próprio no domínio compartilhado do BillionSend, com o nome da equipe. Omita email_address, ou envie o id da linha compartilhada como domain_id, e username dá o nome do endereço:

curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "username": "orders", "name": "Agente de pedidos" }'

Sem username, o endereço é aleatório. Um nome de usuário é recusado (422) quando é reservado (postmaster, abuse, admin, security, support, noreply, no-reply, billing, hostmaster, webmaster, mailer-daemon, root), começa com fwd- ou parece uma marca conhecida. Um já em uso responde 409.

Análise de nomes. Um nome de usuário escolhido, um from_name e o subdomínio da equipe são analisados antes de serem publicados, para barrar nomes que se passam por uma marca, um banco, um governo ou um cargo oficial. Um nome recusado responde 422. Enquanto a análise não consegue responder, você recebe 503 name_review_unavailable; o subdomínio de uma equipe nova é tentado de novo até passar, e após 24 horas a equipe fica com team- e seis caracteres aleatórios. Passados 20 nomes recusados ou 200 análises num dia UTC, a resposta é 429 até a meia-noite UTC.

Os endereços compartilhados seguem regras próprias, já que o domínio é de todas as equipes:

  • Duram até serem excluídos, a menos que expires_in diga outra coisa, e contam para o limite de caixas do seu plano. Uma que ninguém usa há 90 dias é excluída.
  • No plano Free, e em qualquer endereço cujo nome pareça uma marca conhecida, eles só respondem dentro das próprias conversas, a remetentes cujo domínio os garantiu e aos endereços de login dos membros da sua equipe. Num plano pago, pessoas começam conversas por eles, e um agente também começa quando o send_policy é open e a sua equipe já passou dos primeiros envios; caso contrário, as conversas novas dele esperam uma pessoa como rascunhos. Cada mensagem a um desconhecido é verificada contra phishing antes de sair. Uma recusa responde 403 inbox_send_policy.
  • Cada e-mail vai para no máximo 10 destinatários. Uma caixa envia a no máximo 50 destinatários por dia (send_cap de 1 a 50), e todos os endereços compartilhados da sua equipe juntos chegam a 1.000 destinatários por dia UTC; além disso, 429 inbox_send_cap_reached.
  • from precisa ser exatamente o endereço da caixa, e o e-mail não pode ter scheduled_at, reply_to, anexos nem cabeçalhos personalizados (422). POST /emails/batch, broadcasts e o relay SMTP sempre recusam um endereço compartilhado.
  • forward_to aceita só endereços de login de membros.

Os e-mails para postmaster@ e abuse@ no domínio compartilhado vão para o BillionSend, nunca para uma caixa.

Encaminhar uma conta de e-mail para uma caixa

forwarding: true é para um endereço cujos e-mails ficam em outro lugar, como uma conta do Google Workspace. A caixa ganha um receiving_address, um endereço aleatório no subdomínio compartilhado da sua equipe: encaminhe a conta para lá, e a caixa recebe os e-mails e responde pelo próprio endereço. O domínio só precisa estar verificado para envio.

Validade

expires_in é um número seguido de h ou d, de 1h a 365d; omitido, a caixa nunca expira. Um PATCH com um novo expires_in conta a partir desse momento, e null remove a validade. expires_at mostra quando ela termina.

Em expires_at a caixa para: os e-mails para ela são recusados (550 5.1.1), as leituras respondem 404 e as chaves de API dela deixam de funcionar. Dentro de uma hora ela é excluída, com um webhook inbox.expired seguido de inbox.deleted. Alterar a validade exige a função de desenvolvedor, administrador ou proprietário.

Conversas

Toda mensagem de uma caixa pertence a uma conversa, e uma conversa guarda os dois sentidos: o que a caixa recebeu e o que enviou.

  • Como as respostas encontram a conversa. O e-mail que a caixa envia leva um token de conversa no cabeçalho References. Uma resposta cai na mesma conversa quando leva esse token, quando o In-Reply-To dela cita uma mensagem que a caixa enviou, ou quando ela se refere a uma mensagem anterior da conversa. Assuntos nunca juntam conversas.
  • Pastas. Uma conversa fica em uma pasta: inbox, archive, spam, sent ou trash. Um e-mail novo move uma conversa arquivada ou enviada de volta para inbox. DELETE move a conversa para trash, que é esvaziada após 30 dias.
  • Lido/não lido. Um PATCH com read marca a conversa inteira. Um e-mail retido nunca deixa uma conversa não lida. Numa caixa de pessoas, abrir uma conversa a marca como lida; numa caixa de agente, o estado de leitura pertence ao seu agente.
  • Etiquetas. Até 100 por caixa, nomes de 1 a 64 caracteres, cores como #RRGGBB.
Chamada Faz
GET /inboxes/{id}/threads Conversas, da atividade mais recente. Filtros: folders, labels, read, include_quarantined.
GET /inboxes/{id}/threads/search Os mesmos filtros mais query ("frase exata" e -excluído funcionam), from, to, cc, bcc, has_attachment, start_date, end_date.
GET /inboxes/{id}/threads/{thread_id} Uma conversa.
PATCH /inboxes/{id}/threads/{thread_id} Define read ou folder.
POST / PUT / DELETE …/threads/{thread_id}/labels Adiciona, substitui ou remove etiquetas.
DELETE /inboxes/{id}/threads/{thread_id} Move a conversa para a lixeira.
GET /inboxes/{id}/threads/{thread_id}/emails Seus e-mails, do mais antigo ao mais novo.

A busca encontra palavras inteiras, sem diferenciar maiúsculas e minúsculas, no assunto, no remetente (endereço e nome de exibição), nos destinatários, no texto de um e-mail recebido (incluindo as mensagens anteriores que ele cita), nos nomes dos anexos dele e no texto dos anexos em PDF, Word e Excel (depois que esse texto é lido). Textos em chinês, japonês e coreano são divididos em palavras. Cada palavra de query precisa aparecer em algum lugar do mesmo e-mail; from, to, cc e bcc recebem palavras de um endereço ou de um nome. Os e-mails enviados são buscados pelo assunto, pelo remetente e pelos destinatários.

matched_email_id é o e-mail da conversa que melhor corresponde à busca, e highlights marca as palavras no assunto, no remetente e nos destinatários dele (fica {} quando só o texto ou o nome de um anexo correspondeu). Um e-mail novo pode ser buscado um ou dois segundos depois de chegar. Se a busca estiver indisponível por um momento, a chamada responde 503 com search_unavailable e um cabeçalho Retry-After; todas as outras chamadas funcionam normalmente.

Um e-mail de conversa tem direction, from, to, cc, bcc, reply_to, subject, message_id, html, text, attachments, read e received_at. O e-mail recebido acrescenta extracted_text (a resposta, limpa de texto oculto), screening, spam_verdict e virus_verdict.

Enviar de uma caixa

POST /inboxes/{id}/emails (inboxes.send() nos SDKs) inicia uma nova conversa a partir do endereço da caixa numa única chamada.

curl -X POST "https://api.billionsend.com/inboxes/{id}/emails" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d '{
    "to": "ada@example.org",
    "subject": "Seu pedido 1042",
    "text": "Ele sai hoje. A nota fiscal está anexada.",
    "attachments": [{ "filename": "invoice.pdf", "content": "JVBERi0xLjQK..." }]
  }'

Ela aceita to, subject, html e/ou text, e opcionalmente cc, bcc, attachments e requires_approval. As regras da caixa decidem como numa resposta, e as respostas são as de uma resposta: 200 com { "id", "thread_id" }, ou 202 com o rascunho quando as regras seguram o envio (uma caixa que não pode iniciar conversas, um destinatário novo além da rampa, requires_approval: true). Uma chave restrita a uma caixa pode chamá-la para a própria caixa.

Os anexos são os que o POST /emails aceita: filename e content em base64, e opcionalmente content_type e content_id para uma imagem embutida. Um path remoto responde 422. Respostas, encaminhamentos, envios novos e rascunhos aceitam anexos, até 10 MiB decodificados no total (um encaminhamento conta também os arquivos do original); programas e tipos de arquivo disfarçados respondem 422, e uma caixa no domínio compartilhado não aceita nenhum.

Responder e encaminhar

curl -X POST "https://api.billionsend.com/inboxes/{id}/threads/{thread_id}/emails/{email_id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Obrigado, seu pedido sai hoje." }'

Uma resposta vai para o Reply-To da mensagem, ou então para o remetente. reply_all acrescenta os outros endereços de to e cc como cc; bcc nunca é copiado. Um envio aceita no máximo 50 destinatários. …/forward exige to, aceita uma nota e cita o original com seus anexos, mais os attachments que você acrescentar (até 10 MiB no total). Ambos aceitam attachments e requires_approval: true para uma pessoa aprovar o envio. Uma resposta de uma caixa de agente leva Auto-Submitted: auto-replied.

Resposta Significa
200 Enviado: { "id", "thread_id" }.
202 Retido para uma pessoa: o rascunho, com status: "pending_approval" e seus approval_reasons.
403 inbox_send_policy As regras da caixa recusam o envio de vez.
403 email_quarantined O e-mail está retido na quarentena ou tem vírus.
403 restricted_api_key Uma chave restrita a uma caixa tentando alcançar outra.
429 inbox_send_cap_reached O limite diário da caixa foi usado; retry-after conta até a meia-noite UTC.

Para responder a qualquer e-mail recebido, numa caixa ou não, use POST /emails/receiving/{id}/reply.

Rascunhos e aprovação

Um rascunho é avulso, para uma conversa nova, ou uma resposta com thread_id e reply_to_email_id. O seu status:

status Significa
draft Sendo escrito; nada o envia até …/send, ou até o seu send_at.
pending_approval Um envio foi retido e espera uma pessoa. approval_reasons diz por quê. Expira em 7 dias.
sent Enviado; email_id indica o e-mail.
rejected Uma pessoa o descartou.
expired Ninguém aprovou em 7 dias.
Chamada Faz
POST /inboxes/{id}/drafts Cria um rascunho: to, cc, bcc, subject, text, html, attachments, mais thread_id e reply_to_email_id para uma resposta. Um rascunho de resposta não copia os destinatários, então defina to antes de enviar.
GET /inboxes/{id}/drafts Rascunhos não enviados, do atualizado mais recentemente.
GET / PATCH / DELETE /inboxes/{id}/drafts/{draft_id} Lê, altera (definir text ou html substitui o corpo inteiro, e attachments substitui a lista inteira) ou exclui um rascunho; 409 depois de enviado.
POST /inboxes/{id}/drafts/{draft_id}/send Envia. 200 com o id e o thread_id do e-mail enviado, 202 quando retido, 422 sem destinatário.
POST /inboxes/{id}/drafts/{draft_id}/reject Descarta um rascunho (só quem aprova).

Um rascunho guarda os attachments criptografados, à parte do corpo, e os devolve por posição como id, filename, content_type e size, nunca o conteúdo. Eles saem com o e-mail quando o rascunho é enviado, e um envio retido guarda com o rascunho os arquivos que levava. Depois que um rascunho é enviado, descartado, expira ou é excluído, os arquivos dele somem, e a limpeza de conteúdo de 30 dias remove os que sobrarem.

Envios agendados. send_at no POST ou no PATCH (uma extensão do BillionSend) envia o rascunho depois, em nome de quem o definiu (editar o conteúdo de um rascunho agendado faz o envio sair em nome de quem editou): um horário ISO 8601 com fuso, ou um relativo como "in 2 hours", no máximo 30 dias à frente; um horário que já passou envia em até um minuto, e null cancela. O rascunho precisa ter um destinatário até lá, e só um draft pode ser agendado: um que espera aprovação responde 409. Quando chega o send_at, o envio passa por todas as regras e limites, como um envio feito naquele momento. Enviado, o rascunho fica sent; retido pelas regras da caixa, pending_approval; recusado (a chave que o agendou foi revogada, a caixa não existe mais, um limite foi atingido), ele continua draft, com send_at de volta a null, o nome da recusa em send_error e um webhook inbox.draft.send_failed que traz error: { name, message }. Agendar de novo limpa o send_error. Com send_at, criar um segundo rascunho de resposta para o mesmo e-mail responde 409 em vez do rascunho existente.

Quem aprova. Uma pessoa no painel, ou uma chave de API de acesso total da equipe que não seja restrita a uma caixa, aprova enviando: o envio pula as regras que seguram o e-mail de agentes. Um agente não aprova: uma chave restrita a uma caixa ou um cliente MCP que envia um rascunho pendente recebe 403 approval_required. No painel, qualquer membro aprova, edita ou descarta rascunhos na aba Precisa de revisão da caixa, e os proprietários recebem um e-mail por dia enquanto houver algo à espera.

Motivos pelos quais um envio é retido:

Motivo Retido porque
approval_required A requisição pediu uma pessoa (requires_approval: true).
require_approval A caixa exige aprovação em todo envio.
send_policy Um destinatário não é permitido pela regra de envio da caixa.
ramp Destinatários novos demais hoje para uma caixa recente.
private_code Contém um código ou link de acesso que a caixa recebeu.
loop_guard:<motivo> Responde a uma mensagem automática (resposta de ausência, lista de e-mails, retorno de erro).
loop_burst Respostas automáticas demais a um mesmo endereço em uma hora.
reply_to_redirect O Reply-To da mensagem aponta para outra organização.

Configurações de segurança

GET /inboxes/{id}/safety lê as regras de uma caixa, e PATCH altera qualquer uma:

curl -X PATCH "https://api.billionsend.com/inboxes/{id}/safety" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accept_from": "allowlist",
    "allowlist": ["*@billing.example.net", "maria@example.org"]
  }'
Configuração Faz
accept_from Quem alcança a caixa: anyone; verified, remetentes cujo domínio garante o endereço From (mais proprietários, a lista de permitidos e conversas conhecidas); ou allowlist, só proprietários, a lista de permitidos e conversas conhecidas. O resto vai para a quarentena.
allowlist Até 500 entradas: name@domain, ou *@domain para um domínio e seus subdomínios.
owner_addresses Até 50 endereços a mais tratados como responsáveis pela caixa, além dos endereços de login dos membros da equipe. Ignorado no domínio compartilhado.
screening Dá nota de injeção de prompt e phishing aos e-mails de remetentes externos (caixas de agente).
extract_codes Extrai códigos de verificação e links de acesso dos e-mails.
send_policy reply_only; allowlist, que acrescenta conversas novas com proprietários e a lista de permitidos (não no domínio compartilhado); ou open, qualquer pessoa, depois que a equipe passa dos primeiros envios.
require_approval Todo envio da caixa espera uma pessoa.
private_codes Um código ou link de acesso que a caixa recebeu não pode ser enviado a ninguém além dos proprietários e da lista de permitidos.
send_cap Destinatários a quem a caixa pode enviar por dia UTC sem uma pessoa: de 1 a 100.000, ou null para sem limite (de 1 a 50 no domínio compartilhado).
forward_to Até 5 endereços que recebem cópia de toda mensagem entregue, exceto spam: endereços de login de membros ou endereços de responsáveis. Uma cópia que não pode sair de imediato é tentada de novo até ser enviada, recusada em definitivo ou passarem dois dias; nunca é enviada duas vezes.

Uma configuração que quebra uma regra responde 422 com o motivo. Uma chave restrita a uma caixa não altera essas configurações (403 restricted_api_key), e uma chave de agente também não. Um cliente MCP pode lê-las, mas não alterá-las. Só um proprietário, administrador ou desenvolvedor as altera, no painel ou com uma chave de API de acesso total. A Segurança do agente explica o que cada uma faz.

Quarentena

O e-mail que as regras de uma caixa não deixam entrar vai para a quarentena: guardado, listado e liberável, nunca descartado e nunca devolvido ao remetente. Não dispara email.received nem inbox.email.received até ser liberado, e os agentes nunca o veem.

GET /inboxes/{id}/quarantine lista as mensagens retidas com id, from, subject, quarantine_reason, sender_trust, injection_score, phishing_score e virus_signature, sem o conteúdo. POST /inboxes/{id}/quarantine/{email_id}/release entrega uma, e { "trust_sender": true } também coloca o remetente na lista de permitidos. Ambos exigem uma chave de acesso total que não seja restrita a uma caixa. Pessoas liberam pela aba Precisa de revisão da caixa, e clientes MCP com receiving:manage usam release_email. Quem pode liberar cada tipo de retenção está na Segurança do agente.

Códigos de verificação

GET /inboxes/{id}/codes/latest responde o código de verificação ou link de acesso mais recente que a caixa recebeu, para o agente nunca precisar ler HTML:

curl "https://api.billionsend.com/inboxes/{id}/codes/latest?from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
{
  "object": "verification_code",
  "status": "found",
  "kind": "link",
  "code": null,
  "url": "https://app.example.org/verify?token=Qm9vdHN0cmFwLTQ4MjkxMw",
  "link_domain_matches_sender": true,
  "email_id": "155252fb-e93e-45ee-8c19-5080a929c28b",
  "from": "no-reply@example.org",
  "received_at": "2026-10-12T14:03:11.229Z",
  "sender_trust": "external"
}
  • kind é otp (código em code) ou link (endereço em url, com link_domain_matches_sender).
  • from restringe a um remetente; wait (0 a 50 segundos) espera um chegar; max_age (60 a 86.400 segundos, 600 por padrão) ignora códigos mais antigos; since ignora e-mails recebidos nesse horário ou antes, então passe o received_at de um código que você já usou para esperar o próximo.
  • status é found, none, ambiguous (dois códigos igualmente prováveis, então nenhum é respondido) ou timeout. A resposta é sempre 200.
  • Os códigos nunca vêm de e-mails em quarentena, de remetentes que falharam na autenticação, nem de uma caixa com extract_codes desligado. Toda leitura fica registrada na atividade da caixa.

Fluxo de eventos

GET /inboxes/events é um fluxo de eventos enviados pelo servidor (SSE) com tudo o que acontece nas suas caixas, no instante em que é confirmado. Os eventos têm os nomes dos eventos de webhook (inbox.email.received, inbox.thread.created, inbox.draft.created, email.received e os demais eventos inbox.*) e o data do payload do webhook. GET /inboxes/{id}/events transmite uma só caixa e termina quando ela é excluída ou expira.

curl -N "https://api.billionsend.com/inboxes/events?types=inbox.email.received" \
  -H "Authorization: Bearer bs_..." \
  -H "Accept: text/event-stream"
retry: 1000

id: 812.40.1790000000
event: inbox.email.received
data: {"type":"inbox.email.received","created_at":"2026-11-15T09:20:30.131Z","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","data":{"source":"system","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","thread_id":"...","email_id":"...","email":{}}}

: keepalive
  • Envie a chave num cabeçalho Bearer, como em toda requisição. O EventSource dos navegadores não consegue enviá-lo: use fetch e leia o corpo, ou qualquer cliente SSE que aceite cabeçalhos.
  • types restringe o fluxo a alguns eventos, separados por vírgula; /inboxes/{id}/events ainda envia inbox.deleted e inbox.expired, os eventos que o encerram. Todo evento traz só metadados, como um webhook: sem corpo, código ou link. Leia a mensagem pelos endpoints de recebimento.
  • Retomada. Todo evento tem um id. Um cliente que reconecta com Last-Event-ID (ou ?last_event_id=) recebe, em ordem, o que perdeu antes dos eventos ao vivo. Os eventos ficam guardados por 24 horas; uma reconexão com um id mais antigo recebe antes um evento stream.gap, que significa que podem faltar eventos e que as listas devem ser lidas de novo.
  • Sem Last-Event-ID, o fluxo começa sem reenvio. O servidor o fecha a cada 10 minutos, mais ou menos, e quando a API reinicia: reconecte com o último id que você viu. retry: 1000 pede ao cliente que espere um segundo. Uma linha de comentário a cada 15 segundos impede que proxies fechem um fluxo parado.
  • Uma chave da equipe inteira abre /inboxes/events. Uma chave restrita a um domínio, ou a uma caixa, abre /inboxes/{id}/events de uma caixa que ela alcança. Uma chave só de envio não abre fluxos.
  • Um agente (uma chave restrita a uma caixa, ou uma conexão MCP) nunca recebe inbox.email.quarantined, nem ao vivo nem no reenvio, assim como nunca lê e-mail retido; pedi-lo em types dá 403 restricted_api_key.
  • Um fluxo fecha em poucos segundos quando a chave é revogada, quando a pessoa que criou a chave sai do time ou quando a caixa é excluída ou expira.
  • Cada chave pode manter 5 fluxos ao mesmo tempo em cada processo da API e cada equipe 25; o seguinte responde 429 too_many_streams com retry-after. Um fluxo para a equipe toda basta para a maioria dos agentes.

O wait de /emails/receiving e de codes/latest é acordado pelos mesmos eventos, então esperar não custa nada enquanto nenhum e-mail chega.

Chaves de API restritas a uma caixa

Dê a cada agente uma chave que alcança só a caixa dele. Veja Chaves de API.

curl -X POST "https://api.billionsend.com/api-keys" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agente de pedidos",
    "permission": "full_access",
    "inbox_id": "7eeb9517-aed7-40d7-ad65-500be42ed147"
  }'
  • Exige permission: "full_access" e não pode ter também um domain_id. Uma caixa tem no máximo 5 chaves ativas, fora do limite de 25 da equipe.
  • A chave lê a caixa dela (conversas, e-mails, rascunhos, etiquetas, códigos, o fluxo de eventos e /emails/receiving limitado à caixa), responde, encaminha, escreve rascunhos e os envia, envia e-mails novos da própria caixa, e envia somente pelo endereço da caixa (403 restricted_api_key para outro from; 550 5.7.1 por SMTP).
  • Todo o resto responde 403 restricted_api_key: ela não altera configurações de segurança, não lista nem libera quarentena, não aprova rascunhos, não cria chaves e não alcança outra caixa.
  • Ela para de funcionar quando a caixa expira, e excluir a caixa a revoga.

No painel, proprietários, administradores e desenvolvedores escolhem a caixa em Restringir a uma caixa de entrada ao criar a chave.

Webhooks

Os eventos de caixa (inbox.created, inbox.thread.created, inbox.email.received, inbox.email.sent, inbox.email.quarantined, inbox.expired, os eventos inbox.draft.* e outros) vão só para endpoints que os citam, nunca para um endpoint inscrito em todos os eventos. Um endpoint pode ser limitado a algumas caixas com inbox_ids. email.received continua disparando para o e-mail de caixa depois de entregue. Payloads: Webhooks.

Atividade

Tudo o que acontece numa caixa fica registrado: envios e decisões das regras, recusas, rascunhos, aprovações, liberações, leituras de código, mudanças de segurança, exclusões e chaves. A aba Atividade da caixa lista isso com quem agiu: uma pessoa, uma chave de API ou um app conectado. As decisões guardam só códigos de motivo, nunca conteúdo, códigos nem endereços.

Limites

Limite Valor
Caixas 3 no Free, 25 no Starter, ilimitadas no Pro e no Scale.
Caixas criadas por hora 10 no Free, 60 no Starter, 600 no Pro e no Scale.
E-mails por caixa 200 mensagens aceitas por hora corrida numa caixa de agente, 2.000 numa caixa de pessoas. Acima disso, os remetentes recebem 452 4.2.2 e tentam de novo mais tarde.
Envios send_cap destinatários por dia UTC. Uma caixa nova alcança destinatários novos aos poucos: 10 no primeiro dia de envio, depois 20, 40, 80, 160 e assim por diante, até o limite.
Destinatários por envio 50 (to, cc e bcc juntos); 10 a partir de um endereço compartilhado.
Anexos por envio 10 MiB decodificados no total; nenhum a partir de um endereço compartilhado.
Domínio compartilhado 1.000 destinatários por dia UTC para todos os endereços compartilhados da sua equipe; uma caixa compartilhada sem uso há 90 dias é excluída.
Etiquetas 100 por caixa.
Listas de segurança 500 entradas na lista de permitidos, 50 endereços de responsáveis, 5 endereços em forward_to.
Chaves restritas a uma caixa 5 ativas por caixa.
Análise 200 mensagens por caixa por dia; acima disso, o e-mail que precisa de análise vai para a quarentena.
Espera 50 segundos por requisição; 20 esperas ao mesmo tempo por equipe em cada processo da API.
Fluxos de eventos 5 por chave de API e 25 por equipe ao mesmo tempo em cada processo da API; os eventos são reenviados por 24 horas.
Rascunhos e lixeira Um rascunho pendente expira em 7 dias; uma conversa na lixeira é excluída após 30.
Retenção O e-mail da caixa segue a retenção do e-mail recebido: 30 dias.

As caixas em si não custam nada: o e-mail recebido conta uma vez por mensagem no seu limite de recebimento, nunca no seu volume de envio, como em Recebimento.

Painel

Caixas de entrada na barra lateral lista as suas caixas nas abas Todas, Agente e Pessoas, com o que precisa de atenção: rascunhos para aprovar, conversas não lidas e mensagens em quarentena. Uma linha fixa Todos os recebidos abre todos os e-mails que os seus domínios receberam. A página de uma caixa tem quatro abas: Conversas (ler, responder e aprovar rascunhos ali mesmo), Precisa de revisão (rascunhos e quarentena), Segurança e regras e Atividade.

Qualquer membro pode trabalhar nas conversas de uma caixa, aprovar rascunhos e liberar a quarentena. Proprietários, administradores e desenvolvedores também podem criar, alterar e excluir caixas, mudar regras de segurança, criar chaves restritas a uma caixa, apagar e-mails recebidos e ligar o pega-tudo. Veja funções da equipe.

MCP

Os clientes MCP trabalham com caixas sob três permissões: receiving:read (ler e-mails, esperar por eles, ler códigos, listar caixas, conversas, etiquetas e rascunhos, buscar conversas, ler as regras de segurança), receiving:reply (responder, encaminhar, enviar de uma caixa, escrever, enviar e excluir rascunhos, organizar conversas e etiquetas) e receiving:manage (criar, alterar e excluir caixas, listar e liberar a quarentena). Um cliente MCP sempre vê os e-mails como um agente: sem os retidos e com o texto das mensagens isolado como não confiável. Ele nunca aprova rascunhos, e create_inbox aceita accept_from e nenhuma outra configuração de segurança; ele nunca altera as regras de segurança de uma caixa.

Notas da API

  • Criar uma caixa ou um rascunho responde o objeto inteiro.
  • email_address é opcional: omitido, a caixa ganha um endereço aleatório e permanente no domínio compartilhado.
  • kind é agent por padrão, então uma caixa criada sem ele ganha as proteções de um agente.
  • Não há agente hospedado: GET /inboxes/{id}/agent responde instructions, tone e actions vazios, e PATCH /inboxes/{id}/agent responde 422.
  • Ainda não há suporte para: headers personalizados em respostas, encaminhamentos e envios de rascunho, e anexos por path (URL remota). Cada um responde 422 a menos que o valor seja vazio.
  • Uma resposta, encaminhamento ou envio de rascunho retido pelas regras da caixa responde 202 com o rascunho em vez de 200 com o e-mail: confira se object é inbox_draft antes de tratar o resultado como enviado.
  • Erros das caixas: 403 inbox_send_policy, 429 inbox_send_cap_reached, 403 approval_required, 403 email_quarantined e 503 name_review_unavailable (veja Erros).
  • Os eventos de webhook inbox.* são opt-in; inbox.thread.assigned e inbox.thread.unassigned não são enviados.

Esta página foi útil?