Skip to content

feat(migrate-email): attachments for SparkPost - #517

Draft
Silthus wants to merge 32 commits into
feat/migrate-email-sparkpostfrom
feat/migrate-email-sparkpost-attachments
Draft

Silthus wants to merge 32 commits into
feat/migrate-email-sparkpostfrom
feat/migrate-email-sparkpost-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

migrate-email-sparkpost keeps every SparkPost send with attachments or inline images on SparkPost, because PostHog's send didn't take files. #510 taught the shared steps and the Resend variant to move files. This PR maps SparkPost's file fields onto that, so a SparkPost send with an invoice, a receipt, or an inline logo can move too.

Important

Stacked on #468, the SparkPost variant, and merges #510, which brings #486. Until those land and this PR is retargeted to main, the diff includes #486's and #510's shared changes. Only context/skills/migrate-email/references/sparkpost/ is this PR's change. Merge order: #472, the providers, #486, #510, then this one.

Impact

Sends that arrive with migratedFrom: 'sparkpost' and files show whether SparkPost sends with attachments move. Read it 14 days after the release that ships this skill.

Merge risk

Note

🟢 Merge risk: low · two-way door until the next context-mill release ships the skill; one-way per migration once an agent runs it, since its rewrite stays in the app's code
Tier: critical

  • What this diff changes: a SparkPost send with content.attachments or content.inline_images now moves to PostHog by Step 3's "Files" rules, where it stayed before. Separate commits rewrite the SDK claims SparkPost's docs don't back (see "Corrected SDK claims"): where the docs say nothing, the migrating agent reads the SparkPost client installed in the app and decides from it.
  • A wrong mapping would change the files of a moved email, such as an inline image's filename or a file's encoding, in a diff the person reviews. Step 8's check email comes from a site with files, so a project that doesn't take files yet, or a content type with parameters PostHog refuses, puts those sites back.
  • The second failure path is a moved site's error handling or field names, where the agent now reads the installed client instead of this folder and could misread it. Step 8's check email doesn't exercise an error, so only the live run covers it, with the fixtures listed below.
  • Uncovered: a live run of an agent moving a real SparkPost send with files, as for feat(skills): move SparkPost sends to PostHog #468, waits on the released SDKs and the production send API.
  • Switch-off: none. Live with the release; a revert only stops new runs.

Changes

references/sparkpost/mapping.md:

  • The content.attachments and content.inline_images rows move each list to the PostHog send's attachments, by Step 3's "Files" rules, which count both lists together.
  • A new "Attachments" section maps each field:
    • name of an attachment becomes the filename. PostHog refuses a filename with a path, so a name with / or \ keeps only its last part, and a name ending in one keeps the site.
    • name of an inline image becomes the content ID, unchanged, so the HTML's cid: reference still finds it. Its last part after any / or \ also becomes the filename, which PostHog requires and SparkPost never set, with a note in the plan row.
    • Both name rows, and the type row, point to PostHog's header rules in Step 3's "Files" from feat(migrate-email): move a Resend send's attachments to posthog-node #510: a filename of at most 255 characters with no path separator or control character, a content type of at most 78, and a content ID of at most 78 with no <, >, or control character. SparkPost takes a name of up to 255 bytes, so a longer content ID keeps the site.
    • type stays as it is, parameters included. SparkPost's docs ask for a charset parameter where needed, and such a type moves as Step 3 says.
    • data, Base64, becomes the content: the same Base64 string or its decoded bytes, as each rewrite file says.
    • Python's filename path becomes the bytes the code reads from that file. SparkPost's Python library reads and encodes it in the app, so SparkPost fetches nothing.
  • Limits: SparkPost's 20 MB for the whole content fits PostHog's 40 MB after Base64. SparkPost sets no count, so Step 3's 10 files apply. SparkPost forbids .bat and .exe, and PostHog's list in Step 3 is longer.
  • Templates: a transmission with a stored template takes no files, and a stored template holds none, except one stored as a raw RFC 822 message, which stays as the template is a raw MIME message.
  • Rewrite: both lists become one attachments list, attachments first.

references/sparkpost/account.md: the dashboard copy of a template version also asks whether it is stored as a raw RFC 822 message.

Corrected SDK claims

Separate commits recheck every SDK claim in references/sparkpost/ against SparkPost's docs and the SDKs' own docs pages only. #468 lands as it is. Where those pages say nothing, the agent reads the SparkPost client installed in the person's app (node_modules, the virtualenv, vendor, the bundle, the Go module cache, Elixir's deps), decides from it, and names the file it read in the plan row, as Mandrill's #515 does. A site stays only when the installed client doesn't settle it either, with the reason installed SparkPost client doesn't show <the fact>.

  • Error classes. SparkPostError with err.statusCode and err.errors (Node.js), SparkPost::DeliveryException (Ruby), SparkPostException with getCode() and getBody() (PHP), and ResponseException with Response.StatusCode (.NET) are no longer named, and nor are Python's e.status and e.errors. The Python docs name only SparkPostAPIException. The agent reads what the site's handler reads, and the installed client for which property holds the HTTP status and which the API's errors.
  • Network errors. The old text said which SDKs' errors covered a network failure. The docs don't say, so the agent reads the installed client: where it let the HTTP library's error through, network_error goes where Step 7 says; where it gave SparkPost's error, network_error takes the same branch. Unsettled, the site stays.
  • Python EU host. The host is a second positional argument, SparkPost(key, 'https://api.eu.sparkpost.com/api'), as its docs show. base_uri=, sparkpost.EU_API, the Django SPARKPOST_BASE_URI setting, track_initial_opens, and the sparkpost.tornado client are dropped. A keyword the docs don't list is read from the installed package.
  • Elixir error. The docs list SparkPost.Endpoint.Error among the library's exceptions, raised on an errors answer. A rescue of it now moves like a match on it. The claim that it covers network errors, and api_endpoint, are dropped: the installed library settles both.
  • Node.js. The origin and endpoint options, the SDK's handling of cc and bcc, the second argument as query parameters, and client.request and client.post are dropped. The older transmissionBody call and its key renaming are read from the installed client.
  • Ruby. The gem's docs page couldn't be read, and SparkPost's docs have no Ruby sample, so the send_message(to, from, subject, html, ...) argument order, SPARKPOST_API_HOST, and send_payload are dropped. Positional arguments are read from the installed gem.
  • PHP, .NET, Go, Java. PHP's promise and response classes and its 'host' option, .NET's response type, RecipientType, Content.TemplateId, and Client.ApiHost, Java's Maven coordinates and ResourceTransmissions, and the claim that Go's err holds the API's errors are dropped, and read from the installed client where a site needs them. Go's Send signature, Response, SPErrors, Content, Attachment, and TxOptions stay, as its package docs list them.
  • Suppression calls. Node.js's client.suppressionList.* examples became Go's documented client.SuppressionDelete and client.SuppressionUpsert.

Live run fixtures

Only the live run tests the installed-client reads, so its fixture app holds one site for each:

  1. Node.js: a catch that reads the HTTP status and the API's errors from SparkPost's error, and one that branches on 400 or 422.
  2. Node.js: a send wrapped in transmissionBody with camelCase keys, such as substitutionData: { firstName }, rendered by a stored template.
  3. Node.js: a top-level key the API reference doesn't list, other than cc and bcc, and a second argument to send that isn't a callback.
  4. Python: an except SparkPostAPIException that reads the HTTP status, and a keyword the docs don't list, such as track_initial_opens.
  5. Ruby: send_message with positional arguments, and a rescue of SparkPost's error.
  6. PHP: a client that doesn't turn async off, settled with ->wait(), and a catch that reads the status and the body's errors.
  7. Go: a branch on err and on res.HTTP.StatusCode.
  8. .NET: a catch of SparkPost's exception that reads the status, and a property the hub's sample doesn't set, such as a template id on the content.
  9. Elixir: a rescue of SparkPost.Endpoint.Error, and a match on it.
  10. For each language: a handler that named only SparkPost's error, with a network failure, and an EU host set through the client's own option or variable rather than a literal URL.
  11. A client made without a key, which reads a variable of its own.

Sources

  • SparkPost's Transmissions API: the Attachment and Inline Image objects (name, type, data; cid:NAME), the 20 MB content limit, the ban on malicious files, and the "Send a Template" content, which takes only template_id and use_draft_template.
  • SparkPost's Templates API: template content holds from, headers, text, html, and amp_html, or an RFC 822 message.
  • The Python library's transmissions docs: filename in place of data makes the library do the Base64 conversion.
  • SparkPost's developer hub samples for Node.js, Python, PHP, Java, Go, Elixir, and .NET, and the Transmissions API for the EU host and the error answer.
  • The Python library's docs (the EU host, the key variable, send's keywords, its answer, and SparkPostAPIException), the Go package's docs (v0.2.0), and the Elixir library's docs (v0.5.2).
  • Unreachable: the Ruby gem's docs page on rubydoc.info (a 521 error), javadoc.io for Java, and docs.sparkpost.com (a 502 error).
  • SDK source was not read and no package was downloaded: Fleet's Git allowlist blocks gh api for the SparkPost and darrencauthon orgs, and SparkPost/ruby-sparkpost returns 404. The mapping is written against the HTTP fields, which every SDK sends, and claims only the API reference and docs back.

How did you test this code?

  • vitest run scripts: 344 tests pass, including the check that every reference path in the built migrate-email-sparkpost bundle resolves.
  • node scripts/build.js builds every skill.
  • Cross-family review (GPT-6.1 Sol) on the attachment commits only, based on the merge of feat(migrate-email): move a Resend send's attachments to posthog-node #510: round 1 found that an inline image's name can hold a path PostHog refuses as a filename, fixed in 5652ee3; round 2 came back clean. After the merge of feat(migrate-email): move a Resend send's attachments to posthog-node #510's new head (0fbc1c9), rounds 3 to 5 read the header-rule pointers and the SDK claims commit (Fleet bases a round on the last reviewed commit, so round 3 read from 5652ee3): rounds 3 and 4 found that the network-error fallback first widened a SparkPost-only catch, then reraised past later handlers, both fixed by following Step 7; round 5 came back clean. Round 6, on the installed-client reads (a0f4640), came back clean. ec7d3e7 then merges feat(migrate-email): move a Resend send's attachments to posthog-node #510's head 41e37f1, which checks Step 3's header rules on the value the provider's mapping passes: SparkPost's rows already check the filename after taking the part after the last / or \, and the content ID as the image's name unchanged, so no SparkPost text changed. Round 7, a fixes-scope read of that merge from a0f4640, past Fleet's six-round ceiling as a recorded agent decision, came back clean.

🤖 Generated with Claude Code

Silthus and others added 22 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>
Map content.attachments and content.inline_images onto the PostHog
send's attachments: name to filename, an inline image's name to its
content ID and filename, type as it is, and data as Base64 or decoded
bytes per the rewrite file. Python's filename path is read in the app.
A stored template takes no files, except an RFC 822 template, which
stays.

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 7 commits November 13, 2026 07:25
PostHog refuses a filename with a path, and a SparkPost name can hold
one, such as images/logo.png as an inline image's content ID. The
filename becomes the part after the last / or \, the content ID keeps
the whole name, and a name ending in a separator keeps the site.

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>
An inline image's name, kept as the content ID, and the filename taken
from a name keep the header rules Step 3 now lists under "Files": a
SparkPost name can run to 255 bytes, past a content ID's 78 characters.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Recheck every SDK claim in references/sparkpost/ against SparkPost's API
reference, its developer hub samples, and the SDKs' own docs pages
(python-sparkpost on Read the Docs, gosparkpost on pkg.go.dev, the Elixir
library on HexDocs). Claims those pages don't back are dropped or softened:

- Error classes and their properties (Node.js, Ruby, PHP, .NET) are no
  longer named. The skill reads the HTTP status and the API's errors from
  whatever the site's own handler reads.
- Python's EU host is the second positional argument, as its docs show;
  EU_API, the Django base URI setting, track_initial_opens, and the tornado
  client are dropped.
- Elixir's SparkPost.Endpoint.Error is an exception per its docs, so a
  rescue of it moves like a match on it.
- A Node.js transmission wrapped in transmissionBody now stays: no docs
  describe that older SDK's key renaming.
- A Ruby send_message with positional arguments stays unless the site's
  code names each field: the gem's docs couldn't be read.
- Whether an SDK's error covers a network failure is undocumented, so a
  handler that named only SparkPost's error takes network_error and the
  plan row says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A handler that named only SparkPost's error now lets network_error pass,
as Step 7 says, instead of taking it: SparkPost's docs don't say whether
its error covered a network failure, and widening would swallow one.

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>
Silthus and others added 3 commits November 13, 2026 07:57
…does

A reraise inside a handler skips the later handlers of the same try, so
network_error now runs a later handler's code that took network failures,
and is raised or returned past the site only when none did.

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

Where SparkPost's docs and the SDKs' docs pages don't give a fact the
mapping needs, the migrating agent now reads the SparkPost client installed
in the app (node_modules, the virtualenv, vendor, the bundle, the Go module
cache, deps), decides from it, and names the file in the plan row. A site
stays only when the installed client doesn't settle it either.

This replaces the stays the docs-only recheck added: a Node.js
transmissionBody send, a Ruby send_message with positional arguments, a key,
argument, keyword, or property the docs don't list, and a handler that named
only SparkPost's error, for network failures.

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