Conecte um agente de IA com MCP

O que é

O servidor MCP hospedado do Postline está disponível em https://api.srs-postline.com/mcp e oferece ferramentas tipadas para emails, domínios, supressões e webhooks.

Antes de escrever qualquer código

• Peça ao usuário uma chave de API do projeto, ou peça que ele crie uma chave de sandbox em https://app.srs-postline.com/pt/login — nunca invente, adivinhe ou reutilize uma chave de outro projeto.
• Coloque a chave em uma variável de ambiente do lado do servidor. Não a coloque em código de frontend, em um pacote de aplicativo móvel, em um repositório público ou em um arquivo .env versionado.
• Comece com uma chave srs_test_ em um projeto sandbox. O sandbox só entrega a destinatários que o usuário verificou, portanto a entrega real na caixa de entrada requer um projeto live já analisado — não prometa que o envio live funciona antes que essa análise seja concluída.
• Leia /llms.txt e openapi/postline.yaml antes de gerar código de requisição; não adivinhe nomes de campos ou endpoints.

Conexão

Conecte o endpoint hospedado com uma chave Bearer do Postline; nenhum download ou build local é necessário.

claude mcp add --scope user --transport http postline \
  https://api.srs-postline.com/mcp \
  --header "Authorization: Bearer srs_live_xxx"

export POSTLINE_API_KEY='srs_live_xxx'
codex mcp add postline --url https://api.srs-postline.com/mcp \
  --bearer-token-env-var POSTLINE_API_KEY

Verificações a executar antes de cada envio

• Sempre envie um Idempotency-Key derivado da ação que dispara o envio (ID do pedido, ID do evento) para que novas tentativas não causem envio duplicado.
• Nunca coloque códigos OTP, tokens de redefinição de senha ou outros segredos em um campo que é registrado em log ou encaminhado para fora do corpo da mensagem.
• Solicite o escopo de chave de API mais restrito que a tarefa exigir (emails:send é suficiente para envio; não peça domains:write ou api_keys:write a menos que a tarefa exija).
• Limite os destinatários a 100 por chamada. A API atual não aceita anexos nem cabeçalhos personalizados; rejeite o arquivo ou compartilhe um link sem afirmar que ele foi anexado.
• Não repita silenciosamente respostas 4xx. Somente 429 e 503 são seguros para repetir, e apenas com backoff.

Trate cada código de resposta

• 202 — enfileirado, não entregue. Armazene o id retornado caso precise consultar o status depois.
• 400 — payload inválido; corrija a requisição, não repita sem alterações.
• 401 — chave inválida ou expirada; pare e informe o usuário, não fabrique uma nova chave.
• 403 — escopo ausente ou o domínio de envio ainda não foi verificado; diga ao usuário para verificar o domínio antes de continuar.
• 409 — conflito de idempotência; trate a requisição original como já enviada.
• 422 — destinatário está suprimido (bounce/complaint anterior); não repita o envio para esse destinatário.
• 429 — limitação de taxa; aguarde e tente novamente mais tarde, não fique em loop apertado.
• 503 — fila indisponível; tente novamente com backoff, não recorra a um transporte não oficial.

Referências legíveis por máquina

• /llms.txt — índice condensado dessas regras para janelas de contexto de agentes.
• /openapi/postline.yaml — esquema OpenAPI 3.1 completo de todos os endpoints.
• /pt/api/ — referência da API para humanos.
• /pt/webhooks/ — detalhes de assinatura e retentativa de webhooks.