[Silthus]

💡 Motivation and Context

A mailer integration built on posthog-php, such as the Symfony Mailer transport that stacks on this PR or the Laravel mail driver, can't tell PostHog that it sent an email. Every send looks like a plain posthog-php call, so PostHog can't count framework sends per integration.

emails()->send() now takes one more option, 'integration' => '<name>/<version>', such as laravel/1.4.0. The client checks it against ^[a-z0-9-]{1,40}/[0-9A-Za-z.+-]{1,40}$ and sends it as the X-PostHog-Integration header of that send, on every retry. A bad value fails locally with invalid_integration and sends nothing, not even a file upload. The User-Agent and the analytics client don't change. Apps leave the option out; integrations set it.

Stacked on #292 (merge that first). #292 now carries main itself, and this branch merges #292's head forward, so this PR's diff against #292 is only the integration option.

Seams for reviewers. The same option, with the same pattern and header, lands in posthog-node and posthog-ruby; the server reads the header's name into the send event's client. The Symfony Mailer transport stacked on this PR passes posthog-php-mailer/<version>, and the Laravel driver will pass laravel/<version> through that transport. A break here is a value one of those accepts and this one refuses, or the reverse. The sdk-specs emails spec doesn't cover integration, so nothing here diverges from it. Ticket: https://github.com/PostHog/michaelr-context/issues/42

Impact

Lets PostHog count transactional email sends per framework integration. Watch, from release day: weekly organizations whose transactional email API sends come from a framework integration (the send event's client), broken down by integration. Success: that count rises after the adapter releases, for teams on those frameworks. This PR only adds the marker; the adapters stacked on it set it.

Note

🔵 Merge risk: low · two-way door until the SDK release; the stack's merge to main starts that release and makes integration public API

• Callers that pass integration, in every region: on feat: send cc, bcc and attachments with emails()->send() #292 the send is refused locally as invalid_form; here it carries X-PostHog-Integration on every attempt. Covered by the tests on both forms and on retries, and by the cross-version request diff.
• Callers that pass a malformed integration: refused locally, as before, now as invalid_integration, before any upload or request. Covered by the tests.
• Every other send: the same request as feat: send cc, bcc and attachments with emails()->send() #292, byte for byte, shown by the cross-version request diff.
• Uncovered: PostHog reading the header into the send event's client. The launch train's real send at this head covers it. A miss mislabels attribution only, and the email still sends.
• Switch-off: none. Nothing sends the option until an integration sets it.
• Tier: critical (f: the stack's merge to main starts the SDK release)

💚 How did you test it?

• Red on the base library: the new tests fail because the base refuses integration as an unknown option (invalid_form), 7 tests, 2 errors and 5 failures. After the merge with feat: send cc, bcc and attachments with emails()->send() #292, the invalid-integration case on a send with files failed until the option was checked before the upload.
• Green on this head: the same tests pass with every assertion, none skipped.
• Lane gate on PHP 8.4 in Docker at this head, the CI commands: composer validate --strict, PHPUnit (OK; the skips are the existing environment skips), the compliance adapter tests, PHPCS on the changed files, composer api:check (snapshot up to date: send() takes an array, so its signature is unchanged).
• CI green on this head: PHPUnit on PHP 8.2 to 8.5, the framework jobs, PHPCS, public API, compliance.
• Cross-version: the same send through feat: send cc, bcc and attachments with emails()->send() #292's head and this head with a recording transport. Without the option the request is identical; with it, this head adds only X-PostHog-Integration and feat: send cc, bcc and attachments with emails()->send() #292 refuses the option locally.
• Test seam: Emails::send() with the HTTP transport stubbed, asserting the request's headers and body.
• Live run: owed at this head. It runs in the email launch train, one real send per SDK gate branch to a PostHog inbox, before the merge. An earlier head of this PR passed a real send on US Cloud: PostHog answered 202, the request carried X-PostHog-Integration: posthog-php-mailer/4.20.0, and Emails::get() read it back as delivered.

📝 Checklist

• All commits are signed (see Commit signing)
• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm change to generate a change intent file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Built by Claude Code (Opus 5.5) in a T3 Code stack thread, and taken over in place by a second stack thread that merged #292 and main forward. Hold as a draft: it releases only together with the other SDKs' email send.

Question	Answer	Who	Where
Where does the marker go?	One X-PostHog-Integration header per send, from a per-send option; the User-Agent stays the same	👍 Accepted default	https://github.com/PostHog/michaelr-context/issues/39
What does a bad value do?	Fails locally as invalid_integration with the field integration, like every other bad option, before any upload	🤖 Agent	this PR
How does this branch meet #292 and main?	Merge #292's head forward here, never push #292; #292 now carries main	🤖 Agent	https://github.com/PostHog/michaelr-context/issues/42

Involvement: no grilling for this PR; reviews: one GPT-6.1 Sol round (no findings) and PostHog Review (no findings) on the first head, a qa-swarm panel (round 1 with 10 lenses: no findings in this PR's code, the rest belonging to #292 and handed to its owner) and a clean final read of the #292 merge; proof captured (red, green, lane gate; live run in the launch train).

🤖 Generated with Claude Code

[posthog]

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

See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.

[posthog]

PostHog Review · Standard · reviewed 25bcacd: no findings.

[veria-ai]

PR overview

The PR adds an integration option for naming the sending integration in the email workflow.

One issue remains open in attachment uploads: a malicious uploads API response can direct PUT requests containing attachment bytes and response-selected headers to internal HTTPS services whose certificates the application trusts. HTTPS enforcement and disabled redirects do not constrain the initial destination, leaving a destination-validation gap. No issues have been addressed yet.

Open issues (1)

• Medium: Upload destinations are not constrained — lib/Emails.php:866

Fixed/addressed: 0 · PR risk: 4/10

Reviews

• 25bcacd — 1 new issue

[veria-ai]

Medium: Upload destinations are not constrained

These checks accept any HTTPS upload destination, including loopback/private services; a malicious uploads API response can therefore direct PUTs containing attachment bytes and response-chosen headers to internal endpoints whose certificates the application trusts. As defense in depth, restrict uploads to operator-approved storage hosts and validate the actual resolved connection addresses, with explicit exceptions for private/self-hosted storage; HTTPS and disabled redirects do not constrain the initial destination. (curl.se)