Send transactional emails with Node.js

The Node.js SDK sends transactional emails from version 5.61.2. Before you start, create a transactional email and create a project secret API key.

Install

npm install posthog-node

Set up the client

Reuse the PostHog client your application already creates, and set secretKey to your project secret API key. The client still captures events with your project token. Shut the client down when your application exits, not after each send.

import { PostHog } from "posthog-node"

const posthog = new PostHog("<ph_project_token>", {
    host: "https://us.i.posthog.com",
    secretKey: process.env.POSTHOG_PROJECT_SECRET_API_KEY,
    // This client only sends email, so it doesn't poll flag definitions with the secret key
    enableLocalEvaluation: false,
})

• Local evaluation: The client starts polling flag definitions with the secret key when it starts. A key with only the Workflow scope can't do that, so a client that only sends email needs enableLocalEvaluation: false. If your application evaluates flags locally with the same client, give the key the Feature flag read scope too, and leave local evaluation on.
• Host: On PostHog Cloud, the client sends email to the app host of your region, even when host is an ingestion host such as us.i.posthog.com. For any other host, such as a reverse proxy or a self-hosted instance, set appHost to your PostHog app URL. The client refuses to send the secret key to a host that might be a proxy.

Send an email

export async function sendPasswordReset({ userId, email, firstName, resetLink, resetRequestId }) {
    const { data, error } = await posthog.emails.send({
        to: email,
        templateId: "<template_id>",
        templateData: { first_name: firstName, reset_link: resetLink },
        distinctId: userId,
        // Identifies this one email, so a retry never sends it twice
        idempotencyKey: `password-reset-${resetRequestId}`,
    })
    if (error) {
        // An EmailError. Branch on error.code
        throw error
    }
    return data.id
}

send returns { data, error } and doesn't throw. data.id is the message ID. error is an EmailError with the code from the errors table. After a network_error or a 503, PostHog might have queued the email. Retry with the same idempotency key rather than sending the email through another provider, or the recipient can get it twice.

Timeouts and retries

Each request times out after 15 seconds. The client retries network errors, rate limits, an in-flight idempotency key, and a 503 up to two times, with the same idempotency key. It waits about 1 and then 2 seconds, or longer if the server's Retry-After asks for it. A Retry-After over 30 seconds returns the error at once.

To change this, set emailRequestTimeoutMs and emailRequestMaxRetries on the client, or maxRetries on one send. When a job queue already retries the send, set the retries to 0 and pass an idempotencyKey that identifies the email.

Link emails to your users

Pass the distinct ID that you pass to identify(), usually the ID your app gives that user, as distinctId. 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 distinctId out.

Send content from your code

From version 5.62.0, send also takes content that your code rendered, without a template in PostHog. Name the email with templateKey, and pass subject and html, text, or both. PostHog sends the content as you wrote it.

For a React Email component, render it to HTML with render from @react-email/render, and pass the result as html:

import { render } from "@react-email/render"
import { PasswordResetEmail } from "./emails/password-reset"

export async function sendPasswordReset({ userId, email, firstName, resetLink, resetRequestId }) {
    const html = await render(<PasswordResetEmail firstName={firstName} resetLink={resetLink} />)
    const { data, error } = await posthog.emails.send({
        to: email,
        templateKey: "password-reset",
        subject: "Reset your password",
        html,
        from: "Hedgebox <security@example.com>",
        distinctId: userId,
        idempotencyKey: `password-reset-${resetRequestId}`,
    })
    if (error) {
        throw error
    }
    return data.id
}

• Key: templateKey names the email, such as password-reset. PostHog groups the email's metrics and sends under it, so use the same key every time you send this email.
• Text: If you leave out text, PostHog makes it from html.
• Sender: from needs an address on a domain that your project verified. Without it, PostHog uses the project's default sender. replyTo takes one address or a list.
• Engagement: PostHog captures the email's engagement events unless you pass captureEngagement: false.
• One form per send: A send has templateId or templateKey, not both. Content from your code takes no templateData, because PostHog renders nothing.

See content from your code for each field and its checks.

Check an email's status

export async function emailBounced(messageId) {
    const { data: status, error } = await posthog.emails.get(messageId)
    if (error) {
        if (error.code === "not_found") {
            // The first status can take a few seconds to arrive. Try again later.
            return null
        }
        throw error
    }
    return status.status === "bounced"
}

get returns { data, error }. data has id, status, createdAt, statusAt, and reason. See statuses and reasons. The client doesn't retry a not_found, so retry it yourself a few times, with a wait in between, before you treat the email as missing. A status that isn't there yet doesn't mean the email failed.

Test without sending email

Pass your own fetch to check what your code sends, without a network call. This checks your integration, not delivery. To check delivery, send a real email to your own address.

import assert from "node:assert/strict"
import { PostHog } from "posthog-node"

const requests = []
const posthog = new PostHog("phc_test", {
    secretKey: "phs_test",
    enableLocalEvaluation: false,
    fetch: async (url, options) => {
        requests.push({ url, options })
        return new Response(JSON.stringify({ message_id: "msg_1", replayed: false }), { status: 202 })
    },
})

const { data } = await posthog.emails.send({
    to: "jane@example.com",
    templateId: "<template_id>",
    idempotencyKey: "password-reset-1",
})

assert.equal(data.id, "msg_1")
assert.equal(requests[0].options.headers["Idempotency-Key"], "password-reset-1")