feat: send transactional email with emails()->send()

.changeset/emails-send.md

@@ -0,0 +1,30 @@
+---
+"posthog-php": minor
+---
+
+The new `emails()` sends transactional email from your PHP code and reads each email's delivery status.
+
+```php
+PostHog::init('phc_...', ['host' => 'https://us.i.posthog.com'], secretKey: 'phs_...');
+
+$result = PostHog::emails()->send([
+    'to' => 'user@example.com',
+    'distinct_id' => 'user_123',
+    'template_key' => 'password-reset',
+    'subject' => 'Reset your password',
+    'html' => $renderedHtml,
+]);
+
+// 'delivered', 'bounced', ...
+$status = PostHog::emails()->get($result->getId())->getStatus();
+```
+
+You can also send a template made in PostHog by its `template_id`.
+
+You need a project secret API key, the kind that starts with `phs_`. Create one under **Project secret API keys** in your project settings. Set its **Transactional email** scope to Write to send emails, or to Read for a key that only reads statuses. Pass it to the client as `secretKey`. Set the `app_host` option to your PostHog app URL when you self-host PostHog or send through a reverse proxy. The client also loads feature flags with this key when it starts, so give it **Feature flags: Read** too, or it logs an error each time a client starts.
+
+PostHog records each email's delivery, opens and clicks on the person with that `distinct_id`. It groups every email with the same `template_key`, so you see their metrics and logs in one place. The SDK retries a request that hits a network error, a rate limit or an outage twice by default. Every send carries an idempotency key, so a retry never sends the email twice. Pass your own `idempotency_key`, such as `welcome:user_123`, and your job runner's retries are safe too.
+
+A send with your own content also takes `from`, `reply_to` and `'capture_engagement' => false`. Set the `migrated_from` option to tell PostHog which email provider you moved from. A failed call throws a `PostHog\EmailError`. Its `getErrorCode()` returns PostHog's code, and `getStatusCode()` returns the HTTP status.
+
+Docs: [Send transactional emails with PHP](https://posthog.com/docs/workflows/transactional-emails/php) and the [transactional email overview](https://posthog.com/docs/workflows/transactional-emails).

README.md

@@ -23,6 +23,52 @@ The registered processor also enables request span enrichment when `withContext(
 
 Existing span attributes take precedence. The processor preserves the application's provider, sampling, and exporters. See the [PHP tracing guide](https://posthog.com/docs/distributed-tracing/installation/php) and [Laravel guide](https://posthog.com/docs/libraries/laravel) for setup.
 
+## Transactional email
+
+`emails()` sends one email to one recipient, from an email template made transactional in PostHog or from content your code rendered, and reads what happened to it.
+
+The client needs a project secret API key (`phs_...`) as `secretKey`. Create it with the "Send transactional email" preset (`transactional_email:write`) in your project settings, and add `transactional_email:read` if you read statuses with a key that can't send. Keys made with `hog_flow:write` still work. A client whose `host` is PostHog Cloud sends to its region's app host. For any other `host`, such as a reverse proxy, set the `app_host` option to your PostHog app host: email requests never go to a custom `host`. Loading flag definitions still sends the secret key to `host`, so when your proxy must not see the key, build the client with `loadFeatureFlags: false` and don't call `loadFlags()`:
+
+```php
+$client = new \PostHog\Client('phc_...', [
+    'host' => 'ph.example.com', // your proxy
+    'app_host' => 'https://eu.posthog.com',
+], loadFeatureFlags: false, secretKey: 'phs_...');
+PostHog::init(client: $client);
+```
+
+```php
+PostHog::init('phc_...', ['host' => 'https://eu.i.posthog.com'], secretKey: 'phs_...');
+
+// A template made in PostHog, by its ID
+$result = PostHog::emails()->send([
+    'to' => 'user@example.com',
+    'template_id' => '0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b',
+    'template_data' => ['name' => 'Ada'], // fills {{ variables.name }}
+    'distinct_id' => 'user_123',
+    'idempotency_key' => 'welcome:user_123',
+]);
+
+// Content your code rendered, named by a key
+PostHog::emails()->send([
+    'to' => 'user@example.com',
+    'template_key' => 'password-reset',
+    'subject' => 'Reset your password',
+    'html' => $html,
+    'distinct_id' => 'user_123',
+]);
+
+// Later, such as in a job: for a few seconds after the send, get() throws not_found
+$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.
+- **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.
+- **Retries.** Network errors, rate limits and an unavailable service are retried up to `email_request_max_retries` times (default 2) with the same idempotency key, so a retry never sends twice. Each request times out after `email_request_timeout_ms` (default 15000). When a job runner already retries the send, pass `'max_retries' => 0` and an `idempotency_key` derived from what the email is for, such as `welcome:user_123`. A generated key does not survive a job retry.
+- **Moving from another provider.** Set the `migrated_from` option, such as `'resend'`, so PostHog knows where your sends came from.
+
 ## Questions?
 
 ### [Join our Slack community.](https://join.slack.com/t/posthogusers/shared_invite/enQtOTY0MzU5NjAwMDY3LTc2MWQ0OTZlNjhkODk3ZDI3NDVjMDE1YjgxY2I4ZjI4MzJhZmVmNjJkN2NmMGJmMzc2N2U3Yjc3ZjI5NGFlZDQ)