AhaSend Email API & SMTP relay

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

ahasend-mcp

Un module Go avec des outils MCP pour AhaSend. Avec ces outils, un agent IA peut envoyer des e-mails, découvrir pourquoi un e-mail a échoué, et gérer les domaines, modèles, contacts, listes, campagnes, webhooks, routes, suppressions, identifiants SMTP et sous-comptes.

Chaque outil appelle l'API AhaSend v2 via ahasend-go. Les portées de la clé API déterminent ce que l'agent peut faire.

Le module construit un serveur avec le SDK MCP officiel Go. Votre programme choisit comment le servir : stdio, HTTP, ou tout autre transport du SDK.

go get github.com/AhaSend/ahasend-mcp

Exemple

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{})

Options

Champ	Ce qu'il fait
Client	Le client ahasend-go, avec la clé API. Obligatoire.
AccountID	Le compte sur lequel les outils travaillent. Obligatoire.
DashboardBaseURL	L'URL du tableau de bord AhaSend, utilisée dans les liens de campagne. Obligatoire.
ConfirmationKey	Un secret d'au moins 32 octets qui signe les questions d'envoi de campagne. Obligatoire.
Scopes	Les portées de la clé API. Seuls les outils que la clé peut utiliser sont affichés. nil affiche tous les outils.
Toolsets	Afficher uniquement ces ensembles d'outils. nil affiche tout.
ReadOnly	Afficher uniquement les outils qui ne modifient rien.
Stateless	Définir sur true si vous servez via HTTP sans état.
MaxRecipientsPerSend	Le nombre maximal de destinataires pour un envoi. Par défaut 50.
ReadInbound	Permettre aux outils de messagerie de renvoyer les e-mails reçus par le compte. Désactivé par défaut.
Blocked	Si défini, chaque appel d'outil renvoie ce texte comme erreur et ne fait rien.
Recorder	Reçoit un enregistrement par appel d'outil : nom de l'outil, succès, type d'erreur et durée. Jamais les entrées ni les résultats.

Si vous servez de nombreux utilisateurs, construisez un nouveau serveur pour chaque requête avec la clé et les portées de cet utilisateur. C'est peu coûteux. Utilisez le même ConfirmationKey sur chaque instance.

Catalogue() liste chaque outil avec les portées dont il a besoin. OfferedScopes() liste chaque portée utilisée par les outils, pour une page où un utilisateur choisit les portées.

Outils

Ensemble d'outils	Outils
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

Chaque outil a besoin des portées dont son point de terminaison API a besoin. send_campaign et schedule_campaign ont aussi besoin de campaigns:read et lists:read, et segments:read pour envoyer une campagne qui utilise des segments. Les outils de modèle de campagne ont aussi besoin de campaigns:read. preview_segment, list_segment_contacts et list_contact_segments ont besoin de contacts:read ainsi que de segments:read.

Les outils de liste renvoient 20 éléments par défaut et au maximum 100. Passez le curseur renvoyé pour obtenir la page suivante.

Il n'y a pas d'outils pour créer des clés API ou des identifiants SMTP, modifier les paramètres du compte, la facturation ou les membres de l'équipe, supprimer toutes les suppressions, ni supprimer ou suspendre des sous-comptes.

Designs du Simple Editor et AhaML

Les outils de modèle, de modèle de campagne et de campagne lisent et écrivent un design du Simple Editor du tableau de bord sous forme d'AhaSend Markup (AhaML), une forme XML du design, dans le champ markup du contenu. get_template renvoie la copie de travail d'un modèle, le brouillon tant qu'il existe, afin qu'un agent modifie ce qu'il a lu ; get_published_template renvoie la copie qu'un envoi utilise.

Le serveur a une ressource, ahasend://docs/ahaml : la référence AhaML, avec chaque balise, attribut, limite et code d'erreur. Elle est aussi à https://ahasend.com/docs/send-api/ahaml. La ressource est listée sur chaque connexion, afin qu'un agent sans accès web puisse la lire.

Règles de sécurité

Les envois de campagne nécessitent l'accord d'une personne. send_campaign et schedule_campaign montrent à l'utilisateur un formulaire avec l'heure d'envoi, le nombre de contacts, le nom de la campagne, l'objet, l'expéditeur, les listes et segments, et les listes et segments exclus. Ils n'envoient que si l'utilisateur répond oui. Si la campagne change après la question, l'outil redemande. Si le client ne peut pas afficher de formulaire, l'outil n'envoie rien et renvoie un lien vers la campagne dans le tableau de bord.

Les envois ponctuels ont une limite de destinataires. Un envoi unique à plus de MaxRecipientsPerSend destinataires (50 par défaut) est refusé. Utilisez une campagne pour les e-mails en masse.

Les e-mails reçus sont masqués par défaut. N'importe qui peut envoyer un e-mail aux adresses entrantes d'un compte, et cet e-mail peut contenir du texte qui tente de tromper l'agent. Sauf si ReadInbound est activé, les outils de messagerie ne renvoient pas les e-mails reçus. Lorsqu'il est activé, les messages reçus sont marqués untrusted: true.

Erreurs

Lorsque l'API refuse un appel, l'outil renvoie une erreur avec le message de l'API et ce qu'il faut faire ensuite. Lorsqu'elle refuse AhaML, l'erreur liste les problèmes, jusqu'aux 100 premiers, chacun avec son code, sa ligne, sa colonne, son chemin et son indice ; le message de l'API indique combien il y en a.

Essai local

cmd/ahasend-mcp-dev sert tous les outils via stdio avec votre propre clé API. Il est destiné uniquement aux tests.

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

Définissez AHASEND_BASE_URL pour utiliser une API autre que celle par défaut.

Licence

MIT