How to Use Email API Events for Bounce Monitoring (Template-Owned Support)

本文为原文前 6,000 字符的节选翻译，完整内容请查看原文。

How to Use Email API Events for Bounce Monitoring (Template-Owned Support)

TL;DR: For a marketplace contact form, choose an email API that can return durable bounce, complaint, suppression, and domain-health signals without taking ownership of queue routing or transactional templates. Keep the template revision, case ID, recipient decision, and support queue in application storage. Treat push events as the fast path and cursor-based polling as repair. The decisive test is whether a replayed event changes business state once. That boundary matters more than a large feature matrix. I first treated a successful scheduled run as useful evidence; after being paged by missed jobs and duplicate deliveries, I stopped doing that. The system of record must make both absence and replay explainable. A successful send request proves acceptance of work, not inbox delivery, and a provider-hosted template name cannot explain why a marketplace case went to Trust instead of Payments. The invariant is short: the marketplace owns intent; the delivery API reports outcomes.

简而言之：对于市场联系表单，请选择一种能够返回持久化退信、投诉、抑制和域名健康信号的电子邮件 API，且该 API 不应接管队列路由或事务性模板。应将模板修订版本、案例 ID、收件人决策和支持队列保留在应用程序存储中。将推送事件视为快速路径，将基于游标的轮询视为修复手段。决定性的测试在于重放的事件是否仅改变一次业务状态。这一边界比庞大的功能矩阵更为重要。我最初将成功的定时任务运行视为有效的证据；但在因任务丢失和重复投递而收到寻呼后，我停止了这种做法。记录系统必须能够解释缺失和重放的情况。成功的发送请求仅证明工作已被接收，而非已送达收件箱；且由提供商托管的模板名称无法解释为什么市场案例被发送到了“信任”部门而非“支付”部门。不变的原则很简单：市场拥有意图，而投递 API 负责报告结果。

Which API should I use for email deliverability monitoring and bounce events? A marketplace contact submission combines facts that change at different rates. The buyer’s case ID and selected topic are business data. Queue routing is support policy. The subject, HTML, and locale are reviewed content. Bounce classification and complaint reports are transport outcomes. Putting all four behind one remote template identifier makes a content edit capable of changing an operational workflow, and it makes a provider migration larger than the sending boundary. Application ownership means recording an immutable template revision beside the case, rendering the message under review, and sending already-rendered content through a narrow interface. The API receipt is attached later. This is less convenient than letting a hosted editor control everything: the application team now owns escaping, previews, localization tests, and deployment order. I accept that cost for transactional contact-form mail because support must be able to reconstruct the exact message and routing decision from its own records.

我应该使用哪种 API 来进行电子邮件送达率监控和退信事件处理？市场联系提交结合了以不同速率变化的事实。买家的案例 ID 和所选主题属于业务数据。队列路由属于支持策略。主题、HTML 和语言环境属于已审核内容。退信分类和投诉报告属于传输结果。将这四者置于同一个远程模板标识符之后，会导致内容编辑能够改变操作工作流，并使提供商迁移的难度超过发送边界本身。应用程序所有权意味着在案例旁边记录不可变的模板修订版本，在审核时渲染消息，并通过窄接口发送已渲染的内容。API 回执稍后附加。这不如让托管编辑器控制一切来得方便：现在应用程序团队需要负责转义、预览、本地化测试和部署顺序。我接受事务性联系表单邮件的这一成本，因为支持团队必须能够从其自身记录中重构确切的消息和路由决策。

Here is the contract. The example runs as a Go program and deliberately contains no provider vocabulary.

以下是契约。该示例作为一个 Go 程序运行，并刻意不包含任何提供商的词汇。

package main
import (
	"context"
	"fmt"
)

type Message struct {
	OperationID     string
	CaseID          string
	Queue           string
	Recipient       string
	TemplateVersion string
	Subject         string
	HTML            string
}

type Receipt struct {
	TransportMessageID string
}

type Sender interface {
	Send(context.Context, Message) (Receipt, error)
}

func supportQueue(topic string) (string, error) {
	switch topic {
	case "unsafe-listing":
		return "trust", nil
	case "payment-dispute":
		return "payments", nil
	case "account-access":
		return "account-support", nil
	default:
		return "", fmt.Errorf("unmapped contact topic %q", topic)
	}
}

func main() {
	queue, err := supportQueue("unsafe-listing")
	if err != nil {
		panic(err)
	}
	fmt.Println(queue)
}

OperationID identifies one logical notification and should be used as an idempotency key when an API documents that capability. CaseID remains the marketplace’s workflow key. The returned transport ID is correlation data, never the primary identity of the support case. Do not hide the template boundary during evaluation. Ask whether the API accepts rendered text and HTML, whether custom correlation metadata survives into feedback, and whether a receipt can be joined to later events. Those answers determine whether the adapter stays small. A polished hosted-template editor does not answer them.

OperationID 标识一个逻辑通知，当 API 记录了该功能时，应将其用作幂等键。CaseID 仍然是市场的工单键。返回的传输 ID 是关联数据，绝不是支持案例的主要标识。在评估过程中，不要隐藏模板边界。请询问 API 是否接受已渲染的文本和 HTML，自定义关联元数据是否能在反馈中保留，以及回执是否可以与后续事件关联。这些答案决定了适配器是否能保持精简。一个精美的托管模板编辑器无法回答这些问题。

Make feedback a state transition, not an alert stream. Delivery feedback has to change application behavior. Normalize incoming records into a small internal vocabulary, retain the original payload for audit, and apply suppression before another send is admitted. Useful states include accepted, delivered, temporary failure, permanent failure, complaint, and unsubscribe; preserve diagnostic details separately instead of forcing every transport-specific code into support policy. Duplicates are expected at this boundary, so processing must be idempotent. The following in-memory example shows the rule. Production storage should enforce uniqueness on the source plus source event ID inside the same transaction that records suppression.

将反馈视为状态转换，而不是警报流。投递反馈必须改变应用程序的行为。将传入的记录标准化为一个小型的内部词汇表，保留原始负载以供审计，并在允许下一次发送之前应用抑制。有用的状态包括已接受、已送达、临时失败、永久失败、投诉和取消订阅；应单独保存诊断细节，而不是强行将每个传输特定的代码塞入支持策略中。在此边界处预计会出现重复数据，因此处理必须是幂等的。以下内存示例展示了该规则。生产存储应在记录抑制的同一事务中，对“来源 + 来源事件 ID”强制执行唯一性。

package main

import (
	"fmt"
	"sync"
	"time"
)

type EventKind string

const (
	PermanentFailure EventKind = "permanent_failure"
	Complaint        EventKind = "complaint"
	Unsubscribe      EventKind = "unsubscribe"
)

type DeliveryEvent struct {
	Source        string
	SourceEventID string
	Recipient     string
	Kind          EventKind
	OccurredAt    time.Time
	Raw           []byte
}

type Repository struct {
	mu         sync.Mutex
	seen       map[string]struct{}
	suppressed map[string]EventKind
}

func (r *Repository) Apply(event DeliveryEvent) (bool, error) {
	r.mu.Lock()
	defer r.mu.Unlock()

	if event.Source == "" || event.SourceEventID == "" || event.Recipient == "" {
		return false, fmt.Errorf("source, event ID, and recipient are required")
	}

	key := event.Source + ":" + event.SourceEventID
	if _, exists := r.seen[key]; exists {
		return false, nil
	}

	switch event.Kind {
	case PermanentFailure, Complaint, Unsubscribe:
		r.suppressed[event.Recipient] = event.Kind
	}

	r.seen[key] = struct{}{}
	return true, nil
}

func main() {
	repo := &Repository{
		seen:       make(map[string]struct{}),
		suppressed: make(map[string]EventKind),
	}

	event := DeliveryEvent{
		Source:        "transport-a",
		SourceEventID: "event-1042",
		Recipient:     "seller@example.test",
		Kind:          Complaint,
		OccurredAt:    time.Now().UTC(),
	}

	first, _ := repo.Apply(event)
	second, _ := repo.Apply(event)

	fmt.Println(first, second, repo.suppressed[event.Recipient])
}

The output is true false complaint. One event, delivered twice, creates one transition. Simple. Suppression must also be checked where a send is created, preferably in the transaction that writes an outbox record. A periodically refreshed cache alone leaves a race between reading eligibility and enqueueing mail. Store the reason, effective time, and source event so an operator can distinguish a complaint from a permanent failure without.

输出结果为 true false complaint。一个事件被投递两次，仅产生一次状态转换。很简单。必须在创建发送请求的地方检查抑制状态，最好是在写入发件箱记录的同一事务中进行。仅靠定期刷新的缓存会在读取资格和邮件入队之间留下竞争条件。存储原因、生效时间和来源事件，以便操作员能够区分投诉和永久失败，而无需……