How to Send Email from PostHog with Volanea

PostHog can send email from PostHog when a meaningful product event occurs, and Volanea can handle the transactional delivery. The reliable route is PostHog’s native webhook destination: filter for one event, transform its event and person data into Volanea’s email payload, and send it to Volanea’s REST API.

There is no native Volanea app, marketplace listing, or one-click PostHog plugin to install. Instead, this integration uses PostHog’s real-time destination framework and its generic Webhook destination. That distinction matters: you own the trigger, field mapping, sender identity, and duplicate-prevention rules rather than relying on an opaque connector.

What this PostHog-to-Volanea integration does

This setup sends one transactional email after PostHog receives a specific event. In this guide, the concrete trigger is the custom PostHog event user signed up. Your application captures that event after it has successfully created an account and identified the person with an email address.

The resulting path is:

1. Your application creates a user and identifies that user in PostHog.
2. Your application captures user signed up with any useful event properties, such as a plan or workspace name.
3. PostHog’s Webhook destination filters for that event.
4. The destination builds a Volanea-compatible JSON email request from the PostHog event and person objects.
5. Volanea accepts the request at POST /v1/send, checks the sender and recipient state, then processes the message for delivery.

This is a good fit for lifecycle email that should happen because of behavior you already track: a welcome message after signup, a workspace invitation after an invitation event, a trial reminder after a backend-generated lifecycle event, or a notification after a user completes a product workflow.

It is not the right place to make email the source of truth for a critical business transaction. For example, an order receipt, password reset, or legal confirmation should normally originate from the application backend that committed the action. PostHog destinations are event-driven exports and should be treated as asynchronous side effects. If an email is required to complete a transaction, send it from the system that owns that transaction first, then capture the analytics event separately.

Why use a PostHog webhook destination

PostHog’s data pipeline destinations can react to events as they arrive. Its generic Webhook destination can send a request to any HTTP endpoint, with a configurable URL, method, headers, filters, and JSON body. It also supports templating with values from the incoming event, associated person, groups, and project context.

That is enough to call Volanea directly. You do not need Zapier, Make, or a custom relay merely to reshape an event into an email request. A direct destination has fewer moving parts, less delay, and one fewer system to monitor.

PostHog gives the destination an event context that includes values such as:

• event.uuid: the unique identifier for the tracked event
• event.event: the event name, such as user signed up
• event.distinct_id: the identity that created the event
• event.timestamp: when the event occurred
• event.properties: custom properties captured with the event
• person.properties: the latest properties on the associated person profile

The person object is especially useful for email, but it has an important implication: it represents the person profile available when PostHog processes the destination, not necessarily an immutable snapshot captured with the original event. If the recipient email must be tied exactly to the moment of signup, include it as an event property from your backend as well, or use a stable user ID and have your application send the email itself.

Prerequisites before you send

Before configuring PostHog, prepare the sending side in Volanea and the event side in your application.

First, verify the domain used in your From address in Volanea. Your chosen sender should use that verified domain, such as hello@updates.example.com. A valid API key alone does not authorize arbitrary From addresses, and an unverified sender should be treated as a configuration error rather than something to work around in a webhook template.

Second, create a Volanea secret API key. The send endpoint uses a secret key such as sk_... or sk_test_...; do not use a credential intended for browser code. The key permits an authenticated email action, so anyone who obtains it could send mail within its scope.

Third, make the PostHog trigger deliberate. For this guide, capture user signed up only after all of the following are true:

• the account record has been created successfully;
• the user has an email address you are willing and permitted to contact;
• the user has been identified in PostHog, or the event itself includes the email property you will map;
• any required product or marketing consent has been evaluated by your application.

A browser button click is usually too early. A visitor might abandon the flow, submit invalid data, refresh a page, or trigger the click multiple times. A backend event emitted after account creation is much more trustworthy.

Capture the user signed up trigger correctly

PostHog’s core model is the event. An event has an event name, a distinct_id, timestamp information, and properties. For this integration, the event that starts the email is exactly user signed up.

Capture it from your backend after user creation. The precise SDK varies by language, but the event data should conceptually look like this:

{
  "event": "user signed up",
  "distinct_id": "usr_01HV7KQ7S6M8X6F9D2ABCD1234",
  "properties": {
    "email": "ada@example.com",
    "first_name": "Ada",
    "plan": "starter",
    "workspace_name": "Analytical Engines"
  }
}

Also ensure the person has current profile properties. In particular, set email and, when available, first_name. You can use the event-level email property as the email payload source in the first version of this destination because it makes the send tied to the data captured at trigger time. Person properties are helpful for personalization, but are mutable and can be absent for anonymous traffic.

Avoid firing user signed up both in the browser and on the server. Two independently captured events are two legitimate destination triggers, even if they represent the same human action. Pick one authoritative producer. For most account creation flows, that is the backend.

Event naming and filtering

Use the exact same spelling and capitalization in PostHog’s destination filter as your captured event name. user signed up, User Signed Up, and user_signup are different event names.

Add narrow filters beyond the event name when useful. For example, you may want to send only if properties.environment equals production, or only if properties.signup_source is not admin_created. A welcome email for production users should not be sent because a developer replayed a test event or an administrator created an imported account.

Configure the Webhook destination in PostHog

In PostHog, open Data pipeline from the sidebar. Choose + New and then Destination, search for Webhook, and select Create. This is the generic destination that can send PostHog data to an HTTP endpoint.

Configure the request with these core values:

The Webhook destination sends a POST request with a templated JSON body by default, and you can customize that body. You can also edit the underlying destination implementation when you need a secret input or a computed header.

For this direct integration, create the destination inputs below. In the destination editor, use Edit source code, then Add input variable for values you want to retain as configurable inputs.

Mark volanea_api_key as a secret input. PostHog documents that destination inputs can be marked secret so they are encrypted at rest. Do not place the key in the outgoing JSON body, a URL query string, an event property, a dashboard note, frontend JavaScript, or a publicly readable feature-flag payload.

Why the API key belongs in a PostHog secret input

The Volanea API key lives on the PostHog side as a secret destination input, used only to construct the outbound Authorization header. It must not live in client-visible configuration because PostHog’s JavaScript SDK and browser-side event payloads are observable by the visitor using browser developer tools, network inspection, page source, extensions, and copied client bundles.

Your PostHog project token is designed for public event ingestion. A Volanea secret key is different: it authorizes email sending. Treat it like a production database password or payment-provider secret. Keeping it in a secret destination input means the browser never receives it and the incoming event does not carry it.

If your organization does not allow a third-party analytics destination to hold a sending credential, use a relay endpoint you control instead. The relay can authenticate PostHog using a separate shared secret, retrieve the Volanea API key from your cloud secret manager, validate the event, and make the send. That adds operational work, but it can satisfy stricter security boundaries.

Map the PostHog payload to Volanea’s send API

PostHog provides an event envelope and optional person data. The Webhook destination can turn those values into the request Volanea expects. The practical mapping for a welcome email is:

The following Hog code is the destination implementation. It builds the actual Volanea POST /v1/send call and maps fields explicitly rather than forwarding the raw PostHog event.

// PostHog Webhook destination: send a welcome email through Volanea.
// Required destination inputs:
// - volanea_api_key (secret)
// - from_email
// - from_name
// - welcome_url

let recipient_email := event.properties.email;
let first_name := event.properties.first_name;
let workspace_name := event.properties.workspace_name;

// Do not try to send if the trigger event did not include an address.
if (empty(recipient_email)) {
    print('Skipping Volanea send: user signed up event has no email', event.uuid);
    return;
}

let greeting_name := if(empty(first_name), 'there', first_name);
let workspace_label := if(empty(workspace_name), 'your workspace', workspace_name);

let email_body := {
    'from': {
        'email': inputs.from_email,
        'name': inputs.from_name
    },
    'to': [recipient_email],
    'subject': 'Welcome to ' + workspace_label,
    'html': '<!doctype html><html><body>' +
        '<p>Hi ' + greeting_name + ',</p>' +
        '<p>Your account is ready. Continue setting up ' + workspace_label + '.</p>' +
        '<p><a href="' + inputs.welcome_url + '">Open your workspace</a></p>' +
        '</body></html>',
    'text': 'Hi ' + greeting_name + ',\n\n' +
        'Your account is ready. Continue setting up ' + workspace_label + '.\n\n' +
        'Open your workspace: ' + inputs.welcome_url
};

let request := {
    'method': 'POST',
    'headers': {
        'Authorization': 'Bearer ' + inputs.volanea_api_key,
        'Content-Type': 'application/json',
        'Idempotency-Key': 'posthog-signup-' + event.uuid
    },
    'body': email_body
};

let response := fetch('https://api.volanea.com/v1/send', request);
print('Volanea send response', response.status, response.body);

The code uses the event UUID as the stable deduplication value because it identifies this particular PostHog event. The same event retried by PostHog retains its UUID, so the destination will present the same Idempotency-Key to Volanea. A genuinely separate signup event receives a new key.

Use a real link under your control for welcome_url. Do not concatenate arbitrary event values into an HTML URL. If URL paths or query parameters must vary per customer, use a backend-generated signed link or a fully validated event property instead.

A note about dynamic HTML

Event properties should not be inserted into HTML without considering escaping. A name or workspace title entered by a user can contain characters that break markup. The example is intentionally short so the mapping is visible, but production templates should either use trusted server-generated values or escape dynamic HTML properly before it reaches the email body.

For more complex layouts, reusable content, localization, or extensive personalization, use Volanea templates rather than embedding a large HTML document in a destination function. Keep the event destination focused on selecting the recipient, template data, and idempotency behavior. The email API reference and setup guides are the appropriate place to confirm the current template-send schema before implementing that variation.

Test the destination before enabling it

Do not begin with live signup traffic. PostHog’s destination editor includes a Testing section where you can run a test invocation and inspect what would be sent. Build a safe test event that contains every property required by the mapping:

{
  "event": "user signed up",
  "distinct_id": "test-user-001",
  "properties": {
    "email": "your-test-inbox@example.com",
    "first_name": "Ada",
    "plan": "starter",
    "workspace_name": "Test Workspace"
  }
}

Check four things during the test:

1. The destination filter matches. If the event does not appear in testing or logs, verify the name and filters before editing code.
2. The outgoing request has the expected body. Confirm the recipient, From address, subject, HTML, text, and idempotency header.
3. Volanea accepts the request. A successful API response means Volanea accepted the send request for processing; it is not proof that the inbox provider delivered the message.
4. The inbox content is usable. Review the From identity, subject, plain-text fallback, link, and personalization in a real test inbox.

After the test passes, enable the destination. Then watch PostHog’s destination logs and metrics during the first production sends. These help distinguish events filtered out by the destination from request failures returned by the target endpoint.

Delivery and sender identity considerations

A webhook call can be syntactically correct and still produce poor email results if the sender configuration is incomplete. Use a verified sending domain, a clear From name, a reply-capable address when replies matter, and copy that matches the event that triggered it.

Keep transactional and promotional intent separate. A welcome email that confirms account access and explains the next onboarding action is transactional in nature. A newsletter, recurring product announcement, or broad upsell campaign has different consent and unsubscribe expectations. Do not convert a behavioral trigger into a marketing blast solely because PostHog can export the event.

Recipient quality matters as well. An event may carry a malformed email, a temporary address, or an address that has previously bounced or been suppressed. Validate input at account creation, preserve your own consent and account-state rules, and understand that a send API accepting a request is not a guarantee that every recipient is eligible to receive it.

If signup happens through a public form, consider validating the address before the event is captured or before the account becomes active. The free email address verification tool can help check an address during testing or manual operations, but production signup validation should be part of your application flow rather than a manual afterthought.

When this breaks

The important failures in this integration occur at the hop between PostHog’s event pipeline and Volanea’s send API. Design for them before you need to investigate a missing or duplicated welcome email.

PostHog retries can cause duplicate send attempts

A network failure, timeout, or non-success response can leave PostHog unsure whether Volanea received the request. PostHog destinations use retryable HTTP behavior, so the same event may be attempted again. Without idempotency, that can create duplicate emails.

The defense is the Idempotency-Key header. The destination code derives it from event.uuid, not from a timestamp, recipient email, or random value. Do not generate a new random key on every retry. A changing key tells Volanea that every attempt is a new message.

Also avoid overlapping destinations. Two active destinations that both match user signed up and send the same welcome email will have different event-processing paths and can each legitimately send one message. PostHog recommends clear, non-overlapping workflows and destination logic because duplicated side effects are otherwise easy to create.

Webhook timeouts and unhealthy responses

PostHog expects destinations to return healthy non-5xx responses in a timely manner. Volanea’s direct API is preferable here because it avoids a slow custom application endpoint between PostHog and the email provider.

If you do use a relay, return a response only after you have durably decided what to do with the event. A relay that accepts the request, starts a background send, and crashes before persistence can lose the action. Conversely, a relay that waits on long-running work can time out and invite retries. A durable queue or database-backed idempotency record is the usual answer for a high-volume or business-critical relay.

For direct calls, check PostHog’s invocation logs for HTTP status codes and Volanea’s send logs for the corresponding request. The shared key is the PostHog event UUID, which should be included in your destination log messages and idempotency header value.

Missing payload fields and plan or data-collection gaps

Do not assume person.properties.email, event.properties.email, or other fields always exist. They can be absent because the event was captured before identification, because a backend integration did not include the property, because privacy settings or transformations removed it, or because the data pipeline configuration available to your PostHog plan does not expose the fields or destination behavior you expected.

The safe pattern is to require the email in the event filter where possible and to make the destination skip, rather than guess, when it is missing. The Hog example uses empty(recipient_email) and exits before making a request. This prevents messages addressed to null, a literal template placeholder, or an unintended fallback address.

Before committing to the integration, test the destination in the exact PostHog project and plan that will run it. Confirm that you can create a Webhook destination, use the inputs you need, mark the API key input secret, view test invocations, and access logs. Product capabilities and plan entitlements can change; your own project UI is the source of truth for what is enabled.

Person properties can be newer than the event

PostHog notes that destination person data reflects the latest profile information available during processing. A user who changes their email address shortly after signup could therefore have a newer profile email than the original signup event.

Use event.properties.email when you want the destination tied to the original trigger payload. Use person.properties.email when you deliberately want the latest known contact address. Do not silently switch between the two without documenting why, because that changes the business meaning of the email.

Sender failures and suppressed recipients

A rejected or skipped send can have nothing to do with PostHog. Common causes include an unverified From domain, an unauthorized sender address, an invalid recipient, a previously bounced or unsubscribed recipient, account limits, or a malformed API request.

Separate the investigation into layers: first verify the PostHog event and filter, then verify the destination request and HTTP response, then inspect Volanea’s sender and message status. That sequence avoids treating an email deliverability issue as an analytics issue, or vice versa.

When to use a middleware route instead

A direct PostHog-to-Volanea destination is the simplest choice when the email is straightforward and PostHog is permitted to hold the Volanea secret as an encrypted destination input. Use it for a single event, a narrow filter, a stable sender, and limited personalization.

Use a middleware route when you need one or more of the following:

• central secret management outside PostHog;
• organization-specific authorization checks before sending;
• complex HTML escaping or template rendering;
• database lookups for current account state;
• a durable queue, rate control, or custom retry policy;
• signed deep links or per-user tokens;
• auditing requirements that require writing a local send record first.

The webhook destination then points to your endpoint instead of Volanea. Your endpoint verifies a shared secret, validates the event shape, saves an idempotency record keyed by event.uuid, and sends the mapped request to https://api.volanea.com/v1/send using an API key stored in your server-side secret manager.

That architecture is more involved, but it gives your application final control. It is particularly appropriate if user signed up has legal, billing, or entitlement implications beyond a simple welcome email.

Operational checklist for production

Before enabling production sends, work through this checklist:

• Capture user signed up only after successful account creation.
• Emit the event from one authoritative producer, ideally the backend.
• Include a valid email event property for the trigger.
• Verify the Volanea sender domain and From address.
• Store the Volanea key as a secret PostHog destination input.
• Filter out staging, internal, imported, and test events.
• Use event.uuid in an Idempotency-Key header.
• Skip the send when the recipient address is missing.
• Test with a real inbox before enabling the destination.
• Monitor PostHog destination logs and Volanea send results after launch.
• Document who owns the event schema, email copy, sender identity, and incident response.

The most reliable integration is usually the least clever one: one clear event, one authoritative source, one destination, one stable idempotency key, and a small payload with only the fields required for the email.

Conclusion

To send email from PostHog with Volanea, use PostHog’s Webhook destination rather than looking for a nonexistent native plugin. Trigger it from a specific event such as user signed up, map the event properties into Volanea’s POST /v1/send payload, keep the Volanea key in a secret destination input, and use the PostHog event UUID as the idempotency key.

That combination makes the integration direct while preserving essential safety controls. It also gives you a clean boundary: PostHog decides when the behavioral event qualifies, while Volanea handles authenticated transactional sending and downstream delivery processing.

FAQ

Does Volanea have a native PostHog integration?

No. Volanea does not provide a native PostHog app, marketplace listing, or one-click plugin. Use PostHog’s generic Webhook destination to call Volanea’s REST API directly, or send to your own middleware endpoint first.

What exactly triggers the email in this setup?

The trigger is the PostHog custom event user signed up. Configure the Webhook destination to process events and filter specifically for that event name, plus any production or consent filters your application requires.

Where should I store the Volanea API key in PostHog?

Store it as a secret input variable on the PostHog destination. Use it only in the server-side destination request header as Authorization: Bearer <key>. Never include it in browser code, event properties, public configuration, or the webhook URL.

How do I prevent duplicate emails when PostHog retries a webhook?

Set Idempotency-Key to a stable value derived from event.uuid, such as posthog-signup-{event.uuid}. A retry of the same PostHog event must send the same idempotency key, not a newly generated value.

Should I use PostHog for receipts and password-reset emails?

Usually no. Those messages are business-critical and should normally be sent by the application backend that creates the order, account state, or reset token. Use the PostHog-to-Volanea path for asynchronous lifecycle messaging where an event-driven side effect is appropriate.