跳转到内容
spacepost文档

退信、投诉与抑制

退信

Section titled “退信”
类型 含义 事件 结果
硬退信（永久性） 地址不存在，或域名永久拒收邮件。 email.bounced last_event 变为 bounced；该地址会被加入你的抑制列表。
软退信（临时性） 邮箱已满或服务器故障等临时问题。SES 会持续重试。 email.delivery_delayed 起初不会抑制任何地址。30 天内对不同邮件发生 3 次软退信后，该地址会被加入你的抑制列表。

硬退信在 Webhook 载荷中包含 bounce.type: "Permanent" 和 bounce.subType。

持续软退信的地址通常已被弃用，而邮箱服务商会把重复尝试算在你的头上。由邮件本身而非地址引起的软退信（邮件过大、内容或附件被拒绝）不计入该上限；请改为修复邮件本身。

投诉

Section titled “投诉”

当收件人将你的邮件标记为垃圾邮件，并且其邮箱服务商将此情况反馈回来（反馈环路）时，就会产生投诉。SpacePost 会触发 email.complained，将 last_event 设为 complained，并将该收件人加入你的抑制列表。投诉是最强烈的负面信号：请将其控制在 0.1% 以下。

抑制列表

Section titled “抑制列表”

抑制列表是每个团队各自的禁发名单。每次发送前，SpacePost 都会用它检查所有收件人（to、cc、bcc）：

  • 被抑制的收件人会从邮件中移除，并触发 email.suppressed 事件。
  • 如果没有剩余的收件人，则不会发送任何内容，邮件的 last_event 为 suppressed。
  • 配额在邮件被接受时计算，早于抑制检查，因此被抑制的收件人仍会计入你的每月配额。

硬退信、反复的软退信和投诉会自动添加条目，也可以通过 API 手动添加。每个条目都有一个 reason（bounce、complaint、unsubscribe 或 manual）和一个便于阅读的 detail，例如 Hard bounce (NoEmail) 或 3 soft bounces in 30 days (MailboxFull)。系统会保留某个地址最先记录的原因：手动添加地址绝不会覆盖已有的退信或投诉记录。

suppressions.ts
import { SpacePost } from "@spacepost/node";


const spacepost = new SpacePost();


await spacepost.suppressions.create({ email: "do-not-mail@example.com" });


const { data } = await spacepost.suppressions.list({ limit: 100 });
for (const s of data?.data ?? []) console.log(s.email, s.reason);


await spacepost.suppressions.remove("do-not-mail@example.com"); // by email or id
Suppression
{
  "object": "suppression",
  "id": "0192e1c4-0000-7000-8000-0000000000d1",
  "email": "nobody@example.com",
  "reason": "bounce",
  "detail": "Hard bounce (NoEmail)",
  "created_at": "2026-10-23T14:02:12.000Z"
}

无法到达的收件人域名

Section titled “无法到达的收件人域名”

如果收件人的域名完全不接收邮件（没有 MX 或 A 记录），SpacePost 会跳过该收件人而不是尝试投递，并触发 email.suppressed。这样可以保护你的退信率。参见账户验证与发送限额。

使用测试地址

Section titled “使用测试地址”

bounced@test.spacepost.dev、complained@test.spacepost.dev 以及（发送三次之后的）softbounced@test.spacepost.dev 会创建真实的抑制条目，并计入你的比率。测试后请将它们移除。参见测试。