快速入门
事务性发送 API 让你自己的后端触发一封邮件——就像调用 Brevo、SendGrid 或 Postmark 的发送端点一样。它非常适合一次性验证码、收据和提醒通知,同样也可以触发你在工作室中设计好的项目,用你自己的数据代替一行联系人数据。
铸造一个密钥
在仪表盘的开发者下,点击创建密钥并为它命名(例如"生产环境后端"、"预发布环境")。完整密钥——mia_live_...——只会显示一次。请把它保存在安全的地方;MailInApp 只保存其哈希值,因此没有办法再次找回它。如果你丢失了它,撤销它并重新铸造一个新的即可。
密钥的作用范围是你的整个账户,而不是单个项目——一个密钥可以触发你拥有的任意项目。可以随意创建多个密钥(每个环境或每个集成各用一个是常见做法),并可以随时独立撤销其中任意一个。
发送 #1:自由格式
对于不涉及工作室项目的纯事务性邮件,自行提供 HTML 和文本内容:
curl -X POST https://mailinapp.com/api/v1/send \
-H "Authorization: Bearer mia_live_..." \
-H "Content-Type: application/json" \
-d '{
"to": "[email protected]",
"subject": "Your one-time code",
"html": "<p>Your code is 123456</p>",
"text": "Your code is 123456"
}'
调用成功会返回:
{ "id": "abc123", "status": "sent" }
发送 #2:模板
这才是真正的差异化优势所在:在工作室中以可视化方式设计一封邮件——降级引擎、互动模块、合并标签——然后从你自己的注册、结账或客服代码中触发它,用 mergeData 代替一行数据源数据:
curl -X POST https://mailinapp.com/api/v1/send \
-H "Authorization: Bearer mia_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_12345" \
-d '{
"to": "[email protected]",
"projectId": "your-project-id",
"mergeData": { "name": "Ada", "orderId": "12345" }
}'
在该项目的工作室 URL(/studio/<projectId>)中找到 projectId。mergeData 字段会像一行联系人数据那样,解析进项目的 {{field}} 合并标签中。收件人会收到一个专属于自己的、经过签名的实时预览链接,与任何其他发送方式相同——互动模块(投票、评分、表单)照常可用,每一次响应都会流入该项目常规的响应视图和 Webhook 投递中,并归因到这一次具体的 API 调用。
Idempotency-Key 请求头是可选的,但对任何可能被重试的操作(结账 Webhook、队列消费者)都建议添加——参见 API 参考中的幂等性。
覆盖发件人
两种发送方式默认都使用你账户已配置的发件人身份——如果你使用原生(SES)发送,则是设置 → 域名页面中的"发件地址"卡片,否则就是你 SMTP 中继配置的发件地址。添加 from 可以为某一次调用覆盖它,例如一个多品牌账户以某个特定团队的身份发送:
curl -X POST https://mailinapp.com/api/v1/send \
-H "Authorization: Bearer mia_live_..." \
-H "Content-Type: application/json" \
-d '{
"to": "[email protected]",
"subject": "Your one-time code",
"html": "<p>Your code is 123456</p>",
"text": "Your code is 123456",
"from": { "email": "[email protected]", "name": "Your Sales Team" }
}'
只要出现了 from,就必须提供 from.email(不支持只提供名称的覆盖方式);from.name 是可选的。在原生(SES)发送下,from.email 必须是你某个已验证域名下的地址——原因以及 SMTP 更宽松的规则,请见 API 参考中的发件地址。
如果你已经在仪表盘中保存了一个发件人身份,可以直接传入其 id 作为 senderId,而不必在每次调用中重复填写地址/名称——这两个字段的说明见API 参考。