Send transactional emails with the API
Contents
Use the API to send transactional emails from any language. For Node.js and Python, the Node.js SDK and the Python SDK handle retries and idempotency keys for you.
Before you start, create a transactional email and create a project secret API key.
Send an email
- Host: Use
https://us.posthog.comorhttps://eu.posthog.com, the host where you log in to PostHog. Don't use an ingestion host likeus.i.posthog.com. If you self-host PostHog, use the URL of your instance. - Project:
@currentis the project that the key belongs to. You can use your project ID instead.
Request
Send these headers:
| Header | Value |
|---|---|
Authorization | Bearer followed by your project secret API key |
Content-Type | application/json |
Idempotency-Key | Optional. A unique key for this email. See retry safely. |
Send a JSON body with these fields:
| Field | Required | Description |
|---|---|---|
template_id | Yes | The ID of the transactional template to send. |
to | Yes | The email address of the recipient. One address for each request. |
message_data | No | An object with the values for the template's {{ variables.* }} placeholders. For example, {"reset_link": "https://example.com/reset"} fills {{ variables.reset_link }}. The template can't read person properties, so pass all the data that the email needs here. |
distinct_id | No | The distinct ID of the recipient's person. PostHog records the send and its engagement events against this person. Pass the distinct ID that you pass to identify(). See link emails to your users. |
In the template, use the same names that you send in message_data:
Response
A successful request returns 202 Accepted:
A 202 means that PostHog queued the email. It doesn't mean that the email was delivered. To see what happened to the email, check its status with its message_id, or open the template's Sends tab.
replayed is true when an earlier request with the same Idempotency-Key already queued this email. In that case, PostHog sent no new email, and message_id is the ID of the first send.
Example
The older route, POST /api/projects/@current/messaging_templates/:template_id/send/, still works. It takes the template ID in the URL and the distinct ID as identifiers.distinct_id.
When a send fails, the response carries a code. See errors and the checks for content from your code.
delivery_unavailable
A 503 with the code delivery_unavailable means that PostHog couldn't confirm that it queued the email. PostHog might still send it. Retry with the same Idempotency-Key rather than sending the email through another provider, or the recipient can get it twice. The SDKs retry this on their own.
Link emails to your users
Pass the distinct ID that you pass to identify(), usually the ID your app gives that user, as distinct_id. PostHog then records the send, and its engagement events such as sent, opened, and clicked, against that user's person, next to their product events.
- If you leave it out, PostHog records the email against a person whose distinct ID is the recipient's email address. Unless your app identifies users by their email address, that's a separate person from your user.
- For someone who isn't a user yet, such as an invite or an email address check before the account exists, there's no distinct ID to pass. Leave
distinct_idout.
Send content from your code
You can also send the subject and the body from your code, without a template in PostHog. Use this when your code renders the email. For a React Email component, render it to HTML with render from @react-email/render, and send the result as html. Name the email with template_key, and send the content in the body. Use the same POST route and headers as for a template send.
| Field | Required | Description |
|---|---|---|
template_key | Yes | A name for this email, such as password-reset. It has at most 400 letters, digits, hyphens (-), and underscores (_). PostHog groups the metrics and the sends of this email under the key, so use the same key every time you send this email. |
to | Yes | The email address of the recipient. |
distinct_id | No | The distinct ID of the recipient's person, as for a template send. See link emails to your users. |
subject | Yes | The subject of the email. |
html | One of html and text | The HTML body. PostHog sends it as you wrote it and renders no placeholders. |
text | One of html and text | The plain-text body. If you leave it out, PostHog makes it from html. |
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. 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. |
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.
If the to address is on the suppression list, PostHog sends nothing and returns recipient_suppressed.
The response is the same 202 as for a template send. A retry with the same Idempotency-Key is the same request when every field in the table above has the same value as in the first request. PostHog also compares the sender that it chose: if you leave out from and the project's default sender changes before the retry, PostHog returns idempotency_key_reused.
Checks for content from your code
These checks apply to content from your code, in addition to the errors of every send. PostHog sends nothing when a check fails.
| Status | Code | Cause | What to do |
|---|---|---|---|
400 | A code for the field, such as required or invalid | A field is missing or breaks a rule above, or PostHog doesn't take the field. The type is validation_error, and attr names the field, such as subject. | Fix the field. If the field comes from a newer SDK, update PostHog or leave the field out. |
400 | sender_not_verified | No verified sender of the project can send from the from address. Or the request has no from, and the project has no verified default sender. | Send from an address on a verified domain, or set a default sender and leave out from. |
Check an email's status
To find out what happened to an email, read its status with the message_id from the send:
Send the same Authorization header as for a send. The key needs the hog_flow:read or hog_flow:write scope. Only a project secret API key can read a status.
A found email returns 200:
See statuses and reasons for what each value means.
A 404 with the code not_found means the status isn't there yet, is older than 30 days, or the ID is wrong. See when a status isn't found. It returns 401 when the request has no project secret API key, 403 when the key doesn't have a Workflow scope, and 429 when you read too often.
Each project secret API key can read 600 statuses per minute and 20,000 per hour. All the keys of one project share the same limits in total. Reads have their own limits, so they don't use up the limits for sends.