Skip to content

fix(emails): send transactional emails through /api/messaging - #327

Merged
rafaeelaudibert merged 2 commits into
mainfrom
rafa/emails-key-scoped-api
Nov 18, 2026
Merged

rafaeelaudibert merged 2 commits into
mainfrom
rafa/emails-key-scoped-api

Conversation

@rafaeelaudibert

Copy link
Copy Markdown
Member

💡 Motivation and Context

Changes:

Request Old path New path
Send /api/projects/@current/messaging/send/email/ /api/messaging/send/email/
Attachment upload /api/projects/@current/messaging/attachments/uploads/ /api/messaging/attachments/uploads/
Status /api/projects/@current/messaging/emails/{id}/ /api/messaging/emails/{id}/

Warning

This is an outright switch with no fallback. A PostHog instance older than PostHog/posthog#137605 answers 404.

  • The SDK does not call the preferences route, so nothing changes there.
  • The emails spec in sdk-specs still names the @current paths. This PR diverges from it until the spec is updated.

💚 How did you test it?

  • Ran test/EmailsTest.php and test/EmailsClientTest.php with PHPUnit 11 on PHP 8.5 in a composer:2 container: 213 tests pass.
  • phpcs reports no errors.
  • Not run: a send against a live PostHog instance.

📝 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)

  • Written with Claude Code (Claude Opus 5.5, claude-opus-5-5). Skills: writing-pr-descriptions.
  • Patch change intent for posthog-php; pnpm adds the Laravel pin patch.

🤖 Generated with Claude Code

The SDK called the transactional email routes under
/api/projects/@current/, and the @current alias is being removed.
PostHog now serves key-scoped routes that take the project from the
project secret API key, so send, attachment upload and status requests
go to /api/messaging/ instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rafaeelaudibert
rafaeelaudibert requested a review from a team as a code owner November 18, 2026 02:29
@rafaeelaudibert rafaeelaudibert self-assigned this Nov 18, 2026
@veria-ai

veria-ai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

PR overview

No security issues were found in this pull request.

Reviews

@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 32162b5: 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.

Comment thread lib/Emails.php
Comment on lines +44 to +46
private const SEND_PATH = '/api/messaging/send/email/';
private const UPLOADS_PATH = '/api/messaging/attachments/uploads/';
private const STATUS_PATH = '/api/messaging/emails/%s/';

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.

P2 · Preserve compatibility with instances that lack the new routes

On self-hosted instances predating the new backend routes, upgrading this SDK makes previously working send() and get() calls fail with HTTP 404, including attachment uploads. These constants switch every request unconditionally, so the patch release breaks existing integrations without any application change. Retain a fallback for servers lacking the new routes.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Not acting on this one on purpose: the SDKs switch to the key-scoped routes outright, with no fallback to the project path. The routes are live on PostHog Cloud (PostHog/posthog#137605), and keeping the old path would keep the SDKs on the @current alias that this change exists to retire.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

posthog-php-socket Compliance Report

Date: 2026-11-18T17:42:01.877269+00:00
Duration: 118940ms

✅ All Tests Passed!

47/47 tests passed


Capture Tests

✅ 30/30 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields ✅ 31ms
Format Validation.Event Has Uuid ✅ 525ms
Format Validation.Event Has Lib Properties ✅ 528ms
Format Validation.Distinct Id Is String ✅ 527ms
Format Validation.Token Is Present ✅ 527ms
Format Validation.Custom Properties Preserved ✅ 527ms
Format Validation.Event Has Timestamp ✅ 555ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc ✅ 524ms
Retry Behavior.Retries On 503 ✅ 5836ms
Retry Behavior.Does Not Retry On 400 ✅ 2529ms
Retry Behavior.Does Not Retry On 401 ✅ 2531ms
Retry Behavior.Respects Retry After Header ✅ 8534ms
Retry Behavior.Implements Backoff ✅ 16250ms
Retry Behavior.Retries On 500 ✅ 5637ms
Retry Behavior.Retries On 502 ✅ 5635ms
Retry Behavior.Retries On 504 ✅ 5635ms
Retry Behavior.Max Retries Respected ✅ 16251ms
Deduplication.Generates Unique Uuids ✅ 533ms
Deduplication.Preserves Uuid On Retry ✅ 5634ms
Deduplication.Preserves Uuid And Timestamp On Retry ✅ 10845ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 5637ms
Deduplication.No Duplicate Events In Batch ✅ 535ms
Deduplication.Different Events Have Different Uuids ✅ 528ms
Compression.Sends Gzip When Enabled ✅ 527ms
Batch Format.Uses Proper Batch Structure ✅ 530ms
Batch Format.Flush With No Events Sends Nothing ✅ 522ms
Batch Format.Multiple Events Batched Together ✅ 512ms
Error Handling.Does Not Retry On 403 ✅ 2530ms
Error Handling.Does Not Retry On 413 ✅ 2529ms
Error Handling.Retries On 408 ✅ 5633ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 528ms
Request Payload.Flags Request Uses V2 Query Param ✅ 524ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 526ms
Request Payload.Flags Request Omits Authorization Header ✅ 524ms
Request Payload.Token In Flags Body Matches Init ✅ 524ms
Request Payload.Groups Round Trip ✅ 525ms
Request Payload.Groups Default To Empty Object ✅ 524ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 526ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 524ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 524ms
Request Lifecycle.No Flags Request On Init Alone ✅ 519ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 510ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 528ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 528ms
Retry Behavior.Retries Flags On 502 ✅ 627ms
Retry Behavior.Retries Flags On 504 ✅ 628ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 528ms

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

posthog-php-lib_curl Compliance Report

Date: 2026-11-18T17:41:53.234715+00:00
Duration: 119336ms

✅ All Tests Passed!

47/47 tests passed


Capture Tests

✅ 30/30 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields ✅ 31ms
Format Validation.Event Has Uuid ✅ 523ms
Format Validation.Event Has Lib Properties ✅ 530ms
Format Validation.Distinct Id Is String ✅ 525ms
Format Validation.Token Is Present ✅ 528ms
Format Validation.Custom Properties Preserved ✅ 527ms
Format Validation.Event Has Timestamp ✅ 528ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc ✅ 526ms
Retry Behavior.Retries On 503 ✅ 5835ms
Retry Behavior.Does Not Retry On 400 ✅ 2530ms
Retry Behavior.Does Not Retry On 401 ✅ 2529ms
Retry Behavior.Respects Retry After Header ✅ 8537ms
Retry Behavior.Implements Backoff ✅ 16253ms
Retry Behavior.Retries On 500 ✅ 5644ms
Retry Behavior.Retries On 502 ✅ 5637ms
Retry Behavior.Retries On 504 ✅ 5636ms
Retry Behavior.Max Retries Respected ✅ 17045ms
Deduplication.Generates Unique Uuids ✅ 247ms
Deduplication.Preserves Uuid On Retry ✅ 5636ms
Deduplication.Preserves Uuid And Timestamp On Retry ✅ 10845ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 5641ms
Deduplication.No Duplicate Events In Batch ✅ 532ms
Deduplication.Different Events Have Different Uuids ✅ 530ms
Compression.Sends Gzip When Enabled ✅ 526ms
Batch Format.Uses Proper Batch Structure ✅ 527ms
Batch Format.Flush With No Events Sends Nothing ✅ 520ms
Batch Format.Multiple Events Batched Together ✅ 516ms
Error Handling.Does Not Retry On 403 ✅ 2529ms
Error Handling.Does Not Retry On 413 ✅ 2528ms
Error Handling.Retries On 408 ✅ 5633ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 526ms
Request Payload.Flags Request Uses V2 Query Param ✅ 526ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 525ms
Request Payload.Flags Request Omits Authorization Header ✅ 523ms
Request Payload.Token In Flags Body Matches Init ✅ 525ms
Request Payload.Groups Round Trip ✅ 523ms
Request Payload.Groups Default To Empty Object ✅ 523ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 523ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 524ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 524ms
Request Lifecycle.No Flags Request On Init Alone ✅ 520ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 510ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 530ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 526ms
Retry Behavior.Retries Flags On 502 ✅ 628ms
Retry Behavior.Retries Flags On 504 ✅ 624ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 527ms

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

posthog-php-fork_curl Compliance Report

Date: 2026-11-18T17:41:54.803266+00:00
Duration: 118760ms

✅ All Tests Passed!

47/47 tests passed


Capture Tests

✅ 30/30 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields ✅ 41ms
Format Validation.Event Has Uuid ✅ 530ms
Format Validation.Event Has Lib Properties ✅ 533ms
Format Validation.Distinct Id Is String ✅ 533ms
Format Validation.Token Is Present ✅ 533ms
Format Validation.Custom Properties Preserved ✅ 533ms
Format Validation.Event Has Timestamp ✅ 534ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc ✅ 534ms
Retry Behavior.Retries On 503 ✅ 5861ms
Retry Behavior.Does Not Retry On 400 ✅ 2534ms
Retry Behavior.Does Not Retry On 401 ✅ 2535ms
Retry Behavior.Respects Retry After Header ✅ 8552ms
Retry Behavior.Implements Backoff ✅ 16267ms
Retry Behavior.Retries On 500 ✅ 5159ms
Retry Behavior.Retries On 502 ✅ 5649ms
Retry Behavior.Retries On 504 ✅ 5647ms
Retry Behavior.Max Retries Respected ✅ 16284ms
Deduplication.Generates Unique Uuids ✅ 540ms
Deduplication.Preserves Uuid On Retry ✅ 5647ms
Deduplication.Preserves Uuid And Timestamp On Retry ✅ 10865ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 5650ms
Deduplication.No Duplicate Events In Batch ✅ 542ms
Deduplication.Different Events Have Different Uuids ✅ 535ms
Compression.Sends Gzip When Enabled ✅ 535ms
Batch Format.Uses Proper Batch Structure ✅ 532ms
Batch Format.Flush With No Events Sends Nothing ✅ 521ms
Batch Format.Multiple Events Batched Together ✅ 520ms
Error Handling.Does Not Retry On 403 ✅ 2536ms
Error Handling.Does Not Retry On 413 ✅ 2533ms
Error Handling.Retries On 408 ✅ 5651ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 525ms
Request Payload.Flags Request Uses V2 Query Param ✅ 524ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 523ms
Request Payload.Flags Request Omits Authorization Header ✅ 523ms
Request Payload.Token In Flags Body Matches Init ✅ 523ms
Request Payload.Groups Round Trip ✅ 524ms
Request Payload.Groups Default To Empty Object ✅ 523ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 526ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 523ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 524ms
Request Lifecycle.No Flags Request On Init Alone ✅ 519ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 516ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 527ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 525ms
Retry Behavior.Retries Flags On 502 ✅ 628ms
Retry Behavior.Retries Flags On 504 ✅ 627ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 534ms

Comment thread .changeset/easy-toys-deny.md Outdated
"posthog-php": patch
---

Transactional email: send, attachment upload and status requests now use the key-scoped `/api/messaging/` routes instead of `/api/projects/@current/messaging/`. They need a PostHog version with those routes; an older self-hosted instance answers 404.

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.

Note

🤖 Claude Opus 5.5 responding on behalf of Michael

One ask on the changeset: could it name the server this needs? Something like "Needs PostHog Cloud, or a self-hosted build from 2026-11-18 or later; older self-hosted builds answer these calls with 404." I'd keep the patch bump: Cloud users see no change, and a major costs every user an upgrade for a self-hosted edge case.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Added in 793a02a: "Needs PostHog Cloud, or a self-hosted PostHog from 2026-11-18 or later. Older self-hosted versions answer these calls with a 404." Kept the patch bump.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rafaeelaudibert
rafaeelaudibert merged commit fe4d04e into main Nov 18, 2026
34 checks passed
@rafaeelaudibert
rafaeelaudibert deleted the rafa/emails-key-scoped-api branch November 18, 2026 18:21
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.

2 participants