How to Send Email From Novu With Volanea Using an HTTP Step

Novu can orchestrate notification workflows, while Volanea can handle the email delivery layer. This guide explains how to send email from Novu through Volanea’s REST API using Novu’s native HTTP step—without claiming there is a native Volanea app, marketplace listing, or one-click provider integration.

The integration is direct: your application triggers a Novu workflow event, the workflow reaches an HTTP action step, and that step makes an authenticated POST request to Volanea’s send endpoint. The critical implementation details are the payload contract, server-side secret storage, and an idempotency key that protects recipients from duplicate email when a workflow step is retried.

What this integration does—and does not do

Novu has a native HTTP step for calling external APIs during workflow execution. That makes it suitable for a direct Volanea integration: configure a POST request in the workflow, map fields from the workflow payload into Volanea’s email request, and store the Volanea secret key in a Novu environment variable.

This is not a native Volanea provider in Novu. There is no Volanea app to install from the Novu marketplace, no provider tile to connect, and no OAuth-style authorization flow between the products. The configuration is an HTTP request you own and maintain.

That distinction matters operationally. A native provider can sometimes hide request formatting and credentials behind a provider setup screen. With an HTTP step, you explicitly control:

• Which workflow event triggers the email.
• Which payload fields become recipient, subject, and content.
• Which Volanea sending domain and From identity are used.
• Which stable identifier becomes the Idempotency-Key.
• Which errors stop the workflow and which failures should be investigated.

The direct route is usually best when your application already triggers Novu from its backend and you want Novu to decide when an email belongs in a broader notification workflow. For example, an order confirmation can produce an in-app notification immediately, wait for a delay condition, call Volanea for the email, and later branch to another channel if your workflow requires it.

The concrete Novu trigger: a workflow event

In Novu’s model, an email does not begin with a database-record trigger inside the dashboard. It begins when your application triggers a workflow event through Novu’s Event API or a server-side SDK. A workflow has a trigger identifier, and your backend sends an event containing the target subscriber and a workflow payload.

For this guide, use a workflow with the trigger identifier order-confirmation. Your application triggers that workflow after it has durably created and paid for an order. The event payload includes all content required to send the receipt-like message.

The event should originate on your server or in a trusted background job, never from a browser. Novu’s secret key is server-only, and a browser-triggered event would make it easier for an attacker to generate notification runs or manipulate email content.

Here is a representative server-side trigger using the Novu JavaScript SDK:

import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: process.env.NOVU_SECRET_KEY!,
});

await novu.trigger({
  workflowId: 'order-confirmation',
  to: {
    subscriberId: `customer_${order.customerId}`,
    email: order.customerEmail,
    firstName: order.customerFirstName,
  },
  payload: {
    eventId: `order-paid:${order.id}`,
    orderId: order.id,
    recipientEmail: order.customerEmail,
    recipientName: order.customerFirstName ?? '',
    subject: `Your order ${order.number} is confirmed`,
    html: renderOrderConfirmationEmail(order),
    text: `Thanks for your order ${order.number}. Total: ${order.totalFormatted}.`,
  },
});

The workflow event—not “a record created” inside Novu—is the concrete trigger that starts the send. In your own application, the business event might be an account invitation accepted, a payment captured, a support ticket updated, or a deployment failed. What matters is that your backend turns that business event into a Novu workflow trigger with a complete and validated payload.

Use a payload schema in the workflow so Novu knows which fields are available to the HTTP step. In Novu’s current dashboard model, declared payload fields become available for workflow content and action-step configuration. This also prevents a silent mismatch where someone renames recipientEmail in application code but leaves an old field reference in the workflow.

A useful payload schema for this example requires eventId, orderId, recipientEmail, subject, html, and text. recipientName can remain optional. Keep the payload intentionally narrow: send the fields required for messaging, not an entire order object with addresses, payment metadata, or internal notes.

Why the Novu HTTP step is the right outbound capability

Novu’s HTTP step is an Action step that calls an external API while a workflow executes. It supports standard HTTP methods, a destination URL, headers, a request body, and an optional response schema for data that later workflow steps need to use.

For Volanea, configure a single HTTP step after any conditions, digests, or delays that should happen before email is accepted for sending. The request is made when the workflow execution reaches that step.

Do not confuse this with Novu’s outbound account webhooks. Account webhooks notify your endpoint about Novu-side events such as message status changes or workflow updates. They are useful for observability, but they are not the best mechanism for constructing a per-workflow Volanea send request. The HTTP step is built specifically for outbound calls inside an executing workflow.

You also do not need Zapier or Make for the direct version of this integration. Middleware can still be a sensible choice when you need transformations that Novu’s request editor cannot express, when your Novu plan does not provide secure environment variables, or when your organization requires all external credentials to remain inside its own secrets manager. But a standard direct implementation should use the native HTTP step first.

Prepare Volanea before configuring the workflow

Before you send production email, create a Volanea secret key and verify the sending domain that will appear in your From address. A Volanea secret key is a privileged credential: anyone who has it can attempt sends within the project’s permissions and limits.

Choose a From address on a domain you have verified in Volanea, such as receipts@example.com. Do not use a customer-provided address as the From value. If users should be able to reply, use Volanea’s single replyTo field with an address you operate, such as support@example.com.

The send endpoint is:

POST https://api.volanea.com/v1/send

Volanea’s single-message endpoint accepts one recipient or up to 50 recipients, but this workflow should normally send one recipient per execution. A one-recipient send keeps data exposure low, makes delivery investigation easier, and aligns cleanly with a Novu workflow targeted at one subscriber.

You should also decide where email markup is rendered. The most reliable option is to render final HTML in your application before triggering Novu and send that HTML in the workflow payload. This keeps template logic under version control and avoids making an HTTP-step body responsible for complex loops, currency formatting, locale logic, and escaping.

If you prefer to keep content in Volanea templates, send a templateId and only the data required by that template instead. That approach can be appropriate for reusable transactional messages, but it changes the payload map and requires the template to be deployed before the workflow is activated. For a first integration, explicit html and text fields are easier to test.

For endpoint details, request fields, domain setup, and delivery records, use the Volanea API reference and setup guides.

Store the Volanea API key in Novu safely

Create a Novu environment variable named VOLANEA_API_KEY. Set its type to string, mark it as secret, and provide separate values for Development and Production. Novu environment variables are environment-scoped, and secret values are encrypted at rest and masked in API responses.

Novu documents environment variables as a Pro-and-higher feature. If your plan does not include them, do not paste the Volanea secret key into a workflow header, workflow body, client-side JavaScript, a shared document, or a visible configuration field. Instead, use the relay pattern described later in this guide.

With environment variables available, the HTTP step header can refer to the secret using Liquid syntax:

Authorization: Bearer {{ env.VOLANEA_API_KEY }}

The key must not live in client-visible configuration for three reasons:

1. A Volanea secret key authorizes sending. Exposing it lets an attacker send unwanted mail, damage sender reputation, and consume your sending quota.
2. Workflow payloads are not a safe secrets store. A trigger payload may be logged, inspected during debugging, retained by application observability systems, or accidentally passed through another integration.
3. Frontend environment variables are often public by design. Variables prefixed for browser bundlers, embedded in a JavaScript bundle, or sent to a browser API route are not secrets even if their names imply otherwise.

Use distinct Volanea keys for test and production environments. Rotate a key by updating the Novu secret variable for the relevant environment, then revoke the old Volanea key after confirming new sends succeed. Keep the key out of source control and out of screenshots of the HTTP-step editor.

Configure the HTTP step to call Volanea

Create or open the order-confirmation workflow in Novu. Add an HTTP Action step at the point where email should be sent. For a straightforward confirmation workflow, it can be the first step. For a fallback workflow, it might appear after an in-app step and delay.

Set the HTTP step to POST and use this URL:

https://api.volanea.com/v1/send

Add these headers as key-value pairs in the HTTP-step editor:

Content-Type: application/json
Authorization: Bearer {{ env.VOLANEA_API_KEY }}
Idempotency-Key: novu-order-{{ payload.eventId }}

The exact body Novu sends is the body you configure in the HTTP step. Novu does not impose a fixed generic outbound-email payload here; it resolves your workflow variables and posts the resulting JSON to Volanea. The following request body maps the earlier workflow payload to Volanea’s single-message send request:

{
  "from": "receipts@example.com",
  "fromName": "Example Store",
  "to": "{{ payload.recipientEmail }}",
  "toName": "{{ payload.recipientName }}",
  "replyTo": "support@example.com",
  "subject": "{{ payload.subject }}",
  "html": "{{ payload.html }}",
  "text": "{{ payload.text }}"
}

This mapping is deliberately direct:

The equivalent request, after Novu renders the Liquid expressions for a paid order, looks like this:

curl --request POST 'https://api.volanea.com/v1/send' \
  --header 'Authorization: Bearer sk_live_replace_me' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: novu-order-order-paid:ord_01JXYZ' \
  --data '{
    "from": "receipts@example.com",
    "fromName": "Example Store",
    "to": "ava@example.net",
    "toName": "Ava",
    "replyTo": "support@example.com",
    "subject": "Your order 1042 is confirmed",
    "html": "<h1>Thanks, Ava</h1><p>Your order is confirmed.</p>",
    "text": "Thanks, Ava. Your order is confirmed."
  }'

Do not paste the curl example into Novu with a real key. It is a representation of the resolved request, not a recommended storage method. In Novu, the secret belongs only in VOLANEA_API_KEY.

If the HTTP step supports a response schema and later steps need to use the Volanea response, define only the response properties you actually need. For example, storing a returned message identifier can help correlate a workflow run with a Volanea send log. If no later step needs the response, omit the response schema rather than coupling your workflow to unnecessary API response fields.

Build a payload contract that survives real production data

A successful preview is not enough. Production data contains null names, malformed addresses, unescaped punctuation, localized characters, unusually large orders, and events that arrive out of order. Treat the Novu payload as a versioned integration contract.

Start by making the recipient address required. Even though Novu subscribers can have an email address, do not assume every subscriber record is populated or current. Your backend should either provide a validated recipientEmail in the payload or explicitly decide to skip the workflow for users without an email address.

Make eventId required and immutable. A stable event identifier should describe the logical business event, not the HTTP attempt. Good examples include order-paid:ord_01JXYZ, invite-created:inv_123, or ticket-status-changed:ticket_82:resolved. A timestamp generated every time a job retries is not stable and will defeat deduplication.

Avoid constructing rich HTML inside the HTTP body from individual user-generated fields. The request editor is not the right place to sanitize a comment, format arbitrary money values, or escape a customer-entered company name. Render HTML on a trusted backend with a proper email template system, provide both HTML and text in the trigger payload, and treat the content as final.

A robust payload policy should include:

• Required fields: eventId, recipientEmail, subject, html, and text.
• Size limits for subject and message content before you call Novu.
• A clear rule for absent optional fields such as recipient name.
• A controlled source for From and Reply-To values instead of passing them from arbitrary trigger payloads.
• A versioning plan when the workflow evolves, such as adding templateVersion or creating a new workflow identifier for a breaking change.

This also limits accidental data disclosure. A notification email generally needs an order number and a secure account link; it rarely needs raw payment details, internal support annotations, or the entire database record that caused the event.

Prevent duplicates with two layers of idempotency

Email delivery is an external side effect. The dangerous failure mode is not only a hard error; it is uncertainty. Novu might make the request, Volanea might accept it, and a timeout or network failure might prevent Novu from receiving the response. Retrying without a stable idempotency key can send a duplicate message.

First, protect the application-to-Novu hop. When your backend calls Novu’s Event API, send an Idempotency-Key header for that trigger request when your client supports it. Novu documents idempotency as the safe way to retry POST and PATCH requests without duplicate workflow runs. A transaction ID is useful for tracing a workflow but is not the same thing as an idempotency key.

Second, protect the Novu-to-Volanea hop. The HTTP step should send a Volanea Idempotency-Key derived from the stable logical event:

novu-order-{{ payload.eventId }}

Volanea supports safe retries through Idempotency-Key on POST /v1/send. Reusing the same key for the same logical email lets Volanea replay the original outcome instead of accepting another separate send during the idempotency window.

Do not derive this header from a workflow execution ID unless that ID remains the same across every retry of the same business event. Do not use a fresh random UUID generated at request time. Those values identify individual attempts, not the one email intent you want to protect.

There is one important design decision: define what “one logical email” means. An order confirmation normally has one immutable email intent, so order-paid:<order-id> is a good key. A status notification may legitimately be sent multiple times as a ticket moves through different states, so use a state transition identifier such as ticket:<id>:status:<version> rather than only the ticket ID.

When this breaks: troubleshoot the Novu-to-Volanea hop

Every integration should be designed around its realistic failure modes. This one has a specific hop: Novu executes an HTTP step, and Volanea accepts or rejects a REST email request. Diagnose both sides rather than assuming a Novu workflow failure always means the email provider failed.

Novu retries cause duplicate sends

HTTP steps participate in workflow retries. A retry can happen after a network timeout, transient upstream failure, or an ambiguous request outcome. Without a stable Volanea Idempotency-Key, the same workflow event can produce two emails.

Fix: derive the header from payload.eventId, which must be stable for one logical business event. Keep that value unchanged across application retries and workflow retries. Then inspect Volanea’s send log for the idempotency replay behavior when validating your setup.

Also protect the inbound trigger. If your job queue retries the call to Novu, use Novu’s own trigger idempotency support. Otherwise, you can create multiple workflow runs before the HTTP step has a chance to deduplicate external sends.

The HTTP request times out

Novu can time out waiting for an external API response even if the destination later completes work. This is exactly why the Volanea idempotency header is required. A timeout is ambiguous: it does not prove Volanea did not receive the request.

Fix: do not respond to the request through a slow custom proxy if you can call Volanea directly. When a proxy is necessary, make it accept the Novu request quickly, queue or perform the Volanea call with the same idempotency key, and return a deterministic status. Keep expensive template rendering, database joins, and third-party lookups out of the critical request path.

For direct sends, investigate both the Novu workflow execution and Volanea send log. If Volanea shows a send for the key but Novu marks the step as failed or timed out, the correct response is usually to preserve the idempotency key and fix the timeout—not to send another message manually.

Required payload fields are absent in a workflow run

A field can be present in a preview but missing in production because an older application worker still sends the old payload shape, a secondary event source does not populate it, or a workflow schema was edited without deploying matching application code.

Fix: declare required fields in the workflow payload schema, validate values before triggering Novu, and add an early workflow condition that only runs the HTTP step when recipientEmail, subject, html, and eventId are present. When an email should not be sent, skip intentionally and emit an application log or monitoring event; do not let a malformed address become a provider-side mystery.

If your Novu plan does not include environment variables, the key itself is the missing configuration field that matters most. Do not work around that limitation by hardcoding it into the HTTP step. Use the relay route below.

Volanea rejects the request

A rejected request commonly points to an invalid credential, a sender address that is not on a verified domain, malformed JSON, an invalid recipient address, or a request field that does not match the API contract.

Fix: test with a Volanea test key or development project first. Confirm the Authorization header resolves from the correct Novu environment variable, verify the From domain in Volanea, and use a known-safe recipient while testing. Keep the sender fields fixed in the workflow configuration instead of accepting them from an arbitrary event payload.

A successful HTTP response only means Volanea accepted the request for processing. It does not guarantee inbox placement or final recipient delivery. Use Volanea delivery events and send logs to distinguish accepted, suppressed, bounced, delivered, and complained outcomes.

Content is malformed or unsafe

If a payload field contains user-generated markup or unexpected characters, directly injecting it into HTML can create broken email layouts or unsafe content. A missing value can also render awkward strings such as Hello, or a literal null-like value.

Fix: generate the final email content in application code, test text and HTML outputs independently, and pass trusted final strings to Novu. Treat the Novu HTTP step as a transport mapping, not as a full template engine or sanitization layer.

Use a relay when direct secret storage is unavailable

If your Novu plan lacks secret environment variables, or your security policy requires API keys to reside only in your cloud provider’s secret manager, use a small server-side relay. Novu’s HTTP step calls your relay with a signed or otherwise authenticated request; the relay validates and maps that request, then calls Volanea with the API key stored in its own runtime environment.

The relay adds an extra component, but it provides stronger control over authentication, validation, rate limiting, audit logging, and transformations. It is also preferable if you want to keep Volanea request details out of the Novu editor.

The architecture becomes:

1. Your backend triggers the Novu order-confirmation workflow.
2. The workflow HTTP step posts the event payload to https://app.example.com/internal/novu/volanea-send.
3. The relay validates that the request came from Novu according to your chosen verification design.
4. The relay checks required fields and calculates or verifies the stable idempotency key.
5. The relay calls POST https://api.volanea.com/v1/send with VOLANEA_API_KEY from its server-side secrets manager.
6. The relay returns a fast success or failure response to Novu.

If you use Novu’s Tool webhook integration instead of the HTTP step for a relay pattern, Novu supports an HMAC signing secret and sends an X-Novu-Signature header. That is useful for verifying requests at your endpoint. For this direct Volanea use case, however, the HTTP action step is simpler because it can call Volanea without introducing an endpoint you must operate.

A relay should still pass through the same stable Idempotency-Key. Do not treat a relay as a reason to generate a new random key per attempt. Its job is to preserve the original message intent and make the send safe to retry.

Test the complete workflow before production

Test the system as one flow, not as isolated API calls. A successful Volanea curl request verifies credentials and sender configuration, but it does not verify that Novu’s Liquid field mappings resolve correctly. A successful Novu preview does not prove the HTTP step has a valid authorization header in Production.

Use a development Novu environment and a Volanea test key or non-production project where possible. Create a test subscriber with an inbox you control, trigger a workflow with a representative payload, and review the HTTP step’s rendered request and execution status.

A production-readiness checklist should include:

1. The workflow trigger identifier matches the backend’s workflowId.
2. The workflow payload schema declares every field used by the HTTP step.
3. The Volanea sender domain is verified and the from address belongs to it.
4. VOLANEA_API_KEY is a secret environment variable with a value in every target Novu environment.
5. The HTTP step uses POST https://api.volanea.com/v1/send.
6. The request includes Content-Type, Authorization, and Idempotency-Key headers.
7. The idempotency key is based on a stable business event ID, not a retry attempt.
8. HTML and text content render correctly for missing optional names and long values.
9. Your application logs the original event ID, Novu workflow run reference, and Volanea message reference where available.
10. A deliberate retry test does not produce a second recipient-visible email.

Do a duplicate test on purpose. Trigger the same logical event twice with the same event ID and verify that the Volanea idempotency behavior prevents a second send. Then trigger a genuinely different event with a different event ID and verify that it sends normally. This test proves the difference between reliable retries and accidental suppression of legitimate messages.

Operational guidance for deliverability and observability

Novu orchestrates the decision to send. Volanea handles the email pipeline, including suppression checks, dispatch, and delivery-related observability. Your operating model should join the two rather than treating them as interchangeable logs.

Use the business event ID as the shared trace value. Put it in the idempotency key and include it in your application logs. If you use custom message headers supported by your Volanea send configuration, you can also attach a non-sensitive correlation header, but do not put customer data or secret values in headers.

Monitor three categories of outcome:

• Workflow execution health: Did Novu trigger the workflow? Did the HTTP step execute, retry, skip, or fail?
• API acceptance health: Did Volanea accept the request, replay an idempotent response, reject the sender, or suppress the recipient?
• Email health: Did messages bounce, generate complaints, or show a sudden change in delivery patterns?

Keep transactional content operationally separate from campaigns. An order confirmation, password reset, or account alert should have its own clear sender identity and should not depend on a marketing audience workflow. That makes suppression behavior, incident handling, and deliverability monitoring easier to reason about.

Finally, be intentional about retry ownership. If Novu retries the HTTP step, do not add a second blind retry loop in your application specifically for the same Volanea request. Let the stable idempotency key make retries safe, but keep retry counts bounded and alerts actionable. Persistent 4xx errors generally require configuration or payload fixes; repeatedly retrying them only creates noise.

Conclusion

The cleanest way to send email from Novu with Volanea is a native Novu HTTP step that posts a mapped workflow payload to POST /v1/send. Your application starts the flow by triggering a Novu workflow event, Novu resolves the configured Liquid fields, and Volanea accepts the resulting transactional email request.

The integration is straightforward, but it should not be casual. Store the Volanea API key as a Novu secret environment variable, keep the key out of browser code and payloads, define a strict payload schema, and pass a stable Idempotency-Key on every Volanea send. Those choices turn a simple HTTP call into a production-safe notification path.

If your Novu plan or security model does not support secure environment variables, use a small relay rather than embedding credentials. The extra hop is preferable to a leaked sending key or an untraceable duplicate-email problem.

FAQ

Does Volanea have a native Novu integration?

No. This setup uses Novu’s native HTTP action step to call Volanea’s REST API. There is no Volanea marketplace app or provider installation flow required for this approach.

What starts the email in Novu?

Your backend triggers a Novu workflow event using the workflow trigger identifier, a subscriber target, and a payload. When the workflow reaches its HTTP step, Novu sends the configured request to Volanea.

Where should the Volanea API key live?

Store it as a secret Novu environment variable such as VOLANEA_API_KEY, referenced in the HTTP step’s authorization header. Never put it in frontend code, a browser-visible environment variable, or the workflow trigger payload.

How do I stop duplicate emails when Novu retries?

Send a Volanea Idempotency-Key based on a stable business event ID, such as novu-order-order-paid:ord_01JXYZ. Reuse that key for retries of the same logical email.

Do I need Zapier or Make to connect Novu and Volanea?

No. Novu’s HTTP step can call Volanea directly. Use a relay, Zapier, or Make only when you need additional transformations, governance, or a server-side place to store secrets because secure Novu environment variables are unavailable.