1. 项目概述：AI智能体如何帮你搞定邮件发送与迁移

如果你正在用Claude Code、Cursor或者Windsurf这类AI编程助手写代码，并且项目里涉及到发送邮件——无论是用户注册后的欢迎信、密码重置通知，还是订单确认——那你大概率遇到过这个痛点：邮件服务商的SDK配置、API密钥管理、域名DNS设置，还有从旧服务商迁移过来的繁琐流程，每一项都够你折腾半天。更别提不同服务商（像SendGrid、Mailgun、Postmark）的API设计、模板语法还都不一样，想换一家，几乎等于重写一遍邮件发送逻辑。

最近我在一个全栈项目里就碰到了这个麻烦。项目原本用的是Resend，但需要更灵活的模板管理和更细致的发送数据洞察。评估了一圈，我盯上了Lettr这个新兴的邮件API服务。它的文档很清晰，功能也够用，但真动手迁移时，我发现工作量不小：要装新SDK、改代码、配域名DNS、还得把老模板导过来。就在我对着终端和代码编辑器发愁，准备手动开干时，我发现了 lettr-com/lettr-skills 这个项目。简单说，它是一套专门为AI编程助手（AI Agent）打造的“技能包”，能让你的AI助手直接理解如何操作Lettr，完成从迁移、发信到域名管理的一系列任务。

这玩意儿本质上是一个“技能”定义库，遵循Vercel Labs的 skills 规范。它不直接运行，而是给你的AI编程助手（比如Cursor的内置AI）提供了一套“操作手册”。当你用自然语言向AI描述任务时，比如“帮我把项目从Resend迁移到Lettr”，AI就能调用对应的技能，自动生成或执行正确的代码、命令和配置步骤。对我而言，它把一次可能耗费数小时、容易出错的配置工作，变成了几分钟的对话和确认，效率提升是实实在在的。接下来，我就结合自己的实操，拆解一下这套技能包到底怎么用，以及背后那些值得注意的细节。

2. 核心技能解析：四大模块如何解放你的生产力

lettr-skills 目前提供了四个核心技能模块，分别对应邮件基础设施迁移和管理中最常见的几个场景。理解每个技能的设计意图和边界，能帮你更精准地向AI助手下达指令。

2.1 onboarding ：一站式迁移，告别手动重写

这是我认为最体现价值的技能。传统迁移需要你：1) 阅读新旧两家服务商的文档；2) 对比API差异；3) 手动替换代码；4) 处理环境变量；5) 配置新域名。每一步都可能踩坑。 onboarding 技能的目标就是把这一系列动作自动化。

它的工作原理是这样的 ：当你发出类似“Migrate my project from SendGrid to Lettr”的指令后，激活该技能的AI助手会尝试做以下几件事：

  1. 项目栈检测 ：它会扫描你的项目根目录，识别出你正在使用的技术栈（比如是Node.js + Express，还是Python + Django，或者是Next.js），以及当前使用的是哪家邮件服务商的SDK（通过查找 package.json 、 requirements.txt 或 import / require 语句）。
  2. 依赖管理 ：根据检测到的栈，它会生成安装Lettr官方SDK的命令。例如，对Node.js项目，它会提供运行 npm install @lettr/email 或 yarn add @lettr/email 的建议。
  3. 代码重写 ：这是核心。它会找到项目中所有调用旧邮件服务商API的代码片段，并将其替换为Lettr SDK的等价写法。例如，将 sgMail.send(...) 替换为 await lettr.send(...) 。技能包里内置了针对主流服务商（Resend, SendGrid, Mailgun等）的转换规则。
  4. 环境变量配置 ：它会提示你将旧的API密钥环境变量（如 SENDGRID_API_KEY ）替换为 LETTR_API_KEY ，并引导你到Lettr后台获取这个密钥。
  5. 域名与模板引导 ：迁移代码后，它会建议你接着运行域名设置和模板导入的技能，形成一个完整的迁移流水线。

注意 ：虽然AI能完成大部分代码替换，但对于高度定制化或非标准的邮件发送逻辑（比如复杂的异步队列处理、自定义的邮件头注入），仍需人工复核。技能提供的是“安全”的通用转换，并非万能。

2.2 send-email ：覆盖主流场景的邮件发送指南

发送邮件是基础操作，但细节很多。 send-email 技能确保了无论你是要发一封简单的文本邮件，还是用HTML模板，或是配置SMTP传统方式，AI都能给出最佳实践代码。

技能涵盖的发送模式 ：

  • 单次发送（Single Send） ：最直接的API调用。AI会生成如何构造收件人、发件人、主题、纯文本/HTML内容体，并调用 lettr.send() 的示例代码。它会特别注意提醒你设置正确的 from 域名，该域名必须已在Lettr验证过。
  • 模板发送（Template-based Send） ：这是事务性邮件的常见模式。你需要先在Lettr后台设计好模板，并定义好“合并标签”（Merge Tags），比如 {{user_name}} 。技能会指导你如何在调用API时，传入一个 data 对象来填充这些标签，实现邮件的个性化。
  • SMTP中继配置 ：有些老旧系统或特定库（如PHP的 mail() 函数或某些CRM系统）只支持SMTP协议。Lettr也提供了SMTP接口。这个技能会告诉你如何配置SMTP服务器地址、端口（通常是587或465）、用户名和密码（这里用户名一般是你的API密钥，密码留空或也为API密钥），并启用TLS加密。

一个实操心得 ：在让AI生成发送代码时，最好明确指定你的技术栈。比如你说“用Node.js给我一个发送欢迎邮件的例子”，比单纯说“怎么发邮件”得到的代码更准确。因为Python的 lettr SDK和Node.js的 @lettr/email SDK在函数签名和异步处理上可能有细微差别。

2.3 domains ：厘清域名验证的DNS迷宫

用自有域名发邮件（比如 noreply@yourdomain.com ）是建立品牌信任的关键，但前提是必须通过SPF、DKIM、DMARC等一系列反垃圾邮件协议的验证。这对很多开发者来说是道坎。 domains 技能的作用就是当你说“Set up my domain example.com on Lettr”时，AI能给你一份清晰的DNS配置清单。

它会引导你完成以下核心步骤 ：

  1. 添加域名 ：首先，你需要在Lettr控制台添加你的发送域名。
  2. 获取DNS记录 ：添加后，Lettr会生成几条你必须添加到你的域名DNS解析商（如Cloudflare, GoDaddy, 阿里云万网）的记录。主要是三类：
    • CNAME记录 ：用于追踪邮件打开、点击等事件。Lettr会提供一个主机名（如 em1234.yourdomain.com ），你需要将其CNAME指向Lettr提供的目标地址。
    • DKIM记录 ：这是数字签名，证明邮件确实由你授权发出，防止被伪造。这是一条TXT记录，包含了一长串的公钥信息。AI会提醒你完整地复制整个字符串，包括引号（如果提供的话）。
    • DMARC记录 ：这是一个策略记录，告诉收件方服务器当邮件验证失败（SPF或DKIM不通过）时该怎么办。AI通常会建议你从一个比较宽松的策略开始，比如 p=none ，这样不会因为配置初期的微小问题导致邮件被拒收。
  3. 验证与等待 ：配置完DNS后，AI会告诉你验证是异步的，通常需要几分钟到几小时才能在全球DNS系统中生效。它可能会建议你使用 dig 或 nslookup 命令来手动检查记录是否已正确传播。

重要提示 ：DNS记录配置错误是域名验证失败的最常见原因。AI给出的记录值必须 一字不差 地复制到你的DNS管理面板。特别注意TXT记录末尾的点号、空格和引号。我个人的习惯是，在DNS保存后，立即用在线DNS查询工具（如 mxtoolbox.com ）检查一下记录值是否已更新且完全匹配。

2.4 templates ：无缝衔接你的设计资产

如果你从其他服务商迁移，很可能已经积累了一批精心设计的邮件模板。手动重做这些模板耗时费力。 templates 技能就是为了解决这个痛点，支持从Mailgun、SendGrid、Postmark、AWS SES和Mandrill导入模板。

它的核心能力是“合并标签转换” 。不同服务商的模板变量语法不同：

  • SendGrid: {{ first_name }}
  • Mailgun: %recipient.first_name%
  • Postmark: {{first_name}}
  • Lettr: 也使用 {{first_name}} 这类双花括号语法。

当AI执行导入技能时，它会尝试解析源模板，识别出这些变量占位符，并将其自动转换为Lettr兼容的格式。同时，它也会处理模板的HTML/纯文本内容，以及主题行中的变量。

使用这个技能时需要注意 ：

  1. 权限与API密钥 ：导入模板需要你提供 源服务商 的API密钥（比如SendGrid的API Key），以便AI技能能通过官方API读取你的模板列表和内容。你需要提前准备好这个密钥。
  2. 模板复杂度 ：对于极其复杂、包含大量自定义逻辑或嵌套结构的模板，自动转换可能无法完美处理。导入后，务必在Lettr的模板编辑器中预览和测试，确保格式和变量渲染正确。
  3. 分批操作 ：如果你有大量模板，建议分批导入，而不是一次性操作全部，便于出错时排查。

3. 从零开始：安装、配置与一次完整的迁移实战

了解了技能是什么，我们来看看怎么把它用起来。整个过程非常轻量，核心就是让AI助手获得这些“技能”的上下文。

3.1 环境准备与技能安装

首先，你需要一个已经集成了兼容AI助手的开发环境。目前明确支持的有：

  • Cursor ：这是目前体验最无缝的，因为它深度集成了AI Agent功能。
  • Claude Code / Windsurf / Codex ：这些是其他集成了AI编程助手的编辑器或IDE。
  • 任何兼容 Vercel Skills 规范 的AI编码代理。

安装步骤非常简单，只需一行命令 ： 在你的项目根目录下打开终端，运行：

npx skills add lettr-com/lettr-skills

这条命令会通过 npx （Node.js包执行器）从npm仓库获取 skills 这个工具，然后告诉它去GitHub上找到 lettr-com/lettr-skills 这个技能包，并将其添加到当前项目的上下文中。你可能会看到一些输出，提示技能已成功注册。

关键点解析 ：这个技能是安装在 项目级别 的，而不是全局。这意味着它的上下文只对当前这个项目有效。这样做的好处是隔离性好，不同项目可以使用不同版本或不同集合的技能，不会互相干扰。安装后，通常会在项目根目录生成一个隐藏的配置文件（如 .skills.json ）来记录这些信息。

3.2 核心前提：Lettr账户与API密钥

在让AI开始工作之前，你必须自己完成一项基础配置：准备好Lettr账户和API密钥。这是所有技能能够实际调用API的通行证。

  1. 注册与域名验证 ：前往 lettr.com 注册一个账户。注册后，最重要的一步是添加并验证一个发件域名。在Lettr后台的“Domains”部分，添加你的域名（例如 yourdomain.com ），并按照前面 domains 技能部分提到的步骤，去你的DNS服务商那里添加CNAME、DKIM等TXT记录，直到域名状态显示为“Verified”。
  2. 获取API密钥 ：域名验证通过后，进入Lettr后台的 Settings > API Keys 页面（通常地址是 app.lettr.com/settings/api-keys ）。点击“Create New Key”，给它起个名字（比如“Development”），然后复制生成的那串密钥。 这个密钥只显示一次，务必妥善保存 。
  3. 设置环境变量 ：将复制的API密钥设置为你的项目环境变量，变量名必须是 LETTR_API_KEY 。
    • 本地开发 ：如果你使用 dotenv ，就在项目根目录的 .env 文件中添加一行： LETTR_API_KEY=your_actual_api_key_here 。确保 .env 文件在 .gitignore 中，避免密钥泄露。
    • 部署环境 ：在Vercel、Netlify、Railway或任何你使用的部署平台，找到环境变量配置页面，添加同名变量。

安全警告 ：永远不要将API密钥硬编码在源代码中或提交到版本控制系统（如Git）。环境变量是管理密钥的标准且安全的方式。AI技能在生成代码示例时，也会默认引用 process.env.LETTR_API_KEY （Node.js）或 os.environ['LETTR_API_KEY'] （Python）这样的环境变量读取方式。

3.3 实战演练：一次完整的SendGrid到Lettr迁移

假设我有一个Node.js + Express的API服务，原来使用SendGrid发送邮件，现在想用AI技能辅助迁移到Lettr。以下是我与AI助手（以Cursor为例）的交互过程和背后的逻辑。

第一步：触发迁移技能 我在Cursor的AI聊天框中输入：

“我当前的项目使用SendGrid发送邮件，请帮我将其迁移到Lettr。”

AI助手识别到“迁移到Lettr”这个意图，并检测到项目中有SendGrid的依赖（ @sendgrid/mail ），于是它激活了 onboarding 技能。它首先回复一个分析摘要： “检测到您的项目为Node.js/Express，正在使用 @sendgrid/mail v7.x。我将为您规划迁移到Lettr的步骤：1. 安装Lettr SDK；2. 替换代码中的发送逻辑；3. 更新环境变量。是否继续？”

第二步：代码依赖与重构 我回复“继续”。AI开始工作：

  1. 安装SDK ：它生成终端命令让我执行： npm uninstall @sendgrid/mail 和 npm install @lettr/email 。我运行了这些命令，更新了 package.json 。
  2. 代码替换 ：AI扫描了我的代码库，找到了一个 services/emailService.js 文件，里面有这样的代码： 
    const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
async function sendWelcomeEmail(to, name) {
  const msg = {
    to,
    from: 'welcome@myapp.com',
    subject: `Welcome, ${name}!`,
    text: `Hello ${name}, welcome to our app!`,
    html: `<strong>Hello ${name}, welcome to our app!</strong>`,
  };
  await sgMail.send(msg);
}
    AI将其重构为Lettr版本： 
    const { Lettr } = require('@lettr/email');
// 初始化客户端，API密钥会自动从 LETTR_API_KEY 环境变量读取
const lettr = new Lettr();
async function sendWelcomeEmail(to, name) {
  await lettr.send({
    to,
    from: 'welcome@myapp.com', // 确保此域名已在Lettr验证
    subject: `Welcome, ${name}!`,
    text: `Hello ${name}, welcome to our app!`,
    html: `<strong>Hello ${name}, welcome to our app!</strong>`,
  });
}
    关键变化 ：初始化方式从 setApiKey 变成了实例化 Lettr 类，且默认从环境变量读密钥。发送函数从 sgMail.send 变成了 lettr.send 。参数结构基本一致，迁移成本很低。

第三步：环境变量与后续引导 代码替换后，AI提醒我： “代码已更新。请将项目中的 SENDGRID_API_KEY 环境变量更名为 LETTR_API_KEY ，并在Lettr后台获取您的API密钥填入。另外，您需要验证发送域名 myapp.com 。是否需要我引导您设置域名DNS记录？”

我回答“是”。AI便切换到 domains 技能模式，给出了需要在DNS服务商处添加的CNAME和TXT记录的具体值。

第四步：模板导入（可选） 如果我的SendGrid里还有现成的模板，我可以继续问：

“我还有一些SendGrid的模板，能导入到Lettr吗？”

AI激活 templates 技能，回复道： “可以。我需要您提供SendGrid的API密钥来读取模板。请先在SendGrid后台创建一个有‘模板读取’权限的API密钥，然后将其临时设置为环境变量 SENDGRID_API_KEY 。之后，我可以为您列出模板并指导导入过程。”

我按提示操作，AI最终生成了一个脚本的大致思路，或者指导我使用Lettr可能的导入工具或API（具体实现取决于Lettr官方是否提供批量导入API，技能可能提供代码示例或指向相关文档）。

整个流程下来 ，我从一个模糊的迁移想法，通过和AI的自然语言对话，获得了分步的、可执行的指令和代码修改，极大地减少了查阅两份文档和手动对比的时间。

4. 避坑指南与常见问题排查

即使有AI技能辅助，在实际操作中还是会遇到一些典型问题。下面是我在迁移和后续使用中踩过的坑和总结的排查思路。

4.1 迁移过程中的典型陷阱

1. 环境变量未生效

  • 症状 ：代码运行时报错，提示API密钥无效或未设置。
  • 排查 ：
    • 在Node.js中，运行 console.log(process.env.LETTR_API_KEY) ，检查是否输出 undefined 。
    • 确认 .env 文件是否位于项目根目录，且变量名拼写完全正确（大小写敏感）。
    • 如果你在终端直接运行，是否在运行命令前重新加载了环境？修改 .env 后，需要重启终端或使用 source .env （在bash中）使其生效。
    • 在Docker或容器环境中，确保环境变量在构建或运行时被正确注入。

2. 域名验证失败或邮件被标记为垃圾邮件

  • 症状 ：域名在Lettr后台长时间显示“Pending Verification”，或者邮件能发但直接进入收件人的垃圾箱。
  • 排查 ：
    • DNS传播延迟 ：添加DNS记录后，等待足够时间（最多48小时，通常几分钟到几小时）。使用 dig TXT _dmarc.yourdomain.com 或在线工具检查记录是否已全球生效。
    • 记录值错误 ：这是最常见原因。逐字核对AI给出的记录值和你在DNS面板输入的值。特别注意：
      • DKIM的TXT记录值通常非常长，包含引号，复制时不要遗漏开头结尾的引号，也不要添加多余空格或换行。
      • CNAME记录的目标地址（指向值）是否正确。
    • SPF记录冲突 ：如果你之前为其他邮件服务（如Google Workspace）设置过SPF记录，现在又为Lettr添加了新的SPF包含机制（ include: ），可能会超过DNS查询的10次限制，导致SPF失效。需要合并SPF记录。

3. 代码替换不完整或引入语法错误

  • 症状 ：迁移后应用启动失败，或某些邮件发送功能异常。
  • 排查 ：
    • AI可能只替换了它识别到的明显调用（如 sgMail.send ），但一些间接调用（如封装在工具函数里、通过动态引入的模块）可能被遗漏。全局搜索旧SDK的包名或关键函数名（如 @sendgrid/mail , Mailgun 等）。
    • 仔细检查AI生成的代码。虽然错误率低，但偶尔可能在异步/同步处理（比如忘了加 await ）、参数格式（比如Lettr的 from 字段可能需要一个对象 { email, name } 而不仅是字符串）上与原代码逻辑不完全匹配。对照Lettr官方SDK文档进行最终核对。

4.2 技能使用与AI交互技巧

1. AI没有激活技能

  • 可能原因 ：你的指令不够明确，或者AI助手的上下文没有正确加载技能包。
  • 解决 ：
    • 使用技能文档中建议的“示例提示词”，如“Migrate my project from Resend to Lettr”。这些提示词经过了优化，更容易被识别。
    • 确认技能已成功安装。可以尝试在项目根目录再次运行 npx skills list （如果 skills 工具支持）来查看已注册的技能。
    • 在Cursor中，有时需要重启编辑器或重新打开项目，以确保AI Agent加载了最新的项目上下文。

2. 技能给出的方案不适合我的特殊场景

  • 场景 ：我的邮件发送逻辑与AI生成的通用示例差别很大，比如使用了消息队列（RabbitMQ/Kafka）来异步处理邮件发送任务。
  • 解决 ：不要期望AI技能能完全理解并重构你所有的复杂业务逻辑。它的价值在于提供 标准的、正确的代码片段和配置指南 。你可以这样利用它：
    • 分步询问 ：不要一次性要求“迁移我的整个邮件系统”。而是问：“如何用Lettr的Node.js SDK发送一封邮件？”获得基础代码片段。
    • 针对性提问 ：“我的消费者从RabbitMQ队列里拿到任务，里面包含收件人和数据，如何在这个场景下调用Lettr API？”AI可以根据基础SDK用法，帮你写出适配你消费者逻辑的代码。
    • 将技能作为高级文档 ：当你对某个具体操作（如设置DMARC记录）不确定时，直接问AI，它给出的解释和步骤往往比直接翻文档更聚焦。

3. 模板导入后格式错乱

  • 原因 ：不同邮件服务商的模板引擎和CSS内联支持度不同。
  • 解决 ：
    • 导入后预览 ：务必在Lettr的模板编辑器中预览导入的模板，发送测试邮件到自己的邮箱查看实际效果。
    • 手动调整CSS ：对于复杂的响应式模板，可能需要在Lettr编辑器内重新调整样式，或使用Lettr支持的CSS内联工具进行处理。
    • 考虑手动重建 ：如果只有少数几个核心模板，且自动导入效果不佳，评估一下手动在Lettr的可视化编辑器中重建是否更快。有时这比调试导入的模板更有效率。

4.3 性能、成本与进阶考量

1. 发送延迟与速率限制 Lettr和所有邮件API服务一样，有发送速率限制。如果你需要发送大批量邮件（如营销活动），需要注意：

  • 异步与队列 ：即使在事务性邮件中，也建议将邮件发送任务放入后台队列（如使用Bull、Kue for Node.js或Celery for Python），避免阻塞主请求线程，并能更好地处理重试。
  • 批处理 ：查阅Lettr API文档，看是否支持批量发送接口。如果有，AI技能可能在你询问“如何发送大量邮件”时给出批处理的代码示例。
  • 监控 ：利用Lettr后台的仪表盘监控发送状态、打开率、点击率和退回率。设置告警（如果支持）或定期检查，以便及时发现发送问题。

2. 成本优化

  • 模板管理 ：在Lettr中创建可复用的模板，而不是在代码中硬编码HTML。这样更易于设计和修改，也符合技能导入的初衷。
  • 测试环境 ：为开发和测试环境使用单独的Lettr子账户或不同的发送域名（如 sandbox.yourdomain.com ），并使用测试专用的API密钥。避免在测试中消耗生产环境的发送额度或影响主域名的信誉。
  • 退信处理 ：实现良好的退信（Bounce）和取消订阅（Unsubscribe）处理逻辑。持续向无效地址发送邮件会损害你的发送信誉，可能导致所有邮件被拒。Lettr的Webhook可以推送这些事件，你的应用需要监听并相应更新用户状态。

3. 安全与合规

  • API密钥轮换 ：定期在Lettr后台轮换API密钥，并更新所有环境中的环境变量。降低密钥泄露的风险。
  • 隐私数据 ：不要在邮件模板或主题行中直接传递敏感的个人身份信息（PII），除非经过加密或脱敏处理。确保你的邮件发送实践符合像GDPR这样的数据保护法规。
  • 内容审核 ：虽然Lettr会进行基本的内容过滤，但作为发送方，你仍需确保邮件内容不违反垃圾邮件法规（如CAN-SPAM Act），包含清晰的退订链接和你的物理邮寄地址。

5. 总结与个人体会

回顾整个使用 lettr-skills 进行项目迁移和邮件系统重构的过程，我的核心感受是：它并不是一个全自动的、点一下就能完成的“魔法按钮”，而是一个强大的“副驾驶”和“加速器”。它最大的价值在于，将那些需要反复查阅文档、复制粘贴代码、配置繁琐服务的“体力活”和“记忆负担”，转化为了与AI的自然语言对话。

对于开发者，尤其是独立开发者或小团队，这意味着你可以将精力更集中在业务逻辑和产品本身，而不是基础设施的集成细节上。当你需要切换一个云服务、升级一个库、或者采用一项新工具时，如果它有对应的“技能包”，你的启动成本将大大降低。

从技术角度看， lettr-skills 项目也体现了当前AI编程工具生态的一个有趣趋势： 工具正在变得“可教导” 。通过一套规范的“技能”定义，服务提供商可以将其领域知识（Domain Knowledge）封装起来，让AI助手能够理解并执行该领域的特定任务。这比让AI去全网搜索不准确的教程或阅读冗长的官方文档要高效和可靠得多。

最后，给打算尝试的朋友一点建议： 信任，但要验证 。充分相信AI技能能给你一个90%正确的优秀起点，但最后那10%的关键配置、安全设置和与你自己业务逻辑的深度集成，仍然需要你带着思考去完成。把它当作一个超级得力的初级工程师，你给出战略指令，它高效完成战术执行，而你负责最终的代码审查和系统设计把关。这种协作模式，或许就是当下AI赋能开发的最优解。

Logo
亚马逊云科技技术品牌专区

更多推荐

cover

别再只聊大模型！AI的下一场革命，藏在“身体”里

avatar 亚马逊云科技技术品牌专区
cover

别再只聊大模型！人工智能的下一场革命，藏在“身体”里

avatar 亚马逊云科技技术品牌专区
cover

别再只聊大模型！AI的下一场革命，藏在“身体”里

avatar 亚马逊云科技技术品牌专区