Send transactional emails with the API

Use the API to send transactional emails from any language. The SDKs for Node.js, Python, Go, .NET, Rust, Ruby, Elixir, and PHP call this API, and retry with idempotency keys for you. If your language has an SDK, start there. The examples on this page show each SDK next to cURL.

You need a transactional email and a project secret API key first. The quick start sets up both and sends a test email in a few minutes.

Send an email

POST https://us.posthog.com/api/projects/@current/messaging/send/email/

Host - Use https://us.posthog.com or https://eu.posthog.com, the host where you log in to PostHog. Don't use an ingestion host like us.i.posthog.com. If you self-host PostHog, use the URL of your instance.
Project - @current is 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:

liquid

Hi {{ variables.first_name }}, use this link to reset your password: {{ variables.reset_link }}

Response

A successful request returns 202 Accepted:

JSON
{
  "message_id": "01963d8a-6f2c-7d4e-9b1a-3c5e8f2a7b10",
  "replayed": false
}

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

curl -X POST "https://us.posthog.com/api/projects/@current/messaging/send/email/" \
  -H "Authorization: Bearer $POSTHOG_PROJECT_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: password-reset-8f14e45f" \
  -d '{
    "template_id": "<template_id>",
    "to": "jane@example.com",
    "distinct_id": "user_123",
    "message_data": { "first_name": "Jane", "reset_link": "https://example.com/reset?token=abc123" }
  }'
const { data, error } = await posthog.emails.send({
    to: "jane@example.com",
    templateId: "<template_id>",
    templateData: { first_name: "Jane", reset_link: "https://example.com/reset?token=abc123" },
    distinctId: "user_123",
    idempotencyKey: "password-reset-8f14e45f",
})
result = posthog.emails.send(
    to="jane@example.com",
    template_id="<template_id>",
    template_data={"first_name": "Jane", "reset_link": "https://example.com/reset?token=abc123"},
    distinct_id="user_123",
    idempotency_key="password-reset-8f14e45f",
)
result, err := client.Emails().Send(ctx, posthog.TemplateEmail{
    To:             "jane@example.com",
    TemplateID:     "<template_id>",
    TemplateData:   map[string]interface{}{"first_name": "Jane", "reset_link": "https://example.com/reset?token=abc123"},
    DistinctID:     "user_123",
    IdempotencyKey: "password-reset-8f14e45f",
})
var result = await posthog.Emails.SendAsync(new SendTemplateEmailOptions
{
    To = "jane@example.com",
    TemplateId = Guid.Parse("<template_id>"),
    TemplateData = new Dictionary<string, object>
    {
        ["first_name"] = "Jane",
        ["reset_link"] = "https://example.com/reset?token=abc123",
    },
    DistinctId = "user_123",
    IdempotencyKey = "password-reset-8f14e45f",
});
let result = posthog
    .emails()
    .send(
        TemplateEmail::new("jane@example.com", "<template_id>")
            .template_data(json!({ "first_name": "Jane", "reset_link": "https://example.com/reset?token=abc123" }))
            .distinct_id("user_123")
            .idempotency_key("password-reset-8f14e45f"),
    )
    .await?;
result = posthog.emails.send(
  to: 'jane@example.com',
  template_id: '<template_id>',
  template_data: { first_name: 'Jane', reset_link: 'https://example.com/reset?token=abc123' },
  distinct_id: 'user_123',
  idempotency_key: 'password-reset-8f14e45f'
)
{:ok, result} =
  PostHog.Emails.send(
    to: "jane@example.com",
    template_id: "<template_id>",
    template_data: %{first_name: "Jane", reset_link: "https://example.com/reset?token=abc123"},
    distinct_id: "user_123",
    idempotency_key: "password-reset-8f14e45f"
  )
$result = PostHog::emails()->send([
    'to' => 'jane@example.com',
    'template_id' => '<template_id>',
    'template_data' => ['first_name' => 'Jane', 'reset_link' => 'https://example.com/reset?token=abc123'],
    'distinct_id' => 'user_123',
    'idempotency_key' => 'password-reset-8f14e45f',
]);

Each SDK page shows how to set up the client and handle errors.

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. It doesn't mean that the email failed, because PostHog can still send it. Retry with the same Idempotency-Key. If you resend the email through another email provider, the recipient can get it twice. The SDKs retry a 503 for you.

Link emails to your users

Pass the distinct ID that you pass to identify() as distinct_id. This is usually your user's ID. PostHog then records the email's engagement events, such as sent, opened, and clicked, on that user's person, in the same timeline as their product events.

No distinct ID - PostHog records the email on a person whose distinct ID is the email address. That's a different person from your user, unless your app identifies users by their email address.
Not a user yet - For an invite, or an email address check before the account exists, leave distinct_id out.

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.
`sensitive`	No	Whether the email is sensitive. Mark the email as sensitive when it carries login links, reset tokens, or codes. If you leave it out, the email takes the setting of the template with the same key, or is sensitive when no template has that key. See sensitive emails.
`tracking`	No	Whether PostHog tracks the email's opens and clicks, and captures its engagement events. Send `true`, `false`, or an object. If you leave it out, PostHog tracks opens and captures engagement events, and tracks clicks only when the email isn't sensitive. See open and click tracking.
`capture_engagement`	No	Deprecated. Use `tracking` with `engagement` instead. It still works: `false` turns off engagement events for this email, the same as `"tracking": {"engagement": false}`. A request can't have both `capture_engagement` and `tracking`.

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, sensitive, tracking, 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.

curl -X POST "https://us.posthog.com/api/projects/@current/messaging/send/email/" \
  -H "Authorization: Bearer $POSTHOG_PROJECT_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: password-reset-8f14e45f" \
  -d '{
    "template_key": "password-reset",
    "to": "jane@example.com",
    "distinct_id": "user_123",
    "subject": "Reset your password",
    "html": "<p>Hi Jane,</p><p><a href=\"https://example.com/reset?token=abc123\">Reset your password</a>.</p>",
    "from": "Hedgebox <security@example.com>"
  }'
const { data, error } = await posthog.emails.send({
    to: "jane@example.com",
    templateKey: "password-reset",
    subject: "Reset your password",
    html,
    from: "Hedgebox <security@example.com>",
    distinctId: "user_123",
    idempotencyKey: "password-reset-8f14e45f",
})
result = posthog.emails.send(
    to="jane@example.com",
    template_key="password-reset",
    subject="Reset your password",
    html=html,
    from_="Hedgebox <security@example.com>",
    distinct_id="user_123",
    idempotency_key="password-reset-8f14e45f",
)
result, err := client.Emails().Send(ctx, posthog.CodeEmail{
    To:             "jane@example.com",
    TemplateKey:    "password-reset",
    Subject:        "Reset your password",
    HTML:           html,
    From:           "Hedgebox <security@example.com>",
    DistinctID:     "user_123",
    IdempotencyKey: "password-reset-8f14e45f",
})
var result = await posthog.Emails.SendAsync(new SendCodeEmailOptions
{
    To = "jane@example.com",
    TemplateKey = "password-reset",
    Subject = "Reset your password",
    Html = html,
    From = "Hedgebox <security@example.com>",
    DistinctId = "user_123",
    IdempotencyKey = "password-reset-8f14e45f",
});
let result = posthog
    .emails()
    .send(
        CodeEmail::new("jane@example.com", "password-reset", "Reset your password")
            .html(html)
            .from("Hedgebox <security@example.com>")
            .distinct_id("user_123")
            .idempotency_key("password-reset-8f14e45f"),
    )
    .await?;
result = posthog.emails.send(
  to: 'jane@example.com',
  template_key: 'password-reset',
  subject: 'Reset your password',
  html: html,
  from: 'Hedgebox <security@example.com>',
  distinct_id: 'user_123',
  idempotency_key: 'password-reset-8f14e45f'
)
{:ok, result} =
  PostHog.Emails.send(
    to: "jane@example.com",
    template_key: "password-reset",
    subject: "Reset your password",
    html: html,
    from: "Hedgebox <security@example.com>",
    distinct_id: "user_123",
    idempotency_key: "password-reset-8f14e45f"
  )
$result = PostHog::emails()->send([
    'to' => 'jane@example.com',
    'template_key' => 'password-reset',
    'subject' => 'Reset your password',
    'html' => $html,
    'from' => 'Hedgebox <security@example.com>',
    'distinct_id' => 'user_123',
    'idempotency_key' => 'password-reset-8f14e45f',
]);

Sensitive emails

Mark the email as sensitive when it carries login links, reset tokens, or codes. For a sensitive email, PostHog:

Keeps links unchanged - PostHog doesn't rewrite the email's links to count clicks, so a token in a link never goes through a tracking redirect. tracking can still turn clicks on.
Leaves the subject off engagement events - The email's engagement events don't carry its subject.
Keeps no copy of the content - PostHog doesn't keep the email's subject or body.

sensitive takes true or false. If you leave it out:

A template has the same key - When a template in your project has the key that you send as template_key, the email takes that template's Protect sensitive data setting.
No template has the key - The email is sensitive.

Send "sensitive": false for an email that carries no secrets, such as an order confirmation. PostHog then tracks its clicks too, as it does for a template without Protect sensitive data. sensitive doesn't change opens or engagement events.

JSON
{
  "template_key": "order-shipped",
  "to": "jane@example.com",
  "subject": "Your order is on its way",
  "html": "<p>Hi Jane, your order has shipped.</p>",
  "sensitive": false
}

Open and click tracking

tracking decides what PostHog tracks for an email from your code. Send true, false, or an object with any of opens, clicks, and engagement:

`tracking`	Opens	Clicks	Engagement events
Left out	On	Follows `sensitive`	On
`true`	On	On	On
`false`	Off	Off	Off
An object	`opens`, on by default	`clicks`, default follows `sensitive`	`engagement`, on by default

Opens - PostHog adds an open pixel to the email, so it can count opens.
Clicks - PostHog rewrites the email's links to go through a tracking redirect, so it can count clicks.
Engagement events - PostHog captures the email's engagement events, such as sent, opened, and clicked, on the recipient's person. If the project's Capture email engagement events setting is off, PostHog captures nothing, whatever you send.

A key that you leave out of the object keeps its default, so {} is the same as leaving out tracking.

Clicks and sensitive emails

When you leave out clicks, PostHog tracks clicks only for an email that isn't sensitive. A tracked link goes through a redirect, so a login link or a reset token in it would go through the redirect too.

An email without secrets - Send "sensitive": false, and PostHog tracks its clicks.
A sensitive email with safe links - Send "tracking": {"clicks": true}, or "tracking": true. PostHog tracks its clicks, and keeps the email's other protections.
An email that isn't sensitive - Send "tracking": {"clicks": false} to keep its links unchanged.

A clicks value that you send wins over sensitive. To keep one link as it is, add data-ph-no-track or clicktracking="off" to its <a> tag, as for workflow emails.

Turn tracking off

With "tracking": false, the email goes out without the open pixel and without rewritten links. PostHog can't count its opens and clicks, and it captures no engagement events for it. You can still read the email's status. false also turns off any kind of tracking that PostHog adds later.

JSON
{
  "template_key": "welcome",
  "to": "jane@example.com",
  "subject": "Welcome to Hedgebox",
  "html": "<p>Hi Jane, welcome to Hedgebox.</p>",
  "tracking": false
}

In a form-encoded request, tracking and sensitive take true or false. Send JSON to use the tracking object.

Requests that PostHog refuses

PostHog returns a 400 and sends nothing when:

An unknown key - The object has a key other than opens, clicks, and engagement.
Clicks without opens - opens is false and clicks is true. Click tracking needs open tracking. Turn on opens, or turn off clicks. With opens set to false and clicks left out, PostHog tracks no clicks, whatever sensitive says.
Both fields - The request has tracking and capture_engagement. Move the value of capture_engagement to tracking.engagement.
A template send - The request has template_id and tracking or sensitive. A template uses its own settings.

Copies and attachments

Attachments are temporarily unavailable

A send with attachments gets a 400 error with the code invalid_request, and attr is attachments. PostHog sends nothing. Leave out attachments to send the email. cc and bcc work as described below.

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

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.

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:

GET https://us.posthog.com/api/projects/@current/messaging/emails/:message_id/

Send the same Authorization header as for a send. The key needs the transactional_email:read or transactional_email:write scope. A key with a hog_flow scope still works. Only a project secret API key can read a status.

A found email returns 200:

JSON
{
  "id": "01963d8a-6f2c-7d4e-9b1a-3c5e8f2a7b10",
  "status": "delivered",
  "created_at": "2026-10-28T16:27:44.364000Z",
  "status_at": "2026-10-28T16:27:49.625000Z",
  "reason": null
}

See statuses and reasons for what each value means.

A 404 with the code not_found right after a send means the status isn't there yet: a new send can take a few seconds to get its first status, so retry after a short wait. Later, a 404 means the email 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.

Example

curl "https://us.posthog.com/api/projects/@current/messaging/emails/<message_id>/" \
  -H "Authorization: Bearer $POSTHOG_PROJECT_SECRET_API_KEY"
const { data: status, error } = await posthog.emails.get("<message_id>")
status = posthog.emails.get("<message_id>")
status, err := client.Emails().Get(ctx, "<message_id>")
var status = await posthog.Emails.GetAsync("<message_id>");
let status = posthog.emails().get("<message_id>").await?;
status = posthog.emails.get('<message_id>')
{:ok, status} = PostHog.Emails.get("<message_id>")
$status = PostHog::emails()->get('<message_id>');

Send transactional emails with the API

Contents

Send an email

Request

Response

Example

`delivery_unavailable`

Link emails to your users

Send content from your code

Sensitive emails

Open and click tracking

Clicks and sensitive emails

Turn tracking off

Requests that PostHog refuses

Copies and attachments

Checks for content from your code

Check an email's status

Example

Still have questions?

Was this page useful?