Mailtrap

oficial

Integra-se com Mailtrap Email API.

O que você pode fazer com Mailtrap MCP?

  • Enviar e-mail transacional — Peça ao assistente para enviar um e-mail com assunto e corpo em texto ou HTML, opcionalmente usando um modelo e variáveis.
  • Testar no Email Sandbox — Envie mensagens para um sandbox e inspecione o conteúdo, os cabeçalhos e os anexos sem que elas cheguem a destinatários reais.
  • Depurar a entrega com logs — Liste e filtre os logs de e-mails enviados e, em seguida, abra uma mensagem específica para revisar o histórico de eventos e o status da entrega.
  • Analisar estatísticas de envio — Obtenha taxas de entrega, rejeição, abertura, cliques e spam para um período, detalhadas por domínio, categoria ou data.
  • Gerenciar modelos — Crie, liste, atualize e exclua modelos de e-mail armazenados na sua conta do Mailtrap.
  • Gerenciar domínios e supressões — Liste domínios, obtenha instruções de configuração de DNS e consulte ou remova endereços suprimidos.

Documentação

TypeScript test NPM

Servidor MCP oficial do Mailtrap

O servidor MCP oficial do Mailtrap — a plataforma de entrega de e-mails. Ele conecta sua conta do Mailtrap ao Claude, Cursor, VS Code e outros assistentes de IA compatíveis com MCP.

Envie e-mails transacionais e em massa, teste mensagens com segurança no Email Sandbox, gerencie modelos, contatos, domínios e webhooks, inspecione logs de e-mail e estatísticas de entrega, solucione problemas de entregabilidade e gerencie recursos da conta — tudo usando prompts em linguagem natural.

Recursos

  • API de e-mail e SMTP — Envie e-mails transacionais e em massa, incluindo mensagens em lote e baseadas em modelos.
  • Testes de e-mail — Teste mensagens no Email Sandbox e inspecione conteúdo, cabeçalhos, anexos, pontuações de spam e compatibilidade com clientes de e-mail HTML.
  • Monitoramento de entrega — Pesquise logs de e-mail, inspecione o histórico de eventos e analise taxas de entrega, rejeição, abertura, cliques e spam.
  • Infraestrutura de e-mail — Gerencie domínios, verificação de DNS, webhooks e supressões.
  • Contatos — Gerencie contatos, listas, campos personalizados e eventos, com importações e exportações.
  • Gerenciamento da conta — Consulte o uso de cobrança e gerencie acesso, permissões, tokens de API e subcontas.

Clientes MCP compatíveis

Funciona com Claude Desktop, Claude Code, Cursor, VS Code e qualquer outro cliente compatível com MCP. As instruções de configuração de cada um estão abaixo.

Pré-requisitos

Antes de usar este servidor MCP, você precisa:

  1. Criar uma conta no Mailtrap
  2. Verificar seu domínio
  3. Obter seu token de API em configurações da API do Mailtrap
  4. Obter seu ID da conta em gerenciamento da conta do Mailtrap
  5. Instalar o Node.js 22 ou posterior, a menos que você execute a imagem do Docker

Variáveis de ambiente obrigatórias:

  • MAILTRAP_API_TOKEN - Obrigatória para todas as funcionalidades
  • MAILTRAP_ACCOUNT_ID - Obrigatória para modelos, get-sending-stats, logs de e-mail, list/show do sandbox, domínios e supressões. Opcional apenas para as ferramentas de envio (send-email, send-sandbox-email e as ferramentas batch-send-*), as ferramentas de campanhas de e-mail, get-marketing-stats, as ferramentas de informações da empresa, as ferramentas de desativação do rastreamento e list-accounts.

Opcionais (também podem ser passadas como parâmetros das ferramentas):

  • DEFAULT_FROM_EMAIL - E-mail do remetente padrão quando from não é fornecido a send-email, send-sandbox-email ou às ferramentas batch-send-* (quando preenche base.from). Permite trocar o remetente em cada chamada usando o parâmetro from.
  • MAILTRAP_SANDBOX_ID - ID padrão do sandbox quando sandbox_id de uma ferramenta não é fornecido (o test_inbox_id legado ainda é aceito nas ferramentas de envio/listagem/exibição de mensagens do sandbox). Permite trocar de sandbox em cada chamada usando parâmetros.
  • MAILTRAP_TEST_INBOX_ID - Alias obsoleto de MAILTRAP_SANDBOX_ID; ainda é lido como alternativa para configurações existentes e registra um aviso de obsolescência em stderr quando usado.
  • MAILTRAP_ORGANIZATION_ID - Obrigatória para ferramentas da organização (list-sub-accounts, create-sub-account, delete-sub-account).
  • MAILTRAP_ORGANIZATION_API_TOKEN - Token de API com escopo da organização. Obrigatório para ferramentas da organização (separado de MAILTRAP_API_TOKEN).

Instalação rápida

Install in Cursor

Install with Node in VS Code

Docker

Execute o servidor por stdio usando a imagem do Docker MCP Catalog:

docker run --rm -i \
  -e MAILTRAP_API_TOKEN="${MAILTRAP_API_TOKEN}" \
  -e MAILTRAP_ACCOUNT_ID="${MAILTRAP_ACCOUNT_ID}" \
  -e DEFAULT_FROM_EMAIL="${DEFAULT_FROM_EMAIL}" \
  -e MAILTRAP_SANDBOX_ID="${MAILTRAP_SANDBOX_ID}" \
  -e MAILTRAP_ORGANIZATION_ID="${MAILTRAP_ORGANIZATION_ID}" \
  -e MAILTRAP_ORGANIZATION_API_TOKEN="${MAILTRAP_ORGANIZATION_API_TOKEN}" \
  mcp/mailtrap

Consulte Pré-requisitos para ver as variáveis de ambiente obrigatórias e opcionais.

Para compilar a partir deste repositório: docker build -t mcp/mailtrap .

Smithery CLI

Smithery é um registro e instalador de servidores MCP compatível com clientes de IA.

Instale o servidor publicado (mailtrap/mailtrap-mcp) em um cliente local (substitua o nome do cliente conforme necessário):

npx -y smithery mcp add mailtrap/mailtrap-mcp --client claude

Consulte a documentação do Smithery CLI para outros clientes (cursor, windsurf etc.) e para publicar atualizações.

Configuração

Claude Desktop

Use o MCPB para instalar o servidor Mailtrap. Você encontra esses arquivos em Releases.
Baixe o arquivo .MCPB e abra-o. Se você tiver o Claude Desktop, ele será aberto e sugerirá a configuração.

Claude Desktop ou Cursor

Adicione a seguinte configuração:

{
  "mcpServers": {
    "mailtrap": {
      "command": "npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

Se você estiver usando asdf para gerenciar o Node.js, deverá usar o caminho absoluto para o executável (exemplo para Mac)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "22.14.0",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

Localização do arquivo de configuração do Claude Desktop

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Localização do arquivo de configuração do Cursor

Mac: ~/.cursor/mcp.json

Windows: %USERPROFILE%\.cursor\mcp.json

VS Code

Alterar a configuração manualmente

Execute na Paleta de Comandos: Preferences: Open User Settings (JSON)

Em seguida, adicione a seguinte configuração ao arquivo de configurações:

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "npx",
        "args": ["-y", "mcp-mailtrap"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
        }
      }
    }
  }
}

[!TIP] Não se esqueça de reiniciar o servidor MCP depois de alterar a seção "env".

Pacote MCP (MCPB)

Para facilitar a instalação em hosts compatíveis com Pacotes MCP, você pode distribuir um arquivo de pacote .mcpb.

# Build TypeScript and pack the MCPB bundle
npm run mcpb:pack

# Inspect bundle metadata
npm run mcpb:info

# Sign the bundle for distribution (optional)
npm run mcpb:sign

Isso cria mailtrap-mcp.mcpb. O script copia dist/, manifest.json, icon.png e a licença para mcpb-build/, instala as dependências de produção nesse diretório e empacota somente esse diretório. Não execute mcpb pack . a partir da raiz do repositório.

Uso

Depois de configurar, você pode pedir ao agente que envie e-mails e gerencie modelos, por exemplo:

Operações de envio de e-mail:

  • "Envie um e-mail para john.doe@example.com com o assunto 'Meeting Tomorrow' e um lembrete simpático sobre nossa próxima reunião."
  • "Envie um e-mail para sarah@example.com sobre a atualização do projeto e coloque a equipe em cópia em team@example.com"
  • "Envie o modelo de boas-vindas (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) para new@example.com com as variáveis { name: 'Alex' }"
  • "Envie um e-mail de sandbox para test@example.com com o assunto 'Test Template' para visualizar como fica nosso e-mail de boas-vindas"

Logs de e-mail (depuração da entrega):

  • "Liste meus logs recentes de e-mails enviados"
  • "Mostre os logs de e-mail das mensagens enviadas para user@example.com"
  • "Obtenha o log da mensagem de e-mail com o ID abc-123-uuid para verificar o status da entrega"

Estatísticas:

  • "Obtenha as estatísticas de envio de janeiro de 2025"
  • "Mostre as taxas de entrega por domínio do mês passado"
  • "Quais são minhas estatísticas de e-mail por categoria de 2025-01-01 a 2025-01-31?"
  • "Qual foi o desempenho do meu marketing por e-mail no mês passado? Compare campanhas com automações"

Operações do sandbox:

  • "Obtenha todas as mensagens do meu sandbox"
  • "Mostre a primeira página de mensagens do sandbox"
  • "Pesquise mensagens que contenham 'test' no meu sandbox"
  • "Crie um sandbox chamado 'QA' no projeto 42 e me forneça as credenciais SMTP"
  • "Exclua todas as mensagens do sandbox 1234"
  • "Mostre os detalhes da mensagem do sandbox com o ID 5159037506"

Operações com modelos:

  • "Liste todos os modelos de e-mail da minha conta do Mailtrap"
  • "Crie um novo modelo de e-mail chamado 'Welcome Email' com o assunto 'Welcome to our platform!'"
  • "Atualize o modelo com o ID 12345 para alterar o assunto para 'Updated Welcome Message'"
  • "Exclua o modelo com o ID 67890"

Domínios:

  • "Liste meus domínios"
  • "Obtenha o domínio com o ID 3938"
  • "Crie um domínio para example.com"
  • "Ative o rastreamento de cliques para o domínio 3938"
  • "Exclua o domínio 3938"
  • "Obtenha o domínio 3938 com instruções de configuração de DNS"
  • "Mostre as informações da empresa para o domínio 3938"
  • "Defina as informações da empresa para o domínio 3938 como Acme Inc, 123 Main St, San Francisco, US, 94105, https://acme.com"
  • "Altere a cidade nas informações da empresa do domínio 3938 para New York"

Supressões:

Desativações do rastreamento:

  • "Pare de rastrear aberturas e cliques de privacy@example.com no domínio 3938"
  • "Liste todas as pessoas que desativaram o rastreamento"

Contatos e listas:

  • "Adicione john.doe@example.com à minha lista de contatos da newsletter"
  • "Mostre todas as minhas listas de contatos"
  • "Crie um campo de contato chamado 'signup_source' para registrar de onde vieram os contatos"
  • "Atualize o contato john.doe@example.com para definir o plano como 'pro'"
  • "Importe estes contatos CSV para minha lista de integração"
  • "Exporte todos os contatos da minha lista de newsletter"
  • "Registre um evento 'trial_started' para o contato john.doe@example.com"

Webhooks:

  • "Liste todos os webhooks configurados na minha conta"
  • "Crie um webhook apontando para https://example.com/hooks/mailtrap para eventos de rejeição e spam"
  • "Atualize o webhook 4821 para também enviar eventos de entrega"
  • "Exclua o webhook 4821"

Conta e cobrança:

  • "Qual é meu uso de cobrança neste mês?"
  • "Quantos e-mails ainda posso enviar no meu plano?"
  • "Liste todas as pessoas que têm acesso a esta conta do Mailtrap"
  • "Mostre os recursos de permissão disponíveis na minha conta"

Tokens de API:

  • "Liste todos os tokens de API da minha conta"
  • "Crie um novo token de API para o ambiente de staging"
  • "Redefina o token de API com o ID 1234"
  • "Exclua o token de API não utilizado 1234"

Organização e subcontas:

  • "Liste todas as subcontas da minha organização"
  • "Crie uma nova subconta para o projeto do cliente 'Acme Corp'"

Ferramentas renomeadas

O Mailtrap agora chama as caixas de entrada de teste de sandboxes e os domínios de envio de domínios, e as ferramentas seguem essa nomenclatura. Os nomes antigos não aparecem mais na lista de ferramentas, mas as chamadas a eles ainda funcionam e registram um aviso de obsolescência em stderr. Eles serão removidos em uma versão principal futura.

Clientes MCP e frameworks de agentes comparam listas de permissão, bloqueio e filtragem com o nome anunciado da ferramenta. Portanto, atualize as entradas por ferramenta para os novos nomes: uma entrada de bloqueio para delete-sending-domain não bloqueia mais delete-domain.

Nome antigoNome novo
create-sandbox-inboxcreate-sandbox
get-sandbox-inboxget-sandbox
update-sandbox-inboxupdate-sandbox
delete-sandbox-inboxdelete-sandbox
clean-sandbox-inboxclean-sandbox
list-sending-domainslist-domains
get-sending-domainget-domain
create-sending-domaincreate-domain
update-sending-domainupdate-domain
delete-sending-domaindelete-domain
send-sending-domain-setup-instructionssend-domain-setup-instructions
parâmetro sending_domain_id das ferramentas de domínio e informações da empresadomain_id
variável de ambiente MAILTRAP_TEST_INBOX_IDMAILTRAP_SANDBOX_ID

Os filtros que correspondem a um campo da API mantêm seus nomes: sending_domain_id em list-email-logs e sending_domain_ids nas ferramentas de estatísticas.

Ferramentas disponíveis

send-email

Envia um e-mail transacional pelo Mailtrap. Oferece dois modos mutuamente exclusivos — conteúdo em linha (subject + text/html) ou baseado em modelo (template_uuid).

Parâmetros:

  • from (opcional): Remetente como { email, name? } (uma string de e-mail simples também é aceita em tempo de execução). Se não for fornecido, DEFAULT_FROM_EMAIL será usado.
  • to (opcional): Array de destinatários como objetos { email, name? } (strings de e-mail simples ou um único endereço que não seja um array também são aceitos em tempo de execução). Opcional se cc ou bcc for fornecido; pelo menos um entre to / cc / bcc deve conter um destinatário.
  • cc (opcional): Array de destinatários em cópia (CC) como objetos { email, name? } (strings de e-mail simples também são aceitas em tempo de execução).
  • bcc (opcional): Array de destinatários em cópia oculta (BCC) como objetos { email, name? } (strings de e-mail simples também são aceitas em tempo de execução).
  • subject (condicional): Linha de assunto do e-mail. Obrigatória para envios inline; deve ser omitida quando template_uuid estiver definido.
  • text (condicional): Texto do corpo do e-mail. Obrigatório (junto com ou em vez de html) para envios inline; deve ser omitido quando template_uuid estiver definido.
  • html (condicional): Versão HTML do corpo do e-mail. Obrigatória (junto com ou em vez de text) para envios inline; deve ser omitida quando template_uuid estiver definido.
  • category (opcional): Categoria do e-mail para rastreamento e análise. Deve ser omitida quando template_uuid estiver definido.
  • template_uuid (opcional): Use um modelo de e-mail do Mailtrap em vez de conteúdo inline. Quando definido, subject / text / html / category devem ser omitidos (conforme a API do Mailtrap).
  • template_variables (opcional): Objeto de variáveis substituídas no modelo referenciado por template_uuid. Permitido somente junto com template_uuid.

batch-send-transactional-email

Envia um lote de e-mails transacionais em uma única chamada à API do Mailtrap (fluxo de envio padrão). Os campos compartilhados ficam em base; as substituições por destinatário ficam em requests[]. Cada solicitação deve incluir pelo menos um destinatário por meio de to, cc ou bcc. A mesma exclusão mútua entre inline e modelo de send-email se aplica — verificada após mesclar a base com cada solicitação.

Parâmetros:

  • base (opcional): Objeto com campos compartilhados por todo o lote.
    • from (opcional): Remetente como { email, name? } (uma string de e-mail simples também é aceita em tempo de execução). Usa DEFAULT_FROM_EMAIL como alternativa.
    • reply_to (opcional): Endereço para resposta.
    • subject / text / html / category (opcional, modo inline): Conteúdo padrão para cada solicitação.
    • template_uuid / template_variables (opcional, modo de modelo): Modelo padrão + variáveis. Mutuamente exclusivos em relação aos campos inline.
    • custom_variables (opcional): Variáveis personalizadas padrão (com valores de string).
    • headers (opcional): Cabeçalhos personalizados padrão.
  • requests (obrigatório): Array não vazio de mensagens por destinatário. Cada entrada contém:
    • to (opcional): Array de destinatários como objetos { email, name? } (strings de e-mail simples ou um único endereço que não seja um array também são aceitos em tempo de execução). Opcional se cc ou bcc for fornecido; pelo menos um entre to / cc / bcc deve conter um destinatário.
    • cc, bcc, reply_to (opcional).
    • Substituições inline (subject/text/html/category) ou de modelo (template_uuid/template_variables); qualquer campo omitido usa o valor correspondente de base.
    • custom_variables, headers (opcional).

batch-send-bulk-email

Envia um lote de e-mails em massa pela API de fluxo em massa do Mailtrap. Tem o mesmo formato base + requests[], as mesmas regras de validação e as mesmas regras de conteúdo inline versus modelo de batch-send-transactional-email — a única diferença é que esta ferramenta encaminha a chamada pelo endpoint em massa, em vez do endpoint transacional. Consulte os parâmetros acima.

list-email-logs

Lista os registros de e-mails enviados (histórico de entrega), com paginação e filtros opcionais. Use para depurar problemas de entrega no IDE.

Parâmetros:

  • search_after (opcional): Cursor de paginação da resposta anterior, em next_page_cursor
  • sent_after (opcional): Data/hora ISO 8601; somente registros enviados após esse horário
  • sent_before (opcional): Data/hora ISO 8601; somente registros enviados antes desse horário
  • from_email (opcional): Filtrar pelo e-mail do remetente; use com from_operator (padrão: ci_equal)
  • to_email (opcional): Filtrar pelo e-mail do destinatário; use com to_operator (padrão: ci_equal)
  • status (opcional): Filtrar pelo status de entrega: delivered, not_delivered, enqueued, opted_out; use com status_operator (padrão: equal)
  • subject (opcional): Filtrar pelo assunto do e-mail; use com subject_operator (padrão: ci_contain). Use subject_operator: empty/not_empty para filtrar pela presença do assunto.
  • sending_domain_id (opcional): Filtrar pelo ID do domínio (número); use com sending_domain_id_operator (padrão: equal)
  • sending_stream (opcional): Filtrar pelo fluxo: transactional ou bulk; use com sending_stream_operator (padrão: equal)
  • events (opcional): Filtrar por tipo(s) de evento: delivery, open, click, bounce, spam, unsubscribe, soft_bounce, reject, suspension; use com events_operator (include_event / not_include_event)
  • clicks_count / opens_count (opcional): Filtrar pela contagem de cliques/aberturas; use com *_operator: equal, greater_than, less_than
  • client_ip / sending_ip (opcional): Filtrar por IP; use com *_operator: equal, not_equal, contain, not_contain
  • email_service_provider_response (opcional): Filtrar pelo texto da resposta do provedor; use com *_operator (ci_contain etc.)
  • email_service_provider (opcional): Filtrar pelo provedor (exato); use com *_operator: equal, not_equal
  • recipient_mx (opcional): Filtrar pelo MX do destinatário; use com recipient_mx_operator (ci_contain etc.)
  • category (opcional): Filtrar pela categoria do e-mail; use com category_operator: equal, not_equal

Todos os parâmetros são opcionais.

get-email-log-message

Obtém uma única mensagem de registro de e-mail pelo ID (UUID): um resumo legível (remetente, destinatário, assunto, horário de envio, status, categoria, fluxo, engajamento, contexto de entrega), seguido do histórico detalhado de eventos. Opcionalmente, com include_content: true, você também pode carregar e exibir o corpo da mensagem (HTML e texto simples) quando o Mailtrap disponibilizar uma URL da mensagem bruta.

Parâmetros:

  • message_id (obrigatório): UUID da mensagem de registro de e-mail (da resposta de envio ou de list-email-logs). Use list-email-logs para encontrar IDs de mensagens.
  • include_content (opcional): Quando true, busca o EML bruto (se raw_message_url estiver disponível) e acrescenta seções com o corpo em HTML e texto simples analisados, de forma semelhante a show-sandbox-email-message.

get-sending-stats

Obtém estatísticas de envio de e-mails (taxas de entrega, rejeição, abertura, clique e spam) para um intervalo de datas. Opcionalmente, divide os dados por domínio, categoria, provedor de serviços de e-mail ou data. Confira as taxas de entrega sem sair do editor.

Parâmetros:

  • start_date (obrigatório): Data inicial do intervalo das estatísticas (YYYY-MM-DD)
  • end_date (obrigatório): Data final do intervalo das estatísticas (YYYY-MM-DD)
  • breakdown (opcional): Como dividir as estatísticas: aggregated (padrão), by_domain, by_category, by_email_service_provider ou by_date
  • sending_domain_ids (opcional): Limitar os resultados a estes IDs de domínio (array de inteiros)
  • sending_streams (opcional): Limitar a transactional e/ou bulk (array de strings)
  • categories (opcional): Limitar a estas categorias de e-mail (array de strings)
  • email_service_providers (opcional): Limitar a estes provedores, por exemplo, Google, Yahoo, Outlook (array de strings)

get-marketing-stats

Obtém estatísticas agregadas de Email Marketing em campanhas e automações para um intervalo de datas: contagens e taxas de envios, entregas, rejeições, aberturas, cliques, spam e cancelamentos de inscrição. delivery_rate e bounce_rate são proporções de sent_count; as outras taxas são proporções de delivery_count.

Parâmetros:

  • start_date (obrigatório): Início do intervalo de datas (inclusivo), YYYY-MM-DD
  • end_date (obrigatório): Fim do intervalo de datas (inclusivo), YYYY-MM-DD
  • sending_domain_ids (opcional): Limitar os resultados a estes IDs de domínio (array de inteiros)
  • sources (opcional): campaigns ou automations restringe as estatísticas a essa origem; omita ou informe ambos para incluir todo o tráfego de Email Marketing (array de strings)
  • email_service_providers (opcional): Limitar a estes provedores, por exemplo, Google, Yahoo, Outlook (array de strings)

create-template

Cria um novo modelo de e-mail na sua conta do Mailtrap.

Parâmetros:

  • name (obrigatório): Nome do modelo
  • subject (obrigatório): Linha de assunto do e-mail
  • html (ou text é obrigatório): Conteúdo HTML do modelo
  • text (ou html é obrigatório): Versão em texto simples do modelo
  • category (opcional): Categoria do modelo (o padrão é "General")

list-templates

Lista os modelos de e-mail da sua conta do Mailtrap com paginação por token de página. Quando houver mais modelos, o resultado informa token da próxima página. As páginas são deslocamentos na lista ordenada dos mais recentes para os mais antigos; portanto, após excluir modelos, liste novamente a partir de token 1 em vez de continuar com o próximo token. Uma página vazia informa a última página que ainda contém modelos.

Parâmetros:

  • token (opcional): Número da página a recuperar (paginação por token de página). O padrão é 1
  • per_page (opcional): Número de modelos por página. O padrão é 50, máximo de 100. Informe o mesmo valor em todas as páginas

get-template

Obtém um único modelo de e-mail pelo ID, incluindo assunto, categoria e corpo em HTML/texto.

Parâmetros:

  • template_id (obrigatório): ID do modelo a buscar

update-template

Atualiza um modelo de e-mail existente.

Parâmetros:

  • template_id (obrigatório): ID do modelo a atualizar
  • name (opcional): Novo nome do modelo
  • subject (opcional): Nova linha de assunto do e-mail
  • html (opcional): Novo conteúdo HTML do modelo
  • text (opcional): Nova versão em texto simples do modelo
  • category (opcional): Nova categoria do modelo

[!NOTE] Pelo menos um campo atualizável (nome, assunto, html, texto ou categoria) deve ser fornecido ao chamar update-template para realizar uma atualização.

delete-template

Exclui um modelo de e-mail existente.

Parâmetros:

  • template_id (obrigatório): ID do modelo a excluir

send-sandbox-email

Envia um e-mail para o sandbox do Mailtrap para fins de desenvolvimento e teste. É ideal para testar modelos de e-mail sem enviar mensagens a destinatários reais. Oferece os mesmos dois modos que send-email — conteúdo inline ou baseado em modelo (template_uuid).

Parâmetros:

  • sandbox_id (opcional): Preferencial. ID do sandbox do Mailtrap. Obrigatório, a menos que MAILTRAP_SANDBOX_ID esteja definido.
  • test_inbox_id (opcional): Alias legado de sandbox_id quando sandbox_id é omitido.
  • from (opcional): Remetente como { email, name? } (uma string de e-mail simples também é aceita em tempo de execução). Se não for fornecido, DEFAULT_FROM_EMAIL será usado.
  • to (opcional): Array de destinatários como objetos { email, name? } (strings de e-mail simples no array ou uma string separada por vírgulas contendo e-mails simples também são aceitas em tempo de execução). Opcional se cc ou bcc for fornecido; pelo menos um de to / cc / bcc deve conter um destinatário.
  • cc (opcional): Array de destinatários em cópia (CC) como objetos { email, name? } (strings de e-mail simples também são aceitas em tempo de execução).
  • bcc (opcional): Array de destinatários em cópia oculta (BCC) como objetos { email, name? } (strings de e-mail simples também são aceitas em tempo de execução).
  • subject (condicional): Assunto do e-mail. Obrigatório para envios inline; deve ser omitido quando template_uuid estiver definido.
  • text (condicional): Texto do corpo do e-mail. Obrigatório (junto com ou em vez de html) para envios inline; deve ser omitido quando template_uuid estiver definido.
  • html (condicional): Versão HTML do corpo do e-mail. Obrigatória (junto com ou em vez de text) para envios inline; deve ser omitida quando template_uuid estiver definido.
  • category (opcional): Categoria do e-mail para rastreamento. Deve ser omitida quando template_uuid estiver definido.
  • template_uuid (opcional): Use um modelo de e-mail do Mailtrap em vez de conteúdo inline. Quando definido, subject / text / html / category devem ser omitidos.
  • template_variables (opcional): Objeto de variáveis substituídas no modelo referenciado por template_uuid. Permitido somente junto com template_uuid.

batch-send-sandbox-email

Envia um lote de e-mails para seu sandbox do Mailtrap em uma única chamada de API, sem entregá-los a destinatários reais. Mesma estrutura de base + requests[], validação e regras de conteúdo inline versus modelo de batch-send-transactional-email — a diferença é que esta ferramenta encaminha a chamada pelo endpoint do sandbox para um único sandbox.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox do Mailtrap. Obrigatório, a menos que MAILTRAP_SANDBOX_ID esteja definido; informe por chamada para direcionar a um sandbox específico.
  • base (opcional), requests (obrigatório): Consulte batch-send-transactional-email acima.

[!NOTE] A maioria das ferramentas de sandbox usa sandbox_id (ou recorre a MAILTRAP_SANDBOX_ID; a variável de ambiente obsoleta MAILTRAP_TEST_INBOX_ID ainda funciona). send-sandbox-email, get-sandbox-messages e show-sandbox-email-message também aceitam o valor legado test_inbox_id. get-sandbox, update-sandbox, delete-sandbox e clean-sandbox usam sandbox_id com o valor legado inbox_id (mesmo ID; inbox_id não é usado nas ferramentas de mensagens). As ferramentas de e-mail recebido usam inbox_id para um produto diferente (e-mails recebidos), não para o sandbox.

get-sandbox-messages

Recupera uma lista de mensagens do seu sandbox do Mailtrap. Útil para verificar quais e-mails foram recebidos no sandbox durante os testes.

Parâmetros:

  • sandbox_id (opcional): Preferencial. ID do sandbox, a menos que MAILTRAP_SANDBOX_ID esteja definido.
  • test_inbox_id (opcional): Alias legado de sandbox_id.
  • page (opcional): Número da página para paginação (mínimo: 1)
  • last_id (opcional): Paginação usando o ID da última mensagem. Retorna mensagens posteriores ao ID de mensagem especificado (mínimo: 1)
  • search (opcional): Consulta de pesquisa para filtrar mensagens

[!NOTE] Os parâmetros de ID do sandbox são opcionais quando MAILTRAP_SANDBOX_ID está definido. Se nenhum de sandbox_id, test_inbox_id ou a variável de ambiente for fornecido, a chamada falhará. Paginação: use page, last_id ou search conforme necessário.

show-sandbox-email-message

Exibe informações detalhadas e o conteúdo de uma mensagem de e-mail específica do seu sandbox do Mailtrap, incluindo o conteúdo do corpo em HTML e texto.

Parâmetros:

  • sandbox_id (opcional): Preferencial. ID do sandbox, a menos que MAILTRAP_SANDBOX_ID esteja definido.
  • test_inbox_id (opcional): Alias legado de sandbox_id.
  • message_id (obrigatório): ID da mensagem de e-mail do sandbox a recuperar

[!NOTE] Use get-sandbox-messages primeiro para obter os IDs das mensagens e, em seguida, esta ferramenta para acessar o conteúdo completo.

list-sandbox-projects

Lista todos os projetos de sandbox e seus sandboxes.

Parâmetros:

  • Nenhum parâmetro obrigatório

create-sandbox-project

Cria um novo projeto de sandbox para agrupar sandboxes.

Parâmetros:

  • name (obrigatório): Nome do projeto (2–100 caracteres)

get-sandbox-project

Obtém um projeto de sandbox pelo ID, incluindo seus sandboxes e a quantidade de e-mails.

Parâmetros:

  • project_id (obrigatório): ID do projeto a buscar

update-sandbox-project

Renomeia um projeto de sandbox existente.

Parâmetros:

  • project_id (obrigatório): ID do projeto a atualizar
  • name (obrigatório): Novo nome do projeto (2–100 caracteres)

delete-sandbox-project

Exclui um projeto de sandbox e todos os seus sandboxes.

Parâmetros:

  • project_id (obrigatório): ID do projeto a excluir

create-sandbox

Cria um novo sandbox dentro de um projeto. Retorna as novas credenciais SMTP do sandbox.

Parâmetros:

  • project_id (obrigatório): ID do projeto no qual criar o sandbox
  • name (obrigatório): Nome do sandbox

get-sandbox

Obtém os detalhes do sandbox, incluindo credenciais SMTP, quantidade de e-mails e status.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Obrigatório, a menos que MAILTRAP_SANDBOX_ID esteja definido.
  • inbox_id (opcional): Alias legado de sandbox_id.

update-sandbox

Atualiza o nome ou o nome de usuário de e-mail de um sandbox.

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox (alias legado: inbox_id)
  • name (opcional): Novo nome do sandbox
  • email_username (opcional): Novo nome de usuário de e-mail do sandbox

Pelo menos um de name ou email_username deve ser fornecido.

delete-sandbox

Exclui um sandbox e todas as suas mensagens.

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox (alias legado: inbox_id)

clean-sandbox

Exclui todas as mensagens de um sandbox sem excluir o próprio sandbox.

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox (alias legado: inbox_id)

list-sandboxes

Lista todos os sandboxes acessíveis pelo token de API em todos os projetos.

Parâmetros:

  • Nenhum parâmetro obrigatório

mark-sandbox-as-read

Marca todas as mensagens de um sandbox como lidas.

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox a ser usado

reset-sandbox-credentials

Redefine as credenciais SMTP de um sandbox. Retorna o novo nome de usuário e a nova senha.

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox a ser usado

enable-sandbox-email-address

Ativa o endereço de recebimento de e-mails de um sandbox (habilita o endereço do Mailtrap que entrega mensagens ao sandbox via SMTP).

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox a ser usado

reset-sandbox-email-address

Gera um novo endereço de recebimento de e-mails para um sandbox.

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox a ser usado

forward-sandbox-message

Encaminha uma mensagem do sandbox para um endereço de e-mail externo. O encaminhamento é contabilizado na sua cota mensal.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obrigatório): ID da mensagem do sandbox a encaminhar
  • email (obrigatório): Endereço de e-mail para o qual encaminhar a mensagem

update-sandbox-message

Marca uma mensagem do sandbox como lida ou não lida.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obrigatório): ID da mensagem do sandbox a atualizar
  • is_read (obrigatório): true marca como lida; false marca como não lida

delete-sandbox-message

Exclui uma única mensagem do sandbox.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obrigatório): ID da mensagem do sandbox a excluir

get-sandbox-message-spam-score

Obtém o relatório de spam do SpamAssassin para uma mensagem do sandbox (pontuação, regras e relatório completo). Alternativa independente a include_spam_report: true em show-sandbox-email-message.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-html-analysis

Obtém o relatório de análise HTML de uma mensagem do sandbox (pontuações de compatibilidade com clientes e elementos problemáticos). Alternativa independente a include_html_analysis: true em show-sandbox-email-message.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-headers

Obtém os cabeçalhos de e-mail analisados de uma mensagem do sandbox.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-html

Obtém o corpo HTML renderizado de uma mensagem do sandbox.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-text

Obtém o corpo em texto simples de uma mensagem do sandbox.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-raw

Obtém a mensagem bruta, formatada em MIME (cabeçalhos + corpo), de uma mensagem do sandbox.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-eml

Obtém a mensagem renderizada como conteúdo de arquivo EML (adequado para anexar a um chamado ou importar para outro cliente de e-mail).

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-html-source

Obtém o código-fonte HTML não renderizado de uma mensagem do sandbox (HTML antes de quaisquer transformações feitas pelo Mailtrap, como reescritas de links CID).

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obrigatório): ID da mensagem do sandbox

list-sandbox-attachments

Lista todos os anexos de uma mensagem do sandbox (nome do arquivo, tipo de conteúdo, tamanho e caminho de download).

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-attachment

Obtém os metadados e a URL de download de um único anexo.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obrigatório): ID da mensagem do sandbox que contém o anexo
  • attachment_id (obrigatório): ID do anexo a buscar

list-domains

Lista os domínios e o status de verificação de DNS.

Parâmetros:

  • Nenhum parâmetro obrigatório

get-domain

Obtém um domínio pelo ID e seu status de verificação (incluindo registros DNS). Opcionalmente, inclua instruções de configuração de DNS definindo include_setup_instructions como true.

Parâmetros:

  • domain_id (obrigatório): ID do domínio (alias legado: sending_domain_id)
  • include_setup_instructions (opcional): Se true, acrescenta instruções de configuração de DNS à resposta. Padrão: false

create-domain

Cria um novo domínio. Após a criação, adicione registros DNS para verificar o domínio (use get-domain com include_setup_instructions: true para ver os registros).

Parâmetros:

  • domain_name (obrigatório): Nome do domínio (por exemplo, example.com)

update-domain

Atualize as configurações de rastreamento e recebimento de um domínio.

Parâmetros:

  • domain_id (obrigatório): ID do domínio (alias legado: sending_domain_id)
  • open_tracking_enabled (opcional): Rastrear aberturas de e-mails enviados deste domínio
  • click_tracking_enabled (opcional): Rastrear cliques em links de e-mails enviados deste domínio
  • tracking_opt_out_enabled (opcional): Adicionar o link para desativar o rastreamento aos e-mails rastreados. Requer rastreamento de aberturas ou cliques
  • auto_unsubscribe_link_enabled (opcional): Adicionar automaticamente um link de cancelamento de inscrição aos e-mails
  • inbound_enabled (opcional): Permitir que o domínio seja associado a uma caixa de entrada de recebimento como um endereço catch-all

É necessário fornecer pelo menos uma configuração além de domain_id.

delete-domain

Excluir um domínio.

Parâmetros:

  • domain_id (obrigatório): ID do domínio a excluir (alias legado: sending_domain_id)

send-domain-setup-instructions

Enviar por e-mail as instruções de configuração de DNS de um domínio para um endereço informado. Útil para encaminhar registros DNS a um colega da equipe de DevOps.

Parâmetros:

  • domain_id (obrigatório): ID do domínio (alias legado: sending_domain_id)
  • email (obrigatório): Endereço de e-mail para o qual enviar as instruções de configuração de DNS

get-company-info

Obter as informações da empresa de um domínio, usadas para a verificação de conformidade do domínio.

Parâmetros:

  • domain_id (obrigatório): ID do domínio (alias legado: sending_domain_id)

create-company-info

Definir as informações da empresa de um domínio, necessárias para a verificação de conformidade do domínio.

Parâmetros:

  • domain_id (obrigatório): ID do domínio (alias legado: sending_domain_id)
  • name (obrigatório): Nome da empresa ou da pessoa física
  • address (obrigatório): Endereço
  • city (obrigatório): Cidade
  • country (obrigatório): País
  • zip_code (obrigatório): CEP ou código postal
  • website_url (obrigatório): URL do site da empresa
  • phone (opcional): Número de telefone
  • privacy_policy_url (opcional): URL da página da política de privacidade
  • terms_of_service_url (opcional): URL da página dos termos de serviço
  • info_level (opcional): business ou individual

update-company-info

Atualizar as informações da empresa de um domínio.

Parâmetros:

  • domain_id (obrigatório): ID do domínio (alias legado: sending_domain_id)
  • Todos os campos de create-company-info são opcionais. É necessário fornecer pelo menos um; os campos omitidos permanecem inalterados.

list-suppressions

Listar ou pesquisar supressões (rejeições definitivas, reclamações de spam, cancelamentos de inscrição, importações manuais). Retorna até 1000 resultados por chamada.

Parâmetros:

  • email (opcional): Filtro de e-mail. Retorna apenas as supressões correspondentes a este endereço.

create-suppression

Adicionar um endereço de e-mail à lista de supressão da conta para que o Mailtrap pare de enviar mensagens para ele.

Parâmetros:

  • email (obrigatório): Endereço de e-mail a suprimir
  • domain_id (obrigatório): ID do domínio ao qual a supressão se aplica
  • sending_stream (obrigatório): transactional ou bulk
  • type (opcional): hard bounce, spam complaint, unsubscription ou manual import. O padrão é manual import

delete-suppression

Excluir uma supressão pelo ID. O Mailtrap retomará o envio para este endereço de e-mail, a menos que ele seja suprimido novamente.

Parâmetros:

  • suppression_id (obrigatório): ID da supressão a excluir

list-tracking-opt-outs

Listar endereços de e-mail excluídos do rastreamento de aberturas e cliques. Retorna até 1000 registros por chamada.

Parâmetros:

  • email (opcional): Filtro de e-mail. Retorna apenas as exclusões correspondentes a este endereço
  • start_time (opcional): Apenas exclusões criadas neste horário ou depois (ISO 8601)
  • end_time (opcional): Apenas exclusões criadas neste horário ou antes (ISO 8601)
  • last_id (opcional): Cursor de paginação — o last_id da resposta anterior

create-tracking-opt-out

Excluir um endereço de e-mail do rastreamento de aberturas e cliques de um domínio.

Parâmetros:

  • email (obrigatório): Endereço de e-mail a excluir do rastreamento
  • domain_id (obrigatório): ID do domínio ao qual a exclusão se aplica

delete-tracking-opt-out

Remover um endereço de e-mail da lista de exclusão do rastreamento para que o rastreamento de aberturas e cliques volte a se aplicar a ele.

Parâmetros:

  • tracking_opt_out_id (obrigatório): ID da exclusão de rastreamento a remover

list-webhooks

Listar todos os webhooks configurados para a conta. Retorna os registros completos dos webhooks em JSON.

Parâmetros:

  • Nenhum parâmetro obrigatório

get-webhook

Obter um webhook pelo ID. Retorna o registro completo do webhook em JSON. Observação: signing_secret não é retornado aqui — ele só está disponível na resposta de create-webhook.

Parâmetros:

  • webhook_id (obrigatório): ID do webhook a buscar

create-webhook

Criar um webhook. A resposta inclui um signing_secret para verificar as assinaturas dos payloads do webhook — esse segredo é retornado somente na criação, portanto, armazene-o agora. Se você o perder, recrie o webhook.

Parâmetros:

  • url (obrigatório): URL para a qual o Mailtrap enviará eventos do webhook por POST
  • webhook_type (obrigatório): "email_sending", "audit_log" ou "inbound_receiving"
  • active (opcional, booleano): o padrão é true
  • payload_format (opcional): "json" ou "jsonlines". O padrão é "json"
  • sending_stream (opcional, somente email_sending): "transactional" ou "bulk"
  • event_types (opcional, somente email_sending): matriz de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • domain_id (opcional, somente email_sending): ID do domínio ao qual limitar este webhook
  • inbound_inbox_id (opcional, somente inbound_receiving): ID da caixa de entrada de recebimento à qual o webhook está vinculado; omita para aplicá-lo a todas as caixas de entrada da conta

update-webhook

Atualizar os campos editáveis de um webhook. webhook_type, sending_stream e domain_id não podem ser alterados após a criação — recrie o webhook se precisar alterá-los.

Parâmetros:

  • webhook_id (obrigatório): ID do webhook a atualizar
  • url (opcional): Nova URL do webhook
  • active (opcional, booleano): Ativar ou desativar o webhook
  • payload_format (opcional): "json" ou "jsonlines"
  • event_types (opcional, somente email_sending): matriz de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • inbound_inbox_id (opcional, somente inbound_receiving): ID da caixa de entrada de recebimento à qual o webhook está vinculado

delete-webhook

Excluir permanentemente um webhook pelo ID. Retorna o registro do webhook excluído.

Parâmetros:

  • webhook_id (obrigatório): ID do webhook a excluir

get-contact

Obter um contato pelo ID ou endereço de e-mail. Retorna o registro completo do contato (associações a listas, status, campos personalizados).

Parâmetros:

  • contact_identifier (obrigatório): ID do contato ou endereço de e-mail

create-contact

Criar um novo contato.

Parâmetros:

  • email (obrigatório): Endereço de e-mail
  • fields (opcional): Valores de campos personalizados identificados pela tag de mesclagem (por exemplo, first_name). Valores de texto, número ou booleano
  • list_ids (opcional): IDs das listas de contatos às quais inscrever este contato
  • unsubscribed (opcional, booleano): Criar o contato com o status unsubscribed

update-contact

Atualizar um contato existente identificado pelo ID ou endereço de e-mail. list_ids substitui o conjunto completo de associações do contato; list_ids_included/list_ids_excluded adicionam/removem sem afetar as demais.

Parâmetros:

  • contact_identifier (obrigatório): ID do contato ou endereço de e-mail
  • email (opcional): Novo endereço de e-mail
  • fields (opcional): Valores de campos personalizados identificados pela tag de mesclagem
  • list_ids (opcional): Substituir o conjunto de associações por esta lista exata
  • list_ids_included (opcional): IDs de listas a adicionar (aditivo)
  • list_ids_excluded (opcional): IDs de listas a remover
  • unsubscribed (opcional, booleano): Definir como unsubscribed (true) ou subscribed (false)

delete-contact

Excluir permanentemente um contato pelo ID ou endereço de e-mail. Retorna o registro do contato excluído quando a API fornece um; caso contrário, retorna um payload de confirmação.

Parâmetros:

  • contact_identifier (obrigatório): ID do contato ou endereço de e-mail

create-contact-event

Registrar um evento de contato para um contato (pelo ID ou endereço de e-mail). Usado para acionar automações de listas de contatos.

Parâmetros:

  • contact_identifier (obrigatório): ID do contato ou endereço de e-mail
  • name (obrigatório): Nome do evento (corresponde aos gatilhos de automação)
  • params (obrigatório): Objeto com pares arbitrários de chave/valor. Os valores podem ser texto, número, booleano ou nulo

list-contact-lists

Listar todas as listas de contatos da conta.

Parâmetros:

  • search (opcional): Filtrar listas de contatos pelo nome (correspondência sem distinção entre maiúsculas e minúsculas), por exemplo, news

get-contact-list

Obter uma lista de contatos pelo ID.

Parâmetros:

  • list_id (obrigatório): ID da lista de contatos a buscar

create-contact-list

Criar uma nova lista de contatos.

Parâmetros:

  • name (obrigatório): Nome da nova lista

update-contact-list

Renomear uma lista de contatos existente.

Parâmetros:

  • list_id (obrigatório): ID da lista de contatos
  • name (obrigatório): Novo nome da lista

delete-contact-list

Excluir permanentemente uma lista de contatos pelo ID.

Parâmetros:

  • list_id (obrigatório): ID da lista de contatos a excluir

list-contact-fields

Listar todas as definições de campos de contato da conta.

Parâmetros:

  • Nenhum parâmetro obrigatório

get-contact-field

Obter uma definição de campo de contato pelo ID.

Parâmetros:

  • field_id (obrigatório): ID do campo de contato

create-contact-field

Criar uma nova definição de campo de contato. merge_tag deve ser exclusivo na conta e é usado como nome do placeholder nas variáveis de modelo.

Parâmetros:

  • name (obrigatório): Nome de exibição (por exemplo, "Nome")
  • merge_tag (obrigatório): Nome exclusivo do placeholder (por exemplo, first_name)
  • data_type (obrigatório): Um de text, number, boolean, date

update-contact-field

Atualizar uma definição de campo de contato. Qualquer combinação de name, merge_tag e data_type pode ser alterada.

Parâmetros:

  • field_id (obrigatório): ID do campo de contato
  • name (opcional): Novo nome de exibição
  • merge_tag (opcional): Nova tag de mesclagem (deve continuar sendo exclusiva)
  • data_type (opcional): Um de text, number, boolean, date

delete-contact-field

Excluir permanentemente uma definição de campo de contato pelo ID.

Parâmetros:

  • field_id (obrigatório): ID do campo de contato a excluir

create-contact-import

Importar contatos em massa. Retorna um registro de tarefa de importação; consulte o status com get-contact-import.

Parâmetros:

  • contacts (obrigatório): Matriz de entradas de contato. Cada entrada precisa de:
    • email (obrigatório): Endereço de e-mail do contato
    • fields (opcional): Valores de campos personalizados identificados pela tag de mesclagem (valores de texto ou número)
    • list_ids_included (opcional): IDs das listas às quais adicionar o contato
    • list_ids_excluded (opcional): IDs das listas das quais remover o contato

get-contact-import

Obter o status de uma tarefa de importação de contatos (created/started/finished/failed), com as contagens de contatos criados/atualizados/acima do limite.

Parâmetros:

  • import_id (obrigatório): ID da tarefa de importação de contatos

create-contact-export

Exportar contatos que correspondam a um conjunto de filtros combinados com AND. Retorna um registro de tarefa de exportação; consulte o status com get-contact-export para obter a URL de download quando status for finished.

Parâmetros:

  • filters (obrigatório): Array de objetos de filtro. Cada um contém:
    • name (obrigatório): Campo a filtrar (list_id, subscription_status, email, etc.)
    • operator (obrigatório): Um de equal, not_equal, contains, not_contains, is_empty, is_not_empty
    • value (obrigatório): Valor de comparação (string, número, booleano ou array)

get-contact-export

Obter o status de uma tarefa de exportação de contatos. Quando status for finished, o campo url conterá o link para baixar o CSV.

Parâmetros:

  • export_id (obrigatório): ID da tarefa de exportação de contatos

list-email-campaigns

Listar as campanhas de e-mail da conta, da mais recente para a mais antiga, com paginação por token de página. Opcionalmente, filtrar por nome com search.

Parâmetros:

  • token (opcional): Número da página a recuperar (paginação por token de página). O padrão é 1
  • per_page (opcional): Número de campanhas por página. O padrão é 50, máximo de 100
  • search (opcional): Filtrar campanhas por nome (correspondência parcial sem distinção entre maiúsculas e minúsculas)

get-email-campaign

Obter uma campanha de e-mail pelo ID.

Parâmetros:

  • email_campaign_id (obrigatório): ID da campanha de e-mail

create-email-campaign

Criar uma nova campanha de e-mail. A campanha é sempre criada no estado draft; o agendamento e o início são feitos por ferramentas separadas (schedule-email-campaign, start-email-campaign).

Parâmetros:

  • name (obrigatório): Nome da campanha
  • domain_id (obrigatório): ID do domínio verificado usado na campanha, conforme retornado por list-domains
  • from_local_part (obrigatório): Parte local (antes do @) do endereço From
  • template_attributes (obrigatório): Modelo de e-mail em linha. Contém:
    • subject (obrigatório): Linha de assunto do e-mail (máximo de 255 caracteres). Aceita tags de mesclagem, por exemplo, Hi {{first_name}}
    • body_html (opcional): Corpo HTML (o design). Obrigatório antes que a campanha possa ser agendada ou iniciada. Inclua um link de cancelamento de inscrição por meio de uma âncora cujo href contenha o placeholder __unsubscribe_url__
    • body_text (opcional): Alternativa em texto simples do corpo do e-mail
    • merge_tags (opcional): Nomes simples das tags de mesclagem referenciadas no assunto/corpo, por exemplo, ["first_name"]
  • from_display_name (opcional): Nome de exibição mostrado no cabeçalho From
  • reply_to (opcional): Partes do endereço Reply-To (display_name, local_part, domain)
  • delivery_mode (opcional): rapid (enviar o mais rápido possível) ou gradual (limitar a taxa a delivery_options.emails_per_hour)
  • delivery_options (opcional): Opções de limitação da taxa de entrega (emails_per_hour)
  • contact_list_ids (opcional): IDs das listas de contatos para envio (tratadas como o conjunto completo de listas incluídas)
  • contact_segment_ids (opcional): IDs dos segmentos de contatos para envio (tratados como o conjunto completo de segmentos incluídos)

update-email-campaign

Atualizar uma campanha de e-mail draft. Somente os campos fornecidos são alterados; o modelo é editado no próprio lugar. Campanhas em qualquer outro estado não podem ser atualizadas.

Parâmetros:

  • email_campaign_id (obrigatório): ID da campanha de e-mail a atualizar
  • Todos os outros parâmetros são opcionais e idênticos aos de create-email-campaign (name, domain_id, from_local_part, from_display_name, reply_to, template_attributes, delivery_mode, delivery_options, contact_list_ids, contact_segment_ids)

delete-email-campaign

Excluir uma campanha de e-mail pelo ID. Somente uma campanha no estado draft pode ser excluída.

Parâmetros:

  • email_campaign_id (obrigatório): ID da campanha de e-mail a excluir

start-email-campaign

Iniciar imediatamente o envio de uma campanha de e-mail draft. Somente campanhas draft podem ser iniciadas; o modelo deve ter um design body_html, e o público e o domínio verificado devem estar definidos.

Parâmetros:

  • email_campaign_id (obrigatório): ID da campanha de e-mail a iniciar

schedule-email-campaign

Agendar uma campanha de e-mail draft para começar a ser enviada em um horário futuro. Somente campanhas draft podem ser agendadas.

Parâmetros:

  • email_campaign_id (obrigatório): ID da campanha de e-mail a agendar
  • datetime (obrigatório): Quando enviar a campanha (ISO 8601). Deve ser no futuro e não pode ultrapassar 1 mês

cancel-email-campaign

Cancelar uma campanha de e-mail scheduled, retornando-a ao estado draft. Somente campanhas scheduled podem ser canceladas.

Parâmetros:

  • email_campaign_id (obrigatório): ID da campanha de e-mail a cancelar

terminate-email-campaign

Encerrar uma campanha de e-mail que está sendo enviada no momento (started, queued ou paused), interrompendo o envio em andamento.

Parâmetros:

  • email_campaign_id (obrigatório): ID da campanha de e-mail a encerrar

reset-email-campaign

Redefinir uma campanha de e-mail scheduled para draft. Somente campanhas scheduled podem ser redefinidas.

Parâmetros:

  • email_campaign_id (obrigatório): ID da campanha de e-mail a redefinir

get-email-campaign-stats

Obter estatísticas agregadas de desempenho de uma campanha de e-mail (contagens e taxas de entregas, aberturas, cliques, devoluções, reclamações de spam e cancelamentos de inscrição).

Parâmetros:

  • email_campaign_id (obrigatório): ID da campanha de e-mail
  • start_date (opcional): Início da janela de agregação (inclusivo), YYYY-MM-DD. O padrão é o dia em que a campanha foi iniciada pela última vez
  • end_date (opcional): Fim da janela de agregação (inclusivo), YYYY-MM-DD. O padrão é a data atual

list-accounts

Listar as contas do Mailtrap às quais o token de API atual pode acessar, incluindo os níveis de acesso de cada conta. Funciona sem MAILTRAP_ACCOUNT_ID, então use-o para encontrar o ID da sua conta.

Parâmetros:

  • Nenhum parâmetro obrigatório

get-billing-usage

Obter o uso do ciclo de cobrança atual da conta: planos de envio e teste, limites e contagens atuais.

Parâmetros:

  • Nenhum parâmetro obrigatório

list-account-accesses

Listar os acessos à conta (usuários, convites, tokens de API). Filtros opcionais restringem o resultado a recursos específicos. Requer permissões de administrador/proprietário da conta.

Parâmetros:

  • domain_uuids (opcional): Filtrar por UUIDs de domínio (array de strings)
  • inbox_ids (opcional): Filtrar por IDs de sandbox (array de strings)
  • project_ids (opcional): Filtrar por IDs de projetos de sandbox (array de strings)

remove-account-access

Remover um acesso à conta pelo ID. Para identificadores User, isso revoga as permissões; para identificadores Invite ou ApiToken, isso remove o identificador por completo. Requer permissões de administrador/proprietário.

Parâmetros:

  • account_access_id (obrigatório): ID do registro de acesso a remover

get-permission-resources

Obter todos os recursos (sandboxes, projetos, domínios, cobrança, conta) aos quais o token de API tem acesso de administrador, organizados hierarquicamente.

Parâmetros:

  • Nenhum parâmetro obrigatório

bulk-update-permissions

Criar, atualizar ou excluir permissões em lote para um único acesso à conta. Pares (resource_type, resource_id) existentes são atualizados; novos são criados. Defina destroy: true em uma entrada para removê-la.

Parâmetros:

  • account_access_id (obrigatório): ID do acesso à conta de destino
  • permissions (obrigatório): Array de entradas de permissão. Cada uma contém:
    • resource_id (obrigatório): ID do recurso (número ou string)
    • resource_type (obrigatório): Um de account, project, inbox, domain, billing
    • access_level (opcional): admin/100 ou viewer/10
    • destroy (opcional, booleano): Quando true, remove esta permissão em vez de criá-la/atualizá-la

list-api-tokens

Listar todos os tokens de API da conta.

Parâmetros:

  • Nenhum parâmetro obrigatório

create-api-token

Criar um novo token de API. A resposta inclui o valor secreto token — esta é a única vez que o token completo é retornado, então armazene-o imediatamente. Se você perdê-lo, crie outro token.

Parâmetros:

  • name (obrigatório): Nome de exibição do token
  • expires_at (opcional): Expiração do token como data e hora ISO 8601. Omita para usar o padrão do servidor (1 ano); passe um null explícito para um token que nunca expira. Valores no passado ou mais de 5 anos no futuro são rejeitados
  • resources (opcional): Array de permissões de recursos para limitar o escopo do token. Cada entrada contém:
    • resource_type (obrigatório): Um de account, project, inbox, domain, billing
    • resource_id (obrigatório): ID do recurso
    • access_level (obrigatório): 100 (administrador) ou 10 (visualizador)

get-api-token

Obter um token de API pelo ID. Retorna apenas metadados — o valor secreto do token não é retornado aqui (somente por create-api-token / reset-api-token).

Parâmetros:

  • api_token_id (obrigatório): ID do token de API

reset-api-token

Redefinir (rotacionar) um token de API pelo ID. A resposta inclui o novo valor secreto token — retornado somente nesta chamada, então armazene-o imediatamente. O token anterior é invalidado.

Parâmetros:

  • api_token_id (obrigatório): ID do token de API a redefinir
  • expires_at (opcional): Expiração do novo token como data e hora ISO 8601. Omita para usar o padrão do servidor (1 ano); passe um null explícito para um token que nunca expira. Valores no passado ou mais de 5 anos no futuro são rejeitados

delete-api-token

Excluir permanentemente um token de API pelo ID. O token não poderá mais autenticar após a exclusão.

Parâmetros:

  • api_token_id (obrigatório): ID do token de API a excluir

list-sub-accounts

Listar as subcontas da organização. Requer a variável de ambiente MAILTRAP_ORGANIZATION_ID e permissões de gerenciamento de subcontas.

Parâmetros:

  • Nenhum parâmetro obrigatório

create-sub-account

Criar uma nova subconta na organização. Requer a variável de ambiente MAILTRAP_ORGANIZATION_ID e permissões de gerenciamento de subcontas.

Parâmetros:

  • name (obrigatório): Nome de exibição da nova subconta

delete-sub-account

Excluir permanentemente uma subconta pelo ID, removendo todos os seus dados. A exclusão da última subconta exclui a organização; uma chamada repetida retorna 404. Uma exclusão simultânea da mesma subconta retorna 409. Requer a variável de ambiente MAILTRAP_ORGANIZATION_ID e permissões de administrador da organização, e a organização deve ter o recurso Organization & Sub-accounts habilitado (caso contrário, retorna 403).

Parâmetros:

  • sub_account_id (obrigatório): ID da subconta a excluir

list-inbound-folders

Listar todas as pastas de entrada da conta. Retorna um resumo formatado.

Parâmetros:

  • Nenhum parâmetro obrigatório

get-inbound-folder

Obter uma pasta de entrada pelo ID. Retorna o registro completo da pasta como JSON.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada

create-inbound-folder

Criar uma nova pasta de entrada.

Parâmetros:

  • name (obrigatório): Nome da pasta

update-inbound-folder

Renomear uma pasta de entrada.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada
  • name (obrigatório): Novo nome da pasta

delete-inbound-folder

Excluir permanentemente uma pasta de entrada e todas as caixas de entrada nela contidas.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada

list-inbound-inboxes

Listar todas as caixas de entrada de uma pasta de entrada. Retorna um resumo formatado.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada

get-inbound-inbox

Obter uma caixa de entrada pelo ID. Retorna o registro completo da caixa de entrada como JSON.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada
  • inbox_id (obrigatório): ID da caixa de entrada

create-inbound-inbox

Criar uma nova caixa de entrada em uma pasta.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada
  • name (obrigatório): Nome da caixa de entrada
  • domain_id (opcional): Vincular a um domínio personalizado (caixa de entrada catch-all). Omita para uma caixa de entrada hospedada pelo Mailtrap

update-inbound-inbox

Renomeia uma caixa de entrada.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada
  • inbox_id (obrigatório): ID da caixa de entrada
  • name (obrigatório): Novo nome da caixa de entrada

delete-inbound-inbox

Exclui permanentemente uma caixa de entrada.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada
  • inbox_id (obrigatório): ID da caixa de entrada

list-inbound-messages

Lista as mensagens recebidas em uma caixa de entrada (paginação por cursor). Retorna um resumo formatado com uma indicação da próxima página quando houver mais resultados.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • last_id (opcional): Cursor de paginação da resposta anterior de last_id

get-inbound-message

Obtém uma mensagem recebida com o corpo completo e URLs para baixar anexos. Retorna o registro completo da mensagem como JSON.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • message_id (obrigatório): ID da mensagem

delete-inbound-message

Exclui permanentemente uma mensagem recebida.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • message_id (obrigatório): ID da mensagem

reply-to-inbound-message

Responde a uma mensagem recebida (envia para o remetente original). Envia um e-mail real. Os endereços aceitam uma string de e-mail simples ou { email, name? }.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • message_id (obrigatório): ID da mensagem a responder
  • text / html (pelo menos um recomendado): Corpo da resposta
  • from (opcional): Remetente. Rejeitado para caixas de entrada hospedadas pelo Mailtrap; obrigatório para caixas de entrada com domínio personalizado
  • cc / bcc / reply_to (opcional): Endereços adicionais
  • category (opcional): Categoria da mensagem
  • attachments (opcional): Array de { content (base64), filename, type?, disposition?, content_id? }
  • headers / custom_variables (opcional): Objetos com valores de string

reply-all-to-inbound-message

Responde a uma mensagem recebida e inclui os outros destinatários da mensagem original. Envia um e-mail real. Mesmos parâmetros de reply-to-inbound-message.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • message_id (obrigatório): ID da mensagem a responder
  • Além dos mesmos campos opcionais de envio de reply-to-inbound-message

forward-inbound-message

Encaminha uma mensagem recebida para novos destinatários. Envia um e-mail real.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • message_id (obrigatório): ID da mensagem a encaminhar
  • to (obrigatório): Pelo menos um destinatário (string de e-mail simples ou { email, name? }, ou um array)
  • Além dos mesmos campos opcionais de envio de reply-to-inbound-message

list-inbound-threads

Lista as conversas em uma caixa de entrada (paginação por cursor), com filtragem opcional por search. Retorna um resumo formatado com uma indicação da próxima página quando houver mais resultados.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • last_id (opcional): Cursor de paginação da resposta anterior de last_id
  • search (opcional): Texto que não diferencia maiúsculas de minúsculas, comparado ao assunto da conversa e aos endereços de remetente/destinatário/cc/cco das mensagens. Passe o mesmo valor ao paginar

get-inbound-thread

Obtém uma conversa com as mensagens incorporadas (da mais antiga para a mais recente). Retorna o registro completo da conversa como JSON.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • thread_id (obrigatório): ID da conversa

delete-inbound-thread

Exclui permanentemente uma conversa recebida.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • thread_id (obrigatório): ID da conversa

list-inbound-forward-rules

Lista as regras de encaminhamento de uma caixa de entrada. Retorna um resumo formatado.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada

get-inbound-forward-rule

Obtém uma regra de encaminhamento pelo ID. Retorna o registro completo da regra, incluindo suas condições e destinos, como JSON.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • forward_rule_id (obrigatório): ID da regra de encaminhamento

create-inbound-forward-rule

Cria uma regra de encaminhamento em uma caixa de entrada. As mensagens recebidas que corresponderem a todas as condições serão encaminhadas aos destinos da regra.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • name (obrigatório): Nome da regra, exclusivo na caixa de entrada
  • conditions (opcional): Array de { match_type, operator, value?, header_key? }. match_type é sender, recipient ou header; operator é equal, not_equal, contains, starts_with, ends_with, empty ou not_empty (empty/not_empty somente para header, e não aceitam value); header_key é obrigatório para header. Omita ou passe [] para corresponder a todas as mensagens
  • destinations (opcional): Array de { email } para encaminhar as mensagens correspondentes

update-inbound-forward-rule

Atualiza uma regra de encaminhamento. Somente os campos fornecidos são alterados; um array conditions ou destinations fornecido substitui o conjunto inteiro.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • forward_rule_id (obrigatório): ID da regra de encaminhamento
  • name (opcional): Novo nome da regra
  • conditions (opcional): Conjunto de condições substituto (mesma estrutura da criação); [] remove todas as condições, fazendo com que a regra corresponda a todas as mensagens
  • destinations (opcional): Conjunto de destinos substituto; [] remove todos os destinos

delete-inbound-forward-rule

Exclui permanentemente uma regra de encaminhamento.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • forward_rule_id (obrigatório): ID da regra de encaminhamento

Desenvolvimento

  1. Clone o repositório:
git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp
  1. Instale as dependências:
npm install

Configuração com Claude Desktop ou Cursor

[!TIP] Consulte a localização do arquivo de configuração na seção Configuração.

Adicione a seguinte configuração:

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

Se você estiver usando asdf para gerenciar o Node.js, use o caminho absoluto para o executável:

(exemplo para Mac)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "22.14.0",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

VS Code

[!TIP] Consulte a localização do arquivo de configuração na seção Configuração.

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
        }
      }
    }
  }
}

Testes

Executar ferramentas com o Mailtrap real

Há duas maneiras de testar uma ferramenta de ponta a ponta com uma conta real do Mailtrap: a interface do navegador do MCP Inspector para exploração interativa ou o modo CLI para chamadas únicas pelo shell.

Ambas exigem que o pacote seja compilado primeiro:

npm run build

e que MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID estejam exportados no shell (o script mcp:cli encaminha ambos para o servidor iniciado).

Interface do navegador

npm run dev

O Inspector exibe uma URL como http://localhost:6274. Abra-a, acesse a aba Tools, escolha uma ferramenta (por exemplo, get-template), preencha os parâmetros como JSON e clique em Run. A resposta do Mailtrap aparecerá no painel abaixo.

CLI

Para fazer chamadas únicas sem a interface, use npm run mcp:cli. Passe as opções CLI do Inspector após -- para que o npm as encaminhe sem alterações:

# List all tools
npm run mcp:cli -- --method tools/list

# Call a tool — flags after the `--`
npm run mcp:cli -- \
  --method tools/call \
  --tool-name get-template \
  --tool-arg template_id=12345

# Multiple --tool-arg flags for tools with several params
npm run mcp:cli -- \
  --method tools/call \
  --tool-name send-domain-setup-instructions \
  --tool-arg domain_id=3938 \
  --tool-arg email=devops@example.com

Executar o servidor MCPB

# Run the MCPB server directly
node dist/mcpb-server.js

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] Para desenvolvimento com o MCP Inspector:

npm run dev:mcpb

Tratamento de erros

Este servidor usa tratamento estruturado de erros, alinhado às convenções do MCP:

  • VALIDATION_ERROR: Falhas na validação de entrada
  • CONFIGURATION_ERROR: Configuração ausente ou inválida
  • EXECUTION_ERROR: Erros de execução
  • TIMEOUT: Tempo limite da operação (30 segundos por padrão)

Os erros incluem mensagens práticas e são registrados em formato estruturado.

Segurança

  • Entradas validadas por meio de esquemas Zod
  • Variáveis de ambiente tratadas com segurança
  • Proteção contra tempo limite nas operações (30 segundos)
  • Detalhes confidenciais sanitizados na saída de erros

Registro de logs

Logs JSON estruturados com os níveis: INFO, WARN, ERROR, DEBUG.

Ative o registro de depuração definindo DEBUG=true.

# Example: enable debug logging
DEBUG=true node dist/mcpb-server.js

Importante: o servidor grava os logs em stderr para que stdout permaneça reservado aos quadros JSON-RPC. Isso evita erros de análise de JSON nos hosts causados pela intercalação de logs.

Exemplo de análise de logs usando jq:

# Filter error logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "error")'

# Filter debug logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "debug")'

Solução de problemas

Problemas comuns:

  1. Token de API ausente: verifique se MAILTRAP_API_TOKEN está definido
  2. Sandbox não funciona: forneça sandbox_id na chamada da ferramenta (ou o legado test_inbox_id nas ferramentas de envio/listagem/exibição de mensagens) ou defina a variável de ambiente MAILTRAP_SANDBOX_ID
  3. Erros de tempo limite: verifique a conectividade de rede e o status da API do Mailtrap
  4. Erros de validação: verifique se todos os campos obrigatórios foram fornecidos

Contribuição

Relatos de bugs e pull requests são bem-vindos no GitHub. Este projeto pretende ser um espaço seguro e acolhedor para colaboração, e espera-se que os colaboradores sigam o código de conduta.

Licença

O pacote está disponível como código aberto sob os termos da Licença MIT.

Código de conduta

Espera-se que todas as pessoas que interagem com as bases de código, os rastreadores de problemas, as salas de bate-papo e as listas de e-mail do projeto Mailtrap sigam o código de conduta.