Crie fluxos de e-mail de agentes com domínio verificado.

Primeiros passos

O beta pessoal do LoftBox começa com um e-mail de proprietário. O cadastro cria a organização e envia por e-mail um token de verificação de 6 dígitos. Somente após a verificação do e-mail do proprietário o LoftBox retorna a primeira chave de API, e essa chave em texto puro é exibida uma única vez. A verificação também envia ao proprietário um e-mail de boas-vindas com os limites do beta e o caminho futuro de cadastro de administração/faturamento.

Contas do beta pessoal são limitadas a 100 envios de saída por dia. A retenção de mensagens da caixa de correio é, por padrão, de 7 dias. Onboarding empresarial, faturamento, associação à organização e limites maiores são itens do roadmap.

• POST /v1/auth/signupCrie uma organização do beta pessoal e envie o token de verificação do e-mail do proprietário.
• POST /v1/auth/signup/verifyVerifique o e-mail do proprietário, receba a chave de API inicial uma única vez e dispare o aviso de boas-vindas ao proprietário.
• POST /v1/agentsCrie uma identidade de agente com proprietário, finalidade e escopo de política.
• POST /v1/domainsInicie o onboarding de domínio personalizado para um domínio que você controla.
• POST /v1/agents/{agent_id}/mailboxesCrie uma caixa de correio beta gerenciada pelo LoftBox ou uma caixa de correio de domínio personalizado verificado.
• POST /v1/messagesEnvie e-mail operacional a partir da caixa de correio do agente.
• GET /v1/mailboxes/{id}/inboxConsulte mensagens de entrada não confirmadas quando o agente não tiver um endpoint de webhook.

URL base e documentação legível por máquina

O endpoint público canônico da API é https://api.loftbox.net. A página inicial mantém um /api/* caminho de proxy para verificação de preview, mas integrações em produção devem usar o hostname dedicado da API.

export BASE_URL="https://api.loftbox.net"
export LOFTBOX_API_KEY="lb_live_replace_me"

Verifique o edge e o schema antes de conectar uma integração:

curl -i "$BASE_URL/health"
curl -i "$BASE_URL/openapi.json"
curl -i "$BASE_URL/llms.txt"

A https://loftbox.net/api rota remove o /api prefixo e encaminha para a mesma origem da API Fly. Use-a para verificações de preview do Pages, não como URL principal de integração.

Autenticação da API

Comece registrando o e-mail do proprietário para a organização do beta pessoal. O proprietário recebe um token de verificação por e-mail; a chamada de verificação retorna a chave de API inicial uma única vez e envia o aviso de boas-vindas ao proprietário.

export LOFTBOX_OWNER_EMAIL="[email protected]"

curl -i -X POST "$BASE_URL/v1/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "'"$LOFTBOX_OWNER_EMAIL"'",
    "organization_name": "Example Agents",
    "slug": "example-agents"
  }'

export LOFTBOX_VERIFICATION_TOKEN="123456"

curl -i -X POST "$BASE_URL/v1/auth/signup/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "'"$LOFTBOX_OWNER_EMAIL"'",
    "verification_token": "'"$LOFTBOX_VERIFICATION_TOKEN"'"
  }'

Use a chave de API server-side retornada com o cabeçalho Authorization . Nunca exponha chaves de API em navegadores, clientes móveis, logs públicos ou eventos de analytics.

curl -i "$BASE_URL/v1/agents" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

Armazene as chaves em armazenamento de segredos server-side, como Fly secrets, variáveis de ambiente gerenciadas pela plataforma de deploy ou um gerenciador de segredos dedicado. Não cole chaves reais em comentários de issues, capturas de tela, ferramentas de analytics ou código de navegador.

Rotacione as chaves quando um operador sair, um segredo puder ter vazado ou um ambiente não precisar mais de acesso à API.

Instalação em uma linha e prompt do agente

Os agentes podem instalar as skills públicas de e-mail do LoftBox e então executar o fluxo de onboarding apenas com o e-mail do proprietário. A skill de registro deriva o rótulo da organização, o external_idestável, o slug do agente e a parte local da caixa de correio a partir do agente atual. Após o registro, as skills instaladas de envio e verificação de inbox usam a chave de API emitida e o ID da caixa de correio.

curl -fsSL https://loftbox.net/install.sh | sh

curl -fsSL https://loftbox.net/install.sh | sh -s -- --agent codex
curl -fsSL https://loftbox.net/install.sh | sh -s -- --agent claude
curl -fsSL https://loftbox.net/install.sh | sh -s -- --target "$HOME/.my-agent/skills"

If the LoftBox mail skill is missing, install it with:
curl -fsSL https://loftbox.net/install.sh | sh

Use register-loftbox-mail-agent to register this agent for LoftBox personal beta.
Ask me only for my owner email.
After registration, use send-loftbox-mail to send and check-loftbox-mail to check replies.

curl -fsSL https://loftbox.net/install.sh | sh -s -- --check
curl -fsSL https://loftbox.net/install.sh | sh -s -- --update

Use as verificações de atualização apenas como caminho de notificação. Instalar um novo bundle de skills altera o comportamento do agente, portanto as atualizações devem ser executadas após aprovação do operador.

Solicite outro valor somente se a identidade do agente não puder ser derivada ou se um ID externo duplicado pertencer a um agente diferente.

Onboarding de domínio personalizado

Todo domínio de saída deve ser verificado antes que as caixas de correio possam usá-lo. A API retorna os registros DNS necessários para propriedade, roteamento de entrada, alinhamento do remetente e verificação de entrega.

1. Crie o domínio com POST /v1/domains.
2. Busque os registros necessários com GET /v1/domains/{id}/dns.
3. Adicione os registros TXT, MX, DKIM e return-path retornados no seu provedor de DNS.
4. Chame POST /v1/domains/{id}/verify após a propagação do DNS.
5. Aguarde até que os status de entrada e saída estejam ambos verificados antes de criar caixas de correio de produção.

curl -i "$BASE_URL/v1/domains" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"mail.example.com"}'

curl -i "$BASE_URL/v1/domains/domain_uuid/dns" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i -X POST "$BASE_URL/v1/domains/domain_uuid/verify" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

Ou deixe um agente conduzir todo o onboarding empresarial de ponta a ponta com o fluxo unificado onboard-business-domain (autenticação de e-mail → onboarding de domínio → DNS). Cole este prompt no seu agente:

If the LoftBox mail skill is missing, install it with:
curl -fsSL https://loftbox.net/install.sh | sh

Use onboard-business-domain to connect my business domain for verified sending.
Ask me only for my owner email and the domain to send from.

1. Email auth: register my owner email. LoftBox emails a 6-digit token — ask me
   to paste it, then verify to obtain my organization API key (LoftBox-managed
   sending is available immediately once approved).
2. Domain onboard: run add <domain> (note the returned domain id), then read
   next_actions for the exact DNS records (TXT, DKIM, return-path, inbound MX).
   Show me each record (host, type, value).
3. DNS: let me add the records at my DNS host myself, or auto-apply them with
   apply-dns --provider route53|cloudflare using my own cloud credentials from
   the environment (they stay in my environment; LoftBox never receives them).
4. The domain re-verifies asynchronously on the server after DNS propagates.
   Poll status <domain_id> until inbound and outbound are both verified, then
   report — custom-domain sending activates once verified.
Operate only on my organization. Do not fabricate DNS values; use exactly what the API returns. If onboarding cannot proceed (domain previously deleted, or in use by another org), report it and stop.

Skills oficiais & código-fonte

onboard-business-domain e setup-loftbox-domain são skills oficiais do LoftBox. Elas são publicadas no repositório público de skills e instaladas por https://loftbox.net/install.sh — se um agente não conseguir encontrá-las, seu bundle instalado está desatualizado e reexecutar o instalador as adiciona.

• Repositório (público): github.com/TheMagicTower/loftbox-agent-mail-skill
• Diretórios de skills: onboard-business-domain/, setup-loftbox-domain/
• Versão do bundle instalado & commit fixado: loftbox.net/skill-version.json

A setup-loftbox-domain skill é invocada executando seu script diretamente (o instalador não cria um setup-loftbox-domain comando de shell). $SKILL_DIR é onde quer que install.sh tenha colocado a skill — por exemplo ~/.claude/skills/setup-loftbox-domain, ~/.codex/skills/setup-loftbox-domain, ou no Hermes ~/.hermes/skills/email/setup-loftbox-domain. A skill chama a API do LoftBox — use exatamente os valores de DNS que a API retorna, nunca os invente:

SKILL_DIR=<path to setup-loftbox-domain>   # e.g. ~/.claude/skills/setup-loftbox-domain

python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" add <domain>
   # onboard the domain (idempotent: resolves an existing active row on 409)
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" dns <id>
   # list the exact DNS records to set (TXT, DKIM, return-path, MX)
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" status <id>
   # structured status: inbound/outbound flags + next_actions
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" verify <id>
   # trigger verification after the DNS records are in place
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" apply-dns <id> --provider route53|cloudflare [--dry-run] [--overwrite]
   # auto-apply the next_actions records using cloud credentials from your OWN
   # environment (they never leave it). With no credentials, add the records
   # manually instead — onboarding still completes.

onboard-business-domain orquestra register-loftbox-mail-agent (autenticação de e-mail) e setup-loftbox-domain (onboarding de domínio + DNS) de ponta a ponta. A etapa do token de e-mail de 6 dígitos requer um humano, portanto não é totalmente autônoma.

Para o lançamento, o beta pessoal usa entrega gerenciada pelo LoftBox e tratamento de MX de entrada gerenciado pelo LoftBox. Domínios personalizados são habilitados somente após a verificação.

Agentes e caixas de correio

Os agentes contêm a finalidade de negócio, o contexto de propriedade e o ID externo estável. As caixas de correio anexam um endereço e um domínio a esse agente. Mantenha nomes de exibição, proprietários e escopo de política claros o suficiente para a revisão do operador.

• Use uma caixa de correio por agente operacional ou papel de fluxo de trabalho.
• Use external_id para verificações de duplicidade e configuração idempotente do agente.
• Use domínios personalizados verificados para e-mail de saída de produção.
• Desabilite ou retenha envios autônomos quando a finalidade do agente não estiver clara.

curl -i "$BASE_URL/v1/agents?external_id=hermes:support-agent" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i "$BASE_URL/v1/agents" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "slug": "support-agent",
    "external_id": "hermes:support-agent",
    "description": "Handles controlled support follow-up",
    "purpose": "Reply to support conversations after policy checks",
    "owner_label": "Customer Operations",
    "policy_scope": "agent"
  }'

curl -i "$BASE_URL/v1/agents/agent_uuid/mailboxes" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "support-agent",
    "display_name": "Support Agent",
    "retention_days": 7
  }'

Omita domain_id para o domínio do beta pessoal gerenciado pelo LoftBox. Registre um webhook de agente separadamente se o agente tiver um endpoint HTTPS.

Em um domínio personalizado verificado, você pode marcar uma caixa de correio como catch-all ("is_catch_all": true na criação ou atualização). Qualquer endereço nesse domínio sem uma caixa de correio exata é então roteado para ela — útil para capturar support@, sales@, ou anything@yourdomain com um único agente.

Envio de mensagens

Envie mensagens operacionais ou transacionais pela API a partir de uma caixa de correio verificada. O LoftBox registra referências de entrega, estado de entrega, decisões de limite de taxa e resultados de aprovação do operador.

curl -i "$BASE_URL/v1/messages" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mailbox_id": "mailbox_uuid",
  "to": ["[email protected]"],
  "subject": "Support follow-up",
  "body_text": "Thanks for your message. We are checking this now.",
  "metadata": { "ticket_id": "ticket_123" },
  "send_at": "2030-01-01T09:00:00Z"
}'

Passe send_at (RFC3339, futuro) para agendar a entrega, e um cabeçalho Idempotency-Key para deduplicar retentativas (uma repetição retorna a mensagem original). Liste e pesquise mensagens enviadas ou recebidas com GET /v1/messages?q=<text>&label=<name>, e organize threads via POST/DELETE /v1/messages/{id}/labels.

O LoftBox não é um remetente de marketing em massa. Listas compradas, destinatários extraídos por scraping e uso de relay SMTP genérico estão fora da política do MVP.

Webhooks de entrada e polling

As respostas são armazenadas como mensagens de entrada. Agentes com um endpoint HTTPS podem receber eventos de webhook assinados; agentes sem um deles devem consultar a inbox da caixa de correio e confirmar cada mensagem processada.

• message.inboundUma nova mensagem de entrada ou resposta foi analisada, organizada em thread e disponibilizada ao webhook configurado.
• message.deliveredA entrega foi reportada para o destinatário.
• message.failedA entrega de saída falhou permanentemente ou esgotou o tratamento de retentativas.

curl -i "$BASE_URL/v1/agents/agent_uuid/webhooks" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/loftbox",
    "event_types": [
      "message.inbound",
      "message.delivered"
    ]
  }'

O segredo do webhook é retornado uma única vez quando o webhook é criado. Armazene-o imediatamente e verifique toda assinatura de entrada antes de confiar no conteúdo do evento.

curl -i "$BASE_URL/v1/mailboxes/mailbox_uuid/inbox?limit=20" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i -X POST "$BASE_URL/v1/mailboxes/mailbox_uuid/inbox/ack" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message_ids":["message_uuid_or_msg_public_id"]}'

Confirme somente após o agente ter processado a mensagem de forma durável. O polling de inbox vazia deve aplicar backoff; o polling ativo deve usar um intervalo moderado, como 30-60 segundos.

Streaming em tempo real (WebSocket)

Agentes que não conseguem hospedar um webhook HTTPS (por exemplo, executando atrás de NAT ou de um firewall) podem assinar eventos em tempo real por meio de um WebSocket. O stream transporta os mesmos tipos de evento que os webhooks, com entrega em menos de um segundo e replay baseado em cursor de eventos perdidos enquanto desconectado. Requer o escopo receive .

• GET /v1/wsUpgrade de WebSocket. Autentique com Authorization: Bearer. Filtre com ?event_types= e ?agent_id=; retome com ?after=<cursor>.
• GET /v1/ws/asyncapi.jsonEspecificação AsyncAPI para o stream (pública).

wscat -c "wss://api.loftbox.net/v1/ws?event_types=message.inbound" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

# frames: {"type":"ready",...} then {"type":"event","event":{...},"cursor":"..."}
# on reconnect, pass ?after=<last cursor> to replay missed events

Em um error frame com código lagged ou resync_required, reconecte usando o último cursor recebido.

Permissões e chaves de API

As chaves de API carregam escopos. Escopos amplos (send, receive, admin) implicam escopos granulares (message:send, message:read, domain:manage, approval:decide, keys:manage, …), de modo que as chaves existentes continuam funcionando enquanto você pode emitir chaves filhas de menor privilégio para sub-agentes.

• POST /v1/auth/keysEmita uma chave filha. Os escopos solicitados devem ser um subconjunto dos do chamador (sem escalonamento de privilégios). Opcional expires_in_days. Chave em texto puro retornada uma única vez.
• GET /v1/auth/keysListe as chaves da organização (somente metadados, sem segredos). Requer keys:manage.
• DELETE /v1/auth/keys/{id}Revogue uma chave e todos os seus descendentes (cascata). Permitido para keys:manage ou para o pai da chave.

Relatórios agregados DMARC

Provedores de caixa de correio (Gmail, Outlook, Yahoo, …) enviam diariamente relatórios agregados (rua) DMARC resumindo quais IPs de origem enviaram e-mail como seus domínios verificados e se SPF/DKIM/DMARC estavam alinhados. O LoftBox ingere esses dados em relatórios estruturados para que você possa monitorar a entregabilidade e detectar spoofing. Cada relatório armazenado também registra o domínio autenticado do reportador.

• GET /v1/dmarc/reportsListe os relatórios agregados DMARC da sua organização, do mais recente ao mais antigo. Paginação por cursor via before_date_end + before_id (retornados juntos como next_cursor). Requer domain:read.
• GET /v1/dmarc/reports/{id}Recupere um relatório com seus registros por IP de origem (contagem de mensagens, disposição, alinhamento DKIM/SPF, header-from). Requer domain:read.

curl -i "$BASE_URL/v1/dmarc/reports" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i "$BASE_URL/v1/dmarc/reports/REPORT_ID" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

Os relatórios aparecem conforme os provedores os enviam (normalmente uma vez por dia por reportador). Somente relatórios dos seus próprios domínios verificados são retornados; relatórios da plataforma ou de domínios não hospedados nunca são expostos.

Eventos de entrega

O status de entrega é normalizado entre callbacks de entrega gerenciada e o estado interno de envio. Use IDs de evento e referências de entrega para suporte, não dados privados do destinatário.

• queued: aceito pelo LoftBox para entrega.
• sent: aceito para entrega de saída.
• delivered: a entrega foi reportada para o destinatário.
• failed: a entrega falhou permanentemente ou esgotou as retentativas.
• blocked: política, limite de taxa ou controle de relatório bloqueou o envio.

Limites de taxa e controles de relatório

O envio de saída é limitado por política de organização, agente, caixa de correio, destinatário e domínio. Organizações do beta pessoal têm limite de 100 envios por dia. Mensagens de alto risco podem ser retidas para aprovação antes de a entrega ser tentada.

Trate as respostas 429 aplicando backoff. Não tente novamente indefinidamente nem ignore retenções de aprovação a partir de outra caixa de correio.

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Entrega gerenciada e configuração de segurança

O LoftBox opera a entrega de saída gerenciada para contas beta. A documentação pública deve descrever os controles visíveis ao cliente sem expor nomes internos de fornecedores, credenciais ou detalhes de roteamento.

• Natureza do negócio: identidades de e-mail operacional gerenciadas por API para agentes de IA com domínio verificado.
• Tipos de e-mail: notificações transacionais/de sistema, respostas de agente iniciadas por usuários verificados, mensagens de onboarding/teste e tratamento de relatórios/contatos.
• Controles: somente domínios verificados, limites de taxa explícitos, logs de entrega, tratamento de supressão/reclamação e contato de relatório monitorado.
• Páginas públicas: Privacidade, Termos, e Política antispam.

As retenções de propagação de DNS e de verificação de entrega devem ser tratadas como estado de configuração, não como prova de que o proxy da API ou a documentação da página inicial estão quebrados.