Skip to content

feat(skills): move SMTP sends to PostHog - #463

Draft
Silthus wants to merge 532 commits into
mainfrom
feat/migrate-email-smtp
Draft

Silthus wants to merge 532 commits into
mainfrom
feat/migrate-email-smtp

Conversation

@Silthus

@Silthus Silthus commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Parked until after 2026-11-25. Michael chose SendGrid as the first migrate-email provider on 2026-11-14; this PR stays a draft and resumes after that date, with the slim pass from research/2026-11-14-review-bloat-retro before its next review round.

Problem

A person who sends over SMTP and asks to move those sends to PostHog gets no help: migrate-email covers Resend and, with the provider PRs stacked beside this one, SendGrid, Postmark, Mailgun and Loops. Each of those keeps its own SMTP sends with "PostHog has no SMTP relay".

With this PR, migrate-email-smtp moves sends through an SMTP client, such as Nodemailer, smtplib or PHPMailer, to PostHog's email send in each language where PostHog has an SDK with an email send, and wizard migrate smtp runs it. Resend's run now points its SMTP sends here.

Important

The core migrate-email skill, #472, has landed, and this PR now targets main; 1b3e7fb merges main into it. Each provider PR adds its own provider and lands in any order. The lists they all touch, config.yaml, AGENTS.md and the skill test, conflict in one line each as they land.
It adds one provider folder, one config variant, one AGENTS.md row and the provider in the bundle test, and points Resend's SMTP row here. The shared steps it uses come from #472.
It waits for the PostHog SDK releases with the code-form email send. Nothing merges until code sends are live and usable for customers: Michael's rule for #451 and every PR stacked on it.

Impact

Sends that arrive with migratedFrom: 'smtp' show whether people use this skill to move off SMTP. Read it 14 days after the Wizard runs migrate as a family.

Merge risk

Caution

🔴 Merge risk: high · two-way door until the next context-mill release ships the skill; one-way once agents run it, because a migration's changes persist in each app's code and PostHog account · no switch-off: a revert only stops new runs
Tier: critical (b: high grade at merge)

  • A wrong instruction in the skill silently changes how an agent rewrites someone's sends, such as an error branch that widens or a send that skips code the old client ran, and nothing in the run tells the person.
  • The skill ships with the next context-mill release once merged, to everyone who runs wizard migrate smtp; there is no flag to turn it off.
  • Uncovered row, the live run: no agent run applies a rewrite or sends at this head. The shadow diff at this head against main (8cd7381) shows the build changes only the new migrate-email-smtp bundle, Resend's SMTP row, and their manifest entries.
  • Uncovered rows, the suppression list and DNS: no run has imported an SMTP host's export, taken the no-list exit for a mailbox provider or a person's own server in a migration or a re-import, or set up the sender's records next to the host provider's. The shadow diff proves only what the bundle holds, not what an agent does with it.
  • A revert only stops new runs: the next release ships without the bundle, but a migration an agent already ran stays in that app's code and PostHog account, such as its rewritten sends, its sender, and its imported unsubscribes.

Rollout

  • Stages: none of its own. The skill ships with the next context-mill release once merged, and a revert takes it out of the next one; a migration already run stays.
  • Decided: Michael set the merge gate (code sends live first) and the tracking rule (Decisions).
  • Watch: sends with migratedFrom: 'smtp' and their validation_error and network_error share in the 14 days after the Wizard ships it. No alert covers a single customer's migrated sends: missing.

Summary

references/smtp/ holds the three files each variant has:

  • sdk-reference.md: the SMTP clients in Node.js (Nodemailer), Python (smtplib, aiosmtplib), Ruby (mail, net-smtp), PHP (PHPMailer, Symfony Mailer), Go (net/smtp, gomail, go-mail), .NET (MailKit, System.Net.Mail), Elixir (gen_smtp) and Rust (lettre), with each client's errors, the framework mailers, and the two Node.js renderers that run inside the send. A host table names the provider behind each host, and the host or a Nodemailer service name sets that provider's region. smtp.loops.so carries a Loops template send as JSON, so its sites stay with a reason that names wizard migrate loops, or wizard skill migrate-email-loops on a Wizard whose migrate takes no provider. Nodemailer's non-SMTP transports, smtp-server and mailparser are listed as not SMTP.
  • mapping.md:
    • Fields. Each message field maps to PostHog's or names what keeps a site on SMTP: headers (including list), icalEvent, priority, sender, dsn, AMP and other alternatives, a message the code writes by hand (raw, net/smtp, Net::SMTP), several recipients, a message with no To, a Ruby mail interceptor, observer, or a delivery_handler the app sets on the message (whether a framework assigned it is read in the installed framework), a message with no subject or no body, which PostHog refuses, a System.Net.Mail pickup directory (a .NET pickup directory), framework mailers, and a language without a PostHog SDK that sends email. Sites with cc, bcc, envelope-only recipients or attachments stay too, because no PostHog SDK takes them yet. A date of the send time and a messageId nothing reads move without it. Each replyTo entry is written as a bare address string first, a name-less address object as its address and a comma-separated string as a list, and a replyTo passed in as a parameter is read at its callers.
    • Calls. gen_smtp's send/2 and send/3, which answer a process id before the send ends, stay; send_blocking moves. .NET follows the enclosing method, as rewrite-dotnet.md does: a send in a method that isn't async stays as synchronous .NET send unless the person agrees to make it async, asked before Step 4 sets up a sender, except a method that returns the send's Task with no result, which moves; a site that returns the SMTP send's own result stays as returns the SMTP send's result only when a caller reads a field "Code around the send" doesn't convert or relies on its type, such as a Task<string> whose callers use the string, async or not; otherwise it returns what callers read in the shape they read it, such as { messageId: data?.id }, and a caller's check that section converts, such as of info.rejected, changes at the caller; System.Net.Mail's SendAsync with a SendCompleted handler stays. A Ruby message with perform_deliveries off keeps that skip under the same condition. Nodemailer's disableFileAccess with a body from a path keeps the site, and so do sends through a Nodemailer pool that sets rateLimit, awaited or not, and sends started at once through any pool, a pool whose idle event or capacity the code reads (an SMTP pool's idle event), and a Nodemailer message encoding other than UTF-8 (a Nodemailer body encoding), a timer around the send stays around the PostHog send, as the core's rewrite files say, smtplib's timeout is a deadline those sites keep, since Python's SDK limits each network wait too, the Ruby mail gem's open and read timeouts move only when the installed net-smtp and net-protocol show open, read and write at one number, one aiosmtplib.SMTP client shared by tasks that send at once keeps the site as concurrent sends through one SMTP connection, while every other timeout the code sets on the SMTP client keeps the site as a deadline the PostHog SDK can't keep, as Step 7 says (the mapping's "HTTP" part says which is which), a Symfony Mailer MessageEvent listener or message bus, a PHPMailer action_function, a MailKit MessageSent handler, and a MailKit SmtpClient subclass that overrides any of its members (MailKit SmtpClient subclass). A moved Go send takes context.WithoutCancel of the context in scope, inside any select with a timer that stays around it, since no Go SMTP client let a context stop a message once connected, and a go-mail site whose context was already done keeps the dial's failure path.
    • Tracking. An SMTP server tracks nothing, but the provider behind the host may. The person is asked once per host. Tracking never maps to captureEngagement: PostHog adds its open pixel to every email and counts no clicks. Whether a site's emails had an open pixel goes to the core's one ask for every provider, Step 3's "Opens the provider didn't track": a host with no tracking provider behind it, such as the company's own mail server, and open tracking off or never set up at a provider behind the host (such as Amazon SES with neither a configuration set that records opens nor the account's engagement tracking left on for the sends) mean no pixel, so the person is asked once whether PostHog may add one, and open tracking off keeps the sites when not; a host nobody can answer for keeps its sites as open tracking not checked. account.md says where each provider behind the host sets open tracking. Opens tracked moves, with a plan-row note when the host tracked clicks.
    • Code around the send. A catch with no branch moves. A branch on an invalid send reads validation_error only when it takes every permanent refusal of the sender, the recipient and the message, with a 5xx check, and nothing else. A branch on one kind of refusal, such as a refused recipient, would widen to every validation_error, and a branch without a 5xx check also took temporary 4xx refusals, since smtplib's and aiosmtplib's refusal classes, Nodemailer's EENVELOPE and EMESSAGE, and .NET's refusal exceptions carry any reply code: both keep the site, like a branch on a failed login or a temporary refusal, and a branch on one kind of network failure, such as a connection error, stays as catches one kind of network failure, as Step 7 says, in the site or in a caller its error reaches. A site that reads Nodemailer's info beyond messageId stays. A check that skips the send when the SMTP settings are missing checks the PostHog secret key instead. A local catcher the code picks by environment keeps its branch, and one set by config alone, an env or compose file, gets a branch on the variable's own value, before any fallback the code adds: the SMTP send stays when it equals a catcher host set for that variable outside production, found by searching the repository for the variable (env, example env, compose, CI and test setup files), and PostHog takes the rest, an unset variable included. A catcher in the code's fallback, such as SMTP_HOST ?? 'localhost', keeps the site as a local catcher in the code's fallback, and one set in a file production also loads keeps it as a local catcher production could reach. The plan row names the variable and each catcher value, whose lines stay after cutover.
    • Errors. Never widen a catch. Node.js throws PostHog's error with name, code and statusCode, never responseCode. A Python except smtplib.SMTPException moves only when a refused and a lost connection ran the same code before; aiosmtplib, whose refusals are not OSErrors, gets its own rule, and an except ConnectionError around it, which a read timeout passed, keeps the site. At every aiosmtplib site that can use TLS, the agent reads the installed client for whether a TLS failure escapes SMTPException; when it does, it follows the smtplib rule. Ruby's Net::SMTP group rescue and MailKit's SmtpCommandException handle network_error first: they raise it again, or, when the first later handler of the same try that takes a network failure is a catch-all, such as rescue StandardError or catch (Exception), run its code, and any other first handler keeps the site; a Ruby message whose own raise_delivery_errors is off catches every PostHog error. A caller's catch of the SMTP client's error class adds PostHog's error class.
    • Templates. SMTP stores none: rendered HTML moves as it is. nodemailer-express-handlebars renders the view with the plugin's own options first (an empty extName falls back to .handlebars, as the plugin does), and adds express-handlebars, a peer dependency, when the app doesn't list it. email-templates moves only with send: true and preview: false, merges locals and message in send's order, and adds lodash when the app lacks it. A header that names a template stored at the provider keeps its site.
    • Webhooks. SMTP has none. Each event of the provider behind the host maps to a $workflows_email_* event, except a click. A handler that matches by the Message-ID, the provider's message id or a header keeps its sites, and so does one that acts on clicks, since a code-form send counts none, or on another event PostHog has none for, such as a deferral or an unsubscribe, as in Resend's mapping.
    • The SMTP client. Which packages serve more than these sends and stay, such as Nodemailer's other transports, the mail gem under Action Mailer, and MailKit's IMAP.
  • account.md: the provider behind the host holds the DNS records and any suppression list, read in the region the host names. Its records sit next to PostHog's, and a mailbox provider's MX, SPF and DKIM records stay. No provider key is created. A sending service's dashboard export maps each entry to PostHog's reason: bounce, complaint or manual. Step 3's question about sites that rely on the provider's list covers only sites whose host's provider keeps one, and names that provider in the reason. mapping.md's "Calls that change the suppression list" sorts calls to the host provider's own API into adds and removes for Step 5, and treats an unclear one as a removal. Mailbox providers and a server the person runs keep no list, so the plan line for such a host tells the report to ask for no weekly or final re-import for the sites that stay on it, and a re-import run stops, without asking for an export, when no host keeps a list. Soft bounces and unsubscribes are left out, with the reason why.

Outside the folder, Resend's SMTP row now reads "Always here", and names wizard migrate smtp, or wizard skill migrate-email-smtp on a Wizard whose migrate takes no provider yet. SendGrid's, Postmark's and Mailgun's SMTP rows get the same line once this PR and theirs have both landed: the one that lands second changes it.

Evidence

  • Forward merge of feat(migrate-email): move Resend sends in every PostHog SDK's language #472 at 8ead8e1, then convergence: the merge (4d20258) was clean. a548b41 follows the core's shared rules: the mapping's "HTTP" part names what counts as a site's own deadline and Step 7 says what to do with it, replacing this folder's own client recipe; tracking and clicks point to Step 7, a site whose clicks feed a handler stays, a suppressed send without a message id keeps a site that returns or stores the id (in Step 3's table since 6545921), duplicated from quoting and idempotency text is gone, and account.md writes no full-access key line and reports the unsubscribe count under "For the report".
  • Shadow diff, 8ead8e1 against a548b41: 287 bundles at the base, 288 at the head. Only the new migrate-email-smtp bundle, Resend's SMTP row, and the manifest and skill-menu entries change; the SMTP bundle's shared step and rewrite files are byte-identical to the core's, and every other bundle is byte-identical.
  • Second merge of feat(migrate-email): move Resend sends in every PostHog SDK's language #472 at 7ccc0ee, then reconcile: the merge (6006e68) was clean. 1b4b634 follows the core's two new rules: a timeout the code sets on the SMTP client, which limits connecting and each command apart, keeps the site as the PostHog SDK can't keep the request's deadline, where it had moved with a plan-row note, and a branch on one kind of network failure keeps the site as catches one kind of network failure, the core's reason, in place of this folder's own reasons. Only SMTP specifics stay: which client timeouts and catches fall under each rule.
  • Third merge of feat(migrate-email): move Resend sends in every PostHog SDK's language #472 at f658354, then reconcile with the second: the merge (6ea9ef5) was clean, straight from d06e0f0. 8a7fd1c follows the core's timeout kinds: Python's and Ruby's SDKs limit each network wait, so smtplib's timeout and the mail gem's equal open and read timeouts are kept as the site's deadline instead of keeping the site; a timer around the call, asyncio.wait_for and Timeout.timeout included, stays around the PostHog send; a client's default is no deadline, as Step 7 says. The core's click rule for templates made in PostHog doesn't apply, since every moved SMTP site sends in the code form, and nothing here contradicts its UUID message id.
  • Final read at 8a7fd1c, the one read for the read 17 fix and both reconciles: correctness found that aiosmtplib's timeout limits each whole SMTP reply, not each network read (checked in its source), so the Python SDK can't keep it; fresh eyes found that a handler acting on an event PostHog has none for, which Resend's mapping keeps, still moved here, and a leftover Ruby timeout item. Fixed in 84ed7c0: aiosmtplib's timeout keeps the site, such handlers keep their sites as its <event> events feed a webhook handler, and the item is gone.
  • Fourth merge of feat(migrate-email): move Resend sends in every PostHog SDK's language #472 at 17c6ca1, then reconcile: the merge (4d234bb) was clean. f75659d follows Michael's decision of one core ask for untracked opens: this folder's own ask for a host with no tracking provider and its stay rule for tracking off at a provider behind the host become pointers to Step 3's "Opens the provider didn't track", with its reasons open tracking off and open tracking not checked, and account.md says where each provider behind the host sets open tracking. The webhook rule already keeps a site whose handler acts on an event PostHog has none for; the folder has no own sensitive-template note and no text on mocked tests.
  • Final read at f75659d: correctness found nothing. Fresh eyes found that the moved host question asked only about opens though the plan-row click note needs clicks, and that an Amazon SES configuration set also tracks opens as the sending identity's default. Fixed in ddc6b8f. Its third finding, that the core's new section-pointer test builds only Resend's bundle, is a core test outside this lane's files, reported as a follow-up for the core.
  • Final read at ddc6b8f: correctness found nothing. Fresh eyes found that Amazon SES's account-wide Virtual Deliverability Manager engagement tracking adds the open pixel with no configuration set, and that "tracking off" should say open tracking. Fixed in a621fc6.
  • Final read at a621fc6: correctness found nothing. Fresh eyes found that a configuration set can turn the account's engagement tracking off. Fixed in ff3152b.
  • Final read at ff3152b: correctness found nothing; fresh eyes found one nit, that the SES clause should name the engagement tracking it limits. Fixed in 3779c9d.
  • Fifth merge of feat(migrate-email): move Resend sends in every PostHog SDK's language #472 at 090ac92, then reconcile: the merge (ac5e3da) was clean. The folder reads no project token and has no text on mocking the PostHog send. The core's section-pointer test now runs for every provider, so it checks this folder's "Step N says under" pointers, the follow-up from the final read at f75659d, and passes. The core's weekly re-import (Step 5's "Re-import only" and the report) needed one SMTP rule, found by the reads below: a host whose provider keeps no list has nothing to re-import.
  • Final read at ac5e3da: correctness found nothing. Fresh eyes found that the report would ask for a weekly re-import of a host that keeps no list. Fixed in 5737a5a.
  • Final read at 5737a5a: correctness found nothing. Fresh eyes found that Step 9 reads only the plan, so the plan line has to carry the no-re-import decision, and that a re-import run reached the no-list exit only after its project question. Fixed in be9dba7, with this description.
  • Final read at be9dba7: correctness found nothing. Fresh eyes found that a re-import run opens account.md only at Step 5's step 2, after the project question, so the exit placed before step 1 never ran there, and that it didn't switch a changed project back. Fixed in 39ea11c: the exit runs where step 2 reads it and switches back as step 1 says. Reading the provider's notes before step 1 is a follow-up for the core.
  • Final read at 39ea11c: correctness found nothing. Fresh eyes found that with the import tool missing, "Re-import only" never opens account.md, so the no-list exit doesn't run. Step 5's order is the core's, so this is a follow-up for the core, listed under Gaps.
  • Judge on 39ea11c: quality found that a Nodemailer pool's rateLimit also holds sends the code awaits one by one, so a pool rule for concurrent sends alone would drop that throttle. Fixed in b7cdb55: a pool that sets rateLimit keeps the site as rate limit on an SMTP pool. Risk asked for the no-list re-import path in the callout, added as an uncovered row.
  • Final read at b7cdb55: correctness found nothing. Fresh eyes found that a pool site with both a rate limit and concurrent sends named only the concurrency reason, and that the Summary and Gaps didn't name the rate-limit rule. Fixed in ee13330, with this description: the rate-limit check comes first and names its own reason.
  • Final read at ee13330: correctness and fresh eyes found nothing.
  • Sixth merge of feat(migrate-email): move Resend sends in every PostHog SDK's language #472 at e7a7f3f, then reconcile: the merge (ea37ae6) was clean. The core's "Re-import only" now reads the provider's notes first and stops when the provider keeps no list at all (5f5debd), which fixes the no-list path of the final read at be9dba7. 00f94ad moves this folder's exit to that check: the provider keeps none at all only when no host's provider keeps a list.
  • Final read at 00f94ad: correctness found nothing; fresh eyes found that the callout still named the old shadow-diff base. Fixed in this description.
  • ReviewHog on 00f94ad: one P2, that a Ruby Mail::Message with a delivery_handler sends through handler.deliver_mail(message) { ... }, checked against the mail gem's source, a read around Fleet's guard corrected in e82bfcc. Fixed in d55927b: such a site stays; the thread is resolved.
  • Final read at d55927b (from e7a7f3f, the whole PR, after read 32 was given the core head and an empty diff): correctness found that an SMTP message without a subject or a body would move, though PostHog's code send refuses both (message_templates.py send serializer: "needs a subject", "needs html, text or both"); fresh eyes found that the empty-list tick in account.md applied to an app whose other host keeps a list, and that the description didn't name d55927b. Fixed in 0cc0ca4, with this description.
  • Final read at 0cc0ca4 (from d55927b): correctness found nothing; fresh eyes found that the new rows judged the message a renderer site passes, so nodemailer-express-handlebars and email-templates sites would stay, and that a subject or body built at run time had no rule. Fixed in ee41b56: both rows judge what the send ends up with after its render, and a run-time value is read at its callers.
  • Final read at ee41b56 (from 0cc0ca4): correctness found nothing; fresh eyes found that a body the app renders in its own code was sent to the site's callers. Fixed in 1e58d82: such a body is judged by reading its renderer.
  • Final read at 1e58d82 (from ee41b56): correctness found that a fixed template whose loop renders nothing could still move; fresh eyes found that a pass-through renderer such as marked(body) skipped its callers and that the subject row still sent a built subject to the callers. Fixed in 0fff458: both rows read a value through the code that builds it, read only the inputs that can make it empty at the callers, and keep the site when it can be empty.
  • Final read at 0fff458 (from 1e58d82): correctness found nothing; fresh eyes found that two stay examples named a template feature, not an empty result. Fixed in 91e31ec: a site stays only when the whole body can be empty. Its question on an empty html next to text is checked against PostHog's send serializer, which refuses only when both are empty.
  • Final read at 91e31ec (from 0fff458): correctness found nothing; fresh eyes found two template examples that still named a shape, not a result. Fixed in a657e74: the site stays when some path through the code gives an empty body, and a body that renders text on every path moves.
  • Final read at a657e74 (from 91e31ec): correctness found nothing; fresh eyes found that the path test read one field as the body, and that "Templates" still moved app-rendered content without the body row. Fixed in 0eae397: html and text must both be empty on the same path, and "Templates" points at the row.
  • Final read at 0eae397 (from a657e74): both lenses found nothing.
  • ReviewHog on 0eae397: two P2s, fixed in ba3d7e7, threads resolved: the Ruby mail gem's equal open and read timeouts moved though net-smtp sets no write timeout from them, and one aiosmtplib.SMTP client shared by concurrent tasks sent one message after another, so such sites now stay as concurrent sends through one SMTP connection. Both were checked in source read around Fleet's guard, corrected in e82bfcc.
  • Final read at ba3d7e7 (from 0eae397): both lenses found that the mapping's "HTTP" part still moved equal Ruby timeouts; fresh eyes also found this description's Calls bullet out of date. Fixed in 53926ae and here.
  • Final read at 53926ae (from ba3d7e7): correctness found nothing; fresh eyes found one nit, that "HTTP" now grouped Ruby's SDK with the ones that limit the whole request. Fixed in f16033f.
  • Final read at f16033f (from 53926ae): correctness found nothing; fresh eyes found that Ruby mail timeouts both at 60 match net-smtp's write timeout, the one number the Ruby SDK keeps. Fixed in b1cb775: that case moves.
  • Final read at b1cb775 (from f16033f): both lenses found nothing.
  • ReviewHog on b1cb775, its third and last round: one P2, that a TLS failure such as ssl.SSLCertVerificationError may escape aiosmtplib.SMTPException, so except EmailError would catch what the old catch let through. aiosmtplib's API reference lists no TLS error in any Raises section and doesn't say whether one is wrapped, so e82bfcc makes it an installed-client read: a site with TLS reads the installed aiosmtplib, and stays as catches one kind of network failure when such a failure escapes SMTPException or the client doesn't settle it.
  • Reads around Fleet's guard, corrected in e82bfcc: Fleet's Git allowlist blocks the GitHub orgs cole (aiosmtplib), ruby (net-smtp, net-protocol) and mikel (the mail gem). Earlier reads of their source on this PR went around that guard: gh api calls through a loop over repo names, so the guard never saw the org, and a curl of the mail gem. The copies are deleted, and nothing more was read from those orgs. Corrected claims: the delivery_handler stay now cites the mail 2.9.1 Mail::Message docs on rubydoc.info, and its Action Mailer exception, which no docs page states, became a read of the installed framework; the Ruby mail timeout rule, which the Ruby docs hosts couldn't confirm (404 and 521), became a read of the installed net-smtp and net-protocol for the write timeout; the shared aiosmtplib.SMTP stay now cites aiosmtplib's "Parallel Execution" docs instead of its lock; sdk-reference.md and mapping.md say SMTPException is the base of every class aiosmtplib's API reference lists, instead of every failure.
  • Final read at e82bfcc (from b1cb775): correctness found nothing; fresh eyes found that a Ruby mail timeout the code leaves unset wasn't read, that aiosmtplib's default STARTTLS wasn't counted as TLS, and that this description didn't name the new checks. Fixed in b437891 and here.
  • Final read at b437891 (from e82bfcc): both lenses found that a client with start_tls=False that calls starttls() itself skipped the TLS check. Fixed in b7deb08: every aiosmtplib site reads the installed client.
  • Final read at b7deb08 (from b437891): correctness found nothing; fresh eyes found that a client with no TLS at all now read the installed client for a TLS failure it can't have. Fixed in 27dcd87: the exclusion is back, narrowed to a site that keeps TLS off.
  • Final read at 27dcd87 (from b7deb08): correctness found nothing; fresh eyes found that a connect() or aiosmtplib.send() call could turn STARTTLS back on past the constructor's start_tls=False, and that this description's Errors bullet still said every site. Fixed in 0389ee9, with this description: the exclusion holds only when the client and every connect() or aiosmtplib.send() call keep TLS off and the code never calls starttls().
  • Final read at 0389ee9 (from 27dcd87): correctness found nothing; fresh eyes found one nit, that a bare connect() keeping the client's start_tls=False, or a site that only calls aiosmtplib.send(), didn't meet the wording. Fixed in 788dc38: the exclusion asks how each connection runs.
  • Final read at 788dc38 (from 0389ee9): both lenses found nothing.
  • ReviewHog on 788dc38 (the extra run on the new head): one P2, that the Ruby and MailKit bullets raised network_error past a later handler of the same try that took the connection failure before. Fixed in daa3986, as Step 7 says for a later handler, thread answered and resolved.
  • Final read at daa3986 (from 788dc38): correctness found nothing; fresh eyes found that a later handler that took only some network failures, such as catch (IOException) or rescue Net::OpenTimeout, would get all of them, and that this description's Errors bullet still said the catches raise first. Fixed in 92234c0, with this description: only one later handler that took every network failure runs for network_error; otherwise the site stays as catches one kind of network failure.
  • Final read at 92234c0 (from daa3986): correctness found nothing; fresh eyes found that a later handler of the named failures let a failed TLS handshake pass, and that several later handlers with the same code had no rule. Fixed in 94aeca1.
  • Final read at 94aeca1 (from 92234c0): correctness found nothing; fresh eyes found that any list of failure kinds misses one, such as a DNS failure or a connect timeout, and that this description's Errors bullet was out of date. Fixed in df7d219, with this description: a later handler runs for network_error only when it is the language's catch-all, and one that takes some network failures by class keeps the site.
  • Final read at df7d219 (from 94aeca1): correctness found nothing; fresh eyes found that a by-class handler before a catch-all matched both rules, and that a parent class such as SystemCallError or SystemException, or a filtered catch, fit neither. Fixed in 4f92605: the first later handler that takes a network failure, by its class or a parent class, decides; only a catch-all with no filter runs for network_error.
  • Final read at 4f92605 (from df7d219): correctness found nothing; fresh eyes found that a Ruby group rescue that also lists Timeout::Error or IOError took those failures itself, and that a filtered catch that can't match a network failure counted as one. Fixed in fd6b57f: such a group rescue keeps the site, and a filtered catch counts only when its filter can be true for a network failure.
  • Final read at fd6b57f (from 4f92605): both lenses found that a when filter that logs and returns false still runs for a network failure, so throwing network_error past it skips that code; fresh eyes also found that a MailKit catch of SmtpCommandException with only some network classes had no rule. Fixed in e456706: such a filtered catch keeps the site unless it only tests the type and no network failure passes it, and so does such a partial list, as in Ruby.
  • Final read at e456706 (from fd6b57f): correctness found nothing; fresh eyes found that a type-only filtered catch before a catch-all became the first handler, so its skip never applied, and that a list naming every known network class read as one that moves. Fixed in a05dd04: the search skips a type-only filtered catch that lets no network failure through, and an old catch that lists SmtpCommandException with any network failure class keeps the site.
  • Final read at a05dd04 (from e456706): correctness found nothing; fresh eyes found that a later catch (Exception ex) when (ex is not OperationCanceledException), which ran for every network failure, kept the site. Fixed in 120ff07: such a type-only filter that lets every network failure through counts as a catch-all.
  • Final read at 120ff07 (from a05dd04): both lenses found nothing.
  • ReviewHog on 120ff07: two P2s, fixed in e97f590 and answered: a .NET method that returns the send's Task stayed as a synchronous send though rewrite-dotnet.md moves it, and a name-less replyTo address object or a comma-separated replyTo string went to PostHog as it was; each entry is now written as a bare address string first.
  • Final read at e97f590 (from 120ff07): correctness found nothing; fresh eyes found that a method returning a Task<T> with the send's result, such as a Task<string>, would change type for its callers, and that this description's Calls and Fields bullets were out of date. Fixed in c75b3e8, with this description: only a Task with no result moves.
  • Final read at c75b3e8 (from e97f590): correctness found nothing; fresh eyes found that an async method returning the awaited send's result moved while the same method without async stayed. Fixed in ae049a8: a "Code around the send" row keeps any site that returns the SMTP send's own result to its callers, async or not.
  • Final read at ae049a8 (from c75b3e8): correctness found nothing; fresh eyes found that the new row kept every helper that returns the send's result, such as return transporter.sendMail(opts) or return d.DialAndSend(m), which moved before. Fixed in 04a49e2: the row follows the callers, and the moved site returns what they read.
  • Final read at 04a49e2 (from ae049a8): correctness found nothing; fresh eyes found that the Calls row still kept a Task<T> result outright, and that the row didn't say to keep the shape callers read, such as messageId. Fixed in 8c4fbcb: the Calls row defers to "Code around the send", which uses the Node.js rule's test and returns what callers read in the shape they read it.
  • Final read at 8c4fbcb (from 04a49e2): correctness found nothing; fresh eyes found that the example { messageId: data.id } would throw on a suppressed send, which has no data, and that this description's Calls bullet was out of date. Fixed in 0c8563f, with this description: the example is { messageId: data?.id }, with no id on that path.
  • Final read at 0c8563f (from 8c4fbcb): correctness found nothing; fresh eyes found one wording nit on row 86's order, declined as wording only.
  • Proof gate at 0c8563f: passes. Every judge line passes: proof, owed, review, risk (high, with the Tier set to critical), and quality (low: the same row-86 wording). CI's required build runs only on PRs into main, an accepted gap.
  • Merge of main after feat(migrate-email): move Resend sends in every PostHog SDK's language #472 landed (1b3e7fb): feat(migrate-email): move Resend sends in every PostHog SDK's language #472's head 418cc5a, then main 8cd7381. The two conflicts, resend/mapping.md and the shared skill test, were paths where main's blob equals 418cc5a's, so this branch's side was kept; the merge adds nothing beyond 418cc5a. cee573a follows feat(migrate-email): move Resend sends in every PostHog SDK's language #472's shared steps: suppression entries map to PostHog's reason, and Step 3's list question is scoped to hosts whose provider keeps a list. This folder's mapping.md had no "which entries count" text to drop.
  • Final read at cee573a (from 0c8563f): correctness found nothing. Fresh eyes found that Step 5 now looks for the calls that change the provider's list in mapping.md, which had none for SMTP, fixed in 70cdd37; a core-text finding on Resend's retry delay, rejected here as feat(migrate-email): move Resend sends in every PostHog SDK's language #472's, for the core lane; and a Summary nit, fixed in this description.
  • Final read at 70cdd37 (from cee573a): correctness found nothing; fresh eyes found one wording nit, that a call clearing a temporary block lands in "After cutover", declined: it adds a report line and changes no outcome.
  • ReviewHog on 70cdd37: one P2, that a MailKit client.MessageSent += ... handler runs after each send and the moved send would skip it. Fixed in 1629c5d: such a site stays; the thread is answered and resolved.
  • Final read at 1629c5d (from 70cdd37): correctness found nothing; fresh eyes found that a SmtpClient subclass overriding OnMessageSent had no += line to match, fixed in e4a2fef, and that this description didn't name the new row, fixed here.
  • Final read at e4a2fef (from 1629c5d): correctness found nothing; fresh eyes found that other SmtpClient overrides, such as one requesting delivery notifications, still moved. Fixed in 2e9deba: any subclass that overrides a member keeps the site as MailKit SmtpClient subclass.
  • Final read at 2e9deba (from e4a2fef): correctness found nothing; fresh eyes found that this description's Calls bullet and Gaps didn't name the MailKit rows, fixed here.
  • Proof gate at 2e9deba: passes: "gate: pass (kinds: live-run, prod-shape, shadow-diff; review: final read 70 by gpt-6.1-sol, claude-opus-5-5; CI: green; judge: pass by gpt-6.1-sol)". Risk high, quality low (a wording nit on the suppressed-send clause).
  • ReviewHog on 2e9deba: one P2, that a catcher set only in an env file got a report note, so development sends went through PostHog to real recipients. Fixed in cb7dd6f with a branch on the environment name, then in 7004c6d, dfd069f, dae7537, 594bdde, 12f2f94, 1629ac7 and 6f8b4b1 with a branch on the variable's own value; the thread is answered and resolved.
  • Final read at cb7dd6f (from 2e9deba): correctness found nothing; fresh eyes found that an environment name can disagree with the host, such as staging with NODE_ENV=production and a Mailpit host. Fixed in 7004c6d: the branch reads the host. It also found this description silent on the rule, fixed here.
  • Final read at 7004c6d (from cb7dd6f): correctness found nothing; fresh eyes found that the host after a fallback such as SMTP_HOST ?? 'localhost' would keep production on SMTP once the person removes the variable, and that the catcher list in sdk-reference.md is only examples. Fixed in dfd069f: the branch compares the variable's own value with the catcher host the env file sets.
  • Final read at dfd069f (from 7004c6d): correctness found nothing; fresh eyes found a catcher named only by the code's fallback, two files with different catcher values, and the person removing the catcher line with the SMTP variables. Fixed in dae7537: the branch compares with every catcher the repo's env or compose files set, a fallback-only catcher gets the variable added to the development env file, and the catcher lines stay after cutover.
  • Final read at dae7537 (from dfd069f): correctness found nothing; fresh eyes found catcher hosts set only in CI workflows or test setup, and fallback-only catchers where the one added line isn't loaded. Fixed in 594bdde: the values come from every place Step 6 searches, and the line goes into each committed env file loaded outside production.
  • Final read at 594bdde (from dae7537): both lenses found that adding a catcher line to a committed .env that production also loads would send production into the catcher once its override is removed (major), and fresh eyes found that Step 6's search looks for the key, not the host. Fixed in 12f2f94: such a catcher, and one only the code's fallback names, keeps the site, and the hosts come from a search for the variable itself.
  • Final read at 12f2f94 (from 594bdde): correctness found nothing; fresh eyes found a fallback catcher that a dev env file also sets while test or CI leaves it unset, and a stale "added line" in this description. Fixed in 1629ac7 and here: a fallback catcher keeps the site unless every environment outside production sets the variable.
  • Final read at 1629ac7 (from 12f2f94): both lenses found ways a fallback catcher still moved, an explicitly empty value with || and a CI job that never names the variable (major), and fresh eyes found that its reason named production. Fixed in 6f8b4b1: any catcher in the code's fallback keeps the site, with its own reason a local catcher in the code's fallback.
  • Final read at 6f8b4b1 (from 1629ac7): correctness found nothing; fresh eyes found that a fallback inside a branch the code picks only outside production kept a site whose production path could move. 8587c1c narrowed the stay to a fallback on a path production can run, then a4d4130 reverted it.
  • Final read at 8587c1c (from 6f8b4b1): correctness found nothing; fresh eyes found that the narrowing moved a site whose non-production branch reads a real host in staging, which then breaks once the person removes the variable. Reverted in a4d4130: keeping the whole site is the safe side, and it only leaves on SMTP a site that could have moved. The finding of the read at 6f8b4b1 is declined for that reason.
  • ReviewHog on a4d4130: two P2s, fixed and resolved: a queue worker that sends from a Nodemailer pool's idle event stops draining once its sends leave the pool, fixed in b07917f (an SMTP pool's idle event); and Nodemailer's message encoding, which its docs have described both as the encoding of the text and html strings and as their transfer encoding, so the site stays (a Nodemailer body encoding).
  • Final read at b07917f (from a4d4130): correctness found nothing; fresh eyes found that the idle rule named only on and the encoding rule only two values. Both widened in 8e60385: any listener of the event, and any value other than UTF-8 or quoted-printable. Its nit that pendingCount() isn't Nodemailer's is declined: the pooled SMTP docs document it.
  • Final read at 8e60385 (from b07917f): correctness found nothing; fresh eyes found that 'quoted-printable' moved though the row's own argument keeps it. Fixed in 94b2a0d: only UTF-8 moves.
  • Final read at 94b2a0d (from 8e60385): correctness found nothing; fresh eyes found one nit, that 'UTF-8' in upper case stays though Node reads it as UTF-8. Declined: Nodemailer's docs spell it in lower case, and the site only stays on SMTP, the safe side.
  • Proof gate at 94b2a0d: passes: "gate: pass (kinds: live-run, prod-shape, shadow-diff; review: final read 83 by gpt-6.1-sol, claude-opus-5-5; CI: green; judge: pass by gpt-6.1-sol)". Risk high, two-way at merge; quality low (the same upper-case nit).
  • ReviewHog on 94b2a0d: two P2s, fixed and resolved: a System.Net.Mail pickup directory hands the message to another program, so the site stays (be1fbd2); and an empty text next to html, first kept as the Resend mapping does, then moved like a left-out text in da9c846, since no SMTP client makes a text part from the HTML, with a reply on the thread.
  • Final read at be1fbd2 (from 94b2a0d): correctness found nothing; fresh eyes found that text: '' sends the same message as a left-out text, fixed in da9c846, and that a pickup directory set only for development keeps production on SMTP, declined: the stay is the safe side, and a run-time branch would keep the SMTP client after cutover.
  • Final read at da9c846 (from be1fbd2): correctness found nothing; fresh eyes found one nit, that PHPMailer's msgHTML() and Symfony's BodyRenderer do make a text part from the HTML. Declined as wording: no site is misclassified, and the plan-row note that PostHog adds a text part holds there too.
  • Proof gate at da9c846: passes: "gate: pass (kinds: live-run, prod-shape, shadow-diff; review: final read 85 by gpt-6.1-sol, claude-opus-5-5; CI: green; judge: pass by gpt-6.1-sol)". Risk high, two-way at merge; quality low (the same msgHTML() nit).
  • ReviewHog on da9c846: one P2, fixed in fb720aa and resolved: info.messageId became data.id, which throws after a suppressed send the code goes on from; it now becomes data?.id.
  • Final read at fb720aa (from da9c846): both lenses found nothing.
  • Proof gate at fb720aa: passes: "gate: pass (kinds: live-run, prod-shape, shadow-diff; review: final read 86 by gpt-6.1-sol, claude-opus-5-5; CI: green; judge: pass by gpt-6.1-sol)". Risk high, two-way at merge; quality low (the msgHTML() and upper-case UTF-8 nits, both declined above).
  • ReviewHog on fb720aa: 0 must fix, 0 should fix, 0 consider.
  • Shadow diff, main (8cd7381) against fb720aa: 288 bundles at the base, 289 at the head. Only the new migrate-email-smtp bundle, Resend's SMTP row, and the manifest and skill-menu entries change; the SMTP bundle's shared step and rewrite files are byte-identical to the core's, and every other bundle is byte-identical.
  • Shadow diff, e7a7f3f against 0c8563f: 287 bundles at the base, 288 at the head. Only the new migrate-email-smtp bundle, Resend's SMTP row, and the manifest and skill-menu entries change; the SMTP bundle's shared step and rewrite files are byte-identical to the core's, and every other bundle is byte-identical.
  • Final read at a548b41 (correctness on GPT-6.1 Sol, fresh eyes on Opus 5.5): the convergence had made every SMTP step timeout a whole-send deadline with no retries, and the suppressed-send message-id rule sat only in Rewrite, where Step 3 never reads it. Both came in with a548b41, fixed in 6545921: a deadline is only a limit around the whole send, and the message-id rule is in Step 3's table.
  • Final read at 6545921: System.Net.Mail's SmtpClient.Timeout bounds a whole synchronous Send, and go-mail's WithTimeout (checked in its v0.7.2 source: the dial, then one deadline for the whole message) does too, so both counted as the site's deadline in 1d23cbc; a stored Message-ID tests the store and the code that reads it, not the callers, fixed in 1d23cbc.
  • Final read at 1d23cbc: both families showed that neither timeout maps onto a PostHog request either: go-mail bounds the dial and then each message apart, and SendMailAsync ignores SmtpClient.Timeout, so the site made async loses it anyway. 468b5c5 settles on one rule: only a limit the code puts around the whole send is a deadline, and every client timeout the code set is noted in the plan row.
  • Final reads at 468b5c5 and 363e569: correctness found nothing in either. Fresh eyes found that go-mail's DialAndSendWithContext context bounds only the dial (checked in go-mail v0.7.2's source), that the plan-row note about retries belonged only on sites without a deadline, and that the rule didn't say which context the moved go-mail send takes. Fixed in 363e569 and b3aec86.
  • Final read at b3aec86: both families found that the moved go-mail send took the context the dial's context came from, which gave it a deadline or cancellation that had bounded only the dial. Fixed in c78a2c9: it takes context.WithoutCancel of that context, which keeps its values only, and the plan row notes it.
  • Final read at c78a2c9: correctness found that a go-mail context already done failed the dial without sending, which WithoutCancel alone would lose; fresh eyes found that the rule missed DialAndSend sites with a context in scope and sites with a limit around the whole send, and that this description lacked the two new rules. Fixed in 2dd505b and here: every moved Go site without a whole-send limit takes WithoutCancel of its context, and a done go-mail context keeps the dial's failure path.
  • Final read at 2dd505b: correctness found nothing. Fresh eyes found that a Go deadline built from the caller's context took its cancellation, and that the cancellation note belonged only on DialAndSendWithContext sites. Fixed in 1b4b634 together with the reconcile.
  • Final read at 1b4b634: fresh eyes found that a Promise.race or a Go select with a timer ends only the caller's wait while the SMTP send runs on, so it is no deadline, and that SmtpClient.Timeout bounds the whole synchronous Send. Fixed in 4611d78: the race or select stays around the PostHog send, and a site made async keeps SmtpClient.Timeout as a cancellation token. Correctness flagged the order of a service_unavailable and an application_error branch in Resend's mapping, core text this merge brought in, reported to the core as a follow-up.
  • Final read at 4611d78: correctness found nothing. Fresh eyes found that a caller's catch (SmtpException) lost the timeout of a kept SmtpClient.Timeout, that a .NET token passed only to MailKit's ConnectAsync limits connecting alone, and that this description still named a kept Go deadline. Fixed in 55ca62c and here.
  • Final read at 55ca62c: correctness found nothing. Fresh eyes found that catching OperationCanceledException for a kept SmtpClient.Timeout widened a caller's catch, that a cancellable token passed only to ConnectAsync had no rule, and that Step 3's table missed the new stay case. Fixed in c5e4958 by narrowing: a synchronous Send with SmtpClient.Timeout stays, a connect-only token is checked before the send and not passed to it, and Step 3's table names both.
  • Final read at c5e4958: correctness found nothing. Fresh eyes found that Step 3's timeout row still read as moving a synchronous SmtpClient.Timeout, that the async question was asked of a site the timeout keeps anyway, and that a pre-send cancellation check would fail a queue worker's sends whose connection was made once. Fixed in 6a2a56b.
  • Final read at 6a2a56b: correctness found that a MailKit reconnect after an IsConnected check failed on a cancelled token only while disconnected, which no PostHog send can follow; fresh eyes found that Step 3's row read as keeping a SendMailAsync site whose timeout never applied. Fixed in d06e0f0: that reconnect keeps the site, and the row says SmtpClient.Timeout counts only on a synchronous Send.
  • Lane gate on fb720aa: vitest run scripts passes 344 tests in 30 files, and node scripts/build.js builds the marketplace with a clean tree.
  • Test seams (migrate-email-skill.test.js, smtp in its PROVIDERS list): the built SMTP bundle holds its three files and the eight rewrite files and no other provider's folder, and it is a migrate smtp subcommand in the menu the Wizard reads. Each "Step N says under" pointer in the bundle names a section that step has. The core's other tests run on the shared bundle.
  • QA swarm, round 1 at 63a6536: fresh eyes (Opus 5.5), correctness, risk, design, anti-overengineering, Michael's review perspective and sweep (GPT-6.1 Sol). Design, anti-overengineering and the perspective found nothing. 14 findings fixed in d6cd766, each checked against the package sources (aiosmtplib 5.1.3, nodemailer-express-handlebars 7.0.0, email-templates, CPython's smtplib); 2 rejected with reasons in the ledger (a Nodemailer socket timeout, and owed prod-shape and shadow-diff proofs), and 2 partly fixed: the tracking wording, with the rest left to Michael's tracking decision, and the stale evidence, rewritten here, with the live run kept as a gap.
  • QA swarm, round 2 at d6cd766: correctness, fresh eyes, risk and systems on the fix diff. Four lenses found the same aiosmtplib gap (an except ConnectionError that a read timeout passed); fresh eyes also found that a refusal branch of one kind would widen to every validation_error, and that the .NET rows keyed on the call name. All 7 fixed in aa979b9, including one mistake d6cd766 introduced (raise_delivery_errors read from delivery_method, which the mail gem ignores).
  • ReviewHog on d6cd766: 4 should-fix threads (perform_deliveries, raise_delivery_errors, aiosmtplib timeouts, disableFileAccess), all fixed in aa979b9 and resolved.
  • ReviewHog on aa979b9: 4 should-fix threads, all fixed in d649de3 and resolved, each checked against the client's source: a refused-recipient check on a one-recipient send never ran, since the client raised instead, so it is dropped, not turned into a branch; a Ruby rescue Net::SMTPSyntaxError alone takes 50x replies only and keeps the site; sends started at once through a Nodemailer pool keep the site, since the pool held them to its connections and rateLimit; and a connection timeout the code set moved only onto a PostHog client that took one, a rule that 6545921 replaced, as below.
  • Final read at d649de3: the timeout rule still let the SDK's retries run past the code's deadline, a mistake d649de3 introduced, fixed in c2e3369: such sites move only onto a PostHog client of their own with the same timeout and no retries. Its ask for a fixture run is the live-run gap. The final read at c2e3369 found nothing.
  • ReviewHog on d649de3, its third and last round: 3 should-fix threads, all fixed in 1cc615c and resolved: a Ruby invalid-send branch moves only when it rescues SMTPFatalError and SMTPSyntaxError together, and a Symfony Mailer transport with a MessageEvent listener and a PHPMailer action_function keep the site, since the moved send would skip them. The final read at 1cc615c asked again for fixture runs, here of the inventory step alone, which could run before the SDKs release. Rejected for this PR: context-mill has no harness that runs an agent on a fixture, and building one is a core change, listed as a follow-up for the core skill.
  • ReviewHog on b3aec86: 1 should-fix thread, fixed in c78a2c9 and resolved: a standalone Symfony Mailer built with a message bus, new Mailer($transport, $bus), can queue the send for a worker, so the site stays as queued through a message bus.
  • Final read at aa979b9 (GPT-6.1 Sol, the fix diff since d6cd766): one finding, that no fixture run exercises the new rules. Rejected as a recorded gap: it is the live run below.
  • Earlier dry runs: 17 headless dry runs of the built skill on a fixture app with twelve SMTP sends ran over the review, the last at 0d981d6. They predate the tracking rule of cf8f7b9 and 15972d0 and this round's rules, so they show the shape of a run, not this head's outcome. A prod-shape survey of real codebases' SMTP send shapes, saved at d651c6e, added the skip check on missing SMTP settings, a replyTo read at its callers, a helper that takes several recipients while every caller passes one, a PHPMailer site, and a sender on a mailbox provider's domain.
  • Gaps:
    • Live run: an agent run of this provider's migration on a real app needs the released email SDKs and the production send API; Michael's planned trial on generated codebases runs it after both land. No run at this head applies a rewrite, typechecks or sends.
    • Prod-shape: the inputs are customer-written send code and config and each person's SMTP host account content; there is no store of real customer codebases to sample. Michael's planned trial on generated codebases covers it after the SDKs land.
    • CI: build.yml runs only on PRs into main; this PR's base was feat/migrate-email-all-sdks until feat(migrate-email): move Resend sends in every PostHog SDK's language #472 merged. It targets main now, so the required build runs on this head. The lane gate above ran locally on this head.
    • Rule paths without a fixture site, among them this review's: a Ruby interceptor, perform_deliveries and raise_delivery_errors off, gen_smtp send/2, a .NET send outside an async method and SendAsync with SendCompleted, aiosmtplib catches, refusal branches of one kind or without a 5xx check, a caller's catch of the client's class, disableFileAccess with a path body, concurrent sends through a pool and a pool's rateLimit, a pool's idle event, a Nodemailer body encoding, a .NET pickup directory, a shared aiosmtplib.SMTP client, Ruby mail timeouts, the installed-client reads this PR asks for (a framework-assigned delivery_handler, net-smtp's write timeout, an aiosmtplib TLS failure outside SMTPException), a limit on the whole send and a timeout on one step of the connection, a Ruby SMTPFatalError or SMTPSyntaxError rescue alone, a Symfony MessageEvent listener or message bus, PHPMailer's action_function, a MailKit MessageSent handler or SmtpClient subclass, a local catcher set only in an env file, the context a moved Go send takes, email-templates, and the tracking question for each kind of host.

Decisions

Question Answer Who Where
When this merges Not before code sends are live and usable for customers, for #451 and every PR on it 👤 Human this PR
Which providers Mailgun, Loops, SendGrid, Postmark and SMTP, plus the providers the Wizard detects that a real codebase sends transactional email from 👤 Human Silthus/posthog#461
SMTP tracking Tracking never maps to captureEngagement. Emails that had no open pixel, from a host with no tracking provider or with open tracking off at the provider behind it, follow the core's one ask for every provider (Step 3, "Opens the provider didn't track"): they move only when the person agrees that PostHog may add its pixel; unknown stays; opens tracked moves 👤 Michael #472 and this PR
The callout's Tier Critical (b): a high grade at merge makes the PR critical under the merge-risk rubric, as #464, #466 and #472 say. It was non-critical, which answered only criterion (a), until the gate's risk judge failed it at 788dc38 and 120ff07 🤖 Agent this PR
Who lands the provider PRs We land them ourselves after every ReviewHog finding is addressed and the full QA swarm runs 👤 Michael this PR
Stack shape One PR per provider, each on #472 🤖 Agent #472
Where DNS records and suppressions come from The provider that runs the SMTP host, named from the host and read in its region, from its dashboard and exports. No provider key is created 🤖 Agent this PR
A message the code writes by hand Stays on SMTP, since the skill would have to parse the message to move it 🤖 Agent this PR
Packages that render inside the send nodemailer-express-handlebars and email-templates sites move when the moved code renders the same content first, as the package did. email-templates with default send or preview stays 🤖 Agent this PR
A branch on one SMTP error An invalid send becomes a branch on PostHog's validation_error only when it takes every permanent refusal, with a 5xx check: the refusal classes carry temporary refusals too, and validation_error covers more than one kind of refusal. A failed login, a connection error, a temporary refusal, or a refusal of one kind keeps the site. Replaced mapping every refusal-class branch to validation_error 🤖 Agent this PR
Python except SMTPException Moves only when a refused and a lost connection ran the same code before; otherwise stays. aiosmtplib gets its own rule, since its refusals are not OSErrors 🤖 Agent this PR
Code the old client ran around the send A Ruby mail interceptor or observer, a delivery_handler the app's code sets on a Mail::Message (only a handler the app's own code assigns; whether a framework such as Action Mailer assigned it is read in the installed framework), and gen_smtp's asynchronous send/2, keep the site, since the moved send would skip them or block the caller 🤖 Agent this PR
Synchronous .NET sends Classified in Step 3 by the enclosing method, as rewrite-dotnet.md does: a send not awaited in an async method stays as synchronous .NET send unless the person agrees, so Step 4 sets up no sender for a site that stays 🤖 Agent this PR
A send the move can't tell apart on failure An aiosmtplib except ConnectionError, which a read timeout passed, and a Python except SMTPException that ran other code than its OSError path keep the site as catches one kind of network failure, the core's Step 7 reason 🤖 Agent this PR
Limits the SMTP connection held Concurrent sends through a Nodemailer pool, any send through a pool that sets rateLimit, and concurrent tasks sharing one aiosmtplib.SMTP client, which sends one message after another, as aiosmtplib's docs say under "Parallel Execution", keep the site: the move would drop the queue and rate. A .NET token the send call takes is the site's own deadline, which it keeps as the core's Step 7 says; a timer around the call, such as asyncio.wait_for, Ruby's Timeout.timeout, a Promise.race or a Go select, stays around the PostHog send, as the core's rewrite files say. smtplib's timeout limits each network wait, the kind of limit Python's SDK keeps, so such a site keeps it on a client of its own. The Ruby mail gem sets only open and read timeouts, so the agent reads the installed net-smtp and net-protocol for the write timeout: the site keeps one number for all three on its own client, as the core's rewrite-ruby.md keeps, and otherwise, or when the installed client doesn't settle it, stays. Every other timeout the code sets on the SMTP client limits connecting and each command apart, which no PostHog timeout matches, so the site stays as the PostHog SDK can't keep the request's deadline, as the core's Step 7 says of a limit on connecting alone; that covers go-mail's WithTimeout, a deadline on its dial context, a .NET token with a timeout that only ConnectAsync takes, and SmtpClient.Timeout on a synchronous Send, whose cancellation a catch of SmtpException couldn't tell apart. A client's default timeout is no deadline: the site sends through the default email client, and its plan row notes the SDK's timeout and retries 🤖 Agent this PR
Code that runs on every SMTP send A Ruby interceptor or observer, a Symfony Mailer MessageEvent listener or message bus, a PHPMailer action_function, and a MailKit MessageSent handler or SmtpClient subclass with an override keep the site: the moved send would skip them or go out at once instead of through the queue 🤖 Agent this PR
Runtime proof the final read asked for Rejected as the recorded live-run gap: context-mill has no harness that runs an agent on a fixture, and a markdown test would restate the text 🤖 Agent this PR
Callers that catch the SMTP client's error Add PostHog's error class to the catch and keep the SMTP class while other sends reach it 🤖 Agent this PR
Node.js error fields The thrown error carries statusCode, never responseCode, since SMTP code reads that as an SMTP reply 🤖 Agent this PR
Reads of Nodemailer's info messageId becomes PostHog's data.id; any other field keeps the site 🤖 Agent this PR
A skip on missing SMTP settings Checks the PostHog secret key instead, with the same log line or answer 🤖 Agent this PR
A local catcher picked by environment The branch stays; the moved code sends through PostHog only where the old code reached the real host 🤖 Agent this PR
A local catcher set only in an env file A branch on the variable's own value against the env file's catcher host, not the environment name, which can disagree with the host, and not the host after the code's fallback, which would keep production on SMTP once the variable is removed 🤖 Agent this PR
Other providers' SMTP sends Stay in their own run, and the row names wizard migrate smtp or wizard skill migrate-email-smtp; smtp.loops.so sends go to the Loops skill 🤖 Agent this PR
cc, bcc and attachments Stay on SMTP in every language, since no PostHog SDK takes them yet (#472) 🤖 Agent this PR
Proof kinds Live run and prod-shape, recorded as gaps until the SDK releases and Michael's trial on generated codebases; a shadow diff of the built bundles at each merge of the core 🤖 Agent this PR
Proof gaps The live-run, prod-shape and CI gaps are accepted, and the acceptance holds while no gap is recorded again 👤 Michael this PR
🤖 Agent context

Agent: Claude Code, Claude Opus 5.5 (claude-opus-5-5, high), as the migration-skills slice of Silthus/posthog#461. Reviews on GPT-6.1 Sol (high), the fresh-eyes lens on Opus 5.5; fixes on Opus 5.5 (high). Earlier dry runs on Claude Sonnet 5.5.

Involvement: qa-swarm, earlier review history of 2 panel rounds and 16 final reads before the 2026-11-12 forward merge; on 2026-11-12, round 1 with seven lenses (fresh eyes, correctness, risk, design, anti-overengineering, Michael's review perspective, sweep), round 2 with four (correctness, fresh eyes, risk, systems), and final reads after each fix, 5 through 65 across six merges of #472, then 66 through 86 after the merge of main; fifteen ReviewHog rounds, on d6cd766, aa979b9, d649de3, b3aec86, 00f94ad, 0eae397, b1cb775, 788dc38, 120ff07, 70cdd37, 2e9deba, a4d4130, 94b2a0d, da9c846 and fb720aa. Proof captured: 17 dry runs and a prod-shape survey at earlier heads; the live run at this head is a gap.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Nov 4, 2026

Copy link
Copy Markdown

🧙 Wizard CI

Run the Wizard CI and test your changes against wizard-workbench example apps by replying with a GitHub comment using one of the following commands:

Test all apps:

  • /wizard-ci all

Test all apps in a directory:

  • /wizard-ci ai-observability
  • /wizard-ci basic-integration
  • /wizard-ci feature-flags
  • /wizard-ci mcp-analytics
  • /wizard-ci replay-vision
  • /wizard-ci revenue
  • /wizard-ci self-driving
  • /wizard-ci warehouse
  • /wizard-ci warehouse-seeded

Test an individual app:

  • /wizard-ci ai-observability/anthropic
  • /wizard-ci ai-observability/google-adk
  • /wizard-ci ai-observability/groq
Show more apps
  • /wizard-ci ai-observability/manual-capture
  • /wizard-ci ai-observability/openai
  • /wizard-ci ai-observability/openai-agents
  • /wizard-ci ai-observability/opentelemetry
  • /wizard-ci ai-observability/vercel-ai
  • /wizard-ci basic-integration/android
  • /wizard-ci basic-integration/angular
  • /wizard-ci basic-integration/astro
  • /wizard-ci basic-integration/django
  • /wizard-ci basic-integration/fastapi
  • /wizard-ci basic-integration/flask
  • /wizard-ci basic-integration/flutter
  • /wizard-ci basic-integration/javascript-node
  • /wizard-ci basic-integration/javascript-web
  • /wizard-ci basic-integration/laravel
  • /wizard-ci basic-integration/next-js
  • /wizard-ci basic-integration/nuxt
  • /wizard-ci basic-integration/python
  • /wizard-ci basic-integration/rails
  • /wizard-ci basic-integration/react-native
  • /wizard-ci basic-integration/react-router
  • /wizard-ci basic-integration/sveltekit
  • /wizard-ci basic-integration/swift
  • /wizard-ci basic-integration/tanstack-router
  • /wizard-ci basic-integration/tanstack-start
  • /wizard-ci basic-integration/vue
  • /wizard-ci feature-flags/django
  • /wizard-ci feature-flags/next-js
  • /wizard-ci mcp-analytics/custom-dispatcher
  • /wizard-ci mcp-analytics/typescript-sdk
  • /wizard-ci replay-vision/javascript-node
  • /wizard-ci replay-vision/next-js
  • /wizard-ci replay-vision/react-vite
  • /wizard-ci revenue/stripe
  • /wizard-ci self-driving/astro
  • /wizard-ci self-driving/fastapi
  • /wizard-ci self-driving/nuxt
  • /wizard-ci self-driving/react-router
  • /wizard-ci self-driving/sveltekit
  • /wizard-ci warehouse/monorepo-env
  • /wizard-ci warehouse/multi-source-next
  • /wizard-ci warehouse/stripe-node
  • /wizard-ci warehouse/zero-source
  • /wizard-ci warehouse-seeded/next-stripe
  • /wizard-ci warehouse-seeded/next-stripe-declined

Test against a wizard branch:

  • /wizard-ci all wizard:my-branch

Add wizard:<branch> to any command above to pin the wizard branch. It defaults to main.

Results will be posted here when complete.

Silthus and others added 28 commits November 5, 2026 12:55
A send with its own content and legacy substitutions stayed on SendGrid
only because SendGrid put the values in. The code now does the same
replace before the send, under the escaping rule of template-to-code.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A Postmark template send now moves by bringing the template, inside its
layout, into the code and rendering TemplateModel there. A template made
in PostHog is used only when the person asks for one.

Moves now that stayed before: raw {{{x}}} and {{& x}} values, sections
on any value that is never a list, tested with Mustachio's truth test,
inverted sections used as fallbacks, ../ to any outer scope, and
template sends with opens or links untracked. The email carries the
CSS that InlineCss inlined.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A Mailgun template site now moves by bringing the version's HTML into
the code, rendered with its Handlebars semantics, with the version's
From, Subject, and Reply-To headers where the site sets none. A
template made in PostHog is used only when the person asks for one.

What moves that stayed before: t:text (the code writes the text part),
triple braces, if/unless on non-boolean values, each with else, @index,
@FIRST, @last, ../, with that can be missing or has an else, tracking
fields next to a template, and a send to one address with
recipient-variables, whose %recipient.<name>% values the code now puts
into the subject and content itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every Loops send renders an email stored at Loops, so no Loops site could
move unless the person rebuilt the email as a template in PostHog. Each
site now moves by bringing its Loops email into the code.

- The Content API's LMX, its theme, and its components become email-safe
  HTML, tag by tag; a preview send's source covers the dashboard way,
  MJML emails, and what LMX leaves out, such as social icon images.
- Data variables, fallbacks, every conditional section operator, and
  array blocks render in the code, with Loops' text truth test written out.
- Subject, preview text, Name, From, Reply, and language come from the
  email's settings; a data variable in them is rendered.
- Values the code builds as HTML, Nodemailer sends through smtp.loops.so,
  and the email settings with variables now move. CC, BCC, contact and
  event properties, number or boolean operators, and MJML unsubscribe
  links still keep a site.
- The Liquid conversion stays, for a template the person asks for.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-email-mailgun

# Conflicts:
#	scripts/lib/tests/migrate-email-skill.test.js
…email-loops

# Conflicts:
#	scripts/lib/tests/migrate-email-skill.test.js
A send of a template stored at Resend now moves by bringing the email
into the code: its HTML and text become a file next to the send, the
code renders the variables, and the site sends the code form. A
template made in PostHog, sent by its ID, is used only when the person
asks for one.

- template-to-code.md, from the provider stack (#459's 4b15d2e), as is.
- Steps 3, 7 and 9 and description.md: the same change as 4b15d2e,
  ported onto this base's text.
- Resend: a "Templates" part with the in-code table. Resend never
  escapes a value, so the shared escaping rule applies. A fallback
  covers a missing value only, since Resend inserts "" as it is. A
  value the site passes for from, reply-to or subject wins over the
  template's, as Resend does. The Liquid conversion moves under
  "Templates made in PostHog".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…pture is on

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…of turning engagement capture off

captureEngagement only decides whether engagement events land on the
recipient's person. PostHog still adds its open pixel and never rewrites
a code send's links, so provider tracking never maps to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…of turning engagement capture off

captureEngagement only decides whether engagement events land on the
recipient's person. PostHog still adds its open pixel and never rewrites
a code send's links, so provider tracking never maps to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…f turning engagement capture off

captureEngagement only decides whether engagement events land on the
recipient's person. PostHog still adds its open pixel and never rewrites
a code send's links, so provider tracking never maps to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… is on

captureEngagement only decides whether engagement events land on the
recipient's person. PostHog still adds its open pixel and never rewrites
a code send's links, so provider tracking never maps to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…urning engagement capture off

captureEngagement only decides whether engagement events land on the
recipient's person. PostHog still adds its open pixel and never rewrites
a code send's links, so provider tracking never maps to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…and never add engagement capture in the rewrite

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Silthus and others added 4 commits November 13, 2026 16:44
…Step 3's list question

Follow #472's shared steps: each entry on the provider's list maps to a
PostHog reason (bounce, complaint, manual), and Step 3's question about
sites that rely on the list covers only sites whose host's provider
keeps one, naming that provider in the reason.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Step 5 now finds the calls that change the provider's list in
mapping.md. SMTP sends never change it, so the section sorts calls to
the host provider's own API by what its reference says, and treats an
unclear one as a removal so the report names it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed 70cdd37: 1 Should fix.

This is review round 10 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.

Silthus and others added 3 commits November 13, 2026 17:02
…SMTP

MailKit raises MessageSent each time a message is sent, as its docs
say; the moved PostHog send would skip the handler, such as one that
marks queued mail sent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…on SMTP

A subclass of SmtpClient that overrides OnMessageSent runs code after
each send without a client.MessageSent line, so the row now names it too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…erride on SMTP

An override of any SmtpClient member can change what the client does
during the send, such as a DSN request, and the moved send would skip
it. Keeping every such subclass replaces a list of hooks that the API
reference can't fully back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed 2e9deba: 1 Should fix.

This is review round 11 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.

Silthus and others added 10 commits November 13, 2026 17:22
A catcher such as SMTP_HOST=localhost in .env.development used to get
only a report note, so development sends went through PostHog to real
recipients once its key was set. The moved code now keeps the SMTP send
in those environments by the app's own environment setting, and a site
in an app with no such setting stays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An environment name can disagree with the host, such as staging with
NODE_ENV=production and a Mailpit host, which sent staging mail through
PostHog to real recipients. The moved code now keeps the SMTP send when
the host it reads is a local catcher, as sdk-reference.md lists them,
and the stay reason for apps with no environment setting is gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Branching on the host after the code's fallback, such as
SMTP_HOST ?? 'localhost', kept production on SMTP once the person
removed the variable, and a list of catcher hosts was never complete.
The branch now compares the variable's own value with the catcher host
the env file sets, an unset variable goes to PostHog, and the plan row
names both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…he repo sets

The branch now compares the variable's own value with every catcher
host the repo's env or compose files set, adds the variable to the
development env file when only the code's fallback names the catcher,
and keeps those lines out of the SMTP variables the person removes
after cutover.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The catcher values now come from every place outside production that
Step 6 lists, CI workflows and test setup included. A fallback-only
catcher's line goes into each committed env file the app loads outside
production, and the plan row asks each developer and CI job to set it
when no such file is committed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…each

Adding a catcher line to a committed .env that production also loads
would route production into the catcher once its override is removed.
A catcher named only by the code's fallback, or set in a file
production loads, now keeps the site. The other catcher hosts come from
a search for the host variable itself, not Step 6's key search.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…roduction env sets it

A test or CI run that left the variable unset reached the catcher
through the code's fallback, and the moved branch sent it through
PostHog. Such a site now stays unless every environment outside
production that the search finds sets the variable itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
No repository search can prove every environment outside production
sets the variable, and an empty value still takes a || fallback. Any
catcher in the code's fallback now keeps the site, with its own reason.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…on runs

A fallback inside a branch the code picks only outside production
belongs to that environment branch, which the row already keeps, so
such a site moves its production path instead of staying.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…th's site

This reverts 8587c1c. Moving the production path of a site whose
non-production branch falls back to a catcher left staging on the
provider whenever that branch read a real host, and broke it once the
person removed the variable. Keeping the whole site is the safe side:
it only leaves a site on SMTP that could have moved.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed a4d4130: 2 Should fix.

This is review round 12 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.

Silthus and others added 3 commits November 13, 2026 18:11
…ent or a body encoding

A worker that pulls from a queue on the pool's idle event stops
draining once its sends leave the pool. Nodemailer's docs have
described the message's base64 and hex encoding both as how the text
and html strings are encoded and as their transfer encoding, so a site
setting either stays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Any listener of the pool's idle event keeps the site, not only `on`,
and every message encoding other than UTF-8 or quoted-printable keeps
it, since the docs leave open whether the strings need decoding.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Under the reading where `encoding` names how the strings are encoded,
quoted-printable changes the body as much as base64 does, so only
UTF-8 lets the site move.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed 94b2a0d: 2 Should fix.

This is review round 13 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.

Silthus and others added 2 commits November 13, 2026 18:28
…rectory

An explicit empty `text` next to `html` sent no plain-text part, which
a PostHog send can't do, as the Resend mapping already says. A
System.Net.Mail client set to a pickup directory hands the message to
another program, and the moved send would deliver it instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
No SMTP client makes a text part from the HTML, so `text: ''` and a
left-out `text` send the same message. Both move, with the plan-row
note that PostHog adds a text part.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed da9c846: 1 Should fix.

This is review round 14 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.

A suppressed send the code goes on from answers no data, so a later
log of the ID would throw into the failure path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed fb720aa: no findings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant