Vaemail

io.github.vaemailPublished by GitHub account vaemailv1.2.0Updated Nov 2, 2026

Email infrastructure for AI agents: send, authenticate domains, track delivery, diagnose issues.

VerifiedSTDIODesktop onlyCloud & InfrastructureCommunication & CollaborationBusiness & Commerce

Overview

AI-generated overview

VaEmail lets an assistant send newsletters and transactional email, manage contacts, authenticate sending domains and diagnose deliverability.

What you can do
  • Prepare, confirm and track newsletters: resolve a list, create a draft with a one-use token, execute the send after human approval, report campaign status
  • Manage contacts and audiences: list lists by folder with subscriber counts, check one address, import or update contacts without re-subscribing unsubscribed ones
  • Send and inspect transactional email: queue a message with an idempotency key, dry-run a send, read delivery status and events, list recent messages
  • Set up and verify sending domains: declare a domain, return the DNS records to publish, re-read SPF, DKIM and DMARC
  • Diagnose deliverability and account state: reputation findings and fixes, suppressed addresses, quota and key…
When to use it
Useful when an assistant should run email end to end without a human watching a dashboard: sending newsletters or transactional messages from an app, onboarding a new sending domain, or explaining why mail lands in spam. Also handy for checking quota and suppression lists before a batch.
Requirements
Runs locally over stdio via npx (Node 18+), no dependencies. Needs a VaEmail account and an API key in VAEMAIL_API_KEY, created in the dashboard and ideally scoped and capped for the agent; every tool except vaemail_capabilities requires it. VAEMAIL_BASE_URL optionally overrides the default API endpoint. Network access to the VaEmail API is required.
Before you install
Sending is irreversible: vaemail_confirmer_envoi and vaemail_send_email are marked destructive, and confirmation tokens are single-use. The API key can send mail and spend quota, so scope it and set a daily cap. Publishing DNS records, creating keys and paying for a plan are human steps the assistant must not claim as done. A sandbox key rolls back writes and is never proof of delivery. Audit logs exclude message bodies but record parameters.

Installation

In SourceWeft

  1. Open Vaemail in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

VaEmail — email infrastructure for AI agents

[Listed on mcpservers.org]

MCP server and CLI for VaEmail. Give an agent the ability to send email, authenticate a sending domain, track delivery and diagnose deliverability — without a human reading a dashboard in between.

European infrastructure: servers in Germany, sending through Amazon SES Europe.

Install

bash
# Claude Codeclaude mcp add vaemail --env VAEMAIL_API_KEY=swm_your_key -- npx -y vaemail mcp
# Any MCP clientnpx -y vaemail mcp

Or as a config block:

json
{  "mcpServers": {    "vaemail": {      "command": "npx",      "args": ["-y", "vaemail", "mcp"],      "env": { "VAEMAIL_API_KEY": "swm_your_key" }    }  }}

GET /api/v1/me identifies the tenant, key prefix, scopes and mode without returning the secret. Contact operations accept a tenant-unique external_reference for CRM identifiers and upserts.

Use a sandbox API key for integration tests: reads work normally, while every write is validated in a transaction that is always rolled back. No row, job, email, SMS, webhook or outbound HTTP call is emitted, and idempotency keys are not stored. Sandbox write responses carry X-VaEmail-Sandbox: 1 and sandbox: true in JSON objects. A sandbox response is never evidence that an email was delivered.

Check everything is wired up:

bash
npx vaemail init

Tools

ToolWhat it does
vaemail_preparer_envoiPrepares a newsletter draft, resolves the list, optionally sends a test, and returns a recap plus a one-use confirmation token. It never sends or schedules.
vaemail_confirmer_envoiExecutes the scheduled or immediate newsletter prepared with the token, after explicit human confirmation. This is destructive.
vaemail_ou_en_est_ma_campagneWhere a campaign stands, in plain sentences: scheduled, sending, sent, opens, clicks.
vaemail_qui_est_abonneLists by folder with subscriber counts, or the lists and status of one address.
vaemail_importer_contactsAdds contacts to a list (created if missing). Never re-subscribes an unsubscribed address.
vaemail_capabilitiesWhat the service supports. No API key needed.
vaemail_send_emailQueue a transactional email, return its id.
vaemail_validate_emailDry run: would this send go out, and what would block it.
vaemail_get_messageDelivery status and every event for one message.
vaemail_list_messagesRecent messages, filtered by status, tag or recipient.
vaemail_list_domainsSending domains with live SPF, DKIM and DMARC state.
vaemail_create_domainDeclare a domain, return the DNS records to publish.
vaemail_verify_domainRe-read the DNS and report what is authenticated.
vaemail_dns_requirementsThe records a declared domain still needs.
vaemail_diagnose_deliverabilityWhy mail is landing badly, with the actions that fix it.
vaemail_list_bouncesAddresses excluded from sending, and why.
vaemail_get_usageQuota, daily cap on the key, what is left.
vaemail_get_audit_logWhat this key has done, to report it accurately.

Both vaemail_confirmer_envoi and vaemail_send_email advertise destructiveHint: true: sending externally is irreversible. The newsletter confirmation guard applies to immediate sending; drafts and scheduled campaigns keep their existing behavior.

What this is built to prevent

An agent fails differently from a person. It retries, it does not read a dashboard, and it reports success from a 200. The API is shaped around that:

  • A send is accepted, not delivered. vaemail_send_email returns 202 and an id. Only vaemail_get_message says what became of it. The tool descriptions say so, so an agent does not announce a delivery it cannot know about.
  • Retries do not duplicate. Pass idempotency_key and a repeat call replays the first response for 24 hours instead of sending twice.
  • Errors say what to do. Every failure carries a stable code, whether it is retryable, and the corrective action with the endpoint that performs it.
  • Keys are bounded. Scopes, a daily send cap, a cap on recipients per email and an allow-list of sender domains. An agent cannot spend more than the key allows.
  • Every call is logged. Which key, which operation, which parameters, which result — message bodies excluded. Autonomous, but accountable.
  • Human steps are named as such. Publishing DNS records is one. A record whose value still contains a placeholder is flagged publishable: false, because publishing it would break the domain's authentication.

CLI

bash
vaemail init                          # check config, print the MCP snippetvaemail capabilities                  # what the service can do (no key needed)vaemail send --to [email protected] --subject Hi --html '<p>Hello</p>'vaemail status 42                     # delivery status of a messagevaemail domains:add exemple.fr        # declare a domain, print DNS recordsvaemail doctor                        # why is my email not arriving?vaemail usage                         # quota and remaining allowancevaemail mcp                           # run the MCP server on stdio

Add --json to any command for machine-readable output.

Use it as a library

The same client the MCP server and the CLI run on is exported, so an application can call VaEmail directly. No dependencies.

js
import { VaEmail } from 'vaemail';
const client = new VaEmail({ apiKey: process.env.VAEMAIL_API_KEY });
await client.send(  {    to: '[email protected]',    subject: 'Your order is on its way',    html: '<p>Tracking number: 1Z999</p>',  },  'order-4711', // idempotency key: safe to replay for 24 hours);

Errors carry what to do next, not just a status code:

js
try {  await client.send({ to: '[email protected]' });} catch (error) {  error.code;        // DOMAIN_NOT_VERIFIED  error.retryable;   // false  error.pourAgent(); // reason, corrective action, whether to retry}

Also: capabilities(), health(), validate(), getMessage(), listMessages(), listDomains(), addDomain(), verifyDomain(), dnsRecords(), diagnoseDeliverability(), listSuppressions(), removeSuppression(), usage(), auditLogs().

Connecter Stripe

Utilise une clé Stripe restreinte rk_live_ ou rk_test_, avec Customers en lecture et Webhook Endpoints en écriture. Une clé secrète sk_ est refusée. VaEmail ne renvoie aucun secret Stripe : l'état de la connexion expose uniquement les quatre derniers caractères de la clé et du token du webhook.

Routes REST :

  • GET /api/v1/integrations/stripe : lire l'état de la connexion ;
  • POST /api/v1/integrations/stripe : créer ou réconcilier le webhook, avec {"api_key":"rk_live_..."} et la portée settings.write ;
  • DELETE /api/v1/integrations/stripe : supprimer le webhook Stripe puis la connexion locale. Action irréversible, à confirmer explicitement par un humain.

Stripe appelle POST /api/v1/webhooks/stripe/{token}. Cette route publique vérifie Stripe-Signature et ne reçoit pas la clé API VaEmail.

Événements pris en charge et déclencheurs d'automatisation :

Événement StripeDéclencheur VaEmail
invoice.payment_failedstripe_payment_failed (payment_failed)
customer.subscription.createdstripe_subscription_created (subscription_created)
customer.subscription.deletedstripe_subscription_deleted (subscription_deleted)
checkout.session.completedstripe_checkout_completed (checkout_completed)

A Python SDK with the same surface is available: pip install vaemail (https://github.com/vaemail/vaemail-python).

Environment

VariableMeaning
VAEMAIL_API_KEYAccount API key. Created from the dashboard, under « Clés API ».
VAEMAIL_BASE_URLAPI base URL. Defaults to https://app.vaemail.fr.

Also available

Skill and examples

Dependencies

None. Node 18+ for the built-in fetch, and nothing else — a package an agent installs on its own should not pull a dependency tree behind it.

License

MIT

Source: README.md at commit b11fa33

Tools

18

vaemail_preparer_envoi

Préparer l’envoi d’une newsletter

Prépare une newsletter à une liste de contacts sans l’envoyer ni la programmer. Fait tout seul : retrouve la liste par son nom, crée la campagne, envoie un test si demandé, et rend un récapitulatif, un jeton à confirmer et l'audience abonnée à ce jour. l'étalement prévu par la chauffe du domaine et le lien vers la campagne dans l'admin. L’outil vaemail_confirmer_envoi exécute ensuite l’envoi ou la programmation après accord humain explicite. Ne fait jamais : envoyer sans « quand » explicite (sans ce champ, la campagne reste en brouillon, rien ne part) ; inventer une liste (si le nom est ambigu, l'outil rend les candidates et vous choisissez avec l'humain). Utilisez-le dès que quelqu'un dit « envoie / programme la newsletter à … ». Exemple : { "sujet": "Votre budget formation 2026 se ferme le 31 décembre", "contenu": "<p>…</p>", "liste": "L'actu BienveNum", "quand": "2026-09-17 10:00", "test_vers": "[email protected]" }.

Parameterslisterequiredquandsujetrequiredapercucontenurequiredtest_versnom_interneliste_exclue

vaemail_confirmer_envoi

Confirmer l’envoi d’une newsletter

Exécute l’envoi ou la programmation préparé(e) après confirmation humaine explicite. Le jeton est à usage unique.

Parametersjetonrequired

vaemail_ou_en_est_ma_campagne

Où en est ma campagne ?

Dit où en est une newsletter, en phrases : brouillon, programmée (et pour quand), en cours d'envoi (envoyés, restent), ou terminée (envoyés, ouverts, cliqués, rebonds, désinscriptions). Retrouve la campagne par son numéro ou par un bout de son sujet ; si plusieurs correspondent, rend la liste et vous choisissez. Lecture seule, ne change rien. Utilisez-le pour « ça en est où ? », « elle est partie ? », « combien ont ouvert ? ». Exemple : { "campagne": "budget formation" } ou { "campagne": 60 }.

Parameterscampagnerequired

vaemail_qui_est_abonne

Qui est abonné à quoi ?

Sans paramètre : toutes les listes du compte, rangées par dossier, avec le nombre d'abonnés de chacune. Avec une adresse : ses listes, et si elle est désinscrite (auquel cas aucun envoi ne l'atteindra, et il ne faut pas la réabonner). Lecture seule. Utilisez-le avant d'envoyer (pour choisir la liste) et pour « est-ce que untel est inscrit ? ». Exemple : {} ou { "adresse": "[email protected]" }.

Parametersadresse

vaemail_importer_contacts

Importer des contacts dans une liste

Ajoute des contacts (email, prénom, nom, attributs libres) à une liste, créée si elle n'existe pas. Met à jour les contacts déjà connus. Ne fait jamais : réabonner quelqu'un qui s'est désinscrit (il est ajouté à la liste mais reste désinscrit, aucun envoi ne l'atteindra) ; supprimer quoi que ce soit. Rend un compte-rendu : lignes reçues, lignes ignorées (adresse invalide), abonnés de la liste avant et après. Utilisez-le pour « ajoute ces contacts à … », « importe ce fichier dans … ». Exemple : { "liste": "Prospects salon", "contacts": [{ "email": "[email protected]", "prenom": "Anne", "nom": "Blin", "attributs": { "SOCIETE": "Blin SA" } }] }.

Parameterslisterequiredcontactsrequired

vaemail_capabilities

What VaEmail can do

Return what VaEmail supports: interfaces, capabilities, limits, scopes and region. No API key needed. Call this first when deciding whether VaEmail fits a need.

Takes no parameters.

vaemail_send_email

Send an email

Queue a transactional email and return its id. The call returns as soon as the message is ACCEPTED, not when it is delivered: use vaemail_get_message to find out what happened to it. Pass idempotency_key when retrying so a network timeout cannot send the same message twice.

Parameterstorequiredtaghtmlsubjectreply_tofrom_namevariablestemplate_ididempotency_key

vaemail_validate_email

Check a send without sending

Dry run: report whether the email would go out, and name what would block it. Sends nothing. Use it right after setup, before the first real message.

Parameterstorequiredhtmlsubjecttemplate_id

vaemail_get_message

Delivery status of one message

Return the delivery status of a message and every event known about it (delivered, opened, clicked, bounced, complained), plus the transport error when it failed.

Parametersidrequired

vaemail_list_messages

List recent messages

List messages newest first, filtered by status, tag or recipient. Paginate with the returned next_cursor.

Parameterstotaglimitcursorstatus

vaemail_list_domains

List sending domains

List the sending domains of the account with the live state of their SPF, DKIM and DMARC records.

Takes no parameters.

vaemail_create_domain

Declare a sending domain

Declare a domain and return the DNS records to add at the registrar, each with what it is for. Declaring a domain does not authenticate it: the records must be published, then verified. Adding DNS records is a human step — report them, do not claim the domain is ready.

Parametersdomainrequireddkim_selectoridempotency_key

vaemail_verify_domain

Verify domain authentication

Read SPF, DKIM and DMARC for a domain in the public DNS and report each record. Without SPF and DMARC, large mailbox providers file the mail as spam.

Parametersdomainrequireddkim_selector

vaemail_dns_requirements

DNS records expected for a domain

Return the DNS records a declared domain needs, record by record, with the role of each.

Parametersdomainrequired

vaemail_diagnose_deliverability

Why is my email not arriving?

Diagnose deliverability for the account: authentication of every domain, reputation findings (hard bounces, complaints, where the contacts came from) and recommended actions, each with the endpoint that performs it. Answers "why are my emails from example.com landing badly?" in one call.

Parametersdomain

vaemail_list_bounces

Addresses removed from sending

List addresses excluded from sending: hard bounces, complaints and unsubscribes, with the reason for each. Sending to one of them is refused, so read this before retrying a failed recipient.

Parameterslimitsincecursorreason

vaemail_get_usage

Usage, quota and key limits

Return the monthly quota and what is left of it, today's sends, and for the key in use: its scopes, its daily cap and the remaining allowance. Read it before a batch to know whether to stop.

Takes no parameters.

vaemail_get_audit_log

What this key has done

Return the log of API actions: which key, which operation, which parameters, which result. Message bodies are never stored in it. Use it to report exactly what was done.

Parameterslimitsincecursoroperation

Version history

2
  1. v1.2.0LatestOct 26, 2026
  2. v1.1.0Sep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts