Skip to content

feat(migrate-email): attachments for Postmark - #523

Draft
Silthus wants to merge 27 commits into
feat/migrate-email-postmarkfrom
feat/migrate-email-postmark-attachments
Draft

Silthus wants to merge 27 commits into
feat/migrate-email-postmarkfrom
feat/migrate-email-postmark-attachments

Conversation

@Silthus

@Silthus Silthus commented Nov 13, 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

The Postmark variant of migrate-email (#460) keeps every send that sets Attachments on Postmark, because PostHog's send didn't take files. The PostHog SDKs now send files from code, and #510 teaches the shared steps and the Resend variant to move them. A Postmark send with an invoice, a receipt, or an inline logo can move too.

Some claims in references/postmark/ also rested on SDK packages downloaded from registries, or on SDK source read past Fleet's GitHub org allowlist. This PR grounds each one in Postmark's docs or in the client installed in the person's app.

Impact

Sends that arrive with migratedFrom: 'postmark' and carry files show whether people move Postmark sends with attachments. Read it 14 days after the next context-mill release ships the skill.

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

  • Once released, every person who runs wizard migrate postmark gets it. Sites with files that stayed on Postmark now move when the SDK takes files, and a wrong file mapping could send a file under another name or type, or drop an inline image's content ID. The recheck also changes how the agent maps every Postmark catch: from each class's coverage in the installed client to PostHog's error, by Postmark's documented status and ErrorCode. The Mustachio recheck keeps a template on Postmark wherever the guide doesn't say how a value renders, such as a number or a boolean, so fewer templates move than before.
  • Uncovered: no run applies a rewrite yet. The live run waits for the released email SDKs, and the fixture list below names each case that only a live run tests. Where the installed client doesn't settle a rule, the site stays on Postmark.
  • Unchanged: every file outside references/postmark/ is feat(migrate-email): map provider tracking settings to tracking and sensitive #486's or feat(migrate-email): move a Resend send's attachments to posthog-node #510's, and every other provider bundle.
  • Switch-off: none. A revert only stops new runs.
  • Tier: critical. context-mill keeps no critical-path list; the grade is high and the door turns one-way once agents run the skill, so an agent decides only process on this PR.

What this PR changes

This diff includes #486 and #510 until they land and this PR is retargeted to main. Only context/skills/migrate-email/references/postmark/ is this PR's change, in four commits after the merge of #510:

  • 0d6c56f maps Postmark's Attachments onto PostHog's files (mapping.md "Attachments", the Fields row, and "The fields").
  • c9e5952 grounds the Postmark SDK claims in Postmark's docs or the installed client (mapping.md, sdk-reference.md, account.md), with Postmark's 413 for an email over 10 MB.
  • 97595fc keeps PostHog's upload_quota_exceeded out of the mapped 429 branch, next to quota_limited, as Step 7 says: no retry fixes a used-up upload allowance.
  • 1f67a9d grounds the Mustachio rows in Postmark's template syntax guide and templates API reference (mapping.md "Templates" and "Templates made in PostHog", sdk-reference.md).

The attachments mapping

Postmark PostHog
Name The filename. A file without one stays, as Step 3 says
Content, Base64 The content: the same Base64 where the SDK reads it, the decoded bytes where it takes bytes only
ContentType As it is, parameters included (Step 3's not_mime_type rule). None set: the type from the extension, noted, or the site stays (a file without a content type)
ContentID, such as cid:logo.png The bare content ID, logo.png: a leading cid: and any < > taken off
Disposition None at Postmark: a file is inline when the HTML shows its ContentID, and PostHog shows a file with a content ID inline
A client's own forms: postmarker's tuple, MIMEBase part, file path, and attach_binary, a Ruby Mail::Message's files, other clients' attachment helpers Read the installed client for the Name, Content, ContentType, and ContentID it sends, and map those
A file the client reads from a path The rewrite reads the same file in the app and passes its bytes. Postmark fetches no file, so no site stays for a fetched one

What stays, and why:

  • A site with files that moves to a template made in PostHog: a template in PostHog takes no files (Step 7: the template form takes none).
  • A file form whose fields the installed client doesn't settle: Postmark's handling of <the form> not checked.
  • Everything Step 3 "Files" keeps: more than 10 files, over 40 MB, a refused extension, a header rule broken, an SDK without files.

Limits side by side: Postmark takes up to 10 MB per email after Base64 (status 413 above that) and gives no count limit. PostHog takes up to 40 MB and 10 files. Postmark refuses 31 extensions with 411. PostHog refuses its own list, and takes .bin, .vba, and .wsl, which Postmark refused: where a site could send such a refused email, the plan row notes that it now goes out.

Claims corrected in references/postmark/

Each of these rested on a registry package (npm postmark, PyPI postmark-python and postmarker, the postmark gem, NuGet Postmark) or on ActiveCampaign source, an org Fleet blocks. A new rule in mapping.md, "What Postmark's docs don't give", has the agent read the installed client instead, and name the file in the plan row:

  • The error classes of each SDK, and which statuses and ErrorCodes each covers: Errors now maps Postmark's documented answers (status and ErrorCode, from its API reference) to PostHog's, and a catch takes the answers its class covered in the installed client.
  • Ruby's split of network failures (Postmark::TimeoutError, Postmark::HttpClientError, a connection error raised as it is), Python's TimeoutException, and the network errors past PHP's and .NET's catches.
  • .NET's and PHP's throw on a non-200 answer, before a check of the answer.
  • Timeouts: postmark.js's timeout before and from version 5, postmark-python's timeout, Ruby's open, read, and write timeouts, PHP's constructor argument, .NET's ClientFactory, and each SDK's default. postmarker's timeout stays, from its docs.
  • Retries: postmark-python's retries and its retried 500, and the Ruby gem's max_retries. postmarker's max_retries stays, from its docs.
  • Tracking values a client sends: Go's dropped TrackOpens: false, PHP's model default, .NET's TrackLinks default, and PHP's template model InlineCss. postmarker's TrackLinks="None" stays, from its reference.
  • Method and field names that only the source gave: batch, template, Mail::Message, and suppression methods, the sync Python client, PHP's and .NET's argument orders, Go's struct, Node's callback, and the answer's field names. Names on Postmark's "Official libraries" page and in postmarker's docs stay, and the rest go by API route.
  • The stream a suppression call uses when it names none, in PHP and .NET.
  • postmark.django.EmailBackend from postmark-python[django].
  • The Mustachio rows, from ActiveCampaign's mustachio source (read on 2026-11-12, before Fleet first refused the org). Rows Postmark's template syntax guide backs now cite it: escaping, a missing or null value, sections and the values they skip, inverted sections, each over a list, and ../ one level up in the model, two out of an each item. Where the guide says nothing, the template stays on Postmark: how a number, a boolean, a list, or an object prints (the source said True and False), a value in the subject or text that HTML encodes (the source said no escaping there), a section on a number or an empty object, {{.}} inside an each, a ../ in a dotted section or past the top, names inside an inverted section, and comments. Line breaks around a tag in the text are kept and noted for a test send, where the source said Mustachio keeps them.

The ReviewHog entry on 43318e5 in #460's description cites postmark-python 0.5.0 and the gem 1.25.1, which came from registries. This PR replaces that retry claim with the installed-client read, and #460's description now says so.

Sources

  • Postmark: the email API reference, "Sending email with API" (Attachments, Limitations, Inline image attachments, tracking), the API overview (HTTP response codes and API error codes), and "Official libraries".
  • Postmark's templates: the template syntax guide, "Mustachio Templating in Postmark", and the templates API reference.
  • postmarker's docs on Read the Docs: "Emails" (attachments, inline images, CSS inlining), "Usage" (timeout, max_retries), and the API reference (send defaults).
  • PostHog: the shared steps and rewrite files from feat(migrate-email): move a Resend send's attachments to posthog-node #510.
  • Blocked by Fleet's GitHub org allowlist, so not read for this PR: ActiveCampaign (postmark.js, postmark-python, the postmark gem, postmark-php, postmark-dotnet), Stranger6667 (postmarker's source), mrz1836 and keighl (the Go packages). ActiveCampaign also holds mustachio. This PR cites no registry package.

Live run fixtures

Only a live run tests the agent's read of the installed client. Each case below needs a fixture:

  • postmarker files as a tuple with a cid: content ID, a MIMEBase part with Content-ID: <...>, a file path with no content type, and attach_binary.
  • A Ruby Mail::Message with a file and an inline image, sent through the postmark gem.
  • A PHP attachment built by the client's helper from a path, a .NET AddAttachment with a cid: content ID, and a Node.js attachment built with the library's class.
  • A narrow catch in each SDK: one class for an inactive recipient, one for 300, one for a rate limit, and a base class that network errors go past.
  • An answer the client can't parse, such as a proxy's HTML 502, behind a narrow catch.
  • A timeout set on each client, and a client with retries.
  • A Go send with TrackOpens: false, a PHP model send, a .NET message without TrackLinks, and a PHP template model with InlineCss off.
  • A Node.js send with a callback that also awaits the promise.
  • A suppression call that names no stream.
  • A template with a section alone on its text line, to compare the text a test send shows.
  • Plan-stage cases that need no released SDK, each expected to stay on Postmark with its send unchanged: a template with a number or a boolean in {{name}}, a subject value that holds & or a quote, {{.}} inside an each, a ../ in a dotted section, and a name inside an inverted section.
  • PHP and .NET sends that take their fields as arguments.

How did you test this code?

  • The lane gate on 1f67a9d: vitest run scripts (344 tests pass) and node scripts/build.js (exit 0), with a clean tree.
  • Each mapping claim was checked against the pages listed under "Sources".

🤖 Generated with Claude Code

Silthus and others added 25 commits November 9, 2026 12:29
…opens_and_clicks

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

PostHog never tracks clicks on a code send, so click tracking that is off needs nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Replace track_opens_and_clicks with tracking in the rewrite step and
every SDK's rewrite file. A provider's open tracking that is off turns
off the opens switch only, so engagement events stay on. The skill
never turns on click tracking, because a link can carry a token, and
it notes sites whose provider tracked clicks for the report.

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

Use the Go, Rust and .NET names for tracking. A site that moves to a
template made in PostHog sends no tracking, because the template uses
its own setting, so the report asks the person to check it.

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

A code send takes an optional sensitive flag, and its clicks follow it
unless tracking sets them. The skill marks a send sensitive when the old
call turned off click tracking for that email or marked it sensitive. It
never marks a send as not sensitive, and drops the claim that clicks are
always off by default for code sends.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A code send that leaves sensitive out takes the setting of a PostHog
template with the same key. The skill can't see the project's templates
or tell whether a link carries a token, so a key that matched a template
without protection would start rewriting a reset link. Pin the flag on
every code send, and say so in the report.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ack-opens-and-clicks

Keeps the base's error-handling rules, setup and write-down additions,
and Elixir's named-instance send, with this branch's tracking and
sensitive rules on top. Step 7 now turns opens off from the plan note
instead of waiting for the person's yes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A site whose emails had no open pixel, or whose provider's open tracking
nobody can confirm, now moves with the opens switch off instead of
staying or waiting for the person's yes. The plan notes it as opens off
with its reason, and the report lists those sites, the clicks PostHog no
longer counts, and that every code send is marked sensitive.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resend's attachments map to the send's attachments in posthog-node:
filename, content, content type and inline content ID. A file with a
path, no filename, a refused extension, or more than 10 files keeps the
site on Resend, as do sites outside JavaScript and TypeScript. Step 8
sends an email with files when a moved site has them, and puts those
sites back when PostHog doesn't take files from the project yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Step 3 decides when a site with files stays, whatever the provider, and
lists every extension PostHog refuses. Resend's mapping keeps only its
own file fields. The report says what would let a staying site move.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nd-clicks' into feat/migrate-email-resend-attachments

# Conflicts:
#	context/skills/migrate-email/references/9-report.md
#	context/skills/migrate-email/references/resend/mapping.md
Step 7 says what every SDK's code send does with files: the 10-file and
40 MB limits, the upload before the send, and its errors. Each rewrite
file names its SDK's field and the form its content takes, since some
take only bytes and some read any text string as Base64. The bundled
api.md may still call attachments unavailable, so the steps win for
files.

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

A provider with no suppression list of its own, such as a mailbox
provider behind an SMTP host, has no list that grows while sites stay.
Step 5 writes that into the plan, and the report then leaves out the
weekly re-import ask.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A run of migrate-email-resend on an app with a calendar invite showed
where the steps fell short. They now cover:

- preflight when the MCP sees another project, or the app already
  sends code emails
- a PostHog key under the app's own name, or in the hosting platform's
  environment
- code and docs around the sends: provider-key switches, counts and
  limits, promises in legal docs and specs, and the app's own PostHog
  sends, whose engagement setting moved sends follow
- a send moved into a runtime the SDK runs in, such as a Convex
  "use node" action
- a deadline that now limits each request of a send with files
- an idempotency key built from a hash of the request body
- tests of sends with files: the upload requests, and hashing under a
  faked clock

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- preflight: an app that already sends code emails wins over an MCP
  that can't see the project; suppressions never import into another
  project
- Step 3 reads the rewrite file's send for the files check, and counts
  the release Step 7 would install
- the email client splits a shared config function, and goes in the
  file of the runtime the send runs in
- one template key for a site that sends several kinds of email
- a used-up quota that the old code retried as a 429 is noted
- tests: answer at once under a faked clock, answer the app's own
  PostHog capture, assert on the added fields, and keep the Node digest
  stub in a setup file outside Convex's folder
- the report's notes placeholder closes where it should

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…pp's own distinct ID helper

Also reads Step 5's MCP check from what Step 2 found, not what it recorded.

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

Run 4 worked around both by hand within Step 8.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ce PostHog takes them

The real send on prod-eu refused `text/calendar; charset=utf-8;
method=REQUEST` with `not_mime_type`: PostHog takes a bare type only.
Taking `method` out makes a mail app show a calendar invite as a file.
Step 3 marks such a site, Step 8's check email decides, and a refusal
puts the site back on the provider rather than stripping the
parameters.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nt ID in Step 3

A filename takes at most 255 characters and no path separator or control
character (unsafe_filename), a content type at most 78 characters, and a
content ID at most 78 characters and no angle bracket or control character
(unsafe_content_id), as code_send_fields.py on PostHog's master refuses them.
A site whose value breaks one stays on its provider with a reason, so each
provider's attachments follow-up points here instead of restating them.

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

Run 5 (Steps 1 to 3 on a fixture with three Resend sends with files) held
a user-built filename and passed a fixed one, as the header rules mean, but
also held `contentId: "<logo>"`, which Resend's mapping already turns into
the bare `logo` the HTML shows. The rules now hold for the value the send
passes after the mapping. The re-run moved that site and still held the
user-built filename. Each file of a moving site now goes in the plan row's
content cell, where both runs had to guess.

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

Claims about client error classes, defaults, timeouts, retries and method
names rested on packages read from registries or on SDK source read past
Fleet's org allowlist. Each now cites Postmark's API reference, its guides,
its Official libraries page, or postmarker's own docs, or tells the
migrating agent to read the client installed in the person's app.

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

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/go-sdk
  • /wizard-ci mcp-analytics/python-sdk
  • /wizard-ci mcp-analytics/ruby-sdk
  • /wizard-ci mcp-analytics/rust-sdk
  • /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 2 commits November 13, 2026 15:54
… branch

PostHog answers a used-up upload allowance with 429 and
upload_quota_exceeded, which no retry fixes. Step 7 sends it down the
path of every other error, so the 429 mapping and its Node, Python and
raw HTTP examples now skip it next to quota_limited.

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

The Mustachio rows rested on ActiveCampaign's mustachio source, an org
Fleet blocks. Each row now cites Postmark's template syntax guide or its
templates API reference, and what neither settles keeps the template on
Postmark: how a number, boolean, list, or object prints, a value that can
be encoded in the subject or text, a section on a number or an empty
object, {{.}} inside an each, ../ in a dotted section or past the top,
names inside an inverted section, and comments. A tag alone on its text
line keeps its lines, noted for a test send.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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