---
title: "Send a transactional email"
method: POST
path: "/api/projects/{project_id}/messaging_templates/{id}/send/"
tags: ["messaging_templates"]
---

# Send a transactional email

`POST /api/projects/{project_id}/messaging_templates/{id}/send/`

## Request

- Base URL: `https://us.posthog.com`
- URL: `https://us.posthog.com/api/projects/{project_id}/messaging_templates/{id}/send/`
- Auth: HTTP bearer

Send one transactional email from this template to one recipient. The template must be made transactional first. `message_data` fills the template's `{{ variables.* }}` placeholders. Transactional emails skip opt-outs and frequency caps. Send an `Idempotency-Key` header to retry safely without sending the email twice.

## Path parameters

- `id` string, uuid, required
- `project_id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- SendTransactionalEmail
  - `to` string, email, required: Email address of the recipient.
  - `identifiers` TransactionalEmailIdentifiers
    - `distinct_id` string, nullable: Distinct ID of the recipient's person. The email's engagement events (sent, delivered, opened, clicked, bounced) and the send itself are recorded against that person. Defaults to the recipient's email address. The template can't read the person's properties, so pass everything it needs in `message_data`.
  - `message_data` object: Data for the template's Liquid placeholders, available as `variables`. For example `{"reset_link": "https://..."}` fills `{{ variables.reset_link }}`.

## Response `202`

Email queued

- SendTransactionalEmailResponse
  - `message_id` string, required: ID of the queued send. Delivery and engagement are reported against the template asynchronously.
  - `replayed` boolean, required: True when an earlier request with the same `Idempotency-Key` already queued this email. No new email was sent, and `message_id` is the earlier send's ID.

## Other responses

- `400`: The template isn't transactional or its email is paused, the recipient can't be used, or the Idempotency-Key is invalid
- `404`: Template not found
- `409`: A request with the same Idempotency-Key is still in progress
- `422`: The Idempotency-Key was already used for a different request
- `429`: Rate limited, or the project is over its email quota
- `503`: The email pipeline did not confirm the send

## Changes

> 53 revisions in range; 1 not diffed.

- **2026-10-21** `e263ffc38ef5`: 4 info
  - added the new optional `header` request parameter `Idempotency-Key`
  - added the non-success response with the status `409`
  - added the non-success response with the status `422`
  - added the required property `replayed` to the response with the `202` status
- **2026-10-16** `405eae87d089`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/posthog/apis/posthog-api/changes/api/projects/:project_id/messaging_templates/:id/send/post.md)

---

[API](https://skmtc.dev/posthog/apis/posthog-api.md) · [All operations](https://skmtc.dev/posthog/apis/posthog-api/llms.txt) · [OpenAPI document](https://skmtc.dev/posthog/apis/posthog-api/revisions/993f70ab941b?raw)