diff --git a/contents/docs/workflows/transactional-emails/api.mdx b/contents/docs/workflows/transactional-emails/api.mdx index 73a377fe34bb..3e0419b6c622 100644 --- a/contents/docs/workflows/transactional-emails/api.mdx +++ b/contents/docs/workflows/transactional-emails/api.mdx @@ -196,8 +196,9 @@ You can also send the subject and the body from your code, without a template in | `from` | No | The sender, as `security@example.com` or `Hedgebox `, on a domain that your project verified. If you leave it out, PostHog uses the project's default sender. | | `reply_to` | No | A list of up to 10 addresses that replies go to, without a display name. | | `capture_engagement` | No | Whether PostHog captures the email's [engagement events](/docs/workflows/engagement-events). The default is `true`. Send `false` to turn capture off for this email. If the project's **Capture email engagement events** setting is off, PostHog captures nothing, whatever you send. | +| `track_opens_and_clicks` | No | Whether PostHog tracks opens and clicks of this email. The default is `true`. Send `false` to send the email with no open pixel and no link tracking, for example when it has a single-use link. | -A request has `template_id` or `template_key`, not both. Content from your code takes no `message_data`, because PostHog renders nothing. A template send takes none of `subject`, `html`, `text`, `from`, `reply_to`, and `capture_engagement`, because the template uses its own settings. PostHog returns a `400` that names the field in `attr`. +A request has `template_id` or `template_key`, not both. Content from your code takes no `message_data`, because PostHog renders nothing. A template send takes none of `subject`, `html`, `text`, `from`, `reply_to`, `capture_engagement`, and `track_opens_and_clicks`, because the template uses its own settings. PostHog returns a `400` that names the field in `attr`. If the `to` address is on the [suppression list](/docs/workflows/opt-outs#the-suppression-list), PostHog sends nothing and returns `recipient_suppressed`. @@ -321,7 +322,7 @@ $result = PostHog::emails()->send([ -### Copies and attachments +### Copies, attachments, and headers Content from your code also takes these fields. A template send takes none of them, because the template uses its own settings. @@ -329,12 +330,30 @@ Content from your code also takes these fields. A template send takes none of th | --- | --- | --- | | `cc` | No | A list of up to 10 addresses that get a copy, without a display name. | | `bcc` | No | A list of up to 10 addresses that get a hidden copy, without a display name. The other recipients don't see them. | -| `attachments` | No | A list of up to 10 files, 512 KB in total after decoding. Each file is an object with `filename`, `content` in Base64, and optionally `content_type`, such as `application/pdf`, and `content_id`. | +| `attachments` | No | A list of up to 10 files, 10 MB in total after decoding. Each file is an object with `filename`, `content` in Base64, and optionally `content_type`, such as `application/pdf`, and `content_id`. | +| `headers` | No | An object of header names and values, with up to 10 headers. See [custom headers](#custom-headers). | - **Inline images** - Set `content_id` on a file, and use it in the HTML as ``. - **Blocked files** - PostHog refuses file types that mailbox providers block, such as `.exe`, and a filename with a path. - **Older PostHog versions** - A PostHog version that doesn't take these fields yet refuses the send with a `400` that names the field. PostHog then sends nothing, and never sends the email without the field. +### Custom headers + +You can send `In-Reply-To`, `References`, `List-Unsubscribe`, `List-Unsubscribe-Post`, `List-Id`, and your own `X-` headers. + +```json +{ + "headers": { + "In-Reply-To": "", + "X-Campaign": "spring-sale" + } +} +``` + +- **Reserved headers** - `X-PostHog-` and `X-SES-` headers are reserved. PostHog refuses them. +- **Other headers** - PostHog refuses any other header, because it sets the headers that decide who an email is from and how its delivery is tracked. +- **Values** - A value has at most 998 characters and no line breaks. Send each header once, in any letter case. + ### Checks for content from your code These checks apply to content from your code, in addition to the [errors](/docs/workflows/transactional-emails#errors) of every send. PostHog sends nothing when a check fails. diff --git a/contents/docs/workflows/transactional-emails/examples.mdx b/contents/docs/workflows/transactional-emails/examples.mdx index 4da220aa6959..e31c5c0a294c 100644 --- a/contents/docs/workflows/transactional-emails/examples.mdx +++ b/contents/docs/workflows/transactional-emails/examples.mdx @@ -161,7 +161,7 @@ Send a receipt with the invoice attached, and a copy to the customer's billing c | --- | --- | | Template key | `receipt` | | Copies | `cc` to the billing contact, if the customer has one | -| Attachment | The invoice PDF, 512 KB at most for all files together | +| Attachment | The invoice PDF, 10 MB at most for all files together | | Distinct ID | The customer's user ID | | Idempotency key | `receipt-{order_id}` | @@ -187,7 +187,7 @@ curl -X POST "https://us.posthog.com/api/projects/@current/messaging/send/email/ -Send the file's content in Base64. See [copies and attachments](/docs/workflows/transactional-emails/api#copies-and-attachments) for the limits. +Send the file's content in Base64. See [copies, attachments, and headers](/docs/workflows/transactional-emails/api#copies-attachments-and-headers) for the limits. ## Measure whether an email works diff --git a/contents/docs/workflows/transactional-emails/index.mdx b/contents/docs/workflows/transactional-emails/index.mdx index e5d94d14b3ef..7b8ecdf48100 100644 --- a/contents/docs/workflows/transactional-emails/index.mdx +++ b/contents/docs/workflows/transactional-emails/index.mdx @@ -90,10 +90,12 @@ You can write the email in PostHog, or send content that your code renders. Both | Who edits it | Anyone on your team, in the PostHog editor, with no deploy | Engineers, in your codebase | | Best for | Copy that changes often, and teams that want drafts, versions, and a preview | [React Email](https://react.email) or other templates that you already have, and a move from another email provider | | What a send carries | `template_id` and the template's variables | `template_key`, `subject`, and `html` or `text` | -| Copies and attachments | Not on the send | `cc`, `bcc`, and `attachments`, on the API | +| Copies and attachments | Not on the send | `cc`, `bcc`, `attachments`, and `headers`, on the API | The rest of this page covers emails that you write in PostHog. For content from your code, see your SDK's page or [the API](/docs/workflows/transactional-emails/api#send-content-from-your-code). +If an app can only send over SMTP, it can [send through PostHog over SMTP](/docs/workflows/smtp) with no code change. + ## Set it up with a coding agent With the [PostHog MCP server](/docs/model-context-protocol) in your coding agent, ask the agent to set up a transactional email. It can design the email from your brand, make it transactional, and write the code that sends it. It asks you to confirm before it makes a template transactional, and you create the API key yourself. diff --git a/src/navs/index.js b/src/navs/index.js index a18d82ec2e32..2a6faf2dccca 100644 --- a/src/navs/index.js +++ b/src/navs/index.js @@ -8363,6 +8363,10 @@ export const docsMenu = { name: 'API', url: '/docs/workflows/transactional-emails/api', }, + { + name: 'SMTP', + url: '/docs/workflows/smtp', + }, { name: 'Examples', url: '/docs/workflows/transactional-emails/examples',