SMTP 中继

SMTP 中继让只支持 SMTP 的软件（CMS、身份验证服务、框架、遗留应用）也能通过 SpacePost 发信。邮件会经过与 API 相同的流程：域名检查、抑制列表、配额、追踪、Webhook。

设置	值
主机	`smtp.spacepost.dev`
端口	`25976`
安全	STARTTLS，身份验证前必须启用
用户名	`spacepost`（迁移时也接受别名 `resend`）
密码	你的 API 密钥（`sp_live_...`）

先以不加密的方式连接，并在登录前通过 STARTTLS 升级；证书对 smtp.spacepost.dev 有效。暂不提供隐式 TLS（465 端口），因此在大多数客户端中请选择“STARTTLS”或“TLS”，而不是“SSL”。

From 地址必须属于已验证的域名。sending_access 密钥就足够了；限定域名的密钥只能使用其所属域名发信。

控制标头

在邮件中添加这些标头，即可使用 SMTP 本身没有对应字段的功能。它们由 SpacePost 处理，不会投递给收件人。

标头	示例	作用
`X-SpacePost-Tags`	`category=welcome, user_id=u_1042`	添加标签。以逗号分隔的 `name=value` 键值对；字符规则与 API 相同。
`X-SpacePost-Scheduled-At`	`2026-11-01T09:00:00Z` 或 `in 1 hour`	定时发送该邮件（最多 30 天）。

其他 X-* 标头、List-Unsubscribe、List-Unsubscribe-Post、In-Reply-To 和 References 会作为自定义标头转发。

示例

import nodemailer from "nodemailer";

const transport = nodemailer.createTransport({
  host: "smtp.spacepost.dev",
  port: 25976,
  secure: false, // STARTTLS: the connection is upgraded to TLS before login
  requireTLS: true,
  auth: { user: "spacepost", pass: process.env.SPACEPOST_API_KEY },
});

await transport.sendMail({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Hello over SMTP",
  html: "<p>It works.</p>",
  headers: { "X-SpacePost-Tags": "category=welcome", "X-SpacePost-Scheduled-At": "in 10 minutes" },
});

import os, smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "Acme <hello@acme.com>"
msg["To"] = "user@example.com"
msg["Subject"] = "Hello over SMTP"
msg["X-SpacePost-Tags"] = "category=welcome"
msg.set_content("It works.")
msg.add_alternative("<p>It works.</p>", subtype="html")

with smtplib.SMTP("smtp.spacepost.dev", 25976) as s:
    s.starttls()
    s.login("spacepost", os.environ["SPACEPOST_API_KEY"])
    s.send_message(msg)

swaks --server smtp.spacepost.dev --port 25976 --tls \
  --auth-user spacepost --auth-password "$SPACEPOST_API_KEY" \
  --from hello@acme.com --to delivered@test.spacepost.dev \
  --header "Subject: Hello" --header "X-SpacePost-Tags: category=test" --body "It works."

邮件如何映射

To、Cc 和 Reply-To 取自邮件头。不在 To 或 Cc 中的信封收件人（RCPT TO）会成为 Bcc。
HTML 和文本部分会被保留。支持附件，包括内联图片（Content-ID）。
没有主题的邮件，其主题会被设为 (no subject)。
与 API 一样，每个收件人都会计入你的配额。

限制与错误码

限制	值
邮件大小	40 MB，应答 `552`
身份验证失败	每个 IP 在 10 分钟内失败 10 次后会被封锁

SMTP 应答与 API 错误的对应关系如下：

情形	应答
超出每日或每月配额	`452`（临时性：你的软件稍后会重试）
触发速率限制	`421`
`From` 域名未验证	`553`
受限密钥、团队被暂停、校验错误、内容被拦截	`550`
我们这边出现临时问题	`451`

框架指南