Entregabilidade e rejeições via API e MCP

O painel do TrekMail apresenta dois tipos de dados de rejeição na guia Estatísticas de cada domínio:

1. Um resumo de 30 dias: quantidades de mensagens enviadas, entregues, com rejeição temporária e com rejeição permanente, além das taxas de entrega e rejeição.
2. Uma lista por destinatário: as últimas 50 rejeições de saída com o código de status e a resposta SMTP do servidor receptor, para que você veja por que uma mensagem específica falhou.

Ambos estão disponíveis pela REST API e pelo servidor MCP. Um agente pode obter os motivos das rejeições, resumir a integridade da reputação e alimentar fluxos de higiene de listas sem abrir o painel.

Dados disponíveis

As três exigem domains:read (ou mailboxes:read para a lista limitada à caixa). Somente leitura. Nenhuma chave de idempotência é necessária.

A API usa os mesmos dados de entregabilidade dos cartões de estatísticas do painel, mantendo as duas visualizações alinhadas.

REST API: exemplos rápidos

Resumo do domínio

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/deliverability?days=30" | jq .

{
  "data": {
    "from": "2026-04-26T00:00:00+00:00",
    "to":   "2026-05-26T23:59:59+00:00",
    "sent": 4180,
    "delivered": 4112,
    "soft_bounce": 22,
    "hard_bounce": 46,
    "forwarding_bounces_excluded": 7,
    "delivery_rate": 0.9837,
    "bounce_rate": 0.0163,
    "status": "good"
  }
}

status é o mesmo sinal de três estados exibido pelo painel:

• good: taxa de rejeição abaixo de 2%.
• warning: taxa de rejeição entre 2% e 5%.
• poor: taxa de rejeição igual ou superior a 5%. Revise e limpe a lista de envio.

forwarding_bounces_excluded informa quantas rejeições relacionadas a encaminhamento foram removidas do cálculo das taxas (como no painel, que as trata como ocorrências de roteamento, e não como problemas da lista do remetente).

Lista de rejeições por destinatário

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/bounces?days=7&type=hard&limit=50" | jq .

{
  "data": [
    {
      "id": 994821,
      "occurred_at": "2026-05-26T18:14:02+00:00",
      "recipient_email": "lost@example.com",
      "event_type": "hard_bounce",
      "smtp_status_code": "550",
      "smtp_response": "5.1.1 The email account that you tried to reach does not exist.",
      "mailbox_id": 7741,
      "domain_id": 123
    }
  ],
  "pagination": { "total": 17, "limit": 50, "offset": 0 }
}

Parâmetros de consulta

Lista limitada à caixa

Para analisar a reputação de cada remetente, limite a consulta a uma caixa:

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/mailboxes/7741/bounces?days=14&type=soft" | jq .

A resposta tem a mesma estrutura do endpoint de domínio.

Privacidade das respostas SMTP

O TrekMail remove informações internas de diagnóstico antes de retornar uma resposta SMTP. A mensagem restante é a mesma exibida ao proprietário da conta no painel e serve para ajudar a diagnosticar a entrega, não para expor detalhes internos do servidor.

Ferramentas MCP

As três ferramentas aceitam os mesmos parâmetros dos endpoints REST. Elas são somente leitura e não alteram mensagens nem configurações da conta.

get_domain_deliverability

{
  "name": "get_domain_deliverability",
  "arguments": {
    "domain_id": 123,
    "days": 30
  }
}

list_domain_bounces

{
  "name": "list_domain_bounces",
  "arguments": {
    "domain_id": 123,
    "type": "hard",
    "days": 7,
    "limit": 100
  }
}

list_mailbox_bounces

{
  "name": "list_mailbox_bounces",
  "arguments": {
    "mailbox_id": 7741,
    "recipient": "@example.com",
    "limit": 50
  }
}

Cabeçalhos de entregabilidade para remetentes em massa

Se você envia mensagens de marketing ou em massa por assinatura, os principais provedores de caixas podem exigir cabeçalhos de cancelamento com um clique. O Google aplica essa regra a mensagens de marketing e por assinatura de remetentes que ultrapassam seu limite de envio em massa; a regra de um clique não se aplica a mensagens transacionais. Há duas maneiras de anexar os cabeçalhos:

Por mensagem (granular). Passe-os pelo campo headers de POST /api/v1/messages/send:

{
  "to": ["recipient@example.com"],
  "subject": "...",
  "body": {"text": "..."},
  "headers": {
    "List-Unsubscribe": "<mailto:bounces@mydomain.com?subject=unsubscribe>, <https://mydomain.com/u/abc123>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}

O campo headers aceita uma pequena lista de itens permitidos: List-Unsubscribe, List-Unsubscribe-Post, Reply-To e qualquer cabeçalho de rastreamento personalizado X-*. A injeção de cabeçalhos (CR/LF) e os cabeçalhos gerenciados (From, Subject, Date, Message-Id, Authentication-Results, DKIM-Signature etc.) são rejeitados com 422.

Na conta inteira (configurar uma vez). Se todas as mensagens de saída dessa conta forem automatizadas, você poderá ativar auto_list_unsubscribe na conta. Quando ativada, a plataforma adiciona um cabeçalho List-Unsubscribe apenas com mailto a todas as mensagens de saída que ainda não tenham um. Ela não adiciona List-Unsubscribe-Post, portanto essa alternativa não oferece cancelamento com um clique conforme a RFC 8058. Para cumprir os requisitos dos provedores, forneça os dois cabeçalhos por mensagem com seu próprio endpoint HTTPS de cancelamento, como no exemplo acima. Os cabeçalhos fornecidos pelo solicitante sempre têm prioridade. A opção fica desativada por padrão e as contas existentes não são alteradas.

Para mensagens pessoais entre duas pessoas, deixe a opção desativada. O Gmail pode mostrar um botão Cancelar inscrição ao lado do remetente quando esse cabeçalho está presente, o que normalmente não é adequado para uma conversa.

Padrões para agentes de IA

Estes endpoints permitem alguns fluxos de alto valor:

• Resumo semanal de reputação. Toda segunda-feira, chame get_domain_deliverability para cada domínio da conta e publique um resumo no Slack/Teams. Destaque apenas os domínios cujo status seja warning ou poor.
• Higiene de lista orientada por rejeições. Chame list_domain_bounces?type=hard&days=14, remova duplicatas de recipient_email e depois suprima esses endereços da sua lista de envio. Rejeições permanentes geralmente indicam que o endereço do destinatário não existe mais, e reenviar consome sua margem de entregabilidade.
• Análise por remetente. Quando o bounce_rate de uma caixa aumentar repentinamente, chame list_mailbox_bounces para ela e agrupe por smtp_status_code. Muitos códigos 550 podem indicar uma lista de endereços desatualizada; muitos códigos 421 podem indicar que o servidor receptor limitou sua frequência.
• Investigação de suporte ao cliente. Quando um usuário informar que uma mensagem não chegou, peça ao agente para chamar list_domain_bounces?recipient=<their-address>. A resposta SMTP pode indicar a próxima ação, como uma caixa do destinatário cheia, um bloqueio do destinatário ou uma rejeição DMARC.

Versionamento

Estes endpoints seguem o mesmo contrato de versionamento do restante da API v1: apenas alterações aditivas e nenhuma renomeação incompatível de campo sem um namespace v2/.

Conteúdo relacionado

• Métricas de spam: telemetria de proteção contra spam de entrada (get_spam_metrics, get_spam_summary).
• Verificador de e-mail: limpeza da lista antes do envio para evitar rejeições.
• Visão geral da API: autenticação, escopos, limites de frequência e idempotência.