Email Delivery and SMTP

Pathrule3 Rules • 2 Memories • 2 Skills

Sending an email is not the same as delivering it. Production mail crosses queue retries, provider acceptance, SMTP responses, domain authentication, reputation, recipient feedback, template rendering, unsubscribe policy, and sensitive-data boundaries. This pattern constrains idempotent enqueueing, authenticated sender identity, recipient policy, and content safety; it records bounce and provider-event ownership and supplies delivery and domain-change procedures. It complements background jobs and notification code by focusing on mail-specific identity, deliverability, feedback loops, message headers, and the operational distinction between accepted, delivered, bounced, complained, and suppressed.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

verify-email-delivery-flow

rotate-email-sending-domain

src/

workers/

Give every logical email a stable idempotency key

email/

Enforce suppression, consent, and message classification before send

Provider acceptance is one delivery state

Templates are versioned data contracts

ops/

email/

Authenticate the exact sending domains and streams

Rules

Give every logical email a stable idempotency key/src/workershighstrictDeduplicate enqueue and provider submission by business event, recipient, template version, and intended delivery occurrence.

1	Queues and providers can retry after timeouts or ambiguous responses. A worker that creates a new message identity on every attempt can send duplicate password links, invoices, or alerts.
2
3	- Construct a stable logical key from the domain event and recipient, adding an occurrence or template version only when the product intends a distinct message.
4	- Store message state before provider submission and return the prior provider identifier or terminal outcome when the same key is processed again.
5	- Separate retry attempts from logical messages so delivery history preserves one intent with several transport attempts.
6	- For bulk or scheduled mail, generate recipient-level identities and checkpoint progress; do not make one failure replay every recipient.
7
8	See /src/email for the adjacent decision or procedure that completes this constraint.

Authenticate the exact sending domains and streams/ops/emailhighstrictAlign visible From identity, envelope domain, DKIM signing, SPF authorization, and DMARC policy for each provider and environment.

1	Mailbox providers evaluate domain identity and reputation across several signals. A valid SMTP credential does not prove that the chosen domain authorizes or aligns with the sender.
2
3	- Inventory transactional, marketing, support, and test streams and assign approved From, return-path, and signing domains without sharing production reputation with uncontrolled environments.
4	- Publish SPF authorization without creating duplicate records or exceeding lookup behavior, and remove providers when they no longer send.
5	- Enable DKIM with managed or rotated selectors and verify signatures on received messages, not only provider-console status.
6	- Introduce DMARC reporting and policy in stages, reviewing legitimate sources and alignment before moving to stronger enforcement.
7
8	See /ops/email for the adjacent decision or procedure that completes this constraint.

Memories

Provider acceptance is one delivery state/src/emailModel queued, submitted, accepted, delivered where observable, deferred, bounced, complained, and suppressed outcomes separately.

1	An API success or SMTP acceptance means the provider took responsibility for the message, not that the mailbox accepted or displayed it. Product behavior must not treat all later outcomes as success.
2
3	- Store provider message identity and correlate signed provider events to the logical email without trusting an arbitrary callback payload.
4	- Classify temporary deferrals separately from permanent recipient or policy failures and cap automatic retries by the provider contract.
5	- Move hard bounces and complaints into suppression promptly while retaining enough reason and timestamp data for support and reputation work.
6	- Expose delivery status to product workflows only at the confidence they need; for example, account recovery may offer another channel without claiming the recipient read the mail.
7
8	See /src/workers for the rule or workflow that puts this decision into practice.

Templates are versioned data contracts/src/emailRender from validated variables, keep text and HTML alternatives, and bind links to short-lived server-side actions.

1	A template change can break rendering, accessibility, localization, tracking, or the security meaning of a link even when the send API remains unchanged. Treat the template and variable schema as one versioned contract.
2
3	- Validate required variables and types before enqueue so workers do not discover a missing value after the business transaction has committed.
4	- Generate text and HTML alternatives from the same semantic content and test escaping, long values, localization, and client-safe layout.
5	- Put opaque, bounded, expiring tokens in action links and resolve state on the server; do not embed secrets, personal records, or authorization decisions in query strings.
6	- Record template version with the logical message so support can reproduce what the recipient was sent without retaining unnecessary rendered personal content.
7
8	See /ops/email for the rule or workflow that puts this decision into practice.

Skills

verify-email-delivery-flow/rootTest enqueue, rendering, provider submission, authentication, feedback events, suppression, retries, and privacy as one flow.

1	---
2	name: verify-email-delivery-flow
3	description: Verify an email type or provider integration before production rollout.
4	---
5
6	# Verify Email Delivery Flow
7
8	Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result.
9
10	- [ ] Generate representative messages for success, duplicate event, missing variable, invalid address, suppressed recipient, and provider timeout using stable logical keys.
11	- [ ] Inspect received headers for From, return path, DKIM, SPF, DMARC alignment, Message-ID, list headers where relevant, and unintended environment leakage.
12	- [ ] Replay signed accepted, deferred, bounced, complained, and malformed provider events and confirm state transitions are idempotent and attributable.
13	- [ ] Render text and HTML in representative clients with long localized content, images disabled, dark mode, and assistive technology expectations.
14	- [ ] Search logs, traces, metrics, URLs, and dead-letter payloads for message bodies, tokens, email addresses, and other data the observability contract excludes.
15
16	## Exit criteria
17
18	The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.

rotate-email-sending-domain/rootMove a sending domain or provider through DNS, authentication, warmup, feedback, and rollback without losing reputation signals.

1	---
2	name: rotate-email-sending-domain
3	description: Change an email provider, sending subdomain, DKIM selector, return path, or DMARC policy.
4	---
5
6	# Rotate Email Sending Domain
7
8	Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result.
9
10	1. Inventory every legitimate sender, stream, domain, provider credential, DNS record, webhook, suppression source, and application configuration involved.
11	2. Publish and verify new SPF, DKIM, return-path, and tracking records while keeping old records active for mail still in flight.
12	3. Send controlled traffic through the new path, inspect authentication and feedback events, and increase volume only while bounce, complaint, and deferral signals remain healthy.
13	4. Synchronize suppression and unsubscribe state before moving recipients; never warm a new provider by resending to addresses the old provider suppressed.
14	5. Retain rollback capability until queued mail and feedback on the old path drain, then remove obsolete credentials and DNS authorization deliberately.
15
16	## Exit criteria
17
18	The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.

Why this pattern

AI agents often retry without a stable message key, treat provider acceptance as delivery, ignore hard bounces and complaints, or put secrets and personal data into logs and tracking URLs.

Built for Product and platform teams sending transactional, account, lifecycle, or operational email.

Keeps your assistant from:

Sending the same transactional message twice after a worker retry
Continuing to send to hard-bounced or complaining recipients
Breaking domain authentication during a provider or DNS change
Leaking personal or secret values through logs and links

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25

1	Unsubscribe, complaint, bounce, consent, and account-security policies differ by message purpose. A generic send function that ignores classification can either suppress critical account mail or continue unwanted promotional delivery.
2
3	- Classify templates and domain events at definition time and require the classification in the send command.
4	- Check hard-bounce, complaint, global suppression, product subscription, and jurisdiction-specific consent state before provider submission.
5	- Keep transactional messages limited to the requested service purpose; adding promotional content can change the applicable policy and recipient expectation.
6	- Provide one reviewed override path for legally or operationally required communication and record why the suppression decision was bypassed.
7
8	See /src/workers for the adjacent decision or procedure that completes this constraint.