From 6a15562f526d63a1979ce554fd18ee9be4930251 Mon Sep 17 00:00:00 2001 From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com> Date: Mon, 9 Nov 2026 12:31:23 +0000 Subject: [PATCH 1/5] feat(emails): let a code send turn off open and click tracking A send with template_key takes track_opens_and_clicks. With false, PostHog sends the email without its open pixel or click-counting links. The client sends the field only when the caller sets it, so a default send keeps today's request body. Co-Authored-By: Claude Opus 5.5 --- .changeset/emails-track-opens-and-clicks.md | 5 +++ README.md | 2 +- lib/Emails.php | 33 +++++++++++++++--- test/EmailsTest.php | 38 +++++++++++++++++++++ 4 files changed, 73 insertions(+), 5 deletions(-) create mode 100644 .changeset/emails-track-opens-and-clicks.md diff --git a/.changeset/emails-track-opens-and-clicks.md b/.changeset/emails-track-opens-and-clicks.md new file mode 100644 index 00000000..1a796917 --- /dev/null +++ b/.changeset/emails-track-opens-and-clicks.md @@ -0,0 +1,5 @@ +--- +"posthog-php": minor +--- + +A send with your own content (`template_key`) takes `'track_opens_and_clicks' => false` to send the email without open and click tracking: no open pixel, and no links rewritten to count clicks. PostHog then can't count that email's opens and clicks. It defaults to `true` and is independent of `capture_engagement`, which decides whether engagement events are captured on the recipient's person. The client sends the field only when you set it. It needs PostHog's API support for the field, which is rolling out. diff --git a/README.md b/README.md index b5a79d4d..68a79ba0 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ PostHog::emails()->send([ $status = PostHog::emails()->get($result->getId()); // queued, sent, delivered, bounced, ... ``` -- **Two forms.** Pass `template_id` with optional `template_data`, or `template_key` with `subject` and `html`, `text` or both. The content form also takes `from` (a verified sender), `reply_to` and `capture_engagement` (default `true`). PostHog derives a missing `text` from the `html`. To send an email built with a template library such as React Email, render it to HTML in your app and pass `html`. The SDK adds no rendering dependency. +- **Two forms.** Pass `template_id` with optional `template_data`, or `template_key` with `subject` and `html`, `text` or both. The content form also takes `from` (a verified sender), `reply_to`, `capture_engagement` (default `true`) and `track_opens_and_clicks` (default `true`). `track_opens_and_clicks` decides whether the email carries PostHog's open pixel and links rewritten to count clicks. With `false`, the email goes out without either, so PostHog can't count its opens and clicks. It is independent of `capture_engagement`, which decides whether engagement events are captured on the recipient's person. PostHog derives a missing `text` from the `html`. To send an email built with a template library such as React Email, render it to HTML in your app and pass `html`. The SDK adds no rendering dependency. - **Pass `distinct_id`.** Without it, the email's engagement events go to a person whose distinct ID is the email address. - **A result means queued**, not delivered. `send()` returns a `SendEmailResult` with the message ID. `get()` reads the status for 30 days after the send. For a few seconds after the send, it throws `not_found`. - **Errors.** A send that is not queued throws `PostHog\EmailError`. Branch on `getErrorCode()`, such as `recipient_suppressed` or `missing_app_host`, or on `getErrorName()`, such as `validation_error`. An invalid argument throws before any request, with an `invalid_*` code. diff --git a/lib/Emails.php b/lib/Emails.php index 28fad04b..7dc1281f 100644 --- a/lib/Emails.php +++ b/lib/Emails.php @@ -56,7 +56,16 @@ final class Emails private const SHARED_FIELDS = ['to', 'distinct_id', 'idempotency_key', 'max_retries']; private const TEMPLATE_FIELDS = ['template_id', 'template_data']; - private const CODE_FIELDS = ['template_key', 'subject', 'html', 'text', 'from', 'reply_to', 'capture_engagement']; + private const CODE_FIELDS = [ + 'template_key', + 'subject', + 'html', + 'text', + 'from', + 'reply_to', + 'capture_engagement', + 'track_opens_and_clicks', + ]; private const TEMPLATE_FORM_WHY = "A template made in PostHog sets its own sender, subject and content, " . "and follows the project's engagement setting."; private const CODE_FORM_WHY = 'A send with template_key takes its content from your code.'; @@ -133,8 +142,13 @@ public function __construct( * 400), `subject`, and `html`, `text` or both. PostHog derives a missing `text` from the `html`, and * sends the content as is without storing it. To send a React email, render it to HTML in your app * first. This form also takes `from` (a verified sender, such as `Acme `), - * `reply_to` (one address or a list; an empty list is left out) and `capture_engagement` (default - * true; a project whose admin turned engagement capture off captures nothing, whatever the send asks). + * `reply_to` (one address or a list; an empty list is left out), `capture_engagement` (default + * true; a project whose admin turned engagement capture off captures nothing, whatever the send asks) + * and `track_opens_and_clicks` (default true). `track_opens_and_clicks` decides whether the email carries + * PostHog's open pixel and links rewritten to count clicks. With false, it goes out without either, so + * PostHog can't count its opens and clicks. The client sends it only when you set it, because a PostHog + * version that predates the field refuses it. It is independent of `capture_engagement`, which decides + * whether engagement events are captured on the recipient's person. * * Both forms take `to` (one address), `distinct_id` (the recipient's distinct ID in your product; * without it, the email's events go to a person whose distinct ID is the address), `idempotency_key` @@ -176,7 +190,8 @@ public function __construct( * text?: string|null, * from?: string|null, * reply_to?: string|list|null, - * capture_engagement?: bool|null + * capture_engagement?: bool|null, + * track_opens_and_clicks?: bool|null * } $email * @return SendEmailResult The queued email. It means PostHog queued the email, not that it was delivered. * @throws EmailError PostHog did not queue the email, or the client could not tell whether it did. A @@ -361,6 +376,16 @@ private static function codeContent(array $email): array throw self::invalid('invalid_form', 'capture_engagement must be true or false.', 'capture_engagement'); } $content['capture_engagement'] = $captureEngagement; + if (array_key_exists('track_opens_and_clicks', $email)) { + if (!is_bool($email['track_opens_and_clicks'])) { + throw self::invalid( + 'invalid_form', + 'track_opens_and_clicks must be true or false.', + 'track_opens_and_clicks' + ); + } + $content['track_opens_and_clicks'] = $email['track_opens_and_clicks']; + } return $content; } diff --git a/test/EmailsTest.php b/test/EmailsTest.php index 6cd0e548..cdf20210 100644 --- a/test/EmailsTest.php +++ b/test/EmailsTest.php @@ -205,6 +205,34 @@ public function testCodeSendKeepsAReplyToListAndCaptureEngagementOff(): void ], $this->body()); } + #[DataProvider('trackOpensAndClicksCases')] + public function testCodeSendPassesTrackOpensAndClicksOnlyWhenSet(?bool $track, array $expected): void + { + $this->emails()->send([ + 'to' => 'user@example.com', + 'template_key' => 'welcome', + 'subject' => 'Welcome', + 'html' => '

Hi

', + 'track_opens_and_clicks' => $track, + ]); + + $this->assertSame([ + 'template_key' => 'welcome', + 'subject' => 'Welcome', + 'html' => '

Hi

', + 'capture_engagement' => true, + ] + $expected + ['to' => 'user@example.com'], $this->body()); + } + + public static function trackOpensAndClicksCases(): array + { + return [ + 'false' => [false, ['track_opens_and_clicks' => false]], + 'true' => [true, ['track_opens_and_clicks' => true]], + 'unset' => [null, []], + ]; + } + public function testNullOptionsAndAnEmptyReplyToCountAsLeftOut(): void { $this->emails()->send([ @@ -327,6 +355,11 @@ public static function argumentErrors(): array 'invalid_form', 'capture_engagement', ], + 'track_opens_and_clicks with a template' => [ + $template + ['track_opens_and_clicks' => false], + 'invalid_form', + 'track_opens_and_clicks', + ], 'unknown option' => [$template + ['cc' => 'boss@example.com'], 'invalid_form', 'cc'], 'template_data with code' => [$code + ['template_data' => ['a' => 1]], 'invalid_form', 'template_data'], 'bad template key' => [['template_key' => 'pass word'] + $code, 'invalid_template_key', 'template_key'], @@ -347,6 +380,11 @@ public static function argumentErrors(): array 'invalid_form', 'capture_engagement', ], + 'track_opens_and_clicks not a bool' => [ + $code + ['track_opens_and_clicks' => 'no'], + 'invalid_form', + 'track_opens_and_clicks', + ], 'idempotency key with a space' => [ $template + ['idempotency_key' => 'welcome user'], 'invalid_idempotency_key', From 90fb70de8bf18b60288cb046d073e74ea35ea804 Mon Sep 17 00:00:00 2001 From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com> Date: Mon, 9 Nov 2026 13:06:14 +0000 Subject: [PATCH 2/5] docs(emails): say track_opens_and_clicks removes only the open pixel PostHog never rewrites the links of an email sent from code, so its clicks go uncounted whatever the field says. With false, the email goes out without PostHog's open pixel. Co-Authored-By: Claude Opus 5.5 --- .changeset/emails-track-opens-and-clicks.md | 2 +- README.md | 2 +- lib/Emails.php | 11 ++++++----- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/.changeset/emails-track-opens-and-clicks.md b/.changeset/emails-track-opens-and-clicks.md index 1a796917..a7b2ca25 100644 --- a/.changeset/emails-track-opens-and-clicks.md +++ b/.changeset/emails-track-opens-and-clicks.md @@ -2,4 +2,4 @@ "posthog-php": minor --- -A send with your own content (`template_key`) takes `'track_opens_and_clicks' => false` to send the email without open and click tracking: no open pixel, and no links rewritten to count clicks. PostHog then can't count that email's opens and clicks. It defaults to `true` and is independent of `capture_engagement`, which decides whether engagement events are captured on the recipient's person. The client sends the field only when you set it. It needs PostHog's API support for the field, which is rolling out. +A send with your own content (`template_key`) takes `'track_opens_and_clicks' => false` to send the email without PostHog's open pixel, so PostHog can't count its opens. PostHog doesn't track clicks on emails sent from code, so their links are never rewritten either way. It defaults to `true` and is independent of `capture_engagement`, which decides whether engagement events are captured on the recipient's person. The client sends the field only when you set it. It needs PostHog's API support for the field, which is rolling out. diff --git a/README.md b/README.md index 68a79ba0..692d6ba3 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ PostHog::emails()->send([ $status = PostHog::emails()->get($result->getId()); // queued, sent, delivered, bounced, ... ``` -- **Two forms.** Pass `template_id` with optional `template_data`, or `template_key` with `subject` and `html`, `text` or both. The content form also takes `from` (a verified sender), `reply_to`, `capture_engagement` (default `true`) and `track_opens_and_clicks` (default `true`). `track_opens_and_clicks` decides whether the email carries PostHog's open pixel and links rewritten to count clicks. With `false`, the email goes out without either, so PostHog can't count its opens and clicks. It is independent of `capture_engagement`, which decides whether engagement events are captured on the recipient's person. PostHog derives a missing `text` from the `html`. To send an email built with a template library such as React Email, render it to HTML in your app and pass `html`. The SDK adds no rendering dependency. +- **Two forms.** Pass `template_id` with optional `template_data`, or `template_key` with `subject` and `html`, `text` or both. The content form also takes `from` (a verified sender), `reply_to`, `capture_engagement` (default `true`) and `track_opens_and_clicks` (default `true`). `track_opens_and_clicks` decides whether PostHog tracks opens and clicks of the email. With `false`, the email goes out without PostHog's open pixel, so PostHog can't count its opens. PostHog doesn't track clicks on emails sent from code, so their links are never rewritten either way. It is independent of `capture_engagement`, which decides whether engagement events are captured on the recipient's person. PostHog derives a missing `text` from the `html`. To send an email built with a template library such as React Email, render it to HTML in your app and pass `html`. The SDK adds no rendering dependency. - **Pass `distinct_id`.** Without it, the email's engagement events go to a person whose distinct ID is the email address. - **A result means queued**, not delivered. `send()` returns a `SendEmailResult` with the message ID. `get()` reads the status for 30 days after the send. For a few seconds after the send, it throws `not_found`. - **Errors.** A send that is not queued throws `PostHog\EmailError`. Branch on `getErrorCode()`, such as `recipient_suppressed` or `missing_app_host`, or on `getErrorName()`, such as `validation_error`. An invalid argument throws before any request, with an `invalid_*` code. diff --git a/lib/Emails.php b/lib/Emails.php index 7dc1281f..b14dc3f0 100644 --- a/lib/Emails.php +++ b/lib/Emails.php @@ -144,11 +144,12 @@ public function __construct( * first. This form also takes `from` (a verified sender, such as `Acme `), * `reply_to` (one address or a list; an empty list is left out), `capture_engagement` (default * true; a project whose admin turned engagement capture off captures nothing, whatever the send asks) - * and `track_opens_and_clicks` (default true). `track_opens_and_clicks` decides whether the email carries - * PostHog's open pixel and links rewritten to count clicks. With false, it goes out without either, so - * PostHog can't count its opens and clicks. The client sends it only when you set it, because a PostHog - * version that predates the field refuses it. It is independent of `capture_engagement`, which decides - * whether engagement events are captured on the recipient's person. + * and `track_opens_and_clicks` (default true), whether PostHog tracks opens and clicks of the email. + * With false, the email goes out without PostHog's open pixel, so PostHog can't count its opens. + * PostHog doesn't track clicks on emails sent from code, so their links are never rewritten either way. + * The client sends `track_opens_and_clicks` only when you set it, because a PostHog version that + * predates the field refuses it. It is independent of `capture_engagement`, which decides whether + * engagement events are captured on the recipient's person. * * Both forms take `to` (one address), `distinct_id` (the recipient's distinct ID in your product; * without it, the email's events go to a person whose distinct ID is the address), `idempotency_key` From 32a145142bfaf6e44c7f5b24cfdb53970b097198 Mon Sep 17 00:00:00 2001 From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com> Date: Tue, 10 Nov 2026 08:20:41 +0000 Subject: [PATCH 3/5] feat(emails): let a code send choose its tracking Replace track_opens_and_clicks with tracking: true, false, or opens, clicks and engagement one by one. It is left out of the request when unset. capture_engagement is deprecated in favor of tracking's engagement and keeps working; the client leaves it out when tracking is set, unless the caller sets it too. Co-Authored-By: Claude Opus 5.5 --- .changeset/emails-track-opens-and-clicks.md | 5 -- .changeset/emails-tracking.md | 5 ++ README.md | 3 +- lib/Emails.php | 74 ++++++++++++++------- test/EmailsTest.php | 50 +++++++------- 5 files changed, 83 insertions(+), 54 deletions(-) delete mode 100644 .changeset/emails-track-opens-and-clicks.md create mode 100644 .changeset/emails-tracking.md diff --git a/.changeset/emails-track-opens-and-clicks.md b/.changeset/emails-track-opens-and-clicks.md deleted file mode 100644 index a7b2ca25..00000000 --- a/.changeset/emails-track-opens-and-clicks.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"posthog-php": minor ---- - -A send with your own content (`template_key`) takes `'track_opens_and_clicks' => false` to send the email without PostHog's open pixel, so PostHog can't count its opens. PostHog doesn't track clicks on emails sent from code, so their links are never rewritten either way. It defaults to `true` and is independent of `capture_engagement`, which decides whether engagement events are captured on the recipient's person. The client sends the field only when you set it. It needs PostHog's API support for the field, which is rolling out. diff --git a/.changeset/emails-tracking.md b/.changeset/emails-tracking.md new file mode 100644 index 00000000..7d87b223 --- /dev/null +++ b/.changeset/emails-tracking.md @@ -0,0 +1,5 @@ +--- +"posthog-php": minor +--- + +A send with your own content (`template_key`) takes `tracking` to choose what PostHog tracks for the email. Left out, PostHog counts opens and captures engagement events, and doesn't track clicks. `true` turns on opens, clicks and engagement events, and `false` turns them all off. An array such as `['clicks' => true]` sets `opens`, `clicks` and `engagement` one by one. `capture_engagement` is deprecated in favor of `tracking` with `engagement`; it still works, but a send can't set both. The client sends `tracking` only when you set it. It needs PostHog's API support for the field, which is rolling out. diff --git a/README.md b/README.md index 692d6ba3..6f8ba1c7 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,8 @@ PostHog::emails()->send([ $status = PostHog::emails()->get($result->getId()); // queued, sent, delivered, bounced, ... ``` -- **Two forms.** Pass `template_id` with optional `template_data`, or `template_key` with `subject` and `html`, `text` or both. The content form also takes `from` (a verified sender), `reply_to`, `capture_engagement` (default `true`) and `track_opens_and_clicks` (default `true`). `track_opens_and_clicks` decides whether PostHog tracks opens and clicks of the email. With `false`, the email goes out without PostHog's open pixel, so PostHog can't count its opens. PostHog doesn't track clicks on emails sent from code, so their links are never rewritten either way. It is independent of `capture_engagement`, which decides whether engagement events are captured on the recipient's person. PostHog derives a missing `text` from the `html`. To send an email built with a template library such as React Email, render it to HTML in your app and pass `html`. The SDK adds no rendering dependency. +- **Two forms.** Pass `template_id` with optional `template_data`, or `template_key` with `subject` and `html`, `text` or both. The content form also takes `from` (a verified sender), `reply_to` and `tracking`. PostHog derives a missing `text` from the `html`. To send an email built with a template library such as React Email, render it to HTML in your app and pass `html`. The SDK adds no rendering dependency. +- **Tracking.** Left out, PostHog counts the email's opens and captures its engagement events, and doesn't track clicks. `'tracking' => true` turns on opens, clicks and engagement events. `'tracking' => false` turns them all off: no open pixel, no rewritten links, no engagement events. An array such as `['clicks' => true]` sets `opens` (default `true`), `clicks` (default `false`) and `engagement` (default `true`) one by one. Clicks are off by default because PostHog can't tell whether an email's links carry login or reset tokens, so turn them on only when the links are safe to rewrite. Click tracking needs open tracking. `capture_engagement` is deprecated in favor of `tracking` with `engagement`. It still works, but a send can't set both. - **Pass `distinct_id`.** Without it, the email's engagement events go to a person whose distinct ID is the email address. - **A result means queued**, not delivered. `send()` returns a `SendEmailResult` with the message ID. `get()` reads the status for 30 days after the send. For a few seconds after the send, it throws `not_found`. - **Errors.** A send that is not queued throws `PostHog\EmailError`. Branch on `getErrorCode()`, such as `recipient_suppressed` or `missing_app_host`, or on `getErrorName()`, such as `validation_error`. An invalid argument throws before any request, with an `invalid_*` code. diff --git a/lib/Emails.php b/lib/Emails.php index b14dc3f0..fd51be29 100644 --- a/lib/Emails.php +++ b/lib/Emails.php @@ -64,9 +64,9 @@ final class Emails 'from', 'reply_to', 'capture_engagement', - 'track_opens_and_clicks', + 'tracking', ]; - private const TEMPLATE_FORM_WHY = "A template made in PostHog sets its own sender, subject and content, " + private const TEMPLATE_FORM_WHY = "A template made in PostHog sets its own sender, subject, content and tracking, " . "and follows the project's engagement setting."; private const CODE_FORM_WHY = 'A send with template_key takes its content from your code.'; @@ -142,14 +142,21 @@ public function __construct( * 400), `subject`, and `html`, `text` or both. PostHog derives a missing `text` from the `html`, and * sends the content as is without storing it. To send a React email, render it to HTML in your app * first. This form also takes `from` (a verified sender, such as `Acme `), - * `reply_to` (one address or a list; an empty list is left out), `capture_engagement` (default - * true; a project whose admin turned engagement capture off captures nothing, whatever the send asks) - * and `track_opens_and_clicks` (default true), whether PostHog tracks opens and clicks of the email. - * With false, the email goes out without PostHog's open pixel, so PostHog can't count its opens. - * PostHog doesn't track clicks on emails sent from code, so their links are never rewritten either way. - * The client sends `track_opens_and_clicks` only when you set it, because a PostHog version that - * predates the field refuses it. It is independent of `capture_engagement`, which decides whether - * engagement events are captured on the recipient's person. + * `reply_to` (one address or a list; an empty list is left out) and `tracking`. + * + * `tracking` says what PostHog tracks for the email. Left out, PostHog counts opens and captures + * engagement events, and doesn't track clicks. `true` turns on opens, clicks and engagement events. + * `false` turns them all off: the email has no open pixel and no rewritten links, and PostHog + * captures no engagement events for it. An array such as `['clicks' => true]` sets `opens` + * (default true), `clicks` (default false) and `engagement` (default true) one by one. Clicks are + * off by default because PostHog can't tell whether an email's links carry login or reset tokens: + * turn them on only when the links are safe to rewrite. Click tracking needs open tracking. A + * project whose admin turned engagement capture off captures nothing, whatever the send says. The + * client sends `tracking` only when you set it, and needs a PostHog version that takes it. + * + * `capture_engagement` is deprecated: use `tracking` with `engagement` instead. It still works, but a + * send can't set both. The client sends `capture_engagement` (default true) only when `tracking` is + * left out, or when you set it. * * Both forms take `to` (one address), `distinct_id` (the recipient's distinct ID in your product; * without it, the email's events go to a person whose distinct ID is the address), `idempotency_key` @@ -191,8 +198,8 @@ public function __construct( * text?: string|null, * from?: string|null, * reply_to?: string|list|null, - * capture_engagement?: bool|null, - * track_opens_and_clicks?: bool|null + * tracking?: bool|array{opens?: bool|null, clicks?: bool|null, engagement?: bool|null}|null, + * capture_engagement?: bool|null * } $email * @return SendEmailResult The queued email. It means PostHog queued the email, not that it was delivered. * @throws EmailError PostHog did not queue the email, or the client could not tell whether it did. A @@ -372,25 +379,44 @@ private static function codeContent(array $email): array if (array_key_exists('reply_to', $email) && $email['reply_to'] !== []) { $content['reply_to'] = self::addresses($email['reply_to']); } - $captureEngagement = $email['capture_engagement'] ?? true; - if (!is_bool($captureEngagement)) { + $tracking = self::tracking($email); + $captureEngagement = $email['capture_engagement'] ?? null; + if ($captureEngagement !== null && !is_bool($captureEngagement)) { throw self::invalid('invalid_form', 'capture_engagement must be true or false.', 'capture_engagement'); } - $content['capture_engagement'] = $captureEngagement; - if (array_key_exists('track_opens_and_clicks', $email)) { - if (!is_bool($email['track_opens_and_clicks'])) { - throw self::invalid( - 'invalid_form', - 'track_opens_and_clicks must be true or false.', - 'track_opens_and_clicks' - ); - } - $content['track_opens_and_clicks'] = $email['track_opens_and_clicks']; + if ($tracking === null || $captureEngagement !== null) { + $content['capture_engagement'] = $captureEngagement ?? true; + } + if ($tracking !== null) { + $content['tracking'] = $tracking; } return $content; } + private static function tracking(array $email): bool|object|null + { + $tracking = $email['tracking'] ?? null; + if ($tracking === null || is_bool($tracking)) { + return $tracking; + } + if (!is_array($tracking) || ($tracking !== [] && array_is_list($tracking))) { + throw self::invalid( + 'invalid_form', + "tracking must be true, false or an array such as ['clicks' => true].", + 'tracking' + ); + } + $tracking = array_filter($tracking, static fn($value): bool => $value !== null); + foreach ($tracking as $kind => $on) { + if (!is_bool($on)) { + throw self::invalid('invalid_form', "tracking['$kind'] must be true or false.", 'tracking'); + } + } + + return (object) $tracking; + } + /** * @return list */ diff --git a/test/EmailsTest.php b/test/EmailsTest.php index cdf20210..3748424a 100644 --- a/test/EmailsTest.php +++ b/test/EmailsTest.php @@ -205,31 +205,39 @@ public function testCodeSendKeepsAReplyToListAndCaptureEngagementOff(): void ], $this->body()); } - #[DataProvider('trackOpensAndClicksCases')] - public function testCodeSendPassesTrackOpensAndClicksOnlyWhenSet(?bool $track, array $expected): void + #[DataProvider('trackingCases')] + public function testCodeSendPassesTrackingOnlyWhenSet(array $options, string $expected): void { $this->emails()->send([ 'to' => 'user@example.com', 'template_key' => 'welcome', 'subject' => 'Welcome', 'html' => '

Hi

', - 'track_opens_and_clicks' => $track, - ]); + ] + $options); - $this->assertSame([ - 'template_key' => 'welcome', - 'subject' => 'Welcome', - 'html' => '

Hi

', - 'capture_engagement' => true, - ] + $expected + ['to' => 'user@example.com'], $this->body()); + $this->assertSame( + '{"template_key":"welcome","subject":"Welcome","html":"

Hi

",' . $expected + . '"to":"user@example.com"}', + $this->requests[0]['body'] + ); } - public static function trackOpensAndClicksCases(): array + public static function trackingCases(): array { return [ - 'false' => [false, ['track_opens_and_clicks' => false]], - 'true' => [true, ['track_opens_and_clicks' => true]], - 'unset' => [null, []], + 'unset' => [['tracking' => null], '"capture_engagement":true,'], + 'true' => [['tracking' => true], '"tracking":true,'], + 'false' => [['tracking' => false], '"tracking":false,'], + 'clicks on' => [['tracking' => ['clicks' => true]], '"tracking":{"clicks":true},'], + 'null kinds left out' => [ + ['tracking' => ['opens' => false, 'clicks' => null, 'engagement' => false]], + '"tracking":{"opens":false,"engagement":false},', + ], + 'empty array' => [['tracking' => []], '"tracking":{},'], + 'with capture_engagement' => [ + ['tracking' => true, 'capture_engagement' => false], + '"capture_engagement":false,"tracking":true,', + ], ]; } @@ -355,11 +363,7 @@ public static function argumentErrors(): array 'invalid_form', 'capture_engagement', ], - 'track_opens_and_clicks with a template' => [ - $template + ['track_opens_and_clicks' => false], - 'invalid_form', - 'track_opens_and_clicks', - ], + 'tracking with a template' => [$template + ['tracking' => false], 'invalid_form', 'tracking'], 'unknown option' => [$template + ['cc' => 'boss@example.com'], 'invalid_form', 'cc'], 'template_data with code' => [$code + ['template_data' => ['a' => 1]], 'invalid_form', 'template_data'], 'bad template key' => [['template_key' => 'pass word'] + $code, 'invalid_template_key', 'template_key'], @@ -380,11 +384,9 @@ public static function argumentErrors(): array 'invalid_form', 'capture_engagement', ], - 'track_opens_and_clicks not a bool' => [ - $code + ['track_opens_and_clicks' => 'no'], - 'invalid_form', - 'track_opens_and_clicks', - ], + 'tracking not a bool or an array' => [$code + ['tracking' => 'no'], 'invalid_form', 'tracking'], + 'tracking a list' => [$code + ['tracking' => [true]], 'invalid_form', 'tracking'], + 'tracking kind not a bool' => [$code + ['tracking' => ['clicks' => 'yes']], 'invalid_form', 'tracking'], 'idempotency key with a space' => [ $template + ['idempotency_key' => 'welcome user'], 'invalid_idempotency_key', From 9f8cade1816415923ff0b701da628dd0d31e0c49 Mon Sep 17 00:00:00 2001 From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com> Date: Tue, 10 Nov 2026 08:27:09 +0000 Subject: [PATCH 4/5] fix(emails): send capture_engagement only when the caller sets it A code send that sets tracking must not also carry capture_engagement, or PostHog refuses it. PostHog reads a missing capture_engagement as true, so a default send still captures engagement. Co-Authored-By: Claude Opus 5.5 --- .changeset/emails-tracking.md | 2 +- lib/Emails.php | 7 +++---- test/EmailsClientTest.php | 1 - test/EmailsTest.php | 4 +--- 4 files changed, 5 insertions(+), 9 deletions(-) diff --git a/.changeset/emails-tracking.md b/.changeset/emails-tracking.md index 7d87b223..996a1acf 100644 --- a/.changeset/emails-tracking.md +++ b/.changeset/emails-tracking.md @@ -2,4 +2,4 @@ "posthog-php": minor --- -A send with your own content (`template_key`) takes `tracking` to choose what PostHog tracks for the email. Left out, PostHog counts opens and captures engagement events, and doesn't track clicks. `true` turns on opens, clicks and engagement events, and `false` turns them all off. An array such as `['clicks' => true]` sets `opens`, `clicks` and `engagement` one by one. `capture_engagement` is deprecated in favor of `tracking` with `engagement`; it still works, but a send can't set both. The client sends `tracking` only when you set it. It needs PostHog's API support for the field, which is rolling out. +A send with your own content (`template_key`) takes `tracking` to choose what PostHog tracks for the email. Left out, PostHog counts opens and captures engagement events, and doesn't track clicks. `true` turns on opens, clicks and engagement events, and `false` turns them all off. An array such as `['clicks' => true]` sets `opens`, `clicks` and `engagement` one by one. `capture_engagement` is deprecated in favor of `tracking` with `engagement`; it still works, but a send can't set both. The client now sends it only when you set it; PostHog already reads a missing value as on. The client sends `tracking` only when you set it. It needs PostHog's API support for the field, which is rolling out. diff --git a/lib/Emails.php b/lib/Emails.php index fd51be29..f5707ecf 100644 --- a/lib/Emails.php +++ b/lib/Emails.php @@ -155,8 +155,7 @@ public function __construct( * client sends `tracking` only when you set it, and needs a PostHog version that takes it. * * `capture_engagement` is deprecated: use `tracking` with `engagement` instead. It still works, but a - * send can't set both. The client sends `capture_engagement` (default true) only when `tracking` is - * left out, or when you set it. + * send can't set both. The client sends `capture_engagement` only when you set it. * * Both forms take `to` (one address), `distinct_id` (the recipient's distinct ID in your product; * without it, the email's events go to a person whose distinct ID is the address), `idempotency_key` @@ -384,8 +383,8 @@ private static function codeContent(array $email): array if ($captureEngagement !== null && !is_bool($captureEngagement)) { throw self::invalid('invalid_form', 'capture_engagement must be true or false.', 'capture_engagement'); } - if ($tracking === null || $captureEngagement !== null) { - $content['capture_engagement'] = $captureEngagement ?? true; + if ($captureEngagement !== null) { + $content['capture_engagement'] = $captureEngagement; } if ($tracking !== null) { $content['tracking'] = $tracking; diff --git a/test/EmailsClientTest.php b/test/EmailsClientTest.php index 91ab6451..a06c26a0 100644 --- a/test/EmailsClientTest.php +++ b/test/EmailsClientTest.php @@ -67,7 +67,6 @@ public function testACodeSendReachesTheSendRouteOverHttp(): void 'template_key' => 'welcome', 'subject' => 'Welcome', 'html' => $html, - 'capture_engagement' => true, 'to' => 'user@example.com', 'distinct_id' => 'user_123', ], json_decode($requests[0]['body'], true)); diff --git a/test/EmailsTest.php b/test/EmailsTest.php index 3748424a..b6a566bb 100644 --- a/test/EmailsTest.php +++ b/test/EmailsTest.php @@ -178,7 +178,6 @@ public function testCodeSendPostsRenderedContent(): void 'text' => 'Reset it here: https://example.com/r', 'from' => 'Acme ', 'reply_to' => ['help@example.com'], - 'capture_engagement' => true, 'to' => 'user@example.com', 'distinct_id' => 'user_123', ], $this->body()); @@ -225,7 +224,7 @@ public function testCodeSendPassesTrackingOnlyWhenSet(array $options, string $ex public static function trackingCases(): array { return [ - 'unset' => [['tracking' => null], '"capture_engagement":true,'], + 'unset' => [['tracking' => null], ''], 'true' => [['tracking' => true], '"tracking":true,'], 'false' => [['tracking' => false], '"tracking":false,'], 'clicks on' => [['tracking' => ['clicks' => true]], '"tracking":{"clicks":true},'], @@ -261,7 +260,6 @@ public function testNullOptionsAndAnEmptyReplyToCountAsLeftOut(): void 'template_key' => 'receipt', 'subject' => 'Your receipt', 'html' => '

Thanks!

', - 'capture_engagement' => true, 'to' => 'user@example.com', ], $this->body()); } From 99f60a19c7c93da311a6bf9e7724b8359e747e62 Mon Sep 17 00:00:00 2001 From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com> Date: Wed, 11 Nov 2026 04:12:21 +0000 Subject: [PATCH 5/5] feat(emails): let a code send mark itself sensitive A send with template_key now takes an optional sensitive flag. The client sends it only when the caller sets it. Left out, PostHog keeps today's behavior: the matching template's setting, else sensitive. Click tracking follows it unless tracking sets clicks. Co-Authored-By: Claude Opus 5.5 --- .changeset/emails-tracking.md | 2 +- README.md | 5 +++-- lib/Emails.php | 39 +++++++++++++++++++++++++---------- test/EmailsTest.php | 12 ++++++++++- 4 files changed, 43 insertions(+), 15 deletions(-) diff --git a/.changeset/emails-tracking.md b/.changeset/emails-tracking.md index 996a1acf..b6170dae 100644 --- a/.changeset/emails-tracking.md +++ b/.changeset/emails-tracking.md @@ -2,4 +2,4 @@ "posthog-php": minor --- -A send with your own content (`template_key`) takes `tracking` to choose what PostHog tracks for the email. Left out, PostHog counts opens and captures engagement events, and doesn't track clicks. `true` turns on opens, clicks and engagement events, and `false` turns them all off. An array such as `['clicks' => true]` sets `opens`, `clicks` and `engagement` one by one. `capture_engagement` is deprecated in favor of `tracking` with `engagement`; it still works, but a send can't set both. The client now sends it only when you set it; PostHog already reads a missing value as on. The client sends `tracking` only when you set it. It needs PostHog's API support for the field, which is rolling out. +A send with your own content (`template_key`) takes `sensitive` and `tracking`. Set `sensitive` to true when the email carries login links, reset tokens or codes: PostHog then keeps its links unchanged unless `tracking` turns clicks on, leaves its subject off engagement events, and keeps its content out of logs. Left out, the email takes the setting of the template made in PostHog whose key matches `template_key`, and is sensitive when no template matches. `tracking` chooses what PostHog tracks for the email. Left out, PostHog counts opens and captures engagement events, and tracks clicks only when the email isn't sensitive. `true` turns on opens, clicks and engagement events, and `false` turns them all off. An array such as `['clicks' => true]` sets `opens`, `clicks` and `engagement` one by one. `capture_engagement` is deprecated in favor of `tracking` with `engagement`; it still works, but a send can't set both. The client now sends it only when you set it; PostHog already reads a missing value as on. The client sends `sensitive` and `tracking` only when you set them. They need PostHog's API support for the fields, which is rolling out. diff --git a/README.md b/README.md index 6f8ba1c7..d6d28987 100644 --- a/README.md +++ b/README.md @@ -62,8 +62,9 @@ PostHog::emails()->send([ $status = PostHog::emails()->get($result->getId()); // queued, sent, delivered, bounced, ... ``` -- **Two forms.** Pass `template_id` with optional `template_data`, or `template_key` with `subject` and `html`, `text` or both. The content form also takes `from` (a verified sender), `reply_to` and `tracking`. PostHog derives a missing `text` from the `html`. To send an email built with a template library such as React Email, render it to HTML in your app and pass `html`. The SDK adds no rendering dependency. -- **Tracking.** Left out, PostHog counts the email's opens and captures its engagement events, and doesn't track clicks. `'tracking' => true` turns on opens, clicks and engagement events. `'tracking' => false` turns them all off: no open pixel, no rewritten links, no engagement events. An array such as `['clicks' => true]` sets `opens` (default `true`), `clicks` (default `false`) and `engagement` (default `true`) one by one. Clicks are off by default because PostHog can't tell whether an email's links carry login or reset tokens, so turn them on only when the links are safe to rewrite. Click tracking needs open tracking. `capture_engagement` is deprecated in favor of `tracking` with `engagement`. It still works, but a send can't set both. +- **Two forms.** Pass `template_id` with optional `template_data`, or `template_key` with `subject` and `html`, `text` or both. The content form also takes `from` (a verified sender), `reply_to`, `sensitive` and `tracking`. PostHog derives a missing `text` from the `html`. To send an email built with a template library such as React Email, render it to HTML in your app and pass `html`. The SDK adds no rendering dependency. +- **Sensitive emails.** Pass `'sensitive' => true` when the email carries login links, reset tokens or codes. A sensitive email keeps its links unchanged unless `tracking` turns clicks on, leaves its subject off engagement events, and keeps its content out of logs. Left out, the email takes the setting of the template made in PostHog whose key matches `template_key`, and is sensitive when no template matches. +- **Tracking.** Left out, PostHog counts the email's opens and captures its engagement events, and tracks clicks only when the email isn't sensitive. `'tracking' => true` turns on opens, clicks and engagement events. `'tracking' => false` turns them all off: no open pixel, no rewritten links, no engagement events. An array such as `['clicks' => true]` sets `opens` (default `true`), `clicks` (default: on unless the email is sensitive) and `engagement` (default `true`) one by one. Turn clicks on for a sensitive email only when its links are safe to rewrite. Click tracking needs open tracking. `capture_engagement` is deprecated in favor of `tracking` with `engagement`. It still works, but a send can't set both. - **Pass `distinct_id`.** Without it, the email's engagement events go to a person whose distinct ID is the email address. - **A result means queued**, not delivered. `send()` returns a `SendEmailResult` with the message ID. `get()` reads the status for 30 days after the send. For a few seconds after the send, it throws `not_found`. - **Errors.** A send that is not queued throws `PostHog\EmailError`. Branch on `getErrorCode()`, such as `recipient_suppressed` or `missing_app_host`, or on `getErrorName()`, such as `validation_error`. An invalid argument throws before any request, with an `invalid_*` code. diff --git a/lib/Emails.php b/lib/Emails.php index f5707ecf..4bcfc1cf 100644 --- a/lib/Emails.php +++ b/lib/Emails.php @@ -64,10 +64,11 @@ final class Emails 'from', 'reply_to', 'capture_engagement', + 'sensitive', 'tracking', ]; - private const TEMPLATE_FORM_WHY = "A template made in PostHog sets its own sender, subject, content and tracking, " - . "and follows the project's engagement setting."; + private const TEMPLATE_FORM_WHY = "A template made in PostHog sets its own sender, subject, content, tracking " + . "and sensitive setting, and follows the project's engagement setting."; private const CODE_FORM_WHY = 'A send with template_key takes its content from your code.'; private const SEND_NOT_DONE = 'no email was sent'; @@ -142,17 +143,25 @@ public function __construct( * 400), `subject`, and `html`, `text` or both. PostHog derives a missing `text` from the `html`, and * sends the content as is without storing it. To send a React email, render it to HTML in your app * first. This form also takes `from` (a verified sender, such as `Acme `), - * `reply_to` (one address or a list; an empty list is left out) and `tracking`. + * `reply_to` (one address or a list; an empty list is left out), `sensitive` and `tracking`. + * + * `sensitive` marks the email as sensitive: set it to true when the email carries login links, reset + * tokens or codes. A sensitive email keeps its links unchanged unless `tracking` turns clicks on, + * leaves its subject off engagement events, and keeps its content out of logs. Left out, the email + * takes the setting of the template made in PostHog whose key matches `template_key`, and is + * sensitive when no template matches. * * `tracking` says what PostHog tracks for the email. Left out, PostHog counts opens and captures - * engagement events, and doesn't track clicks. `true` turns on opens, clicks and engagement events. - * `false` turns them all off: the email has no open pixel and no rewritten links, and PostHog - * captures no engagement events for it. An array such as `['clicks' => true]` sets `opens` - * (default true), `clicks` (default false) and `engagement` (default true) one by one. Clicks are - * off by default because PostHog can't tell whether an email's links carry login or reset tokens: - * turn them on only when the links are safe to rewrite. Click tracking needs open tracking. A - * project whose admin turned engagement capture off captures nothing, whatever the send says. The - * client sends `tracking` only when you set it, and needs a PostHog version that takes it. + * engagement events, and tracks clicks only when the email isn't sensitive. `true` turns on opens, + * clicks and engagement events, even for a sensitive email. `false` turns them all off: the email + * has no open pixel and no rewritten links, and PostHog captures no engagement events for it. An + * array such as `['clicks' => true]` sets `opens` (default true), `clicks` (default: on unless the + * email is sensitive) and `engagement` (default true) one by one. Turn clicks on for a sensitive + * email only when its links are safe to rewrite. Click tracking needs open tracking. A project whose + * admin turned engagement capture off captures nothing, whatever the send says. + * + * The client sends `sensitive` and `tracking` only when you set them, and they need a PostHog + * version that takes them. * * `capture_engagement` is deprecated: use `tracking` with `engagement` instead. It still works, but a * send can't set both. The client sends `capture_engagement` only when you set it. @@ -197,6 +206,7 @@ public function __construct( * text?: string|null, * from?: string|null, * reply_to?: string|list|null, + * sensitive?: bool|null, * tracking?: bool|array{opens?: bool|null, clicks?: bool|null, engagement?: bool|null}|null, * capture_engagement?: bool|null * } $email @@ -386,6 +396,13 @@ private static function codeContent(array $email): array if ($captureEngagement !== null) { $content['capture_engagement'] = $captureEngagement; } + $sensitive = $email['sensitive'] ?? null; + if ($sensitive !== null && !is_bool($sensitive)) { + throw self::invalid('invalid_form', 'sensitive must be true or false.', 'sensitive'); + } + if ($sensitive !== null) { + $content['sensitive'] = $sensitive; + } if ($tracking !== null) { $content['tracking'] = $tracking; } diff --git a/test/EmailsTest.php b/test/EmailsTest.php index b6a566bb..855c089d 100644 --- a/test/EmailsTest.php +++ b/test/EmailsTest.php @@ -205,7 +205,7 @@ public function testCodeSendKeepsAReplyToListAndCaptureEngagementOff(): void } #[DataProvider('trackingCases')] - public function testCodeSendPassesTrackingOnlyWhenSet(array $options, string $expected): void + public function testCodeSendPassesSensitiveAndTrackingOnlyWhenSet(array $options, string $expected): void { $this->emails()->send([ 'to' => 'user@example.com', @@ -237,6 +237,13 @@ public static function trackingCases(): array ['tracking' => true, 'capture_engagement' => false], '"capture_engagement":false,"tracking":true,', ], + 'sensitive unset' => [['sensitive' => null], ''], + 'sensitive' => [['sensitive' => true], '"sensitive":true,'], + 'not sensitive' => [['sensitive' => false], '"sensitive":false,'], + 'not sensitive with clicks off' => [ + ['sensitive' => false, 'tracking' => ['clicks' => false]], + '"sensitive":false,"tracking":{"clicks":false},', + ], ]; } @@ -251,6 +258,7 @@ public function testNullOptionsAndAnEmptyReplyToCountAsLeftOut(): void 'from' => null, 'reply_to' => [], 'capture_engagement' => null, + 'sensitive' => null, 'distinct_id' => null, 'idempotency_key' => null, 'template_id' => null, @@ -362,6 +370,7 @@ public static function argumentErrors(): array 'capture_engagement', ], 'tracking with a template' => [$template + ['tracking' => false], 'invalid_form', 'tracking'], + 'sensitive with a template' => [$template + ['sensitive' => true], 'invalid_form', 'sensitive'], 'unknown option' => [$template + ['cc' => 'boss@example.com'], 'invalid_form', 'cc'], 'template_data with code' => [$code + ['template_data' => ['a' => 1]], 'invalid_form', 'template_data'], 'bad template key' => [['template_key' => 'pass word'] + $code, 'invalid_template_key', 'template_key'], @@ -385,6 +394,7 @@ public static function argumentErrors(): array 'tracking not a bool or an array' => [$code + ['tracking' => 'no'], 'invalid_form', 'tracking'], 'tracking a list' => [$code + ['tracking' => [true]], 'invalid_form', 'tracking'], 'tracking kind not a bool' => [$code + ['tracking' => ['clicks' => 'yes']], 'invalid_form', 'tracking'], + 'sensitive not a bool' => [$code + ['sensitive' => 'yes'], 'invalid_form', 'sensitive'], 'idempotency key with a space' => [ $template + ['idempotency_key' => 'welcome user'], 'invalid_idempotency_key',