Interceptor Address Normalization#

In Bamboo, interceptors run after address normalization, not before. This ordering has a practical consequence: by the time an interceptor's call/1 receives the email, all recipient fields (to, cc, bcc, from) have already been reduced from their original forms (e.g., rich domain structs) to {name, address} tuples via Bamboo.Formatter.

Execution Order in deliver_now/4#

The deliver_now/4 pipeline runs in this sequence:

1. validate_and_normalize/2 — validates the email (from address, recipients, attachment support), then calls normalize_addresses/1 to convert all address fields to {name, address} tuples via the Bamboo.Formatter protocol.
2. apply_interceptors/2 — iterates the configured interceptors list, calling each module's call/1 in order. 1
3. If not blocked and recipients are non-empty, the email is dispatched to the adapter.

The same order applies in deliver_later/3.

What Normalization Does#

normalize_addresses/1 rewrites the from, to, cc, and bcc fields by passing each through Formatter.format_email_address/2. For any rich struct (e.g., a User schema), all fields except the email address and display name are dropped. A plain string like "foo@bar.com" becomes {nil, "foo@bar.com"}. Custom structs must implement the Bamboo.Formatter protocol to control their own conversion.

The Interceptor Limitation (and Proposed Fix)#

Because normalization runs first, interceptors cannot access the original struct. For example, a DenyListInterceptor that checks email.to will see a list of {name, address} tuples — not User structs — making it impossible to branch on arbitrary struct fields like preferences or roles.

The test-suite DenyListInterceptor illustrates this: it checks email.to using elem(&1, 1) to extract the address string from already-normalized tuples. The Bamboo.Interceptor docs show the same assumption 2 — the example checks email.to in @deny_list expecting normalized string/tuple values.

PR #682 proposes reversing this order — running apply_interceptors before validate_and_normalize — so interceptors can access the richer pre-normalized structs. As of this writing the PR is open and unmerged; the current codebase still normalizes first.

Implications for Interceptor Authors#

Only one interceptor config key exists: interceptors. There is no before_interceptors key in the current codebase. 1

Key Files#