Mailtrap

oficial

Integra-se com Mailtrap Email API.

GitHub
65
Experimente este MCPPatrocinado

O que você pode fazer com Mailtrap MCP?

  • Enviar e-mails transacionais — Peça ao seu assistente para enviar um e-mail transacional com conteúdo inline ou um template via send-email.
  • Testar e-mails em sandbox — Envie e-mails de teste para uma caixa de entrada sandbox e inspecione o conteúdo, pontuações de spam e análise de HTML.
  • Monitorar logs de entrega — Pesquise logs de e-mail e inspecione o histórico de eventos para depurar problemas de entrega com list-email-logs.
  • Gerenciar templates de e-mail — Crie, liste, atualize ou exclua templates usando comandos em linguagem natural.
  • Analisar estatísticas de envio — Obtenha taxas de entrega, rejeição, abertura e clique para qualquer intervalo de datas com get-sending-stats.
  • Gerenciar domínios de envio — Liste, crie e configure domínios de envio com verificação de DNS e rastreamento de cliques.

Documentação

TypeScript test NPM

Servidor MCP Oficial do Mailtrap

O servidor MCP oficial para o Mailtrap — a plataforma de entrega de e-mails. Ele conecta sua conta 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 de envio 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

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

Clientes MCP Suportados

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

Pré-requisitos

Antes de usar este servidor MCP, você precisa:

  1. Criar uma conta Mailtrap
  2. Verificar seu domínio
  3. Obter seu token de API nas configurações de API do Mailtrap
  4. Obter seu ID de conta no gerenciamento de conta do Mailtrap

Variáveis de ambiente obrigatórias:

  • MAILTRAP_API_TOKEN - Obrigatório para todas as funcionalidades
  • MAILTRAP_ACCOUNT_ID - Obrigatório para modelos, estatísticas, logs de e-mail, listagem/exibição de sandbox, domínios de envio e supressões. Opcional apenas para as ferramentas de envio (send-email, send-sandbox-email e as ferramentas batch-send-*), as ferramentas de campanha de e-mail, as ferramentas de informações da empresa e as ferramentas de exclusão de rastreamento.

Opcional (pode ser passado como parâmetros de ferramenta):

  • DEFAULT_FROM_EMAIL - E-mail de remetente padrão quando from não é fornecido para send-email, send-sandbox-email ou as ferramentas batch-send-* (onde preenche base.from). Permite alternar o remetente por chamada via o parâmetro from.
  • MAILTRAP_SANDBOX_ID - ID de sandbox padrão para ferramentas de sandbox quando sandbox_id não é fornecido. Permite alternar entre sandboxes por chamada via o parâmetro sandbox_id.
  • MAILTRAP_TEST_INBOX_ID - ID de caixa de entrada de teste padrão para ferramentas de sandbox quando test_inbox_id não é fornecido. Permite alternar entre caixas de entrada por chamada via o parâmetro test_inbox_id. Alias legado para MAILTRAP_SANDBOX_ID, ainda respeitado como fallback.
  • MAILTRAP_ORGANIZATION_ID - Obrigatório para ferramentas de organização (list-sub-accounts, create-sub-account).
  • MAILTRAP_ORGANIZATION_API_TOKEN - Token de API com escopo de organização. Obrigatório para ferramentas de organização (separado de MAILTRAP_API_TOKEN).

Instalação Rápida

Install in Cursor

Install with Node in VS Code

CLI Smithery

Smithery é um instalador e gerenciador de registro para servidores MCP que funciona com todos os clientes de IA.

npx @smithery/cli install mailtrap

O Smithery lida automaticamente com a configuração do cliente e fornece um processo de configuração interativo. É a maneira mais fácil de começar com servidores MCP localmente.

Configuração

Claude Desktop

Use o MCPB para instalar o servidor Mailtrap. Você pode encontrar esses arquivos em Releases.
Baixe o arquivo .MCPB e abra-o. Se você tiver o Claude Desktop - ele abrirá 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_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Se você estiver usando asdf para gerenciar o Node.js, deve 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": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_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

Alterando a configuração manualmente

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

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

{
  "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_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

[!TIP] Não se esqueça de reiniciar seu servidor MCP após alterar a seção "env".

Pacote MCP (MCPB)

Para instalação fácil em hosts que suportam 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 usando o repositório manifest.json e artefatos compilados em dist/.

Uso

Uma vez configurado, você pode pedir ao agente para enviar e-mails e gerenciar modelos, por exemplo:

Operações de envio de e-mail:

  • "Envie um e-mail para john.doe@example.com com o assunto 'Reunião Amanhã' e um lembrete amigável sobre nossa próxima reunião."
  • "Envie um e-mail para sarah@example.com sobre a atualização do projeto e copie a equipe 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 'Modelo de Teste' para visualizar como nosso e-mail de boas-vindas fica"

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

  • "Liste meus logs de e-mail enviados recentemente"
  • "Mostre logs de e-mail para e-mails enviados para user@example.com"
  • "Obtenha a mensagem do log de e-mail para o ID abc-123-uuid para verificar o status da entrega"

Estatísticas de envio:

  • "Obtenha estatísticas de envio para janeiro de 2025"
  • "Mostre as taxas de entrega divididas por domínio no último mês"
  • "Quais são minhas estatísticas de e-mail por categoria de 2025-01-01 a 2025-01-31?"

Operações de sandbox:

  • "Obtenha todas as mensagens da minha caixa de entrada de sandbox"
  • "Mostre-me a primeira página de mensagens de sandbox"
  • "Pesquise mensagens contendo 'teste' na minha caixa de entrada de sandbox"
  • "Mostre-me os detalhes da mensagem de sandbox com ID 5159037506"

Operações de modelo:

  • "Liste todos os modelos de e-mail na minha conta Mailtrap"
  • "Crie um novo modelo de e-mail chamado 'E-mail de Boas-Vindas' com o assunto 'Bem-vindo à nossa plataforma!'"
  • "Atualize o modelo com ID 12345 para alterar o assunto para 'Mensagem de Boas-Vindas Atualizada'"
  • "Exclua o modelo com ID 67890"

Domínios de envio:

  • "Liste meus domínios de envio"
  • "Obtenha o domínio de envio com ID 3938"
  • "Crie um domínio de envio para example.com"
  • "Ative o rastreamento de cliques para o domínio de envio 3938"
  • "Exclua o domínio de envio 3938"
  • "Obtenha o domínio de envio 3938 com instruções de configuração de DNS"
  • "Mostre as informações da empresa para o domínio de envio 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 das informações da empresa para o domínio 3938 para Nova York"

Supressões:

Exclusões de rastreamento:

  • "Pare de rastrear aberturas e cliques para privacy@example.com no domínio 3938"
  • "Liste todos que optaram por sair do rastreamento"

Contatos e listas:

  • "Adicione john.doe@example.com à minha lista de contatos do boletim informativo"
  • "Mostre-me todas as minhas listas de contatos"
  • "Crie um campo de contato chamado 'signup_source' para rastrear de onde os contatos vieram"
  • "Atualize o contato john.doe@example.com para definir o plano como 'pro'"
  • "Importe contatos deste CSV para minha lista de integração"
  • "Exporte todos os contatos da minha lista do boletim informativo"
  • "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 atual neste mês?"
  • "Quantos e-mails ainda tenho no meu plano?"
  • "Liste todos que têm acesso a esta conta Mailtrap"
  • "Mostre-me os recursos de permissão disponíveis na minha conta"

Tokens de API:

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

Organização e subcontas:

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

Ferramentas Disponíveis

send-email

Envia um e-mail transacional através do Mailtrap. Suporta dois modos mutuamente exclusivos — conteúdo inline (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 é usado.
  • to (opcional): Matriz de destinatários como objetos { email, name? } (strings de e-mail simples, ou um único endereço não-matriz, também são aceitos 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): Matriz de destinatários CC como objetos { email, name? } (strings de e-mail simples também são aceitas em tempo de execução).
  • bcc (opcional): Matriz de destinatários CCO 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ó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ório (junto com ou em vez de text) para envios inline; deve ser omitido quando template_uuid estiver definido.
  • category (opcional): Categoria do e-mail para rastreamento e análise. Deve ser omitido quando template_uuid estiver definido.
  • template_uuid (opcional): Use um modelo de e-mail Mailtrap em vez de conteúdo inline. Quando definido, subject / text / html / category devem ser omitidos (de acordo com a API Mailtrap).
  • template_variables (opcional): Objeto de variáveis substituídas no modelo referenciado por template_uuid. Permitido apenas junto com template_uuid.

batch-send-transactional-email

Envia um lote de e-mails transacionais em uma única chamada de API Mailtrap (fluxo de envio padrão). Campos compartilhados vão em base; substituições por destinatário vão em requests[]. Cada solicitação deve incluir pelo menos um destinatário via to, cc ou bcc. Mesma exclusão mútua inline-vs-modelo que send-email — verificada após mesclar a base com cada solicitação.

Parâmetros:

  • base (opcional): Objeto com campos compartilhados em 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 fallback.
    • reply_to (opcional): Endereço de resposta (reply-to).
    • subject / text / html / category (opcional, modo inline): Conteúdo padrão para cada solicitação.
    • template_uuid / template_variables (opcional, modo template): Template padrão + variáveis. Mutuamente exclusivo com os campos inline.
    • custom_variables (opcional): Variáveis personalizadas padrão (com valores de string).
    • headers (opcional): Cabeçalhos personalizados padrão.
  • requests (obrigatório): Matriz não vazia de mensagens por destinatário. Cada entrada contém:
    • to (opcional): Matriz de destinatários como objetos { email, name? } (strings de e-mail simples, ou um único endereço não-matriz, também são aceitos 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, bcc, reply_to (opcional).
    • Substituições inline (subject/text/html/category) ou template (template_uuid/template_variables); qualquer campo omitido usa o valor correspondente de base como fallback.
    • custom_variables, headers (opcional).

batch-send-bulk-email

Envia um lote de e-mails em massa pela API de stream em massa do Mailtrap. Mesma estrutura de base + requests[], validação e regras de inline-vs-template que batch-send-transactional-email — a única diferença é que esta ferramenta roteia a chamada pelo endpoint em massa em vez do transacional. Consulte os parâmetros acima.

list-email-logs

Lista logs de e-mails enviados (histórico de entrega) com paginação e filtros opcionais. Use para depurar problemas de entrega diretamente da IDE.

Parâmetros:

  • search_after (opcional): Cursor de paginação da resposta anterior em next_page_cursor
  • sent_after (opcional): Data/hora ISO 8601; apenas logs enviados após este horário
  • sent_before (opcional): Data/hora ISO 8601; apenas logs enviados antes deste horário
  • from_email (opcional): Filtrar por e-mail do remetente; use com from_operator (padrão: ci_equal)
  • to_email (opcional): Filtrar por e-mail do destinatário; use com to_operator (padrão: ci_equal)
  • status (opcional): Filtrar por status de entrega: delivered, not_delivered, enqueued, opted_out; use com status_operator (padrão: equal)
  • subject (opcional): Filtrar por assunto do e-mail; use com subject_operator (padrão: ci_contain). Use subject_operator: empty/not_empty para filtrar pela presença de assunto.
  • sending_domain_id (opcional): Filtrar por ID do domínio de envio (número); use com sending_domain_id_operator (padrão: equal)
  • sending_stream (opcional): Filtrar por stream: 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 por 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 por texto de resposta do provedor; use com *_operator (ci_contain, etc.)
  • email_service_provider (opcional): Filtrar por provedor (exato); use com *_operator: equal, not_equal
  • recipient_mx (opcional): Filtrar por MX do destinatário; use com recipient_mx_operator (ci_contain, etc.)
  • category (opcional): Filtrar por 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 log de e-mail por ID (UUID): um resumo legível (de, para, assunto, horário de envio, status, categoria, stream, engajamento, contexto de entrega) e, em seguida, o 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 expõe uma URL de mensagem bruta.

Parâmetros:

  • message_id (obrigatório): UUID da mensagem de log 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 anexa seções analisadas do corpo em HTML e texto simples, semelhante a show-sandbox-email-message.

get-sending-stats

Obtenha estatísticas de envio de e-mails (taxas de entrega, bounce, abertura, clique e spam) para um intervalo de datas. Opcionalmente, divida por domínio, categoria, provedor de serviço de e-mail ou data. Verifique as taxas de entrega sem sair do editor.

Parâmetros:

  • start_date (obrigatório): Data inicial para o intervalo de estatísticas (AAAA-MM-DD)
  • end_date (obrigatório): Data final para o intervalo de estatísticas (AAAA-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 resultados a estes IDs de domínio de envio (matriz de inteiros)
  • sending_streams (opcional): Limitar a transactional e/ou bulk (matriz de strings)
  • categories (opcional): Limitar a estas categorias de e-mail (matriz de strings)
  • email_service_providers (opcional): Limitar a estes provedores, ex.: Google, Yahoo, Outlook (matriz de strings)

create-template

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

Parâmetros:

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

list-templates

Lista todos os templates de e-mail na sua conta Mailtrap.

Parâmetros:

  • Nenhum parâmetro necessário

get-template

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

Parâmetros:

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

update-template

Atualiza um template de e-mail existente.

Parâmetros:

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

[!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 template de e-mail existente.

Parâmetros:

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

send-sandbox-email

Envia um e-mail para sua caixa de entrada de teste do Mailtrap para fins de desenvolvimento e teste. Isso é perfeito para testar templates de e-mail sem enviar mensagens para destinatários reais. Suporta os mesmos dois modos que send-email — conteúdo inline ou baseado em template (template_uuid).

Parâmetros:

  • test_inbox_id (opcional): ID da caixa de entrada de teste do Mailtrap. Obrigatório a menos que MAILTRAP_TEST_INBOX_ID esteja definido; passe por chamada para direcionar uma caixa de entrada específica.
  • 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 é usado.
  • to (opcional): Matriz de destinatários como objetos { email, name? } (strings de e-mail simples na matriz, ou uma string separada por vírgulas de 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): Matriz de destinatários CC como objetos { email, name? } (strings de e-mail simples também são aceitas em tempo de execução).
  • bcc (opcional): Matriz de destinatários 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ó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ório (junto com ou em vez de text) para envios inline; deve ser omitido quando template_uuid estiver definido.
  • category (opcional): Categoria do e-mail para rastreamento. Deve ser omitido quando template_uuid estiver definido.
  • template_uuid (opcional): Use um template 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 template referenciado por template_uuid. Permitido apenas junto com template_uuid.

batch-send-sandbox-email

Envia um lote de e-mails para sua caixa de entrada de teste do Mailtrap em uma única chamada de API, sem entregar a destinatários reais. Mesma estrutura de base + requests[], validação e regras de inline-vs-template que batch-send-transactional-email — a diferença é que esta ferramenta roteia a chamada pelo endpoint sandbox para uma única caixa de entrada de teste.

Parâmetros:

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

[!NOTE] Para ferramentas de sandbox, forneça test_inbox_id na chamada da ferramenta ou defina a variável de ambiente MAILTRAP_TEST_INBOX_ID. Você pode alternar entre caixas de entrada por chamada passando test_inbox_id. Ferramentas que usam sandbox_id usam MAILTRAP_SANDBOX_ID primeiro.

get-sandbox-messages

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

Parâmetros:

  • 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 após o ID de mensagem especificado (mínimo: 1)
  • search (opcional): Consulta de busca para filtrar mensagens

[!NOTE] Todos os parâmetros são opcionais. Se nenhum for fornecido, a primeira página de mensagens da caixa de entrada será retornada. Use page para paginação tradicional, last_id para paginação baseada em cursor, ou search para filtrar mensagens por conteúdo.

show-sandbox-email-message

Mostra informações detalhadas e o conteúdo de uma mensagem de e-mail específica da sua caixa de entrada de teste do Mailtrap, incluindo o corpo em HTML e texto.

Parâmetros:

  • message_id (obrigatório): ID da mensagem de e-mail do sandbox a recuperar

[!NOTE] Use get-sandbox-messages primeiro para obter a lista de mensagens e seus IDs, depois use esta ferramenta para visualizar o conteúdo completo de uma mensagem específica.

get-sandbox-project

Obtém um projeto sandbox por ID, incluindo suas caixas de entrada e contagens de e-mails.

Parâmetros:

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

update-sandbox-project

Renomeia um projeto sandbox existente.

Parâmetros:

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

list-sandboxes

Lista todos os sandboxes acessíveis ao token da API em todos os projetos.

Parâmetros:

  • Nenhum parâmetro necessário

mark-sandbox-as-read

Marca todas as mensagens em um sandbox como lidas.

Parâmetros:

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

reset-sandbox-credentials

Reset as credenciais SMTP de um sandbox. Retorna o novo nome de usuário/senha.

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox no qual atuar

enable-sandbox-email-address

Ativa o endereço de recebimento por e-mail de um sandbox (ativa o endereço Mailtrap que entrega mensagens ao sandbox via SMTP).

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox no qual atuar

reset-sandbox-email-address

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

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox no qual atuar

forward-sandbox-message

Encaminha uma mensagem do sandbox para um endereço de e-mail externo. Isso conta contra sua cota mensal de encaminhamento.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como padrão.
  • message_id (obrigatório): ID da mensagem do sandbox a ser encaminhada
  • 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 padrão.
  • message_id (obrigatório): ID da mensagem do sandbox a ser atualizada
  • 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 padrão.
  • message_id (obrigatório): ID da mensagem do sandbox a ser excluída

get-sandbox-message-spam-score

Obtém o relatório de spam do SpamAssassin para uma mensagem do sandbox (pontuação, regras, 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 padrão.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-html-analysis

Obtém o relatório de análise de HTML para uma mensagem do sandbox (pontuações de compatibilidade com clientes, 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 padrão.
  • 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 padrão.
  • 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 padrão.
  • 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 padrão.
  • 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 padrão.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-eml

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

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como padrão.
  • 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 do lado do Mailtrap, como reescritas de links CID).

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Usa MAILTRAP_SANDBOX_ID como padrão.
  • 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, caminho de download).

Parâmetros:

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

get-sandbox-attachment

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

Parâmetros:

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

list-sending-domains

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

Parâmetros:

  • Nenhum parâmetro obrigatório

get-sending-domain

Obtém um domínio de envio por 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:

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

create-sending-domain

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

Parâmetros:

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

update-sending-domain

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

Parâmetros:

  • sending_domain_id (obrigatório): ID do domínio de envio
  • 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 de exclusão de rastreamento a e-mails rastreados. Requer rastreamento de abertura ou clique
  • 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 anexado a uma caixa de entrada de recebimento como catch-all

Pelo menos uma configuração além de sending_domain_id deve ser fornecida.

delete-sending-domain

Exclui um domínio de envio.

Parâmetros:

  • sending_domain_id (obrigatório): ID do domínio de envio a ser excluído

send-sending-domain-setup-instructions

Envia por e-mail as instruções de configuração de DNS de um domínio de envio para um endereço específico. Útil para encaminhar registros DNS a um colega de DevOps.

Parâmetros:

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

get-company-info

Obtém as informações da empresa de um domínio de envio, usadas para verificação de conformidade do domínio.

Parâmetros:

  • sending_domain_id (obrigatório): ID do domínio de envio

create-company-info

Define as informações da empresa de um domínio de envio, obrigatórias para a verificação de conformidade do domínio.

Parâmetros:

  • sending_domain_id (obrigatório): ID do domínio de envio
  • name (obrigatório): Nome da empresa ou pessoa física
  • address (obrigatório): Endereço (rua)
  • 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 de política de privacidade
  • terms_of_service_url (opcional): URL da página de termos de serviço
  • info_level (opcional): business ou individual

update-company-info

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

Parâmetros:

  • sending_domain_id (obrigatório): ID do domínio de envio
  • Todos os campos de create-company-info, todos opcionais. Pelo menos um deve ser fornecido; campos omitidos permanecem inalterados.

list-suppressions

Lista ou pesquisa supressões (rejeições permanentes, 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 supressões que correspondem a este endereço.

create-suppression

Adiciona um endereço de e-mail à lista de supressão da conta, para que o Mailtrap pare de entregar mensagens a ele.

Parâmetros:

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

delete-suppression

Exclui uma supressão por ID. O Mailtrap retomará a entrega para este e-mail, a menos que ele seja suprimido novamente.

Parâmetros:

  • suppression_id (obrigatório): ID da supressão a ser excluída

list-tracking-opt-outs

Lista endereços de e-mail excluídos do rastreamento de abertura e clique. Retorna até 1000 registros por chamada.

Parâmetros:

  • email (opcional): Filtro de e-mail. Retorna apenas exclusões que correspondem 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

Exclui um endereço de e-mail do rastreamento de abertura e clique para um domínio de envio.

Parâmetros:

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

delete-tracking-opt-out

Remove um endereço de e-mail da lista de exclusão de rastreamento, para que o rastreamento de abertura e clique volte a se aplicar a ele.

Parâmetros:

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

list-webhooks

Lista todos os webhooks configurados para a conta. Retorna os registros completos dos webhooks como JSON.

Parâmetros:

  • Nenhum parâmetro obrigatório

get-webhook

Obtém um único webhook por ID. Retorna o registro completo do webhook como JSON. Observação: signing_secret não é retornado aqui — ele está disponível apenas na resposta de create-webhook.

Parâmetros:

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

create-webhook

Cria um webhook. A resposta inclui um signing_secret para verificar assinaturas de payload do webhook — este segredo é retornado apenas na criação, então armazene-o agora. Se você o perder, recrie o webhook.

Parâmetros:

  • url (obrigatório): URL para a qual o Mailtrap fará POST dos eventos do webhook
  • webhook_type (obrigatório): "email_sending", "audit_log" ou "inbound_receiving"
  • active (opcional, booleano): padrão é true
  • payload_format (opcional): "json" ou "jsonlines". Padrão: "json"
  • sending_stream (opcional, apenas email_sending): "transactional" ou "bulk"
  • event_types (opcional, apenas email_sending): array de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • domain_id (opcional, apenas email_sending): ID do domínio de envio para escopar este webhook
  • inbound_inbox_id (opcional, apenas inbound_receiving): ID da caixa de entrada de recebimento à qual o webhook está vinculado; omita para aplicar a todas as caixas de entrada da conta

update-webhook

Atualiza os campos mutá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 ser atualizado
  • url (opcional): Nova URL do webhook
  • active (opcional, booleano): Ativar ou desativar o webhook
  • payload_format (opcional): "json" ou "jsonlines"
  • event_types (opcional, apenas email_sending): array de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • inbound_inbox_id (opcional, apenas inbound_receiving): ID da caixa de entrada de recebimento à qual o webhook está vinculado

delete-webhook

Exclui permanentemente um webhook por ID. Retorna o registro do webhook excluído.

Parâmetros:

  • webhook_id (obrigatório): ID do webhook a ser excluído

get-contact

Obtém um contato por ID ou 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

Cria um novo contato.

Parâmetros:

  • email (obrigatório): Endereço de e-mail
  • fields (opcional): Valores de campos personalizados identificados pela tag de mesclagem (ex.: first_name). Valores string, número ou booleanos
  • list_ids (opcional): IDs das listas de contatos para assinar este contato
  • unsubscribed (opcional, booleano): Criar o contato no status unsubscribed

update-contact

Atualiza um contato existente identificado por ID ou e-mail. list_ids substitui o conjunto completo de associações do contato; list_ids_included/list_ids_excluded adicionam/removem sem alterar o restante.

Parâmetros:

  • contact_identifier (obrigatório): ID do contato ou 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 para adicionar (aditivo)
  • list_ids_excluded (opcional): IDs de listas para remover
  • unsubscribed (opcional, booleano): Definir como unsubscribed (verdadeiro) ou subscribed (falso)

delete-contact

Exclui permanentemente um contato por ID ou e-mail. Retorna o registro do contato excluído quando a API responde com um; caso contrário, retorna um payload de confirmação.

Parâmetros:

  • contact_identifier (obrigatório): ID do contato ou e-mail

create-contact-event

Registra um evento de contato associado a um contato (por ID ou e-mail). Usado para acionar automações de listas de contatos.

Parâmetros:

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

list-contact-lists

Lista todas as listas de contatos da conta.

Parâmetros:

  • search (opcional): Filtrar listas de contatos por nome (correspondência sem diferenciar maiúsculas/minúsculas), ex.: news

get-contact-list

Obtém uma lista de contatos por ID.

Parâmetros:

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

create-contact-list

Cria uma nova lista de contatos.

Parâmetros:

  • name (obrigatório): Nome para a nova lista

update-contact-list

Renomeia uma lista de contatos existente.

Parâmetros:

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

delete-contact-list

Exclui permanentemente uma lista de contatos por ID.

Parâmetros:

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

list-contact-fields

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

Parâmetros:

  • Nenhum parâmetro obrigatório

get-contact-field

Obtém uma definição de campo de contato por ID.

Parâmetros:

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

create-contact-field

Cria uma nova definição de campo de contato. merge_tag deve ser único na conta e é usado como nome do placeholder em variáveis de template.

Parâmetros:

  • name (obrigatório): Nome de exibição (ex.: "Nome")
  • merge_tag (obrigatório): Nome do placeholder único (ex.: first_name)
  • data_type (obrigatório): Um de text, number, boolean, date

update-contact-field

Atualiza 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 permanecer única)
  • data_type (opcional): Um de text, number, boolean, date

delete-contact-field

Exclui permanentemente uma definição de campo de contato por ID.

Parâmetros:

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

create-contact-import

Importa contatos em massa. Retorna um registro de trabalho 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 string ou número)
    • list_ids_included (opcional): IDs de listas para adicionar o contato
    • list_ids_excluded (opcional): IDs de listas para remover o contato

get-contact-import

Obtém o status de um trabalho de importação de contatos (criado/iniciado/concluído/falhou) com contagens de criados/atualizados/acima do limite.

Parâmetros:

  • import_id (obrigatório): ID do trabalho de importação de contatos

create-contact-export

Exporta contatos que correspondem a um conjunto de filtros combinados com E. Retorna um registro de trabalho de exportação; consulte o status com get-contact-export para recuperar a URL de download quando status for finished.

Parâmetros:

  • filters (obrigatório): Matriz de objetos de filtro. Cada um tem:
    • name (obrigatório): Campo para 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 matriz)

get-contact-export

Obtém o status de um trabalho de exportação de contatos. Quando status for finished, o campo url contém o link de download do CSV.

Parâmetros:

  • export_id (obrigatório): ID do trabalho de exportação de contatos

list-email-campaigns

Lista as campanhas de e-mail da conta, das mais recentes para as mais antigas, com paginação por token de página. Opcionalmente, filtre por nome com search.

Parâmetros:

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

get-email-campaign

Obtém uma campanha de e-mail por ID.

Parâmetros:

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

create-email-campaign

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

Parâmetros:

  • name (obrigatório): Nome da campanha
  • domain_id (obrigatório): ID do domínio de envio verificado usado para a campanha, conforme retornado pelos endpoints de Domínios de Envio
  • from_local_part (obrigatório): Parte local (antes do @) do endereço De
  • template_attributes (obrigatório): Template de e-mail inline. Tem:
    • subject (obrigatório): Linha de assunto do e-mail (máx. 255 caracteres). Suporta tags de mesclagem, ex.: Hi {{first_name}}
    • body_html (opcional): Corpo em HTML (o design). Obrigatório antes que a campanha possa ser agendada ou iniciada. Inclua um link de cancelamento de inscrição via 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, ex.: ["first_name"]
  • from_display_name (opcional): Nome de exibição mostrado no cabeçalho De
  • reply_to (opcional): Partes do endereço Responder-Para (display_name, local_part, domain)
  • delivery_mode (opcional): rapid (enviar o mais rápido possível) ou gradual (limitar a delivery_options.emails_per_hour)
  • delivery_options (opcional): Opções de limitação 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

Atualiza uma campanha de e-mail draft. Apenas os campos fornecidos são alterados; o template é editado no local. 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

Exclui uma campanha de e-mail por ID. Apenas 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

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

Parâmetros:

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

schedule-email-campaign

Agenda uma campanha de e-mail draft para começar a enviar em um momento futuro. Apenas 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 estar no futuro e no máximo 1 mês à frente

cancel-email-campaign

Cancela uma campanha de e-mail scheduled, retornando-a para draft. Apenas campanhas scheduled podem ser canceladas.

Parâmetros:

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

terminate-email-campaign

Encerra uma campanha de e-mail que está atualmente enviando (started, queued ou paused), abortando o envio em andamento.

Parâmetros:

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

reset-email-campaign

Redefine uma campanha de e-mail scheduled de volta para draft. Apenas campanhas scheduled podem ser redefinidas.

Parâmetros:

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

get-email-campaign-stats

Obtém estatísticas de desempenho agregadas para uma campanha de e-mail (contagens e taxas de entregas, aberturas, cliques, rejeiçõ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. 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. Padrão: a data atual

list-accounts

Lista as contas Mailtrap que o token de API atual pode acessar, com os níveis de acesso de cada conta.

Parâmetros:

  • Nenhum parâmetro obrigatório

get-billing-usage

Obtém 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

Lista os acessos à conta (usuários, convites, tokens de API) da conta. 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ínios de envio (matriz de strings)
  • inbox_ids (opcional): Filtrar por IDs de caixas de entrada de sandbox (matriz de strings)
  • project_ids (opcional): Filtrar por IDs de projetos de sandbox (matriz de strings)

remove-account-access

Remove um acesso à conta por ID. Para especificadores User, isso revoga suas permissões; para especificadores Invite ou ApiToken, remove o especificador inteiramente. Requer administrador/proprietário.

Parâmetros:

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

get-permission-resources

Obtém todos os recursos (caixas de entrada, projetos, domínios, cobrança, conta) aos quais o token de API tem acesso de administrador, aninhados por hierarquia.

Parâmetros:

  • Nenhum parâmetro obrigatório

bulk-update-permissions

Cria, atualiza ou remove permissões em massa para um único acesso de 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 de conta de destino
  • permissions (obrigatório): Matriz de entradas de permissão. Cada uma possui:
    • 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 verdadeiro, remove esta permissão em vez de criá-la/atualizá-la

list-api-tokens

Lista todos os tokens de API da conta.

Parâmetros:

  • Nenhum parâmetro necessário

create-api-token

Cria 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ê o perder, recrie o token.

Parâmetros:

  • name (obrigatório): Nome de exibição do token
  • expires_at (opcional): Expiração do token como data-hora ISO 8601. Omita para o padrão do servidor (1 ano); passe um null explícito para um token que nunca expira. Valores passados ou valores com mais de 5 anos à frente são rejeitados
  • resources (opcional): Matriz de permissões de recurso para escopar o token. Cada entrada possui:
    • resource_type (obrigatório): Um de account, project, inbox, domain, billing
    • resource_id (obrigatório): ID do recurso
    • access_level (obrigatório): 100 (admin) ou 10 (visualizador)

get-api-token

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

Parâmetros:

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

reset-api-token

Redefine (rotaciona) um token de API por ID. A resposta inclui o novo valor secreto token — retornado apenas nesta chamada, então armazene-o imediatamente. O token anterior é invalidado.

Parâmetros:

  • api_token_id (obrigatório): ID do token de API a ser redefinido
  • expires_at (opcional): Expiração do novo token como data-hora ISO 8601. Omita para o padrão do servidor (1 ano); passe um null explícito para um token que nunca expira. Valores passados ou valores com mais de 5 anos à frente são rejeitados

delete-api-token

Exclui permanentemente um token de API por ID. O token não pode mais autenticar após a exclusão.

Parâmetros:

  • api_token_id (obrigatório): ID do token de API a ser excluído

list-sub-accounts

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

Parâmetros:

  • Nenhum parâmetro necessário

create-sub-account

Cria uma nova subconta sob a 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

list-inbound-folders

Lista todas as pastas de entrada na conta. Retorna um resumo formatado.

Parâmetros:

  • Nenhum parâmetro necessário

get-inbound-folder

Obtém uma única pasta de entrada por ID. Retorna o registro completo da pasta como JSON.

Parâmetros:

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

create-inbound-folder

Cria uma nova pasta de entrada.

Parâmetros:

  • name (obrigatório): O nome da pasta

update-inbound-folder

Renomeia uma pasta de entrada.

Parâmetros:

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

delete-inbound-folder

Exclui permanentemente uma pasta de entrada junto com todas as suas caixas de entrada.

Parâmetros:

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

list-inbound-inboxes

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

Parâmetros:

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

get-inbound-inbox

Obtém uma única caixa de entrada por 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

Cria uma nova caixa de entrada em uma pasta.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada
  • name (obrigatório): O nome da caixa de entrada
  • domain_id (opcional): Anexar a um domínio de envio personalizado (caixa de entrada catch-all). Omita para uma caixa de entrada hospedada pela 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): O 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 mensagens recebidas em uma caixa de entrada (paginação por cursor). Retorna um resumo formatado com uma dica de 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 do last_id de uma resposta anterior

get-inbound-message

Obtém uma única mensagem de entrada com seu corpo completo e URLs de download de 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 de entrada.

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 de entrada (envia para o remetente original). Envia um e-mail real. 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 ser respondida
  • text / html (pelo menos um recomendado): Corpo da resposta
  • from (opcional): Remetente. Rejeitado para caixas de entrada hospedadas pela 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): Matriz de { content (base64), filename, type?, disposition?, content_id? }
  • headers / custom_variables (opcional): Objetos de valores de string

reply-all-to-inbound-message

Responde a uma mensagem de entrada e copia os outros destinatários do 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 ser respondida
  • Além dos mesmos campos opcionais de envio de reply-to-inbound-message

forward-inbound-message

Encaminha uma mensagem de entrada 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 ser encaminhada
  • to (obrigatório): Pelo menos um destinatário (string de e-mail simples ou { email, name? }, ou uma matriz)
  • Além dos mesmos campos opcionais de envio de reply-to-inbound-message

list-inbound-threads

Lista threads de conversa em uma caixa de entrada (paginação por cursor). Retorna um resumo formatado com uma dica de 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 do last_id de uma resposta anterior

get-inbound-thread

Obtém uma única thread de entrada com suas mensagens incorporadas (mais antigas primeiro). Retorna o registro completo da thread como JSON.

Parâmetros:

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

delete-inbound-thread

Exclui permanentemente uma thread de entrada.

Parâmetros:

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

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] Veja a localização do arquivo de configuração na seção Setup.

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_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Se você estiver usando asdf para gerenciar 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": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

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

{
  "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_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

Testes

Executando ferramentas contra a Mailtrap real

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

Ambas exigem que o bundle seja construído primeiro:

npm run build

e MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID exportados no seu shell (o script mcp:cli encaminha ambos para o servidor gerado).

Interface do navegador

npm run dev

O Inspector imprime uma URL como http://localhost:6274. Abra-a, mude para a aba Tools, escolha uma ferramenta (ex.: get-template), preencha os parâmetros como JSON e clique em Run. A resposta da Mailtrap aparece no painel abaixo.

CLI

Para chamadas únicas sem a interface, use npm run mcp:cli. Passe os flags CLI do Inspector após -- para que o npm os encaminhe literalmente:

# 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-sending-domain-setup-instructions \
  --tool-arg sending_domain_id=3938 \
  --tool-arg email=devops@example.com

Executando 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 de erros estruturado alinhado às convenções do MCP:

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

Erros incluem mensagens acionáveis e são registrados em formato estruturado.

Segurança

  • Entrada validada via esquemas Zod
  • Variáveis de ambiente tratadas com segurança
  • Proteção de tempo limite em operações (30 segundos)
  • Detalhes sensíveis sanitizados na saída de erros

Registro de Logs

Logs JSON estruturados com 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 escreve logs em stderr para que stdout permaneça reservado para quadros JSON-RPC. Isso evita que hosts encontrem erros de análise JSON devido a logs intercalados.

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: certifique-se de que MAILTRAP_API_TOKEN esteja definido
  2. Sandbox não funcionando: forneça test_inbox_id na chamada da ferramenta ou defina a env MAILTRAP_TEST_INBOX_ID
  3. Erros de tempo limite: verifique a conectividade de rede e o status da API Mailtrap
  4. Erros de validação: certifique-se de que todos os campos obrigatórios sejam fornecidos

Contribuindo

Relatórios 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 contribuidores 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 todos que interagem nos codebases, rastreadores de problemas, salas de chat e listas de e-mail do projeto Mailtrap sigam o código de conduta.