Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/node-email-preferences.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'posthog-node': minor
---

Opt a recipient out of email topics, or back in, with `posthog.emails.setPreferences({ to, topics, allMarketing })`. One call sends the whole change in one request, using the client's `secretKey`.
2 changes: 1 addition & 1 deletion packages/node/Node.spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ posthog-node, the Node.js backend SDK: server-side capture, identify and local f
- flag definitions: PostHog servers answer the poller with the flag definitions used for local evaluation
handler: FeatureFlagsPoller in src/extensions/feature-flags/feature-flags.ts
trust: posthog-api
- email responses: PostHog servers answer `emails.send` with a queued message ID or an error, and `emails.get` with an email's status or an error
- email responses: PostHog servers answer `emails.send` with a queued message ID or an error, `emails.get` with an email's status or an error, and `emails.setPreferences` with the recipient's preferences or an error
handler: EmailSender in src/emails/emails.ts
trust: posthog-api
control: none — the reply only fills the result the caller awaits, and its one effect, a retry, is bounded by maxRetries and a 30 second ceiling
Expand Down
81 changes: 70 additions & 11 deletions packages/node/references/posthog-node-5.md
Original file line number Diff line number Diff line change
Expand Up @@ -951,14 +951,15 @@ client.debug(false)

> **get** **emails**(): `Emails`

The `posthog.emails` API: sends transactional email from PostHog email templates, and reads
the status of each email it sent.

Needs `secretKey`, a project secret API key with the `transactional_email:write` scope (the
"Send transactional email" preset). A key with only `transactional_email:read` can read
statuses but not send. Keys made with `hog_flow:write` still work. Requests go to `appHost`,
or to the PostHog Cloud app host of `host`. `send` and `get` resolve to `{ data, error }` and
do not reject.
The `posthog.emails` API: sends transactional email from PostHog email templates, reads
the status of each email it sent, and sets a recipient's topic preferences.

Needs `secretKey`, a project secret API key. `send` needs the `transactional_email:write` scope
(the "Send transactional email" preset), and `get` needs `transactional_email:read` or
`transactional_email:write`. `setPreferences` needs the
`messaging_preference:write` scope, which cannot send email. Keys made with `hog_flow:write` still
work for all three. Requests go to `appHost`, or to the PostHog Cloud app host of `host`. `send`,
`get` and `setPreferences` resolve to `{ data, error }` and do not reject.
`data.id` is the queued email's message ID, which `get` takes. A disabled client sends nothing
and returns the error `client_disabled`. After `shutdown()`, the client sends nothing and
returns the error `client_closed`.
Expand All @@ -979,6 +980,9 @@ if (error) {
}

const status = await client.emails.get(data.id) // later, for example from a job

// From a preference center: opt out of one topic, keep the rest
await client.emails.setPreferences({ to: 'user@example.com', topics: { newsletter: false } })
```

##### Returns
Expand All @@ -992,7 +996,7 @@ Needs `secretKey`, a project secret API key with the `transactional_email:write`

### `EmailError`

PostHog did not queue the email, or the client could not tell whether it did.
PostHog refused an email call, or the client could not tell whether it succeeded.

Branch on `code`, PostHog's stable error code, or on `name`, a coarse category of the
failure. The message never contains the secret key or the request body.
Expand Down Expand Up @@ -2884,6 +2888,18 @@ A coarse category of the failure, for code that branches on the kind of failure
| <a id="property-statuscode"></a> `statusCode?` | `number` |
| <a id="property-why"></a> `why?` | `string` |

### `EmailPreferences`

A recipient's preferences after the change.

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="property-allmarketing"></a> `allMarketing` | `boolean` \| `null` | `false` when the recipient opted out of all marketing, `true` when they opted back in, `null` when they never chose. |
| <a id="property-to"></a> `to` | `string` | - |
| <a id="property-topics"></a> `topics` | `Record`\<`string`, `boolean`\> | Topic key to `false` (opted out) or `true` (opted in), for every topic the recipient chose. |

### `EmailReactElement`

A React element, such as `<WelcomeEmail firstName="Ada" />`. Typed by its shape, so
Expand All @@ -2899,7 +2915,8 @@ posthog-node needs no React types.
### `Emails`

The `posthog.emails` API: sends transactional email from PostHog email templates or from
content your code rendered, and reads the status of each email it sent.
content your code rendered, reads the status of each email it sent, and sets a recipient's
topic preferences.

#### Methods

Expand Down Expand Up @@ -2943,6 +2960,29 @@ an unavailable service are retried with the same idempotency key.

`Promise`\<`SendEmailResponse`\>

##### setPreferences()

> **setPreferences**(`options`): `Promise`\<`SetEmailPreferencesResponse`\>

Opt one recipient out of topics, or back in, in one request. PostHog saves the whole change at once. The same
change twice ends the same, but a retry that lands after a newer change for the same recipient undoes that
change. A failed call may still have saved the change. Workflows sends skip a marketing topic the recipient
opted out of.

Resolves to `{ data, error }` and does not reject. The error code is `unknown_topic` when a topic key names no
topic of the project, and nothing is saved. A plain `not_found` means the PostHog instance has no preferences
API yet. Network errors, rate limits and an unavailable service are retried.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | `SetEmailPreferencesOptions` |

###### Returns

`Promise`\<`SetEmailPreferencesResponse`\>

### `EmailStatus`

The status of an email that `posthog.emails.send()` queued.
Expand Down Expand Up @@ -4912,7 +4952,7 @@ What every send takes, whatever its form.
| <a id="property-distinctid-1"></a> `distinctId?` | `string` | The recipient's distinct ID in your product. The email's events go to this person. Without it, they go to a person whose distinct ID is the email address. |
| <a id="property-idempotencykey"></a> `idempotencyKey?` | `string` | 1 to 255 visible ASCII characters. A send with a key that PostHog has already accepted queues nothing and returns the first send's result. The same key with other options sends nothing and returns an error with code `idempotency_key_reused`. Without it, the client makes a UUID that covers its own retries. Pass a key derived from what the email is for, such as `welcome:user_123`, to cover retries outside this call too. |
| <a id="property-maxretries"></a> `maxRetries?` | `number` | Overrides the client's `emailRequestMaxRetries` for this send. `0` turns retries off. |
| <a id="property-to"></a> `to` | `string` | One recipient email address. |
| <a id="property-to-1"></a> `to` | `string` | One recipient email address. |

### `SendEmailOptions`

Expand Down Expand Up @@ -4970,6 +5010,25 @@ The queued email. A result means PostHog queued the email, not that it was deliv
| <a id="sendexceptionstoposthog"></a> `sendExceptionsToPostHog?` | `boolean` |
| <a id="severityallowlist"></a> `severityAllowList?` | `SeverityLevel`[] \| `"*"` |

### `SetEmailPreferencesOptions`

Options for `posthog.emails.setPreferences()`. Set `allMarketing`, `topics`, or both.

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="property-allmarketing-1"></a> `allMarketing?` | `boolean` | `false` opts the recipient out of every marketing topic. `true` lifts that opt-out. Applied before `topics`. |
| <a id="property-to-2"></a> `to` | `string` | The recipient's email address, exactly as Workflows sends to it. Matching is exact, so `Jane@example.com` and `jane@example.com` are two recipients. |
| <a id="property-topics-1"></a> `topics?` | `Record`\<`string`, `boolean`\> | Topic key to `false` to opt the recipient out of that topic, or `true` to opt them back in. Topic keys are the ones you set under Workflows opt-outs. Opting back in to one marketing topic after an all-marketing opt-out lifts that opt-out, so `allMarketing` becomes `true`, and keeps the other marketing topics opted out. Topics you leave out keep their current choice. |

### `SetEmailPreferencesResponse`

> **SetEmailPreferencesResponse** = \{ `data`: `EmailPreferences`; `error`: `null`; \} \| \{ `data`: `null`; `error`: `EmailError`; \}

What `posthog.emails.setPreferences()` resolves to. Exactly one of `data` and `error` is set.
The promise does not reject.

### `SetPersonPropertiesMessage`

> **SetPersonPropertiesMessage** = `object`
Expand Down
81 changes: 70 additions & 11 deletions packages/node/references/posthog-node-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -951,14 +951,15 @@ client.debug(false)

> **get** **emails**(): `Emails`

The `posthog.emails` API: sends transactional email from PostHog email templates, and reads
the status of each email it sent.

Needs `secretKey`, a project secret API key with the `transactional_email:write` scope (the
"Send transactional email" preset). A key with only `transactional_email:read` can read
statuses but not send. Keys made with `hog_flow:write` still work. Requests go to `appHost`,
or to the PostHog Cloud app host of `host`. `send` and `get` resolve to `{ data, error }` and
do not reject.
The `posthog.emails` API: sends transactional email from PostHog email templates, reads
the status of each email it sent, and sets a recipient's topic preferences.

Needs `secretKey`, a project secret API key. `send` needs the `transactional_email:write` scope
(the "Send transactional email" preset), and `get` needs `transactional_email:read` or
`transactional_email:write`. `setPreferences` needs the
`messaging_preference:write` scope, which cannot send email. Keys made with `hog_flow:write` still
work for all three. Requests go to `appHost`, or to the PostHog Cloud app host of `host`. `send`,
`get` and `setPreferences` resolve to `{ data, error }` and do not reject.
`data.id` is the queued email's message ID, which `get` takes. A disabled client sends nothing
and returns the error `client_disabled`. After `shutdown()`, the client sends nothing and
returns the error `client_closed`.
Expand All @@ -979,6 +980,9 @@ if (error) {
}

const status = await client.emails.get(data.id) // later, for example from a job

// From a preference center: opt out of one topic, keep the rest
await client.emails.setPreferences({ to: 'user@example.com', topics: { newsletter: false } })
```

##### Returns
Expand All @@ -992,7 +996,7 @@ Needs `secretKey`, a project secret API key with the `transactional_email:write`

### `EmailError`

PostHog did not queue the email, or the client could not tell whether it did.
PostHog refused an email call, or the client could not tell whether it succeeded.

Branch on `code`, PostHog's stable error code, or on `name`, a coarse category of the
failure. The message never contains the secret key or the request body.
Expand Down Expand Up @@ -2884,6 +2888,18 @@ A coarse category of the failure, for code that branches on the kind of failure
| <a id="property-statuscode"></a> `statusCode?` | `number` |
| <a id="property-why"></a> `why?` | `string` |

### `EmailPreferences`

A recipient's preferences after the change.

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="property-allmarketing"></a> `allMarketing` | `boolean` \| `null` | `false` when the recipient opted out of all marketing, `true` when they opted back in, `null` when they never chose. |
| <a id="property-to"></a> `to` | `string` | - |
| <a id="property-topics"></a> `topics` | `Record`\<`string`, `boolean`\> | Topic key to `false` (opted out) or `true` (opted in), for every topic the recipient chose. |

### `EmailReactElement`

A React element, such as `<WelcomeEmail firstName="Ada" />`. Typed by its shape, so
Expand All @@ -2899,7 +2915,8 @@ posthog-node needs no React types.
### `Emails`

The `posthog.emails` API: sends transactional email from PostHog email templates or from
content your code rendered, and reads the status of each email it sent.
content your code rendered, reads the status of each email it sent, and sets a recipient's
topic preferences.

#### Methods

Expand Down Expand Up @@ -2943,6 +2960,29 @@ an unavailable service are retried with the same idempotency key.

`Promise`\<`SendEmailResponse`\>

##### setPreferences()

> **setPreferences**(`options`): `Promise`\<`SetEmailPreferencesResponse`\>

Opt one recipient out of topics, or back in, in one request. PostHog saves the whole change at once. The same
change twice ends the same, but a retry that lands after a newer change for the same recipient undoes that
change. A failed call may still have saved the change. Workflows sends skip a marketing topic the recipient
opted out of.

Resolves to `{ data, error }` and does not reject. The error code is `unknown_topic` when a topic key names no
topic of the project, and nothing is saved. A plain `not_found` means the PostHog instance has no preferences
API yet. Network errors, rate limits and an unavailable service are retried.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | `SetEmailPreferencesOptions` |

###### Returns

`Promise`\<`SetEmailPreferencesResponse`\>

### `EmailStatus`

The status of an email that `posthog.emails.send()` queued.
Expand Down Expand Up @@ -4912,7 +4952,7 @@ What every send takes, whatever its form.
| <a id="property-distinctid-1"></a> `distinctId?` | `string` | The recipient's distinct ID in your product. The email's events go to this person. Without it, they go to a person whose distinct ID is the email address. |
| <a id="property-idempotencykey"></a> `idempotencyKey?` | `string` | 1 to 255 visible ASCII characters. A send with a key that PostHog has already accepted queues nothing and returns the first send's result. The same key with other options sends nothing and returns an error with code `idempotency_key_reused`. Without it, the client makes a UUID that covers its own retries. Pass a key derived from what the email is for, such as `welcome:user_123`, to cover retries outside this call too. |
| <a id="property-maxretries"></a> `maxRetries?` | `number` | Overrides the client's `emailRequestMaxRetries` for this send. `0` turns retries off. |
| <a id="property-to"></a> `to` | `string` | One recipient email address. |
| <a id="property-to-1"></a> `to` | `string` | One recipient email address. |

### `SendEmailOptions`

Expand Down Expand Up @@ -4970,6 +5010,25 @@ The queued email. A result means PostHog queued the email, not that it was deliv
| <a id="sendexceptionstoposthog"></a> `sendExceptionsToPostHog?` | `boolean` |
| <a id="severityallowlist"></a> `severityAllowList?` | `SeverityLevel`[] \| `"*"` |

### `SetEmailPreferencesOptions`

Options for `posthog.emails.setPreferences()`. Set `allMarketing`, `topics`, or both.

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="property-allmarketing-1"></a> `allMarketing?` | `boolean` | `false` opts the recipient out of every marketing topic. `true` lifts that opt-out. Applied before `topics`. |
| <a id="property-to-2"></a> `to` | `string` | The recipient's email address, exactly as Workflows sends to it. Matching is exact, so `Jane@example.com` and `jane@example.com` are two recipients. |
| <a id="property-topics-1"></a> `topics?` | `Record`\<`string`, `boolean`\> | Topic key to `false` to opt the recipient out of that topic, or `true` to opt them back in. Topic keys are the ones you set under Workflows opt-outs. Opting back in to one marketing topic after an all-marketing opt-out lifts that opt-out, so `allMarketing` becomes `true`, and keeps the other marketing topics opted out. Topics you leave out keep their current choice. |

### `SetEmailPreferencesResponse`

> **SetEmailPreferencesResponse** = \{ `data`: `EmailPreferences`; `error`: `null`; \} \| \{ `data`: `null`; `error`: `EmailError`; \}

What `posthog.emails.setPreferences()` resolves to. Exactly one of `data` and `error` is set.
The promise does not reject.

### `SetPersonPropertiesMessage`

> **SetPersonPropertiesMessage** = `object`
Expand Down
50 changes: 50 additions & 0 deletions packages/node/references/posthog-node-references-latest.json
Original file line number Diff line number Diff line change
Expand Up @@ -2257,6 +2257,27 @@
],
"path": "src/emails/types.ts"
},
{
"id": "EmailPreferences",
"name": "EmailPreferences",
"properties": [
{
"description": "`false` when the recipient opted out of all marketing, `true` when they opted back in, `null` when they never chose.",
"type": "boolean | null",
"name": "allMarketing"
},
{
"type": "string",
"name": "to"
},
{
"description": "Topic key to `false` (opted out) or `true` (opted in), for every topic the recipient chose.",
"type": "Record<string, boolean>",
"name": "topics"
}
],
"path": "src/emails/types.ts"
},
{
"id": "Emails",
"name": "Emails",
Expand Down Expand Up @@ -4779,6 +4800,35 @@
],
"path": "src/extensions/sentry-integration.ts"
},
{
"id": "SetEmailPreferencesOptions",
"name": "SetEmailPreferencesOptions",
"properties": [
{
"description": "`false` opts the recipient out of every marketing topic. `true` lifts that opt-out. Applied before `topics`.",
"type": "boolean",
"name": "allMarketing"
},
{
"description": "The recipient's email address, exactly as Workflows sends to it. Matching is exact, so `Jane@example.com` and `jane@example.com` are two recipients.",
"type": "string",
"name": "to"
},
{
"description": "Topic key to `false` to opt the recipient out of that topic, or `true` to opt them back in. Topic keys are the ones you set under Workflows opt-outs. Opting back in to one marketing topic after an all-marketing opt-out lifts that opt-out, so `allMarketing` becomes `true`, and keeps the other marketing topics opted out. Topics you leave out keep their current choice.",
"type": "Record<string, boolean>",
"name": "topics"
}
],
"path": "src/emails/types.ts"
},
{
"id": "SetEmailPreferencesResponse",
"name": "SetEmailPreferencesResponse",
"properties": [],
"path": "src/emails/types.ts",
"example": "{\n data: EmailPreferences;\n error: null;\n} | {\n data: null;\n error: EmailError;\n}"
},
{
"id": "SetPersonPropertiesMessage",
"name": "SetPersonPropertiesMessage",
Expand Down
Loading
Loading