Vaemail

io.github.vaemail由 GitHub 账号 vaemail 发布v1.2.0更新于 Nov 2, 2026

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

已验证STDIO仅桌面云端与基础设施沟通与协作商业与电商

概览

AI 生成的概览

VaEmail 让助手发送新闻邮件和事务性邮件、管理联系人、验证发信域名并诊断送达问题。

可以做什么
  • 准备、确认并跟踪新闻邮件：按名称找到列表、生成草稿与一次性令牌、经人工确认后执行发送、用自然语言报告活动状态
  • 管理联系人与受众：按文件夹列出列表及订阅人数、查询单个地址的状态、导入或更新联系人且不会重新订阅已退订者
  • 发送与查看事务性邮件：带幂等键排队发送、试运行校验、读取投递状态与事件、按条件列出近期邮件
  • 配置并验证发信域名：声明域名、返回需发布的 DNS 记录、重新读取 SPF、DKIM 与 DMARC
  • 诊断送达率与账户状态：信誉问题与修复建议、被排除的地址、配额与密钥限额、API 操作审计日志
  • 无需 API 密钥即可查询服务支持的能力
适用场景
适合让助手在无人盯看后台的情况下端到端处理邮件：发送新闻邮件或应用触发的事务性邮件、接入新的发信域名，或解释邮件为何进入垃圾箱。批量发送前查看配额与退订名单时也有用。
运行要求
通过 npx 以 stdio 在本地运行（需 Node 18+），无其他依赖。需要 VaEmail 账户，并在 VAEMAIL_API_KEY 中提供仪表盘创建的 API 密钥，最好为该助手限定权限与上限；除 vaemail_capabilities 外所有工具都需要它。可用 VAEMAIL_BASE_URL 覆盖默认 API 地址。需要访问 VaEmail API 的网络。
安装前请注意
发送不可撤销：vaemail_confirmer_envoi 与 vaemail_send_email 被标记为破坏性操作，确认令牌仅可使用一次。API 密钥可发信并消耗配额，应限定范围并设置每日上限。发布 DNS 记录、创建密钥、购买套餐属于人工步骤，助手不得声称已完成。沙箱密钥会回滚写入，不能作为投递成功的证据。审计日志不含邮件正文，但会记录参数。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Vaemail，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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

来源：README.md，提交 b11fa33

工具

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]" }.

输入参数liste必填quandsujet必填apercucontenu必填test_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.

输入参数jeton必填

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 }.

输入参数campagne必填

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]" }.

输入参数adresse

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" } }] }.

输入参数liste必填contacts必填

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.

无需输入参数。

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.

输入参数to必填taghtmlsubjectreply_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.

输入参数to必填htmlsubjecttemplate_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.

输入参数id必填

vaemail_list_messages

List recent messages

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

输入参数totaglimitcursorstatus

vaemail_list_domains

List sending domains

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

无需输入参数。

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.

输入参数domain必填dkim_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.

输入参数domain必填dkim_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.

输入参数domain必填

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.

输入参数domain

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.

输入参数limitsincecursorreason

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.

无需输入参数。

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.

输入参数limitsincecursoroperation

版本历史

2
  1. v1.2.0最新Oct 26, 2026
  2. v1.1.0Sep 16, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分
  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分