AhaSend Email API & SMTP relay

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

ahasend-mcp

Un módulo de Go con herramientas MCP para AhaSend. Con estas herramientas, un agente de IA puede enviar correo, averiguar por qué falló un correo y gestionar dominios, plantillas, contactos, listas, campañas, webhooks, rutas, supresiones, credenciales SMTP y subcuentas.

Cada herramienta llama a la API v2 de AhaSend a través de ahasend-go. Los ámbitos de la clave de API deciden qué puede hacer el agente.

El módulo construye un servidor con el SDK oficial de MCP para Go. Tu programa elige cómo servirlo: stdio, HTTP o cualquier otro transporte del SDK.

go get github.com/AhaSend/ahasend-mcp

Ejemplo

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

Opciones

Campo	Qué hace
Client	El cliente de ahasend-go, con la clave de API. Obligatorio.
AccountID	La cuenta sobre la que trabajan las herramientas. Obligatorio.
DashboardBaseURL	La URL del panel de AhaSend, usada en los enlaces de campaña. Obligatorio.
ConfirmationKey	Un secreto de al menos 32 bytes que firma las preguntas de envío de campaña. Obligatorio.
Scopes	Los ámbitos de la clave de API. Solo se muestran las herramientas que la clave puede usar. nil muestra todas las herramientas.
Toolsets	Mostrar solo estos conjuntos de herramientas. nil muestra todos.
ReadOnly	Mostrar solo las herramientas que no cambian nada.
Stateless	Establécelo en true si sirves por HTTP sin estado.
MaxRecipientsPerSend	El máximo de destinatarios para un envío. Por defecto 50.
ReadInbound	Permite que las herramientas de mensajes devuelvan el correo que recibió la cuenta. Desactivado por defecto.
Blocked	Si se establece, cada llamada a una herramienta devuelve este texto como error y no hace nada.
Recorder	Obtiene un registro por llamada a herramienta: nombre de la herramienta, éxito, tipo de error y tiempo empleado. Nunca las entradas ni los resultados.

Si sirves a muchos usuarios, construye un servidor nuevo para cada solicitud con la clave y los ámbitos de ese usuario. Esto es barato. Usa el mismo ConfirmationKey en cada instancia.

Catalogue() enumera cada herramienta con los ámbitos que necesita. OfferedScopes() enumera cada ámbito que usan las herramientas, para una página donde un usuario elige ámbitos.

Herramientas

Conjunto de herramientas	Herramientas
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 herramienta necesita los ámbitos que necesita su endpoint de API. send_campaign y schedule_campaign también necesitan campaigns:read y lists:read, y segments:read para enviar una campaña que usa segmentos. Las herramientas de plantilla de campaña también necesitan campaigns:read. preview_segment, list_segment_contacts y list_contact_segments necesitan contacts:read además de segments:read.

Las herramientas de listado devuelven 20 elementos por defecto y como máximo 100. Pasa el cursor devuelto para obtener la página siguiente.

No hay herramientas para crear claves de API ni credenciales SMTP, cambiar la configuración de la cuenta, la facturación ni los miembros del equipo, eliminar todas las supresiones, ni eliminar o suspender subcuentas.

Diseños del Editor simple y AhaML

Las herramientas de plantillas, plantillas de campaña y campañas leen y escriben un diseño del Editor simple del panel como AhaSend Markup (AhaML), una forma XML del diseño, en el campo markup del contenido. get_template devuelve la copia de trabajo de una plantilla, el borrador mientras existe, para que un agente edite lo que leyó; get_published_template devuelve la copia que usa un envío.

El servidor tiene un recurso, ahasend://docs/ahaml: la referencia de AhaML, con cada etiqueta, atributo, límite y código de error. También está en https://ahasend.com/docs/send-api/ahaml. El recurso se lista en cada conexión, para que un agente sin acceso web pueda leerlo.

Reglas de seguridad

Los envíos de campaña necesitan el sí de una persona. send_campaign y schedule_campaign muestran al usuario un formulario con la hora de envío, el número de contactos, el nombre de la campaña, el asunto, el remitente, las listas y los segmentos, y las listas y segmentos excluidos. Solo envían si el usuario responde que sí. Si la campaña cambia después de la pregunta, la herramienta vuelve a preguntar. Si el cliente no puede mostrar un formulario, la herramienta no envía nada y devuelve un enlace a la campaña en el panel.

Los envíos puntuales tienen un límite de destinatarios. Se rechaza un único envío a más de MaxRecipientsPerSend destinatarios (por defecto 50). Usa una campaña para el correo masivo.

El correo recibido está oculto por defecto. Cualquiera puede enviar correo a las direcciones de entrada de una cuenta, y ese correo puede contener texto que intente engañar al agente. A menos que ReadInbound esté activado, las herramientas de mensajes no devuelven el correo recibido. Cuando está activado, los mensajes recibidos se marcan untrusted: true.

Errores

Cuando la API rechaza una llamada, la herramienta devuelve un error con el mensaje de la API y qué hacer a continuación. Cuando rechaza AhaML, el error enumera los problemas, hasta los primeros 100, cada uno con su código, línea, columna, ruta y pista; el mensaje de la API indica cuántos hay.

Probarlo localmente

cmd/ahasend-mcp-dev sirve todas las herramientas por stdio con tu propia clave de API. Es solo para pruebas.

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

Establece AHASEND_BASE_URL para usar una API distinta de la predeterminada.

Licencia

MIT