Skip to content
Closed
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
25 changes: 22 additions & 3 deletions contents/docs/workflows/transactional-emails/api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <security@example.com>`, 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`.

Expand Down Expand Up @@ -321,20 +322,38 @@ $result = PostHog::emails()->send([

</MultiLanguage>

### 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.

| Field | Required | Description |
| --- | --- | --- |
| `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 `<img src="cid:logo">`.
- **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": "<order-1042@example.com>",
"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.
Expand Down
4 changes: 2 additions & 2 deletions contents/docs/workflows/transactional-emails/examples.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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}` |

Expand All @@ -187,7 +187,7 @@ curl -X POST "https://us.posthog.com/api/projects/@current/messaging/send/email/

</MultiLanguage>

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

Expand Down
4 changes: 3 additions & 1 deletion contents/docs/workflows/transactional-emails/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 4 additions & 0 deletions src/navs/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
Loading