SendHQ

Envie e receba e-mails dos seus domínios verificados; gerencie domínios, modelos e entregabilidade.

Ver em sendhq.ccExperimente este MCPPatrocinado

Documentação

Servidor MCP SendHQ

Dê a um agente de IA controle total e seguro de um workspace SendHQ por meio de 59 ferramentas MCP estritamente tipadas. Servidor stdio local: sendhq mcp.

curl -fsSL https://downloads.sendhq.cc/install.sh | sh
claude mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp

O que é este servidor

O servidor MCP SendHQ permite que um agente de IA opere um workspace SendHQ por meio do Model Context Protocol: enviar e-mail (único, em lote, com modelo, respostas, anexos, novas tentativas idempotentes), ler e pesquisar e-mails enviados e recebidos (assuntos, corpos e nomes de anexos) e seus eventos de entrega, organizar e-mails em etiquetas com regras de arquivamento automático, gerenciar rascunhos e anexos privados, criar e publicar modelos hospedados, adicionar e verificar domínios e seus DNS, configurar recebimento de e-mails e endereços de entrada, inspecionar entregabilidade, rejeições, reclamações e supressões, e ler uso da conta, estado de cobrança, análises e metadados de chaves de API.

É um servidor local stdio integrado ao binário da CLI sendhq. Seu cliente MCP inicia sendhq mcp como um processo filho e fala JSON-RPC via stdin/stdout. Cada chamada de ferramenta se torna uma solicitação documentada à API REST do SendHQ em https://sendhq.cc/api/v1 autenticada com a chave de API do seu workspace, então o servidor MCP tem exatamente as permissões dessa chave e nada mais.

  • 59 ferramentas em 8 grupos, geradas a partir de um catálogo que também é publicado como tools.json.
  • Schemas JSON estritos: argumentos desconhecidos, tipos errados e campos obrigatórios ausentes são rejeitados localmente antes que qualquer coisa chegue ao SendHQ.
  • Erros estruturados com um code estável, o status HTTP, um explanation, um remedy concreto e se uma nova tentativa pode ajudar.
  • Toda ferramenta que envia e-mail real ou destrói dados diz isso nas primeiras palavras de sua descrição e carrega anotações de segurança MCP.
  • O modo --read-only oculta todas as ferramentas de envio e mutação.
  • Nada é registrado. stdout carrega apenas mensagens de protocolo; a chave de API e o conteúdo das mensagens nunca chegam a um log.

Não é o endpoint MCP de documentação. O SendHQ também hospeda um pequeno endpoint MCP de documentação somente leitura em https://sendhq.cc/api/mcp (preços e consulta de documentação, sem acesso à conta). O servidor nesta página é o completo, com escopo de conta; ele roda localmente ou como o conector hospedado abaixo.

Usar o SendHQ no Claude e no ChatGPT

Sem necessidade de instalação: o SendHQ também executa este servidor como um conector hospedado em https://mcp.sendhq.cc/mcp com as mesmas ferramentas. Você entra com sua conta SendHQ em vez de colar uma chave.

Claude

  1. Abra Configurações → Conectores e encontre o SendHQ no diretório, ou escolha Adicionar conector personalizado e cole https://mcp.sendhq.cc/mcp.
  2. Clique em Conectar, entre no SendHQ, revise o acesso e clique em Permitir.
  3. Peça ao Claude para verificar sua caixa de entrada, enviar um e-mail do seu domínio verificado ou explicar uma rejeição.

ChatGPT

  1. Abra Configurações → Segurança e login e ative o Modo de desenvolvedor.
  2. Vá para chatgpt.com/plugins, clique em Criar app MCP, nomeie como SendHQ e insira https://mcp.sendhq.cc/mcp.
  3. Entre no SendHQ e clique em Permitir, depois escolha SendHQ no menu de ferramentas em um novo chat.

Muse by Meta

No Muse, abra Conectores e pesquise por SendHQ. Clique em Conectar, entre no SendHQ e clique em Permitir.

Aprovação e desconexão

  • A ferramenta request_feature envia uma solicitação de recurso à equipe do SendHQ com os detalhes da sua conta, para que possamos acompanhar por e-mail.
  • Ferramentas que enviam e-mail real ou excluem dados são rotuladas como tal. Se o assistente pergunta primeiro é definido por ferramenta no assistente: no Claude, escolha Precisa de aprovação para essas ferramentas em Configurações → Conectores → SendHQ.
  • O conector recebe sua própria chave de API, nomeada após o assistente (por exemplo, "Claude (conector de IA)"). Exclua-a em Chaves de API para desconectar imediatamente.
  • Ele não pode criar ou revogar chaves de API nem alterar cobrança. Anexos são enviados e retornados como base64; não há acesso a arquivos locais.
  • Workspaces não pagos (teste de integração) podem entregar apenas para o e-mail da conta ou um endereço de simulador AWS SES.

Perguntas: postmaster@sendhq.cc. Privacidade: sendhq.cc/privacy.

Instalação

Instale o binário sendhq (Linux, macOS e Windows em x86-64 e arm64). O instalador verifica a soma de verificação do release e coloca o binário em ~/.local/bin por padrão.

macOS e Linux:

curl -fsSL https://downloads.sendhq.cc/install.sh | sh

Windows PowerShell:

irm https://downloads.sendhq.cc/install.ps1 | iex

Verifique a instalação:

sendhq version
SENDHQ_API_KEY=re_your_key sendhq doctor

Crie uma chave de API no painel em https://sendhq.cc/app#/keys. O servidor MCP não pode criar chaves. O único comando que executa o servidor é:

Execute o servidor stdio:

SENDHQ_API_KEY=re_your_key sendhq mcp

Normalmente você nunca executa isso manualmente: o cliente MCP o inicia. Quando executado em um terminal, ele aguarda JSON-RPC no stdin.

Configurar seu cliente

Claude Code

claude mcp add:

claude mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp

# read-only variant
claude mcp add sendhq-readonly --env SENDHQ_API_KEY=re_your_key -- sendhq mcp --read-only

Adicione --scope user para disponibilizá-lo em todos os projetos, ou --scope project para escrevê-lo no .mcp.json do projeto. Para um .mcp.json compartilhado, referencie a chave do ambiente em vez de commitá-la; o Claude Code expande ${VAR} em .mcp.json.

.mcp.json:

{
  "mcpServers": {
    "sendhq": {
      "command": "sendhq",
      "args": [
        "mcp"
      ],
      "env": {
        "SENDHQ_API_KEY": "${SENDHQ_API_KEY}"
      }
    }
  }
}

OpenAI Codex

~/.codex/config.toml:

[mcp_servers.sendhq]
command = "sendhq"
args = ["mcp"]
env = { SENDHQ_API_KEY = "re_your_key" }

Ou pela linha de comando: codex mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp.

Claude Desktop

Edite claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) e reinicie o aplicativo. Aplicativos de desktop não herdam o PATH do seu shell, então use o caminho absoluto do binário (which sendhq).

claude_desktop_config.json:

{
  "mcpServers": {
    "sendhq": {
      "command": "/Users/you/.local/bin/sendhq",
      "args": [
        "mcp"
      ],
      "env": {
        "SENDHQ_API_KEY": "re_your_key"
      }
    }
  }
}

Qualquer outro cliente MCP

Configure um servidor stdio com o comando sendhq, argumentos ["mcp"] (opcionalmente "--read-only") e as variáveis de ambiente abaixo. O servidor suporta versões de protocolo MCP 2024-11-05, 2025-03-26, 2025-06-18 e 2025-11-25, e implementa initialize, ping, tools/list e tools/call. Os resultados das ferramentas carregam tanto um bloco de texto JSON quanto structuredContent.

Teste rápido de stdio bruto (canalize para sendhq mcp):

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_service_health","arguments":{}}}

Não há transporte HTTP hospedado para o servidor com escopo de conta. Um endpoint MCP remoto com capacidade de escrita exigiria OAuth por usuário, o que o SendHQ não oferece; o binário local mantém a chave na máquina que já a possui.

Ambiente e flags

Variável ou flagObrigatóriaSignificado
SENDHQ_API_KEYsimChave de API do workspace (re_…). Toda ferramenta exceto get_service_health precisa dela. Sem ela, o servidor ainda inicia e toda chamada retorna um auth_error estruturado explicando como corrigir.
SENDHQ_API_BASE_URLnãoURL base da API. Padrão https://sendhq.cc/api/v1. Use apenas para uma implantação local ou de staging. SENDHQ_BASE_URL é aceito como um alias mais antigo.
SENDHQ_MCP_READ_ONLYnão1, true ou yes se comporta como --read-only.
--read-onlynãoExpõe apenas ferramentas que não enviam e-mail nem alteram estado. Ferramentas ocultas também são recusadas se chamadas pelo nome.
SENDHQ_PROFILE / --profilenãoUsa uma chave armazenada por sendhq auth login no chaveiro do SO em vez de SENDHQ_API_KEY. A variável de ambiente vence quando ambas existem.

A chave é enviada apenas como o cabeçalho Authorization: Bearer para a URL base configurada. Ela nunca é impressa, registrada, ecoada em erros ou incluída nos resultados das ferramentas.

Modelo de segurança para agentes

  • Envia e-mail real. send_email, send_batch e send_template_test entregam mensagens a pessoas reais e consomem créditos de entrega. Suas descrições começam com SENDS REAL EMAIL. Chame-as apenas quando o usuário pediu explicitamente que aquela mensagem específica fosse enviada, com destinatários, remetente e conteúdo confirmados.
  • Destrutivo. delete_email, delete_draft, delete_attachment, delete_domain, delete_inbox e remove_suppression são marcadas como destructiveHint: true e suas descrições começam com DESTRUCTIVE. Confirme com o usuário primeiro. remove_suppression enfraquece um bloqueio de segurança e é apropriada apenas quando um humano confirma que o endereço voltou a funcionar.
  • Altera estado. Criar ou atualizar rascunhos, modelos, domínios e caixas de entrada, publicar modelos e iniciar verificação alteram o workspace, mas não enviam e-mail.
  • Somente leitura. Todo o resto é readOnlyHint: true e seguro para chamar livremente.
  • DNS nunca é alterado por este servidor. add_domain retorna registros para um humano publicar; get_domain_connect_link retorna uma URL de consentimento que uma pessoa deve abrir e aprovar no provedor de DNS.
  • Cobrança nunca é alterada por este servidor. get_account lê apenas plano, uso e estado de assinatura.
  • Workspaces não pagos (teste de integração) podem entregar apenas para o e-mail do proprietário da conta (get_account → user.email) ou um endereço de simulador AWS SES como success@simulator.amazonses.com, e não podem enviar anexos.
  • Aceito não é entregue. Um envio bem-sucedido retorna um ID; evidências de entrega, rejeição e reclamação chegam depois em list_email_events. Nunca afirme colocação na caixa de entrada ou que uma pessoa leu uma mensagem.
  • Não alterne para um endereço De diferente para contornar uma pausa de 423, e nunca re-adicione destinatários que cancelaram a assinatura ou reclamaram.

Chaves de API estão fora do escopo

Por design, não há ferramentas que criem, modifiquem, rotacionem, revoguem ou excluam chaves de API. Um agente não deve criar ou destruir credenciais. list_api_keys retorna apenas nomes, prefixos não secretos e horários do último uso. O gerenciamento de chaves permanece no painel com um humano autenticado.

Fluxos de trabalho

1. Primeiro envio

  1. get_service_health confirma que a API está acessível (funciona sem chave).
  2. get_account mostra o plano (access.tier), a cota restante e user.email. No teste, esse e-mail é o único destinatário real permitido.
  3. list_sending_identities lista endereços De que você pode usar. Se estiver vazio, faça o fluxo de domínio primeiro.
  4. Confirme remetente, destinatário, assunto e corpo com o usuário, depois send_email com um idempotency_key.
  5. list_email_events com o id retornado mostra delivery, bounce, complaint ou reject assim que o provedor reportar (geralmente segundos a minutos).

Primeiro envio:

{
  "name": "send_email",
  "arguments": {
    "from": "Acme <hello@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "SendHQ is connected",
    "text": "It works.",
    "idempotency_key": "first-send-2026-09-26"
  }
}

2. Verificação de domínio de ponta a ponta

  1. add_domain com name: "example.com". O resultado inclui os registros DNS (CNAMEs DKIM, verificação SES, SPF, DMARC recomendado).
  2. get_dns_provider com o domain_id detecta o provedor de DNS autoritativo e retorna o host relativo exato a inserir para cada registro nesse provedor.
  3. Se providers.domainConnect.available for verdadeiro, get_domain_connect_link retorna uma URL de consentimento. Entregue-a ao humano; nada muda até que ele aprove no provedor. Caso contrário, entregue os registros ao humano para publicar. Nunca publique um segundo registro SPF: mescle include:amazonses.com no valor v=spf1 existente.
  4. verify_domain reverifica DNS e SES. O status avança por pending, checking e propagating até verified. Consulte verify_domain ou get_domain a cada 30–60 segundos; o DNS pode levar minutos a horas.
  5. Quando status for verified, os endereços do domínio aparecem em list_sending_identities.

3. Rejeições, reclamações e supressões

  1. list_blocked_recipients retorna todo endereço bloqueado com seu motivo (bounce, complaint, unsubscribe) e uma contagem resumida.
  2. list_suppressions retorna supressões por rejeição permanente e reclamação; deliverability_stats fornece taxas de entrega, rejeição e reclamação de 30 dias; list_sender_reputation mostra quais endereços De estão limitados ou pausados.
  3. Um envio contendo um destinatário suprimido falha com 422 recipient_suppressed. Remova esse destinatário e envie novamente.
  4. Somente quando um humano confirmar que uma caixa de entrada rejeitada agora funciona, chame remove_suppression. Supressões por reclamação são permanentes (409 complaint_suppression_locked).

4. Receber e-mail de entrada

  1. O domínio (geralmente um subdomínio como inbound.example.com) deve ser verificado.
  2. setup_inbound provisiona o recebimento e retorna um registro MX. Uma pessoa publica ele.
  3. verify_inbound até status ser ready.
  4. create_inbox com domain_id e local_part (por exemplo support) cria support@inbound.example.com.
  5. Consulte list_emails com direction: "in" e unread: true (opcionalmente inbox_id). Leia uma mensagem com get_email, sua conversa com get_thread, anexos com download_attachment e marque-a como tratada com mark_email (read: true).
  6. Responda no mesmo tópico com send_email e reply_to_email_id; o SendHQ define In-Reply-To, References e o tópico.

5. Webhooks e notificações de eventos

O SendHQ atualmente não oferece webhooks configuráveis pelo cliente, portanto não há ferramenta de webhook. As notificações do provedor são processadas dentro do SendHQ e expostas por meio de leituras. Em vez disso, faça polling: list_email_events para o resultado de uma mensagem, list_emails com status (por exemplo bounced) ou after para alterações recentes, list_emails com direction: "in" e unread: true para novos e-mails recebidos e list_blocked_recipients para novas supressões. Faça polling no máximo cerca de uma vez por minuto por pergunta.

6. Diagnosticar uma falha de entrega

  1. Encontre a mensagem: list_emails com direction: "out" e to ou query, ou get_email se você tiver o ID. status: failed significa que o SendHQ ou o provedor a rejeitou no envio; o erro do e-mail explica o motivo.
  2. list_email_events: bounce (permanente ou transitório, com o diagnóstico do provedor), complaint, reject ou delivery. Ainda não há eventos significa que o provedor não relatou; aguarde e verifique novamente.
  3. Se a própria chamada de envio falhou, leia o erro code: sender_domain_unverified → conclua a verificação do domínio; recipient_suppressed → o endereço teve bounce permanente ou reclamou antes; sender_paused → inspecione list_sender_reputation e corrija a origem da lista; trial_recipient_restricted → limites de teste; quota_exhausted → uso de get_account.
  4. get_domain verifica se DKIM, SPF e DMARC ainda estão publicados; deliverability_stats mostra se o problema é uma mensagem ou uma tendência.
  5. Relate o que as evidências mostram. Um evento delivery significa que o servidor do destinatário aceitou a mensagem, não que ela chegou à caixa de entrada ou foi lida.

7. Ter um bucket de tarefas (etiquetas)

  1. create_label com name (por exemplo Agent/Orders) e skip_inbox: true. Isso torna a etiqueta um bucket: o e-mail recebido que a recebe é arquivado, aparecendo apenas na etiqueta, nunca na Caixa de entrada da pessoa.
  2. Envie e-mails de tarefa com send_email (ou send_batch) e labels: ["Agent/Orders"]. As respostas a essa conversa herdam a etiqueta automaticamente e pulam a Caixa de entrada.
  3. Para e-mails que começam fora das suas conversas, adicione uma regra de arquivamento: create_label_rule com inbox_id (um endereço dedicado como orders@…), from, to ou subject. Passe apply_to_existing: true para arquivar e-mails já recebidos.
  4. Trabalhe no bucket: list_emails com label: "Agent/Orders", direction: "in" e unread: true; leia com get_email ou get_thread, responda com send_email e reply_to_email_id e mark_email read: true quando tratado.
  5. Mova uma mensagem solta para dentro ou para fora com label_email (add / remove). Adicionar uma etiqueta de bucket a uma mensagem recebida também a arquiva.
  6. Opcionalmente, set_inbox_forwarding envia uma cópia de tudo o que um endereço receptor recebe para outra caixa de correio (o destino confirma por e-mail primeiro).

Enviar para um bucket:

{
  "name": "send_email",
  "arguments": {
    "from": "Orders <orders@example.com>",
    "to": [
      "customer@example.net"
    ],
    "subject": "Order 1042: confirm delivery window",
    "text": "Reply with a time that works.",
    "labels": [
      "Agent/Orders"
    ],
    "idempotency_key": "order-1042-window"
  }
}

8. Anexos e modelos

Anexe até 10 arquivos com send_email attachments (cada um precisa de content_base64 ou um file_path local; filename usa como padrão o nome base do arquivo) em um plano pago. Para modelos hospedados: create_template → update_template_draft → render_template para visualizar com dados de exemplo → send_template_test (envia um teste real) → publish_template, depois envie com send_email ou send_batch usando template: {key, data} e exatamente um destinatário to.

Resultados, paginação e erros

Uma chamada bem-sucedida retorna o objeto JSON da API como structuredContent e como um bloco de texto JSON. Toda ferramenta list_* aceita limit (1–200, padrão 50) e offset, e adiciona um objeto pagination. Continue chamando com offset: pagination.next_offset enquanto has_more for verdadeiro.

Resultado paginado:

{
  "data": [
    "…"
  ],
  "count": 50,
  "pagination": {
    "offset": 0,
    "limit": 50,
    "returned": 50,
    "total": 180,
    "has_more": true,
    "next_offset": 50
  }
}

Uma chamada com falha retorna isError: true com um erro estruturado. Siga remedy em vez de tentar novamente às cegas; só tente novamente quando retryable for verdadeiro.

Erro estruturado de ferramenta:

{
  "error": {
    "code": "trial_recipient_restricted",
    "status": 402,
    "message": "The integration trial can deliver only to your account email or an AWS SES simulator address",
    "retryable": false,
    "explanation": "This workspace is on the unpaid integration trial. Trial sends can be delivered only to the account owner's email address or an AWS SES simulator address.",
    "remedy": "Send to the account email (get_account -> user.email) or a simulator address such as success@simulator.amazonses.com to test. To email anyone else, the account owner must activate a paid plan in the dashboard (Profile & Billing). Do not retry the same recipients."
  }
}

Campos de erro opcionais: request_id (cite-o para suporte), retry_after_seconds, problems (lista de violações de esquema para invalid_arguments) e idempotent_replayed (veja Idempotência).

Idempotência

send_email e send_batch aceitam idempotency_key (máximo de 200 caracteres), enviado como o cabeçalho Idempotency-Key. Gere uma chave estável por mensagem lógica, por exemplo invoice-4812-receipt.

  • Uma nova tentativa deve reutilizar a mesma chave E um corpo de solicitação idêntico. A mesma chave com qualquer alteração (destinatário, assunto, corpo, cabeçalho, dados de modelo, até valores de argumento) retorna 409 idempotency_conflict.
  • Mesma chave, mesmo corpo, original concluído: o SendHQ retorna o resultado armazenado sem enviar novamente. É assim que você tenta novamente com segurança após um timeout ou network_error.
  • Mesma chave enquanto o original ainda está em execução: 409 idempotency_in_progress, pode ser tentado novamente após uma curta espera.
  • Uma nova mensagem lógica precisa de uma nova chave.
  • Falhas armazenadas também são repetidas. Se a primeira tentativa falhou, tentar novamente com a mesma chave retorna a mesma falha com idempotent_replayed: true e retryable: false. Verifique list_emails (direction: out) para confirmar que nada foi enviado, corrija a causa e envie com uma chave nova.
  • O servidor nunca tenta um POST novamente por conta própria. Apenas chamadas GET somente leitura são repetidas automaticamente (até 3 tentativas em erros de rede, 429 e 5xx).
  • send_email com attachments inline não pode aceitar um idempotency_key, porque executa várias solicitações. Para envios com anexos seguros para nova tentativa: create_draft → upload_attachment → send_email com draft_id e idempotency_key.

Envio seguro para nova tentativa (repita exatamente em timeout):

{
  "name": "send_email",
  "arguments": {
    "from": "Acme <billing@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "Receipt #4812",
    "text": "Thanks for your payment.",
    "idempotency_key": "receipt-4812"
  }
}

Limites de taxa e cotas

O SendHQ não publica um limite fixo de solicitações por segundo para a API. Os limites que um agente realmente encontra são limites de uso, retornados como 429:

  • Entregas mensais de destinatários por plano. Cada endereço Para, Cc e Cco conta como uma entrega. Veja get_account → usage.recipientDeliveries vs usage.emailQuotaMonth.
  • Destinatários diários por endereço De exato, definido pelo estado de reputação do remetente (list_sender_reputation → dailyLimit, 2.000 por padrão em planos pagos).
  • Teste de integração: 100 destinatários no total, apenas para o e-mail da conta ou endereços do simulador SES.
  • Anexos: no máximo 10 arquivos e 10 MB por mensagem; 10 GB de transferência de anexos ponderada por destinatário por mês em planos pagos.
  • Por solicitação: Para + Cc + Cco até 100 endereços; send_batch até 100 mensagens.
  • Disjuntor de reputação: em uma janela móvel de 7 dias, bounces ou reclamações acima do limite pausam ou limitam um endereço De (423 sender_paused). Ele se recupera automaticamente quando as taxas caem.

quota_exhausted não pode ser tentado novamente até o período reiniciar ou o plano mudar. rate_limited pode ser tentado novamente após retry_after_seconds; para envios, tente novamente com o mesmo idempotency_key e corpo idêntico.

Catálogo de erros

code é estável; use-o em vez de message.

códigoHTTPTentar novamente?O que significa e o que fazer
invalid_arguments—nãoOs argumentos falharam no esquema JSON da ferramenta localmente; nada chegou ao SendHQ. Corrija os campos listados em problems.
auth_error401nãoChave de API ausente, revogada ou incorreta. Defina SENDHQ_API_KEY para o processo do servidor; uma pessoa cria chaves no painel.
trial_recipient_restricted402nãoO teste de integração só pode entregar para o e-mail da conta ou um endereço do simulador SES. Envie para lá, ou o proprietário ativa um plano pago.
payment_required402nãoO recurso precisa de um plano pago (por exemplo, anexos). Envie sem ele ou faça upgrade.
sender_domain_not_owned403nãoO domínio De não está neste workspace. Use list_sending_identities ou add_domain.
sender_domain_unverified403nãoO domínio De ainda não está verificado. get_domain, publique os registros ausentes, verify_domain.
domain_limit_reached403nãoLimite de domínios do plano atingido. Remova um domínio não utilizado (com aprovação) ou faça upgrade.
marketing_not_enabled403nãoA classe de marketing não está habilitada para este domínio ou plano. Use transactional somente se a mensagem realmente for.
forbidden403nãoA política não permite a operação. Ajuste a solicitação.
not_found404nãoO ID não está neste workspace. Liste o recurso para encontrar o ID correto; restaure modelos arquivados primeiro.
idempotency_conflict409nãoChave reutilizada com um corpo diferente. Reenvie o original exato ou use uma nova chave para uma nova mensagem.
idempotency_in_progress409simA solicitação original ainda está em execução. Aguarde e tente novamente com a mesma chave e corpo.
revision_conflict409nãoO rascunho do modelo mudou desde que você o leu. get_template, mescle, salve novamente.
complaint_suppression_locked409nãoO destinatário reclamou. Nunca envie e-mail para ele novamente.
inbound_not_ready409nãoO recebimento de entrada não está pronto. setup_inbound, publique MX, verify_inbound.
conflict409nãoO recurso já existe ou está no estado errado. Leia-o e ajuste.
attachments_too_large413nãoMais de 10 arquivos ou 10 MB. Remova ou reduza os anexos.
recipient_suppressed422nãoUm destinatário teve bounce permanente ou reclamou antes. Remova-o; veja list_blocked_recipients.
recipient_unsubscribed422nãoUm destinatário optou por não receber e-mails de marketing. Remova-o permanentemente.
validation_failed422nãoConteúdo rejeitado, por exemplo, dados de modelo que quebram o contrato de variáveis. Corrija a entrada.
sender_paused423nãoEste endereço De está pausado pelo disjuntor de bounce/reclamação de 7 dias. Pare, corrija a lista, aguarde a recuperação automática.
quota_exhausted429nãoLimite mensal, diário por remetente, de anexos ou de teste atingido. Verifique get_account; aguarde a reinicialização ou faça upgrade.
rate_limited429simReduza a velocidade; aguarde retry_after_seconds. Envios: mesma chave, mesmo corpo.
server_error5xxsimFalha temporária do SendHQ ou do provedor. Aguarde e tente novamente; envios com a mesma chave e corpo. Se idempotent_replayed for verdadeiro, use uma nova chave após confirmar que nada foi enviado.
network_error—simSolicitação ou resposta perdida. Tente novamente; para envios, o mesmo idempotency_key torna isso seguro.
invalid_request400nãoSolicitação malformada. Leia message e corrija-a.
tool_error—nãoFalha local dentro do servidor MCP (por exemplo, um file_path ilegível). Leia message.

Referência de ferramentas

Cada ferramenta com sua classe de segurança, o endpoint REST que ela chama, seus parâmetros, formato de retorno e um exemplo de objeto de parâmetros tools/call. Os parâmetros são exatos: o servidor rejeita qualquer coisa não listada.

E-mails e tópicos

send_email

Enviar um e-mail · Envia e-mail real · POST /emails ENVIA E-MAIL REAL. Envia uma mensagem de um domínio verificado: html/texto bruto, um template hospedado publicado, uma resposta em uma conversa existente ou uma mensagem com anexos. Passe idempotency_key para que uma nova tentativa não envie duas vezes; uma nova tentativa deve reutilizar a mesma chave E uma solicitação idêntica, caso contrário o SendHQ retorna 409. attachments é uma conveniência que cria um rascunho, envia cada arquivo e envia com esse rascunho; não pode ser combinado com idempotency_key ou draft_id (use create_draft + upload_attachment + send_email com draft_id para envios de anexos seguros contra novas tentativas). Workspaces não pagos (teste de integração) podem entregar apenas para o e-mail da conta ou um endereço do simulador AWS SES, e não podem enviar anexos.

Forneça pelo menos um de: html, text, template.

ParâmetroTipoObrigatórioDescrição
fromstringsimRemetente, ex.: Acme <hello@example.com>. O domínio deve ser verificado neste workspace (veja list_sending_identities). (máx. 998 caracteres)
tostring[]simDestinatários. Cada entrada é um endereço, opcionalmente com um nome de exibição. To+cc+bcc podem totalizar no máximo 100; cada destino consome um crédito de entrega. (1–100 itens)
ccstring[]nãoDestinatários em cópia carbono. (0–100 itens)
bccstring[]nãoDestinatários em cópia oculta. (0–100 itens)
subjectstringnãoLinha de assunto. Omita ao enviar um template. (máx. 998 caracteres)
textstringnãoCorpo em texto simples. Forneça texto, html ou template.
htmlstringnãoCorpo em HTML. O SendHQ o sanitiza e deriva o texto quando text é omitido.
reply_tostringnãoEndereço de resposta (Reply-To).
headersobjectnãoCabeçalhos personalizados extras e seguros (valores de string), ex.: {"X-Entity-Ref-ID": "123"}. Cabeçalhos de roteamento como From/To/Message-ID são controlados pelo SendHQ.
message_classstringnãotransactional (padrão) ou marketing. Marketing requer um plano ou domínio habilitado para marketing e adiciona tratamento de cancelamento de inscrição. (um de transactional, marketing)
reply_to_email_idstringnãoResponder dentro de uma conversa existente: o ID em_… da mensagem que está sendo respondida. O SendHQ define In-Reply-To/References e o thread.
thread_idstringnãoID de thread explícito para arquivar a mensagem.
draft_idstringnãoEnviar os anexos de um rascunho armazenado com esta mensagem (dr_…). O rascunho é excluído após um envio bem-sucedido.
templateobjectnãoEnviar um template hospedado publicado em vez de html/texto bruto. Requer exatamente um destinatário to e sem cc/bcc; o template fornece o assunto. Forneça pelo menos um de: id, key.
template.idstringnãoID do template (tmpl_…). Forneça id ou key.
template.keystringnãoChave do template, como account-welcome. Forneça id ou key.
template.version_idstringnãoID de versão publicada opcional (tmplv_…). Padrão para a versão publicada atual.
template.dataobjectnãoValores para as variáveis tipadas do template.
labelsstring[]nãoNomes de rótulos ou IDs lbl_… para arquivar esta mensagem. Nomes desconhecidos são criados. Respostas na conversa herdam os rótulos, e um rótulo de bucket (skip_inbox) mantém essas respostas fora da Caixa de entrada. Máx. 10. (0–10 itens)
idempotency_keystringnãoCabeçalho Idempotency-Key (máx. 200 caracteres). Reutilize-o apenas para repetir esta solicitação exata. (máx. 200 caracteres)
attachmentsobject[]nãoArquivos para anexar (máx. 10 arquivos, 10 MB no total). Cada um precisa de content_base64 (mais filename) ou um file_path local. (0–10 itens) Forneça pelo menos um de: content_base64, file_path.
attachments[].filenamestringnãoNome do arquivo mostrado ao destinatário. Obrigatório com content_base64; padrão para o nome base de file_path. (máx. 255 caracteres)
attachments[].content_typestringnãoTipo MIME, ex.: application/pdf. Padrão para application/octet-stream.
attachments[].content_base64stringnãoConteúdo do arquivo em base64 padrão.
attachments[].file_pathstringnãoCaminho absoluto de um arquivo local legível pelo processo do servidor MCP.

Retorna: {id: em_…, providerMessageId, threadId, templateId, templateVersionId, isTest}. Aceitação não é entrega: acompanhe com list_email_events.

Exemplo:

{
  "name": "send_email",
  "arguments": {
    "from": "Acme <hello@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "Your export is ready",
    "text": "Download it from your dashboard.",
    "idempotency_key": "export-ready-42"
  }
}

send_batch

Enviar um lote de e-mails individualizados · Envia e-mail real · POST /emails/batch

ENVIA E-MAIL REAL. Envie 1–100 mensagens independentes em uma solicitação (use isso para personalização de template por destinatário). Cada item tem a mesma forma que send_email (sem anexos/idempotency_key). Os itens são bem-sucedidos ou falham individualmente: HTTP 207 significa sucesso parcial; inspecione cada data[i].ok e data[i].error. Um idempotency_key cobre todo o corpo do lote.

ParâmetroTipoObrigatórioDescrição
emailsobject[]simMensagens para enviar. (1–100 itens) Forneça pelo menos um de: html, text, template.
idempotency_keystringnãoIdempotency-Key para todo o lote (máx. 200 caracteres). (máx. 200 caracteres)

Retorna: {data: [{index, ok, id?, error?: {message, status}}], count, successful, failed}.

Exemplo:

{
  "name": "send_batch",
  "arguments": {
    "emails": [
      {
        "from": "Acme <hello@example.com>",
        "to": [
          "owner@example.com"
        ],
        "template": {
          "key": "account-welcome",
          "data": {
            "first_name": "Asha"
          }
        }
      }
    ],
    "idempotency_key": "welcome-batch-2026-09-26"
  }
}

list_emails

Listar e pesquisar e-mail · Somente leitura · GET /emails

Liste e-mails enviados (direction: out) e recebidos (direction: in) do mais novo para o mais antigo com filtros. O correio recebido é classificado: leia a caixa de entrada humana com direction: in, archived: false, category: primary; faça triagem com important: true; spam é ocultado a menos que category: spam ou include_spam: true. Paginado: o resultado inclui pagination {offset, limit, returned, total?, has_more, next_offset}.

ParâmetroTipoObrigatórioDescrição
directionstringnãoin para recebidos, out para enviados. (um de in, out)
statusstringnãoFiltro de status, ex.: queued, sent, delivered, bounced, complained, failed.
domainstringnãoApenas mensagens para este domínio, ou uma lista separada por vírgulas de domínios (corresponde a qualquer um).
inbox_idstringnãoApenas mensagens recebidas por esta caixa de entrada (inb_…).
labelstringnãoApenas mensagens com este rótulo: um ID de rótulo lbl_… ou nome exato, ou uma lista separada por vírgulas (corresponde a qualquer um). Use list_labels para ver pastas.
archivedbooleannãofalse = a visualização da Caixa de entrada (correio recebido não arquivado), true = apenas arquivado. Omita para todo o correio.
categorystringnãoprimary (pessoas), updates (newsletters, volume, automatizado) ou spam; ou uma lista separada por vírgulas. Spam é ocultado a menos que solicitado.
importantbooleannãotrue = apenas mensagens marcadas como importantes (respostas a conversas que você iniciou e remetentes marcados como importantes).
include_spambooleannãoIncluir spam nos resultados (para pesquisas em todas as pastas).
fromstringnãoO endereço do remetente contém este valor.
tostringnãoO endereço do destinatário contém este valor.
unreadbooleannãotrue = apenas não lidas, false = apenas lidas.
afterstringnãoCarimbo de data/hora ISO-8601; apenas mensagens criadas depois dele. (data-hora)
beforestringnãoCarimbo de data/hora ISO-8601; apenas mensagens criadas antes dele. (data-hora)
querystringnãoPesquisa de texto livre sobre assuntos, corpos, endereços de remetente/destinatário e nomes de arquivos de anexos. (máx. 200 caracteres)
limitintegernãoTamanho da página. Padrão para 50. (padrão 50; 1–200)
offsetintegernãoNúmero de registros para pular. Use pagination.next_offset da página anterior. (padrão 0; 0–…)

Retorna: {data: [resumos de e-mail], count, pagination}.

Exemplo:

{
  "name": "list_emails",
  "arguments": {
    "direction": "in",
    "unread": true,
    "limit": 25
  }
}

get_email

Obter um e-mail · Somente leitura · GET /emails/:email_id

Recupere uma mensagem com cabeçalhos, corpo html/texto, status, metadados de thread e metadados de anexos (baixe bytes com download_attachment).

ParâmetroTipoObrigatórioDescrição
email_idstringsimID do e-mail (começa com em_), conforme retornado por uma ferramenta de lista ou criação. (máx. 128 caracteres)

Retorna: Objeto de e-mail: {id, direction, status, from, to, cc, bcc, subject, html, text, threadId, messageId, providerMessageId, readAt, createdAt, attachments: [{id, filename, contentType, sizeBytes, available}]}.

Exemplo:

{
  "name": "get_email",
  "arguments": {
    "email_id": "em_123"
  }
}

mark_email

Marcar como lido, arquivado, spam ou importante · Altera o estado · PATCH /emails/:email_id

Atualize uma mensagem: read, archived, category (primary, updates, spam; apenas correio recebido) e important. Reportar spam ou marcar como importante ensina o SendHQ sobre esse remetente para correio futuro; passe learn: false para alterar apenas esta mensagem. Passe pelo menos um campo.

ParâmetroTipoObrigatórioDescrição
email_idstringsimID do e-mail (começa com em_), conforme retornado por uma ferramenta de lista ou criação. (máx. 128 caracteres)
readbooleannãotrue = lido, false = não lido.
archivedbooleannãotrue = arquivar (pular a Caixa de entrada), false = mover de volta para a Caixa de entrada.
categorystringnãoMover uma mensagem recebida para primary, updates ou spam. (um de primary, updates, spam)
importantbooleannãoMarcar ou desmarcar a mensagem como importante.
learnbooleannãofalse = não lembrar este veredito para o remetente (padrão true).

Retorna: O objeto de e-mail atualizado.

Exemplo:

{
  "name": "mark_email",
  "arguments": {
    "email_id": "em_123",
    "read": true
  }
}

delete_email

Excluir um e-mail · Destrutivo · DELETE /emails/:email_id

DESTRUTIVO: excluir permanentemente uma mensagem retida e seus anexos armazenados do SendHQ. Não recupera uma mensagem que já foi entregue.

ParâmetroTipoObrigatórioDescrição
email_idstringsimID do e-mail (começa com em_), conforme retornado por uma ferramenta de lista ou criação. (máx. 128 caracteres)

Retorna: {ok: true}.

Exemplo:

{
  "name": "delete_email",
  "arguments": {
    "email_id": "em_123"
  }
}

list_email_events

Listar eventos de entrega para um e-mail · Somente leitura · GET /emails/:email_id/events

Eventos do provedor para uma mensagem enviada: entrega, bounce, reclamação, rejeição, abertura, clique. Esta é a evidência de se uma mensagem foi entregue ou por que falhou. Paginado: o resultado inclui pagination {offset, limit, returned, total?, has_more, next_offset}.

ParâmetroTipoObrigatórioDescrição
email_idstringsimID do e-mail (começa com em_), conforme retornado por uma ferramenta de lista ou criação. (máx. 128 caracteres)
limitintegernãoTamanho da página. Padrão para 50. (padrão 50; 1–200)
offsetintegernãoNúmero de registros para pular. Use pagination.next_offset da página anterior. (padrão 0; 0–…)

Retorna: {data: [{event_type, recipient, reason, created_at, …}], count, pagination}.

Exemplo:

{
  "name": "list_email_events",
  "arguments": {
    "email_id": "em_123"
  }
}

get_thread

Obter uma conversa · Somente leitura · GET /threads/:thread_id

Recupere todas as mensagens em uma conversa em ordem cronológica (enviadas e recebidas), cada uma com metadados de anexos.

ParâmetroTipoObrigatórioDescrição
thread_idstringsimID da thread (geralmente o ID em_… da primeira mensagem; veja threadId em qualquer e-mail). (máx. 128 caracteres)

Retorna: {id, subject, data: [emails]}.

Exemplo:

{
  "name": "get_thread",
  "arguments": {
    "thread_id": "em_123"
  }
}

Etiquetas e regras de arquivamento automático

list_labels

Listar etiquetas · Somente leitura · GET /labels

Lista as etiquetas (pastas) do workspace com contagens totais e não lidas e suas regras de arquivamento automático. Paginado: o resultado inclui pagination {offset, limit, returned, total?, has_more, next_offset}.

ParâmetroTipoObrigatórioDescrição
limitintegernãoTamanho da página. Padrão: 50. (padrão 50; 1–200)
offsetintegernãoNúmero de registros a pular. Use pagination.next_offset da página anterior. (padrão 0; 0–…)

Retorna: {data: [{id, name, color, totalCount, unreadCount, rules: [...]}], count, pagination}.

Exemplo:

{
  "name": "list_labels",
  "arguments": {}
}

get_label

Obter uma etiqueta · Somente leitura · GET /labels/:label_id

Recupera uma etiqueta com contagens e regras de arquivamento automático.

ParâmetroTipoObrigatórioDescrição
label_idstringsimID da etiqueta (começa com lbl_) ou o nome exato da etiqueta. (máx. 128 caracteres)

Retorna: Objeto da etiqueta.

Exemplo:

{
  "name": "get_label",
  "arguments": {
    "label_id": "Billing"
  }
}

create_label

Criar uma etiqueta · Altera o estado · POST /labels

Cria uma etiqueta no estilo pasta. Defina skip_inbox: true para torná-la um bucket que um agente possui: envie com labels: [name] e as respostas são arquivadas na etiqueta e mantidas fora da Caixa de entrada. Regras opcionais de arquivamento automático arquivam novos e-mails enviados/recebidos (todas as condições de uma regra devem corresponder). Defina apply_to_existing para também arquivar e-mails retidos.

ParâmetroTipoObrigatórioDescrição
namestringsimNome da etiqueta, ex.: Billing ou Clients/Acme. Único por workspace (sem diferenciar maiúsculas/minúsculas). (máx. 64 caracteres)
colorstringnãoCor hexadecimal como #1a73e8. Opcional.
skip_inboxbooleannãoModo bucket: e-mails recebidos que recebem esta etiqueta (por regra, ao responder a uma conversa enviada com esta etiqueta, ou manualmente) são arquivados e aparecem apenas na etiqueta, não na Caixa de entrada.
rulesobject[]nãoRegras opcionais de arquivamento automático (máx. 20). Cada uma precisa de pelo menos um de inbox_id, from, to, subject. (0–20 itens)
rules[].directionstringnãoApenas e-mails in (recebidos) ou out (enviados). Omita para ambos. (um de in, out)
rules[].inbox_idstringnãoApenas e-mails recebidos por esta caixa de entrada (inb_…). Arquiva cada endereço de recebimento em sua própria pasta.
rules[].fromstringnãoRemetente contém este texto (sem diferenciar maiúsculas/minúsculas), ex.: @stripe.com. (máx. 200 caracteres)
rules[].tostringnãoPara/Cc contém este texto (sem diferenciar maiúsculas/minúsculas). (máx. 200 caracteres)
rules[].subjectstringnãoAssunto contém este texto (sem diferenciar maiúsculas/minúsculas). (máx. 200 caracteres)
rules[].skip_inboxbooleannãoArquivar e-mails recebidos correspondentes para que apareçam apenas na pasta da etiqueta, não na Caixa de entrada.
apply_to_existingbooleannãoTambém arquivar e-mails já retidos que correspondam às regras.

Retorna: A etiqueta criada com regras.

Exemplo:

{
  "name": "create_label",
  "arguments": {
    "name": "Agent/Orders",
    "skip_inbox": true,
    "rules": [
      {
        "from": "@stripe.com"
      }
    ]
  }
}

update_label

Renomear, recolorir ou transformar em bucket uma etiqueta · Altera o estado · PATCH /labels/:label_id

Renomeia uma etiqueta, altera sua cor ou alterna o modo bucket (skip_inbox). Ativar o modo bucket arquiva e-mails recebidos já presentes na etiqueta.

ParâmetroTipoObrigatórioDescrição
label_idstringsimID da etiqueta (começa com lbl_) ou o nome exato da etiqueta. (máx. 128 caracteres)
namestringnãoNovo nome. (máx. 64 caracteres)
colorstringnãoNova cor hexadecimal.
skip_inboxbooleannãoModo bucket: e-mails recebidos que recebem esta etiqueta (por regra, ao responder a uma conversa enviada com esta etiqueta, ou manualmente) são arquivados e aparecem apenas na etiqueta, não na Caixa de entrada.

Retorna: Etiqueta atualizada.

Exemplo:

{
  "name": "update_label",
  "arguments": {
    "label_id": "lbl_123",
    "name": "Finance/Billing"
  }
}

delete_label

Excluir uma etiqueta · Destrutivo · DELETE /labels/:label_id

DESTRUTIVO: exclui uma etiqueta e suas regras. O e-mail em si é mantido; ele apenas perde esta etiqueta.

ParâmetroTipoObrigatórioDescrição
label_idstringsimID da etiqueta (começa com lbl_) ou o nome exato da etiqueta. (máx. 128 caracteres)

Retorna: {ok: true}.

Exemplo:

{
  "name": "delete_label",
  "arguments": {
    "label_id": "lbl_123"
  }
}

create_label_rule

Adicionar uma regra de arquivamento automático · Altera o estado · POST /labels/:label_id/rules

Adiciona uma regra a uma etiqueta para que novos e-mails correspondentes sejam arquivados automaticamente. Todas as condições definidas devem corresponder. Use inbox_id para dar a um endereço de recebimento sua própria pasta; adicione skip_inbox para mantê-lo fora da Caixa de entrada.

ParâmetroTipoObrigatórioDescrição
label_idstringsimID da etiqueta (começa com lbl_) ou o nome exato da etiqueta. (máx. 128 caracteres)
directionstringnãoApenas e-mails in (recebidos) ou out (enviados). Omita para ambos. (um de in, out)
inbox_idstringnãoApenas e-mails recebidos por esta caixa de entrada (inb_…). Arquiva cada endereço de recebimento em sua própria pasta.
fromstringnãoRemetente contém este texto (sem diferenciar maiúsculas/minúsculas), ex.: @stripe.com. (máx. 200 caracteres)
tostringnãoPara/Cc contém este texto (sem diferenciar maiúsculas/minúsculas). (máx. 200 caracteres)
subjectstringnãoAssunto contém este texto (sem diferenciar maiúsculas/minúsculas). (máx. 200 caracteres)
skip_inboxbooleannãoArquivar e-mails recebidos correspondentes para que apareçam apenas na pasta da etiqueta, não na Caixa de entrada.
apply_to_existingbooleannãoTambém arquivar e-mails já retidos que correspondam.

Retorna: {id: lrule_…, labelId, direction, inboxId, from, to, subject, skipInbox}.

Exemplo:

{
  "name": "create_label_rule",
  "arguments": {
    "label_id": "Billing",
    "inbox_id": "inb_123",
    "skip_inbox": true
  }
}

delete_label_rule

Excluir uma regra de arquivamento automático · Destrutivo · DELETE /labels/:label_id/rules/:rule_id

DESTRUTIVO: remove uma regra de arquivamento automático. E-mails já arquivados mantêm sua etiqueta.

ParâmetroTipoObrigatórioDescrição
label_idstringsimID da etiqueta (começa com lbl_) ou o nome exato da etiqueta. (máx. 128 caracteres)
rule_idstringsimID da regra (começa com lrule_), de get_label. (máx. 128 caracteres)

Retorna: {ok: true}.

Exemplo:

{
  "name": "delete_label_rule",
  "arguments": {
    "label_id": "lbl_123",
    "rule_id": "lrule_123"
  }
}

label_email

Adicionar ou remover etiquetas em um e-mail · Altera o estado · POST /emails/:email_id/labels

Move uma mensagem entre pastas: adiciona e/ou remove etiquetas por nome ou ID lbl_…. Nomes desconhecidos em add são criados, a menos que create seja false.

ParâmetroTipoObrigatórioDescrição
email_idstringsimID do e-mail (começa com em_), conforme retornado por uma ferramenta de listagem ou criação. (máx. 128 caracteres)
addstring[]nãoEtiquetas a adicionar. (0–10 itens)
removestring[]nãoEtiquetas a remover. (0–10 itens)
createbooleannãoCriar etiquetas desconhecidas em add (padrão true).

Retorna: O e-mail atualizado com labels.

Exemplo:

{
  "name": "label_email",
  "arguments": {
    "email_id": "em_123",
    "add": [
      "Billing"
    ],
    "remove": [
      "Support"
    ]
  }
}

Rascunhos, anexos e identidades de remetente

list_sending_identities

Listar identidades de remetente verificadas · Somente leitura · GET /sending-identities

Endereços e domínios dos quais este workspace pode enviar agora (domínios verificados, seu From padrão e endereços de caixa de entrada ativos). Chame antes de send_email para escolher um from válido.

Sem parâmetros.

Retorna: {domains: [nomes de domínios verificados], addresses: [endereços de remetente], localParts: [...]}.

Exemplo:

{
  "name": "list_sending_identities",
  "arguments": {}
}

create_draft

Criar um rascunho · Altera o estado · POST /drafts

Cria um rascunho no editor. Rascunhos suportam anexos: crie um rascunho, upload_attachment e depois send_email com draft_id. Não envia nada.

ParâmetroTipoObrigatórioDescrição
fromstringnãoEndereço de remetente em um domínio verificado (pode estar vazio durante a elaboração).
tostring[]nãoDestinatários. (0–100 itens)
ccstring[]nãoDestinatários em cópia (Cc). (0–100 itens)
bccstring[]nãoDestinatários em cópia oculta (Cco). (0–100 itens)
subjectstringnãoLinha de assunto. (máx. 998 caracteres)
htmlstringnãoCorpo em HTML.
textstringnãoCorpo em texto simples.
reply_to_email_idstringnãoID do e-mail ao qual este rascunho responde.
thread_idstringnãoID da thread à qual este rascunho pertence.

Retorna: Objeto de rascunho {id: dr_…, from, to, cc, bcc, subject, html, text, attachments: []}.

Exemplo:

{
  "name": "create_draft",
  "arguments": {
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice"
  }
}

list_drafts

Listar rascunhos · Somente leitura · GET /drafts

Lista rascunhos do editor, dos mais recentemente atualizados aos mais antigos. Paginado: o resultado inclui pagination {offset, limit, returned, total?, has_more, next_offset}.

ParâmetroTipoObrigatórioDescrição
limitintegernãoTamanho da página. Padrão: 50. (padrão 50; 1–200)
offsetintegernãoNúmero de registros a pular. Use pagination.next_offset da página anterior. (padrão 0; 0–…)

Retorna: {data: [rascunhos], count, pagination}.

Exemplo:

{
  "name": "list_drafts",
  "arguments": {}
}

get_draft

Obter um rascunho · Somente leitura · GET /drafts/:draft_id

Recupera um rascunho com seus metadados de anexos.

ParâmetroTipoObrigatórioDescrição
draft_idstringsimID do rascunho (começa com dr_), conforme retornado por uma ferramenta de listagem ou criação. (máx. 128 caracteres)

Retorna: Objeto de rascunho com attachments.

Exemplo:

{
  "name": "get_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}

update_draft

Substituir conteúdo do rascunho · Altera o estado · PUT /drafts/:draft_id

Substitui o conteúdo e os destinatários de um rascunho. Esta é uma substituição completa: campos omitidos são limpos, então leia get_draft primeiro e envie todos os campos que deseja manter. Anexos não são afetados.

ParâmetroTipoObrigatórioDescrição
draft_idstringsimID do rascunho (começa com dr_), conforme retornado por uma ferramenta de listagem ou criação. (máx. 128 caracteres)
fromstringnãoEndereço de remetente em um domínio verificado (pode estar vazio durante a elaboração).
tostring[]nãoDestinatários. (0–100 itens)
ccstring[]nãoDestinatários em cópia (Cc). (0–100 itens)
bccstring[]nãoDestinatários em cópia oculta (Cco). (0–100 itens)
subjectstringnãoLinha de assunto. (máx. 998 caracteres)
htmlstringnãoCorpo em HTML.
textstringnãoCorpo em texto simples.
reply_to_email_idstringnãoID do e-mail ao qual este rascunho responde.
thread_idstringnãoID da thread à qual este rascunho pertence.

Retorna: Objeto de rascunho atualizado.

Exemplo:

{
  "name": "update_draft",
  "arguments": {
    "draft_id": "dr_123",
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice (updated)",
    "text": "Attached."
  }
}

delete_draft

Descartar um rascunho · Destrutivo · DELETE /drafts/:draft_id

DESTRUTIVO: descarta um rascunho e exclui permanentemente seus anexos armazenados.

ParâmetroTipoObrigatórioDescrição
draft_idstringsimID do rascunho (começa com dr_), conforme retornado por uma ferramenta de listagem ou criação. (máx. 128 caracteres)

Retorna: {ok: true}.

Exemplo:

{
  "name": "delete_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}

upload_attachment

Enviar um anexo para um rascunho · Altera o estado · POST /drafts/:draft_id/attachments

Envia um arquivo para um rascunho (máx. 10 arquivos e 10 MB no total por mensagem). Forneça content_base64 ou um file_path local. Anexos exigem um plano pago no momento do envio.

Forneça pelo menos um de: content_base64, file_path.

ParâmetroTipoObrigatórioDescrição
draft_idstringsimID do rascunho (começa com dr_), conforme retornado por uma ferramenta de listagem ou criação. (máx. 128 caracteres)
filenamestringnãoNome do arquivo exibido ao destinatário. Padrão: nome base de file_path. (máx. 255 caracteres)
content_typestringnãoTipo MIME, ex.: application/pdf. Padrão: application/octet-stream.
content_base64stringnãoConteúdo do arquivo em base64 padrão.
file_pathstringnãoCaminho absoluto de um arquivo local legível pelo processo do servidor MCP.

Retorna: {id: att_…, filename, contentType, sizeBytes, available}.

Exemplo:

{
  "name": "upload_attachment",
  "arguments": {
    "draft_id": "dr_123",
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "file_path": "/tmp/invoice.pdf"
  }
}

download_attachment

Baixar um anexo · Somente leitura · GET /attachments/:attachment_id

Baixa um anexo privado (enviado, recebido ou rascunho). Retorna o conteúdo em base64 ou grava o arquivo quando save_to_path está definido (recusa sobrescrever, a menos que overwrite seja verdadeiro).

ParâmetroTipoObrigatórioDescrição
attachment_idstringsimID do anexo (começa com att_), conforme retornado por uma ferramenta de listagem ou criação. (máx. 128 caracteres)
save_to_pathstringnãoCaminho local absoluto opcional para gravar o arquivo em vez de retornar base64.
overwritebooleannãoPermite substituir um arquivo existente em save_to_path. Padrão: falso.

Retorna: {attachment_id, filename, content_type, size_bytes, content_base64} ou {attachment_id, filename, content_type, size_bytes, saved_to}.

Exemplo:

{
  "name": "download_attachment",
  "arguments": {
    "attachment_id": "att_123",
    "save_to_path": "/tmp/invoice.pdf"
  }
}

delete_attachment

Excluir um anexo · Destrutivo · DELETE /attachments/:attachment_id

DESTRUTIVO: exclui permanentemente um anexo armazenado (por exemplo, remover um arquivo de um rascunho antes do envio).

ParâmetroTipoObrigatórioDescrição
attachment_idstringsimID do anexo (começa com att_), conforme retornado por uma ferramenta de listagem ou criação. (máx. 128 caracteres)

Retorna: {ok: true}.

Exemplo:

{
  "name": "delete_attachment",
  "arguments": {
    "attachment_id": "att_123"
  }
}

Modelos hospedados

list_templates

Listar modelos hospedados · Somente leitura · GET /templates

Lista modelos de e-mail hospedados com estado de publicação e uso. Paginado: o resultado inclui pagination {offset, limit, returned, total?, has_more, next_offset}.

ParâmetroTipoObrigatórioDescrição
lifecyclestringnãoactive (padrão), archived ou all. (um de active, archived, all)
querystringnãoBusca por nome ou chave. (máx. 120 caracteres)
limitintegernãoTamanho da página. Padrão: 50. (padrão 50; 1–200)
offsetintegernãoNúmero de registros a pular. Use pagination.next_offset da página anterior. (padrão 0; 0–…)

Retorna: {data: [templates], count, pagination}.

Exemplo:

{
  "name": "list_templates",
  "arguments": {
    "lifecycle": "active"
  }
}

create_template

Criar um modelo hospedado · Altera o estado · POST /templates

Cria um modelo com um rascunho editável, opcionalmente a partir de um iniciador (welcome, reset, receipt ou blank). Publique-o antes de enviar pela chave.

ParâmetroTipoObrigatórioDescrição
namestringsimNome legível. (máx. 120 caracteres)
keystringnãoChave de envio estável: letras minúsculas, números, hífens; começa com letra (2–64 caracteres). Derivada do nome quando omitida.
starterstringnãoConteúdo inicial. (um de blank, welcome, reset, receipt)

Retorna: {template, draft, activeVersion, versions, usage}.

Exemplo:

{
  "name": "create_template",
  "arguments": {
    "name": "Account welcome",
    "key": "account-welcome",
    "starter": "welcome"
  }
}

get_template

Obter um modelo · Somente leitura · GET /templates/:template_id

Recupera o rascunho atual de um modelo (com revision), a versão publicada ativa, o histórico de versões e o uso. Aceita ID ou chave.

ParâmetroTipoObrigatórioDescrição
template_idstringsimID do modelo (tmpl_…) ou chave. (máx. 128 caracteres)

Retorna: {template, draft: {id, revision, subjectTemplate, htmlTemplate, textTemplate, variables, sampleData, …} | null, activeVersion, versions, usage}.

Exemplo:

{
  "name": "get_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

update_template_draft

Salvar um rascunho de modelo · Altera o estado · PUT /templates/:template_id/draft

Salva o rascunho editável do modelo usando concorrência otimista: passe o revision atual de get_template (409 significa que outra pessoa salvou primeiro; releia e tente novamente). Isso é uma substituição completa do conteúdo do rascunho: campos omitidos são limpos, então envie todos os campos que deseja manter. Use espaços reservados {{variable}}.

ParâmetroTipoObrigatórioDescrição
template_idstringsimID do modelo ou chave. (máx. 128 caracteres)
revisionintegersimRevisão atual do rascunho de get_template. (1–…)
namestringnãoNome do modelo. (máx. 120 caracteres)
subject_templatestringnãoAssunto com espaços reservados. (máx. 998 caracteres)
preheader_templatestringnãoTexto de pré-visualização. (máx. 240 caracteres)
html_templatestringnãoCorpo HTML com espaços reservados.
text_templatestringnãoCorpo em texto simples com espaços reservados.
fromstringnãoRemetente padrão para envios deste modelo.
reply_tostringnãoResponder-Para padrão.
variablesobject[]nãoContrato de variáveis tipadas. Cada item: {key (minúsculas/sublinhados), label, type: text|number|url|boolean, required (padrão true), fallback, description}.
variables[].keystringsim
variables[].labelstringnão
variables[].typestringnão(um de text, number, url, boolean)
variables[].requiredbooleannão
variables[].fallbackanynão
variables[].descriptionstringnão
sample_dataobjectnãoValores de amostra usados para pré-visualizações e testes.

Retorna: {template, draft: {revision: next}, validation: {valid, findings}}.

Exemplo:

{
  "name": "update_template_draft",
  "arguments": {
    "template_id": "account-welcome",
    "revision": 3,
    "name": "Account welcome",
    "subject_template": "Welcome, {{first_name}}",
    "text_template": "Hi {{first_name}}",
    "variables": [
      {
        "key": "first_name",
        "type": "text",
        "required": true
      }
    ],
    "sample_data": {
      "first_name": "Asha"
    }
  }
}

create_template_draft

Iniciar um novo rascunho a partir da versão publicada · Altera o estado · POST /templates/:template_id/draft

Cria um novo rascunho editável copiado da versão publicada atual (409 se um rascunho já existir ou nada estiver publicado).

ParâmetroTipoObrigatórioDescrição
template_idstringsimID do modelo ou chave. (máx. 128 caracteres)

Retorna: {draft}.

Exemplo:

{
  "name": "create_template_draft",
  "arguments": {
    "template_id": "account-welcome"
  }
}

render_template

Renderizar uma pré-visualização de modelo · Somente leitura · POST /templates/:template_id/render

Renderiza a saída exata do servidor (assunto, html, texto) para o rascunho, a versão publicada ou uma versão específica com os dados fornecidos. Não envia. Retorna 422 com findings quando os dados violam o contrato de variáveis.

ParâmetroTipoObrigatórioDescrição
template_idstringsimID do modelo ou chave. (máx. 128 caracteres)
version_idstringnãoID de versão opcional; padrão: rascunho, depois versão publicada.
dataobjectnãoValores de variáveis; padrão: dados de amostra da versão.

Retorna: {subject, html, text, preheader, versionId, versionNumber, isDraft, findings}.

Exemplo:

{
  "name": "render_template",
  "arguments": {
    "template_id": "account-welcome",
    "data": {
      "first_name": "Asha"
    }
  }
}

send_template_test

Enviar um e-mail de teste de modelo · Envia e-mail real · POST /templates/:template_id/test

ENVIA E-MAIL REAL. Envia um instantâneo do rascunho (ou de uma versão fornecida) com prefixo [Test] para os destinatários fornecidos. Conta para o uso; espaços de trabalho de teste só podem enviar para o e-mail da conta ou um endereço de simulador SES.

ParâmetroTipoObrigatórioDescrição
template_idstringsimID do modelo ou chave. (máx. 128 caracteres)
tostring[]simDestinatários de teste. (1–100 itens)
fromstringnãoRemetente em um domínio verificado; padrão: o De do modelo.
version_idstringnãoID de versão opcional.
dataobjectnãoValores de variáveis; padrão: dados de amostra.

Retorna: {id: em_…, providerMessageId, threadId, isTest: true}.

Exemplo:

{
  "name": "send_template_test",
  "arguments": {
    "template_id": "account-welcome",
    "to": [
      "owner@example.com"
    ]
  }
}

publish_template

Publicar uma versão de modelo · Altera o estado · POST /templates/:template_id/publish

Publica o rascunho atual como uma versão imutável que send_email com template.key usará. Falha com 422 findings em erros de validação, ou 409 se quebrar o contrato de variáveis ativo de um modelo já usado em produção.

ParâmetroTipoObrigatórioDescrição
template_idstringsimID do modelo ou chave. (máx. 128 caracteres)

Retorna: {template, published}.

Exemplo:

{
  "name": "publish_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

archive_template

Arquivar um modelo · Altera o estado · POST /templates/:template_id/archive

Interrompe novos envios que usam este modelo (o histórico é mantido; reversível com restore_template). Qualquer integração que envie esta chave começará a falhar com 404.

ParâmetroTipoObrigatórioDescrição
template_idstringsimID do modelo ou chave. (máx. 128 caracteres)

Retorna: {template}.

Exemplo:

{
  "name": "archive_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

restore_template

Restaurar um modelo arquivado · Altera o estado · POST /templates/:template_id/restore

Torna um modelo arquivado ativo novamente.

ParâmetroTipoObrigatórioDescrição
template_idstringsimID do modelo ou chave. (máx. 128 caracteres)

Retorna: {template}.

Exemplo:

{
  "name": "restore_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

Domínios e DNS

list_domains

Listar domínios · Somente leitura · GET /domains

Lista domínios de envio com setup_status agregado (verified | checking | pending), estado DNS por registro e status de entrada. Pode ser lento: domínios não verificados são re-checados ao vivo. Paginado: o resultado inclui pagination {offset, limit, returned, total?, has_more, next_offset}.

ParâmetroTipoObrigatórioDescrição
limitintegernãoTamanho da página. Padrão: 50. (padrão 50; 1–200)
offsetintegernãoNúmero de registros a pular. Use pagination.next_offset da página anterior. (padrão 0; 0–…)

Retorna: {data: [domains with records], count, pagination}.

Exemplo:

{
  "name": "list_domains",
  "arguments": {}
}

get_domain

Obter detalhes de configuração do domínio · Somente leitura · GET /domains/:domain_id

Recupera um domínio com os registros DNS exatos a publicar (tipo, nome, valor), o estado ao vivo de cada registro de dois resolvedores públicos, dns_issues com correções e status de entrada.

ParâmetroTipoObrigatórioDescrição
domain_idstringsimID do domínio (começa com dom_), conforme retornado por uma ferramenta de listagem ou criação. (máx. 128 caracteres)

Retorna: {id, name, status, setup_status, dns_propagating, records: [{type, name, value, verified, dns_state}], dns_issues: [{code, message, …}], inbound_domain, inbound_status}.

Exemplo:

{
  "name": "get_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}

add_domain

Adicionar um domínio de envio · Altera o estado · POST /domains

Registra um domínio que você controla para envio. Retorna os registros DNS (CNAMEs SES Easy DKIM) que o proprietário deve publicar. Não altera o DNS em si. Conta para o limite de domínios do plano.

ParâmetroTipoObrigatórioDescrição
namestringsimNome de domínio simples, ex.: example.com ou mail.example.com. (máx. 253 caracteres)
default_fromstringnãoEndereço de remetente padrão opcional neste domínio.

Retorna: {id: dom_…, name, status: pending, records: [...], ses: {configured}}.

Exemplo:

{
  "name": "add_domain",
  "arguments": {
    "name": "example.com"
  }
}

verify_domain

Verificar um domínio · Altera o estado · POST /domains/:domain_id/verify Execute uma verificação ao vivo de SES/DNS agora. Seguro repetir; consulte a cada 30–60 s após alterações de DNS (a propagação pode levar de minutos a horas). O envio é permitido assim que o status for verified.

ParâmetroTipoObrigatórioDescrição
domain_idstringsimID do domínio (começa com dom_), conforme retornado por uma ferramenta de listar ou criar. (máx. 128 caracteres)

Retorna: {domain, checks: {ses, dkim, dkim_status}, status: verified|pending}.

Exemplo:

{
  "name": "verify_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}

delete_domain

Excluir um domínio · Destrutivo · DELETE /domains/:domain_id

DESTRUTIVO: remove o domínio do workspace, incluindo sua rota de recebimento de entrada. Os envios a partir dele falham imediatamente depois. Não exclui registros DNS no seu provedor de DNS.

ParâmetroTipoObrigatórioDescrição
domain_idstringsimID do domínio (começa com dom_), conforme retornado por uma ferramenta de listar ou criar. (máx. 128 caracteres)

Retorna: {ok: true}.

Exemplo:

{
  "name": "delete_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}

get_dns_provider

Detectar provedor de DNS e hosts de registro · Somente leitura · GET /dns/provider

Detecta o provedor de DNS autoritativo do domínio e retorna o host relativo para digitar nesse provedor para cada registro, o registro DMARC recomendado, orientação de MX de entrada e se a configuração em um clique (Domain Connect) está disponível.

ParâmetroTipoObrigatórioDescrição
domain_idstringsimID do domínio (começa com dom_), conforme retornado por uma ferramenta de listar ou criar. (máx. 128 caracteres)

Retorna: {detectionStatus, detected, zone, nameservers, recordHosts: {recordId: host}, inbound, recommendations, authentication, providers: {domainConnect: {available, providerName}}}.

Exemplo:

{
  "name": "get_dns_provider",
  "arguments": {
    "domain_id": "dom_123"
  }
}

get_domain_connect_link

Obter um link de configuração de DNS em um clique · Somente leitura · GET /dns/domain-connect/connect

Quando get_dns_provider relatar providers.domainConnect.available, crie uma URL de consentimento assinada. Entregue-a ao humano: ele a abre e aprova a alteração de DNS no provedor. Nada muda até que ele aprove. 409 se não for suportado.

ParâmetroTipoObrigatórioDescrição
domain_idstringsimID do domínio (começa com dom_), conforme retornado por uma ferramenta de listar ou criar. (máx. 128 caracteres)

Retorna: {url, providerName}.

Exemplo:

{
  "name": "get_domain_connect_link",
  "arguments": {
    "domain_id": "dom_123"
  }
}

E-mail de entrada

setup_inbound

Habilitar recebimento de entrada para um domínio · Altera estado · POST /domains/:domain_id/inbound/setup

Provisiona o recebimento de entrada do SES para um domínio verificado. Usa o domínio raiz quando ele não tem MX conflitante; caso contrário, inbound.<domain>. Retorna o registro MX que o proprietário deve publicar; não edita DNS.

ParâmetroTipoObrigatórioDescrição
domain_idstringsimID do domínio (começa com dom_), conforme retornado por uma ferramenta de listar ou criar. (máx. 128 caracteres)

Retorna: {domain: receiving domain, status: dns_pending|ready, record: {type: MX, name, value}}.

Exemplo:

{
  "name": "setup_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}

verify_inbound

Verificar MX de entrada · Altera estado · POST /domains/:domain_id/inbound/verify

Verifica novamente o registro MX de entrada. O status se torna ready quando ambos os resolvedores públicos o veem.

ParâmetroTipoObrigatórioDescrição
domain_idstringsimID do domínio (começa com dom_), conforme retornado por uma ferramenta de listar ou criar. (máx. 128 caracteres)

Retorna: {domain, status: ready|dns_pending|propagating|checking, record}.

Exemplo:

{
  "name": "verify_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}

list_inboxes

Listar endereços de entrada · Somente leitura · GET /inboxes

Lista endereços de recebimento, opcionalmente para um domínio. Paginado: o resultado inclui pagination {offset, limit, returned, total?, has_more, next_offset}.

ParâmetroTipoObrigatórioDescrição
domain_idstringnãoFiltro opcional de ID do domínio.
limitintegernãoTamanho da página. Padrão 50. (padrão 50; 1–200)
offsetintegernãoNúmero de registros a pular. Use pagination.next_offset da página anterior. (padrão 0; 0–…)

Retorna: {data: [{id, address, name, status, domainId}], count, pagination}.

Exemplo:

{
  "name": "list_inboxes",
  "arguments": {
    "domain_id": "dom_123"
  }
}

get_inbox

Obter uma caixa de entrada · Somente leitura · GET /inboxes/:inbox_id

Recupera um endereço de entrada.

ParâmetroTipoObrigatórioDescrição
inbox_idstringsimID da caixa de entrada (começa com inb_), conforme retornado por uma ferramenta de listar ou criar. (máx. 128 caracteres)

Retorna: Objeto da caixa de entrada.

Exemplo:

{
  "name": "get_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}

create_inbox

Criar um endereço de entrada · Altera estado · POST /inboxes

Cria um endereço como support@<receiving domain> em um domínio cujo status de entrada é ready (execute setup_inbound e verify_inbound primeiro). O e-mail recebido aparece em list_emails com direção in.

ParâmetroTipoObrigatórioDescrição
domain_idstringsimID do domínio (começa com dom_), conforme retornado por uma ferramenta de listar ou criar. (máx. 128 caracteres)
local_partstringsimParte antes de @, ex.: support. (máx. 64 caracteres)
namestringnãoNome de exibição opcional.

Retorna: {id: inb_…, address, name, status: active}.

Exemplo:

{
  "name": "create_inbox",
  "arguments": {
    "domain_id": "dom_123",
    "local_part": "support",
    "name": "Support"
  }
}

update_inbox

Renomear, habilitar ou desabilitar uma caixa de entrada · Altera estado · PATCH /inboxes/:inbox_id

Renomeia uma caixa de entrada ou define seu status como active / disabled.

ParâmetroTipoObrigatórioDescrição
inbox_idstringsimID da caixa de entrada (começa com inb_), conforme retornado por uma ferramenta de listar ou criar. (máx. 128 caracteres)
namestringnãoNovo nome de exibição.
statusstringnãoNovo status. (um de active, disabled)

Retorna: Caixa de entrada atualizada.

Exemplo:

{
  "name": "update_inbox",
  "arguments": {
    "inbox_id": "inb_123",
    "status": "disabled"
  }
}

set_inbox_forwarding

Encaminhar uma caixa de entrada para outro endereço · Envia e-mail real · PUT /inboxes/:inbox_id/forwarding

ENVIA E-MAIL REAL ao encaminhar para alguém diferente do proprietário da conta: define para onde o e-mail recebido de uma caixa de entrada é encaminhado. O próprio endereço do proprietário é ativado imediatamente; qualquer outro endereço recebe um e-mail de confirmação e o encaminhamento permanece pending até que alguém confirme. Passe forward_to: null para desativar o encaminhamento. As cópias encaminhadas vêm do endereço da caixa de entrada com o remetente original como Reply-To.

ParâmetroTipoObrigatórioDescrição
inbox_idstringsimID da caixa de entrada (começa com inb_), conforme retornado por uma ferramenta de listar ou criar. (máx. 128 caracteres)
forward_tostring,nullsimEndereço de e-mail de destino do encaminhamento, ou null para desativar o encaminhamento. (máx. 254 caracteres)

Retorna: Caixa de entrada com forwardTo e forwardStatus (off, pending ou active).

Exemplo:

{
  "name": "set_inbox_forwarding",
  "arguments": {
    "inbox_id": "inb_123",
    "forward_to": "team@example.net"
  }
}

delete_inbox

Excluir uma caixa de entrada · Destrutivo · DELETE /inboxes/:inbox_id

DESTRUTIVO: exclui um endereço de entrada. O e-mail já recebido é retido; novos e-mails para o endereço não são mais arquivados nele.

ParâmetroTipoObrigatórioDescrição
inbox_idstringsimID da caixa de entrada (começa com inb_), conforme retornado por uma ferramenta de listar ou criar. (máx. 128 caracteres)

Retorna: {ok: true}.

Exemplo:

{
  "name": "delete_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}

Entregabilidade, rejeições e supressões

deliverability_stats

Obter estatísticas de entrega de 30 dias · Somente leitura · GET /deliverability/stats

Totais de 30 dias em todo o workspace: enviados, entregues, rejeitados, reclamações, recusados, abertos, clicados e deliveryRate (%).

Sem parâmetros.

Retorna: {window: 30d, sent, delivery, bounce, complaint, reject, open, click, deliveryRate}.

Exemplo:

{
  "name": "deliverability_stats",
  "arguments": {}
}

list_sender_reputation

Listar reputação do remetente · Somente leitura · GET /deliverability/reputation

Estado da reputação por endereço De exato: active, throttled (limite diário menor) ou paused (envios retornam 423), com o motivo e o limite diário. Verifique isso quando os envios falharem com 423 ou 429. Paginado: o resultado inclui pagination {offset, limit, returned, total?, has_more, next_offset}.

ParâmetroTipoObrigatórioDescrição
limitintegernãoTamanho da página. Padrão 50. (padrão 50; 1–200)
offsetintegernãoNúmero de registros a pular. Use pagination.next_offset da página anterior. (padrão 0; 0–…)

Retorna: {data: [{sender, status, dailyLimit, reason, cleanSince, warnedAt, pausedAt, evaluatedAt}], count, pagination}.

Exemplo:

{
  "name": "list_sender_reputation",
  "arguments": {}
}

list_suppressions

Listar supressões · Somente leitura · GET /suppressions

Lista de supressões do workspace: destinatários bloqueados após uma rejeição permanente ou uma reclamação de spam. Envios para eles falham com 422. Paginado: o resultado inclui pagination {offset, limit, returned, total?, has_more, next_offset}.

ParâmetroTipoObrigatórioDescrição
limitintegernãoTamanho da página. Padrão 50. (padrão 50; 1–200)
offsetintegernãoNúmero de registros a pular. Use pagination.next_offset da página anterior. (padrão 0; 0–…)

Retorna: {data: [{email, reason, detail, created_at}], count, pagination}.

Exemplo:

{
  "name": "list_suppressions",
  "arguments": {}
}

remove_suppression

Remover uma supressão de rejeição · Destrutivo · DELETE /suppressions/:email

DESTRUTIVO (enfraquece um bloqueio de segurança): remove uma supressão de rejeição para que o endereço possa receber e-mails novamente. Faça isso somente quando o humano confirmar que o endereço agora é válido. Supressões por reclamação não podem ser removidas (409).

ParâmetroTipoObrigatórioDescrição
emailstringsimEndereço do destinatário suprimido. (máx. 320 caracteres)

Retorna: {ok: true}.

Exemplo:

{
  "name": "remove_suppression",
  "arguments": {
    "email": "fixed-mailbox@example.net"
  }
}

list_blocked_recipients

Listar destinatários bloqueados · Somente leitura · GET /blocked-recipients

Todo destinatário que o SendHQ recusará: rejeições, reclamações e cancelamentos de assinatura de marketing por domínio, com um resumo por tipo. Lê até os 500 mais recentes. Paginado: o resultado inclui pagination {offset, limit, returned, total?, has_more, next_offset}.

ParâmetroTipoObrigatórioDescrição
limitintegernãoTamanho da página. Padrão 50. (padrão 50; 1–200)
offsetintegernãoNúmero de registros a pular. Use pagination.next_offset da página anterior. (padrão 0; 0–…)

Retorna: {data: [{email, domain, kind: bounce|complaint|unsubscribe, reason, detail, source, status, created_at}], count, summary: {total, bounce, complaint, unsubscribe}, pagination}.

Exemplo:

{
  "name": "list_blocked_recipients",
  "arguments": {}
}

Conta, uso, análises e chaves

get_account

Obter conta, uso e cobrança · Somente leitura · GET /account

E-mail do proprietário da conta, plano/nível de acesso, entregas de destinatários do período atual usadas vs. cota, domínios usados vs. limite, transferência de anexos, resumo de reputação, estado da assinatura, planos publicados e contagens do workspace. Use para verificar a cota restante ou para quem o teste pode entregar (o e-mail da conta).

Sem parâmetros.

Retorna: {user: {email, …}, usage: {domainsUsed, domainLimit, recipientDeliveries, emailQuotaMonth, attachmentBytes, attachmentByteLimit, periodKey}, access: {tier, planCode}, reputation, infrastructure, billing: {status, subscriptions, …}, plans, workspace: {mailer, stats}}.

Exemplo:

{
  "name": "get_account",
  "arguments": {}
}

get_analytics

Obter análises de envio · Somente leitura · GET /analytics

Análises do painel para os últimos 7, 30 ou 90 dias: totais de enviados/recebidos/entregues/rejeitados/bloqueados/abertos/clicados/reclamações, uma linha do tempo diária, principais domínios de envio e principais assuntos.

ParâmetroTipoObrigatórioDescrição
daysinteironãoJanela em dias: 7, 30 (padrão) ou 90. (um de 7, 30, 90)

Retorna: {window, days, metrics, timeline: [{day, sent, received}], domains, topContent}.

Exemplo:

{
  "name": "get_analytics",
  "arguments": {
    "days": 30
  }
}

list_api_keys

Listar metadados de chaves de API · Somente leitura · GET /keys

Lista nomes de chaves de API, prefixos não secretos e horários do último uso. Somente leitura: este servidor MCP não pode criar, rotacionar ou revogar chaves; um humano faz isso no painel. Paginado: o resultado inclui pagination {offset, limit, returned, total?, has_more, next_offset}.

ParâmetroTipoObrigatórioDescrição
limitinteironãoTamanho da página. Padrão: 50. (padrão 50; 1–200)
offsetinteironãoNúmero de registros a pular. Use pagination.next_offset da página anterior. (padrão 0; 0–…)

Retorna: {data: [{id, name, prefix, lastUsedAt, createdAt}], count, pagination}.

Exemplo:

{
  "name": "list_api_keys",
  "arguments": {}
}

get_service_health

Verificar saúde do serviço SendHQ · Somente leitura · GET /health

Verifica se a API do SendHQ está ativa e qual provedor de e-mail está em uso. Não requer uma chave de API válida.

Sem parâmetros.

Retorna: {ok, service, mailer}.

Exemplo:

{
  "name": "get_service_health",
  "arguments": {}
}

Inventário de cobertura da API

Cada operação na API pública e a ferramenta que a cobre. Tudo o que um usuário pode fazer no painel que tenha API é coberto; as exclusões abaixo são deliberadas.

EndpointFerramentaNotas
POST /emailssend_emailEnviar um e-mail
POST /emails/batchsend_batchEnviar até 100 mensagens individualizadas
GET /emailslist_emailsListar e-mails enviados e recebidos
GET /emails/:idget_emailRecuperar um e-mail e seus anexos
PATCH /emails/:idmark_emailAtualizar lido, arquivado, spam, categoria ou importância
POST /emails/:id/labelslabel_emailAdicionar ou remover rótulos em um e-mail
DELETE /emails/:iddelete_emailExcluir um e-mail retido
GET /emails/:id/eventslist_email_eventsListar eventos de entrega de um e-mail
GET /threads/:idget_threadRecuperar uma conversa cronologicamente
GET /labelslist_labelsListar rótulos com contagens de mensagens e regras de arquivamento
POST /labelscreate_labelCriar um rótulo, opcionalmente com regras de arquivamento automático
GET /labels/:idget_labelRecuperar um rótulo por ID ou nome
PATCH /labels/:idupdate_labelRenomear, recolorir ou transformar um rótulo em um bucket
DELETE /labels/:iddelete_labelExcluir um rótulo sem excluir seus e-mails
POST /labels/:id/rulescreate_label_ruleAdicionar uma regra de arquivamento automático a um rótulo
DELETE /labels/:id/rules/:rule_iddelete_label_ruleExcluir uma regra de arquivamento automático
POST /draftscreate_draftCriar um rascunho no editor
GET /draftslist_draftsListar rascunhos do editor
GET /drafts/:idget_draftRecuperar um rascunho e anexos
PUT /drafts/:idupdate_draftSubstituir o conteúdo do rascunho
DELETE /drafts/:iddelete_draftDescartar um rascunho
POST /drafts/:id/attachmentsupload_attachmentEnviar um anexo para um rascunho
GET /attachments/:iddownload_attachmentBaixar um anexo privado
DELETE /attachments/:iddelete_attachmentExcluir um anexo privado
GET /sending-identitieslist_sending_identitiesListar identidades de remetente verificadas
GET /templateslist_templatesListar modelos hospedados
POST /templatescreate_templateCriar um modelo hospedado
GET /templates/:idget_templateRecuperar rascunhos, versões e uso
PUT /templates/:id/draftupdate_template_draftSalvar automaticamente um rascunho de modelo
POST /templates/:id/draftcreate_template_draftCriar um novo rascunho a partir da versão publicada
POST /templates/:id/renderrender_templateRenderizar a saída exata do servidor
POST /templates/:id/testsend_template_testEnviar um snapshot de teste
POST /templates/:id/publishpublish_templatePublicar uma versão imutável do modelo
POST /templates/:id/archivearchive_templateArquivar um modelo
POST /templates/:id/restorerestore_templateRestaurar um modelo arquivado
POST /domainsadd_domainAdicionar um domínio de envio
GET /domainslist_domainsListar domínios e estado DNS em cache
GET /domains/:idget_domainRecuperar detalhes de configuração do domínio
POST /domains/:id/verifyverify_domainAtualizar verificação SES e DNS
POST /domains/:id/inbound/setupsetup_inboundProvisionar recebimento de entrada SES
POST /domains/:id/inbound/verifyverify_inboundVerificar roteamento MX de entrada
DELETE /domains/:iddelete_domainExcluir um domínio
GET /dns/providerget_dns_providerDetectar o provedor DNS autoritativo e os hosts de registro relativos
GET /dns/domain-connect/connectget_domain_connect_linkCriar um link de consentimento Domain Connect para configuração DNS em um clique
POST /inboxescreate_inboxCriar um endereço de entrada
GET /inboxeslist_inboxesListar endereços de entrada
GET /inboxes/:idget_inboxRecuperar um endereço de entrada
PATCH /inboxes/:idupdate_inboxRenomear, ativar ou desativar uma caixa de entrada
PUT /inboxes/:id/forwardingset_inbox_forwardingEncaminhar o e-mail recebido de uma caixa de entrada para outro endereço
DELETE /inboxes/:iddelete_inboxExcluir uma caixa de entrada mantendo as mensagens
GET /deliverability/statsdeliverability_statsRecuperar estatísticas de entrega de 30 dias
GET /deliverability/reputationlist_sender_reputationListar estado de reputação por identidade de remetente exata
GET /suppressionslist_suppressionsListar supressões do workspace
DELETE /suppressions/:emailremove_suppressionRemover uma supressão de bounce elegível
GET /blocked-recipientslist_blocked_recipientsListar bounces, reclamações e cancelamentos de assinatura
GET /accountget_accountRecuperar conta, uso, estado de cobrança e contagens do workspace com uma chave de API
GET /analyticsget_analyticsRecuperar análises de envio do painel para 7, 30 ou 90 dias
GET /profileget_accountGêmeo somente de sessão de GET /account; o servidor MCP lê a rota de chave de API.
POST /billing/checkoutnão expostoAlterações de cobrança são somente de sessão por design e exigem o proprietário da conta no painel. O estado de cobrança é legível com get_account.
POST /billing/cancelnão expostoAlterações de cobrança são somente de sessão por design e exigem o proprietário da conta no painel. O estado de cobrança é legível com get_account.
POST /keysnão expostoExcluído deliberadamente: um agente não deve criar ou destruir credenciais. As chaves são gerenciadas por um humano no painel.
GET /keyslist_api_keysListar metadados de chaves de API
DELETE /keys/:idnão expostoExcluído deliberadamente: um agente não deve criar ou destruir credenciais. As chaves são gerenciadas por um humano no painel.

Deliberadamente indisponível

CapacidadeEndpointsMotivo
Criar, rotacionar, revogar ou excluir chaves de APIPOST /keys, DELETE /keys/:idExcluído deliberadamente: um agente não deve criar ou destruir credenciais. As chaves são gerenciadas por um humano no painel.
Iniciar um checkout ou cancelar uma assinaturaPOST /billing/checkout, POST /billing/cancelAlterações de cobrança são somente de sessão por design e exigem o proprietário da conta no painel. O estado de cobrança é legível com get_account.
DNS em um clique do Cloudflare (OAuth)GET /api/dns/cloudflare/connectRequer uma sessão de navegador interativa e consentimento OAuth do Cloudflare. Use get_domain records, get_dns_provider hosts ou get_domain_connect_link em vez disso.
Cadastrar, entrar, sair, vinculação de conta Google/api/auth/*Autenticação humana no navegador; o servidor MCP autentica com uma chave de API.
Formulário de contato de suportePOST /api/contactFormulário público do site de marketing para humanos, não uma operação do workspace.

Catálogo legível por máquina: /docs/mcp/tools.json (schemas, anotações, mapeamento de endpoints, exclusões). Versão em Markdown desta página: /docs/mcp.md. Com a CLI instalada, sendhq commands --format json imprime o mesmo catálogo.