AhaSend Email API & SMTP relay

npx add-mcp 'https://mcp.ahasend.com/mcp'

ahasend-mcp

Um módulo Go com ferramentas MCP para o AhaSend. Com essas ferramentas, um agente de IA pode enviar e-mail, descobrir por que um e-mail falhou e gerenciar domínios, templates, contatos, listas, campanhas, webhooks, rotas, supressões, credenciais SMTP e subcontas.

Cada ferramenta chama a API v2 do AhaSend por meio do ahasend-go. Os escopos da chave de API decidem o que o agente pode fazer.

O módulo constrói um servidor com o SDK MCP oficial para Go. Seu programa escolhe como servi-lo: stdio, HTTP ou qualquer outro transporte do SDK.

go get github.com/AhaSend/ahasend-mcp

Exemplo

server, err := ahasendmcp.NewServer(
	&mcp.Implementation{Name: "my-app", Version: "1.0.0"},
	ahasendmcp.Options{
		Client:           api.NewAPIClient(api.WithAPIKey(apiKey)),
		AccountID:        accountID,
		DashboardBaseURL: "https://dash.ahasend.com",
		ConfirmationKey:  key, // at least 32 random bytes
	},
)
if err != nil {
	return err
}
return server.Run(ctx, &mcp.StdioTransport{})

Opções

Campo	O que faz
Client	O cliente ahasend-go, com a chave de API. Obrigatório.
AccountID	A conta em que as ferramentas operam. Obrigatório.
DashboardBaseURL	A URL do painel do AhaSend, usada em links de campanha. Obrigatório.
ConfirmationKey	Um segredo de pelo menos 32 bytes que assina as perguntas de envio de campanha. Obrigatório.
Scopes	Os escopos da chave de API. Apenas as ferramentas que a chave pode usar são exibidas. nil exibe todas as ferramentas.
Toolsets	Exibe apenas estes conjuntos de ferramentas. nil exibe todos.
ReadOnly	Exibe apenas ferramentas que não alteram nada.
Stateless	Defina como true se você servir via HTTP sem estado.
MaxRecipientsPerSend	O número máximo de destinatários por envio. Padrão 50.
ReadInbound	Permite que as ferramentas de mensagem retornem e-mails recebidos pela conta. Desativado por padrão.
Blocked	Se definido, toda chamada de ferramenta retorna este texto como erro e não faz nada.
Recorder	Recebe um registro por chamada de ferramenta: nome da ferramenta, sucesso, tipo de erro e tempo gasto. Nunca as entradas ou resultados.

Se você atende muitos usuários, construa um novo servidor para cada requisição com a chave e os escopos daquele usuário. Isso é barato. Use o mesmo ConfirmationKey em todas as instâncias.

Catalogue() lista cada ferramenta com os escopos de que precisa. OfferedScopes() lista cada escopo usado pelas ferramentas, para uma página em que o usuário escolhe escopos.

Ferramentas

Conjunto de ferramentas	Ferramentas
sending	send_email, send_conversation_email, send_template_email, cancel_scheduled_email
diagnostics	list_messages, get_message, diagnose_message, get_deliverability_stats, get_bounce_stats, get_delivery_time_stats
domains	list_domains, get_domain, add_domain, check_domain_dns, update_domain, delete_domain
templates	list_templates, get_template, get_published_template, create_template, update_template, delete_template, discard_template_draft, publish_template, list_template_versions, get_template_version, restore_template_version, list_campaign_templates, get_campaign_template, create_campaign_template, update_campaign_template, delete_campaign_template
audience	list_contacts, get_contact, create_contact, upsert_contacts, update_contact, delete_contact, list_contact_lists, list_lists, get_list, create_list, update_list, delete_list, list_list_contacts, add_contacts_to_list, upsert_list_contact, remove_contact_from_list, list_segments, get_segment, create_segment, update_segment, delete_segment, preview_segment, list_segment_contacts, list_contact_segments
campaigns	list_campaigns, get_campaign, create_campaign, update_campaign, delete_campaign, duplicate_campaign, send_campaign_test, send_campaign, schedule_campaign, unschedule_campaign, get_campaign_stats, list_campaign_recipients
management	get_account, list_webhooks, get_webhook, create_webhook, update_webhook, delete_webhook, list_routes, get_route, create_route, update_route, delete_route, list_suppressions, add_suppression, remove_suppression, list_smtp_credentials, get_smtp_credential, delete_smtp_credential, list_sub_accounts, get_sub_account, create_sub_account, update_sub_account, get_sub_account_usage

Cada ferramenta precisa dos escopos de que seu endpoint de API precisa. send_campaign e schedule_campaign também precisam de campaigns:read e lists:read, e segments:read para enviar uma campanha que usa segmentos. As ferramentas de template de campanha também precisam de campaigns:read. preview_segment, list_segment_contacts e list_contact_segments precisam de contacts:read além de segments:read.

As ferramentas de listagem retornam 20 itens por padrão e no máximo 100. Passe o cursor retornado para obter a próxima página.

Não há ferramentas para criar chaves de API ou credenciais SMTP, alterar configurações da conta, cobrança ou membros da equipe, remover todas as supressões, ou excluir ou suspender subcontas.

Designs do Simple Editor e AhaML

As ferramentas de template, template de campanha e campanha leem e gravam um design do Simple Editor do painel como AhaSend Markup (AhaML), uma forma XML do design, no campo markup do conteúdo. get_template retorna a cópia de trabalho de um template, o rascunho enquanto ele existir, para que um agente edite o que leu; get_published_template retorna a cópia que um envio usa.

O servidor tem um recurso, ahasend://docs/ahaml: a referência AhaML, com cada tag, atributo, limite e código de erro. Ele também está em https://ahasend.com/docs/send-api/ahaml. O recurso é listado em toda conexão, para que um agente sem acesso à web possa lê-lo.

Regras de segurança

Envios de campanha precisam do sim de uma pessoa. send_campaign e schedule_campaign mostram ao usuário um formulário com o horário de envio, o número de contatos, o nome da campanha, assunto, remetente, listas e segmentos, e as listas e segmentos excluídos. Eles enviam somente se o usuário responder sim. Se a campanha mudar após a pergunta, a ferramenta pergunta novamente. Se o cliente não puder exibir um formulário, a ferramenta não envia nada e retorna um link para a campanha no painel.

Envios avulsos têm um limite de destinatários. Um único envio para mais de MaxRecipientsPerSend destinatários (padrão 50) é recusado. Use uma campanha para e-mail em massa.

E-mails recebidos ficam ocultos por padrão. Qualquer pessoa pode enviar e-mail para os endereços de entrada de uma conta, e esse e-mail pode conter texto que tenta enganar o agente. A menos que ReadInbound esteja ativado, as ferramentas de mensagem não retornam e-mails recebidos. Quando estiver ativado, as mensagens recebidas são marcadas untrusted: true.

Erros

Quando a API recusa uma chamada, a ferramenta retorna um erro com a mensagem da API e o que fazer em seguida. Quando ela recusa AhaML, o erro lista os problemas, até os primeiros 100, cada um com seu código, linha, coluna, caminho e dica; a mensagem da API informa quantos são.

Testando localmente

cmd/ahasend-mcp-dev serve todas as ferramentas via stdio com sua própria chave de API. É apenas para testes.

go build -o ahasend-mcp-dev ./cmd/ahasend-mcp-dev
claude mcp add ahasend \
  -e AHASEND_API_KEY=... -e AHASEND_ACCOUNT_ID=... \
  -- ./ahasend-mcp-dev

Defina AHASEND_BASE_URL para usar uma API diferente da padrão.

Licença

MIT