How to Send Email From Ongage With Volanea

Ongage is built to manage campaign audiences and marketing automation, while Volanea can handle the API call that delivers a transactional message. This guide explains how to send email from Ongage with Volanea without pretending there is a native Ongage app or marketplace plug-in.

The dependable architecture is simple: an Ongage automation event calls an outbound webhook, your server verifies and normalizes that request, and the server sends an email through Volanea. That small middleware layer is important. It keeps the Volanea API key private, gives you a place to prevent duplicate messages, and separates marketing-contact data from the rules for a transactional send.

The integration architecture

Ongage and Volanea solve different parts of an email program. Ongage manages contacts, lists, campaigns, and automation activity. Volanea is the sending service your application calls through SMTP or an API. Connecting the two does not turn Volanea into an Ongage campaign channel; it lets an event in Ongage initiate a message sent by Volanea.

The practical flow has four parts:

1. A contact reaches an Ongage automation trigger, such as being added or subscribed to the list that starts the automation.
2. The automation’s outbound webhook action posts contact and event data to an HTTPS endpoint you control.
3. That endpoint validates the request, maps the supplied contact fields to an email request, and creates an idempotency record.
4. The endpoint calls Volanea’s email API and records the result for support, monitoring, and replay protection.

This is deliberately not a browser-to-API integration. A contact should never receive JavaScript containing a live email API credential, and a public form should never be able to choose arbitrary recipients, sender identities, or message templates.

Why put middleware between the services?

It may be tempting to point the Ongage webhook directly at an email API URL. That approach is usually too brittle for a production transactional flow. It gives you limited control over validation, makes retries hard to reason about, and can expose a reusable credential in a third-party configuration.

A thin endpoint—an Express route, Cloudflare Worker, AWS Lambda, Vercel Function, or similar service—is enough. It can enforce your own rules: only send a welcome email for a known list, only use approved from domains, reject malformed addresses, and deduplicate a repeated event.

It also lets you evolve the implementation. For example, the same Ongage webhook can initially send a welcome email, later enqueue work to a queue, and eventually select a localized Volanea template without changing the automation’s destination URL.

What starts the send in Ongage

In this pattern, the concrete Ongage-side starting point is a contact entering the automation because it has been added or subscribed to the list used by that automation. The automation then reaches its outbound webhook action and posts to your middleware endpoint.

That distinction matters. A list event is not necessarily evidence that a person has just completed a website signup. Contacts can enter a list through imports, an API process, a synchronization, manual operations, or another automation. Before wiring a transactional email to the trigger, define which of those paths should create a send.

For a genuine signup confirmation, use a dedicated list or a field that only your signup process sets. For an account-status message, make the automation contingent on the status event or contact-field change that represents that status in your data model. Avoid using a broad master marketing list as the source of a sensitive operational email.

Make the trigger narrow enough to be safe

A good trigger definition includes both the business event and the audience boundary. For example:

• A contact is subscribed to product-signups, then receives a product onboarding message.
• A contact is added to trial-started, then receives a trial-start email.
• A vetted synchronization updates a custom field such as invoice_ready, then starts an automation that posts an invoice-notification request.

A weak definition is “a contact exists in Ongage.” That can result in a large historical audience entering a workflow after an import or automation edit. Transactional systems should be intentionally event-driven, not accidentally batch-driven.

Before enabling the webhook, test with a seed list containing only internal addresses. Confirm whether re-adding an existing contact, updating a contact, or importing a file can make the automation run again. Those behaviors determine the deduplication rule you need downstream.

Configure the outbound webhook payload

Configure the automation’s outbound webhook to call an HTTPS URL that you own, such as:

https://email-events.example.com/ongage/welcome

Use a request body that explicitly identifies the event and carries only the fields your sender needs. An outbound webhook is easier to maintain when it has a stable, purpose-built contract instead of forwarding every possible Ongage contact field.

A useful JSON body for a welcome-message automation looks like this:

{
  "event": "contact_subscribed",
  "event_id": "{{event_id}}",
  "contact_id": "{{contact_id}}",
  "email": "{{email}}",
  "first_name": "{{first_name}}",
  "list_id": "{{list_id}}",
  "list_name": "{{list_name}}",
  "occurred_at": "{{event_time}}"
}

The exact merge-field tokens available in an Ongage webhook depend on the automation context and the contact fields configured in the account. Use the webhook’s test or preview facility to inspect the resolved request from a real seed contact before deploying. Do not assume that a custom field is always present merely because it exists in your schema.

The important part is the resulting payload shape received by your endpoint. After merge values are resolved, your service should receive JSON like this:

{
  "event": "contact_subscribed",
  "event_id": "evt_9d4d91e8",
  "contact_id": "8421981",
  "email": "ada@example.net",
  "first_name": "Ada",
  "list_id": "3412",
  "list_name": "product-signups",
  "occurred_at": "2026-10-10T09:30:00Z"
}

Treat this request as input, not as trusted instruction. In particular, do not accept a from address, raw HTML, an arbitrary subject line, or a recipient list from the webhook body. Those values should be owned by your application.

Send a versioned contract

Add a schema_version field when you control the JSON body. A value such as 1 lets you introduce a new payload without silently breaking an old handler.

For example, if you later replace first_name with a nested contact object, create version 2 and let the endpoint support both versions during rollout. This is much safer than editing a live automation, deploying code, and hoping all delayed executions use the new body immediately.

Keep contact payloads minimal. Data minimization is good operational practice as well as a privacy principle: the webhook does not need a physical address, purchase history, or dozens of custom fields to send a basic welcome message.

Map the Ongage event to a Volanea email request

The middleware owns the field mapping. It converts Ongage’s event-oriented contact data into Volanea’s send request while keeping sender identity, template content, and business rules in code or server-side configuration.

The basic mapping is straightforward:

The example below uses Node.js with Express. It receives the JSON posted by Ongage, validates the event, ensures the same event cannot send twice, and makes the Volanea REST request. Set VOLANEA_API_KEY and your sender address as deployment secrets, not as source-code constants.

import express from "express";

const app = express();
app.use(express.json({ limit: "64kb" }));

const ALLOWED_LIST = "product-signups";
const sentEventIds = new Set(); // Use Redis or a database in production.

function escapeHtml(value = "") {
  return String(value)
    .replaceAll("&", "&")
    .replaceAll("<", "&lt;")
    .replaceAll(">", "&gt;")
    .replaceAll('"', "&quot;")
    .replaceAll("'", "&#039;");
}

function validEmail(value) {
  return typeof value === "string" && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
}

app.post("/ongage/welcome", async (req, res) => {
  const { event, event_id, contact_id, email, first_name, list_name, occurred_at } = req.body;

  // Accept only the event and source list this endpoint was created for.
  if (event !== "contact_subscribed" || list_name !== ALLOWED_LIST) {
    return res.status(202).json({ ignored: true });
  }

  if (!event_id || !contact_id || !validEmail(email)) {
    return res.status(400).json({ error: "Missing or invalid webhook fields" });
  }

  const idempotencyKey = `ongage:${event_id}`;
  if (sentEventIds.has(idempotencyKey)) {
    return res.status(200).json({ duplicate: true });
  }

  const name = escapeHtml(first_name || "there");
  const emailPayload = {
    from: process.env.VOLANEA_FROM,
    to: [email],
    subject: "Welcome to Example Product",
    html: `<p>Hi ${name},</p><p>Thanks for signing up. Your account is ready.</p>`,
    text: `Hi ${first_name || "there"},\n\nThanks for signing up. Your account is ready.`
  };

  const volaneaResponse = await fetch("https://api.volanea.com/v1/emails", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.VOLANEA_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey
    },
    body: JSON.stringify(emailPayload)
  });

  if (!volaneaResponse.ok) {
    const detail = await volaneaResponse.text();
    console.error("Volanea send failed", {
      status: volaneaResponse.status,
      contact_id,
      event_id,
      occurred_at,
      detail
    });
    return res.status(500).json({ error: "Email provider request failed" });
  }

  sentEventIds.add(idempotencyKey);
  const result = await volaneaResponse.json();
  console.info("Volanea email accepted", { contact_id, event_id, result });

  return res.status(202).json({ accepted: true, message: result });
});

app.listen(process.env.PORT || 3000);

Verify the current endpoint, request schema, authentication format, and idempotency support against the email API reference and setup guides before deployment. API providers can add fields or evolve conventions, and your production code should follow the version documented for your Volanea account.

Use a persistent idempotency store

The Set in the example makes the logic readable, but it is not durable. A server restart forgets it, and multiple server instances do not share it. Production systems should atomically store ongage:<event_id> in Redis, a database table with a unique constraint, or a purpose-built idempotency store.

Record a state such as processing, accepted, or failed, plus the Volanea message identifier returned by the API. That record lets you distinguish a safe retry from a new event and lets your support team answer the question “was this recipient sent this message?” with evidence rather than guesswork.

Keep the Volanea API key server-side

The Volanea API key belongs in a secret store or environment variable available only to the server-side component making the send. In this design, it lives in the deployment configuration for your middleware—such as VOLANEA_API_KEY—not in an Ongage contact field, an automation body, a browser form, a mobile app, or a public repository.

If your Ongage webhook configuration supports a static authentication header for your own endpoint, use that header for a separate inbound webhook secret. For example, configure a random value in an X-Webhook-Secret header and compare it server-side using a timing-safe comparison. That secret authenticates the Ongage-to-middleware hop; it is not the Volanea key.

Keeping those credentials separate provides two benefits. First, rotating the inbound webhook secret does not affect email sending. Second, compromise of the webhook configuration does not automatically grant an attacker the ability to send through Volanea from any machine.

What not to put in the webhook

Never send the Volanea credential as a query parameter, a JSON property, or a client-visible header. URLs are often retained in logs, reverse-proxy records, monitoring products, analytics tools, and support screenshots. Query-string secrets are especially difficult to remove once recorded.

Do not let the webhook body decide the sender domain. Sender control should be an allowlist in your code or configuration, backed by a domain you have authenticated for Volanea. This limits the effect of a malformed workflow or a compromised external source.

Use separate API keys where your account supports scoped or environment-specific credentials. Development and staging should not be able to send from a production sender identity or to a production customer audience.

When this breaks: failures in the Ongage-to-Volanea hop

A webhook integration is a distributed system. The automation can retry, your endpoint can time out, the endpoint can return success before work is durable, and the email API can accept a request just as the connection is lost. Design for these situations before they occur.

Retries can create duplicate sends

If Ongage does not receive a successful response from your endpoint, it may retry the webhook delivery. A network timeout is ambiguous: your endpoint might have sent the Volanea request successfully but failed to return its HTTP response before the connection closed.

That is why event_id must become an idempotency key. Store it before or during processing using an atomic operation. If the exact event arrives again, return a successful response indicating it is already handled instead of creating another send.

Do not deduplicate only on email address. One person can legitimately generate multiple events: a new trial, a password-reset request, a second purchase, or a different account. The event identifier is the correct unit of work; a recipient is not.

Webhook timeouts should not hold the request open

Your middleware should respond quickly. If template rendering, a database transaction, or the Volanea request can take long enough to challenge the webhook timeout, acknowledge the validated event after saving it durably and perform the actual send asynchronously with a queue worker.

The queue design is especially valuable during provider incidents. Your endpoint can accept and persist an event, workers can retry provider failures with backoff, and you retain a visible backlog instead of losing the connection between an automation execution and a message request.

Avoid returning a success response before the event is durably stored. Doing so prevents Ongage from retrying but leaves you with no recoverable record if the process crashes immediately afterward.

Missing fields are normal, not exceptional

A contact field can be absent because it was never collected, was added after older contacts were created, was excluded from a particular list process, or is unavailable in the webhook context. Some account configurations and plan capabilities can also affect which automation or contact-data features are available.

Code defensively. first_name can have a fallback like “there,” but email, event identity, and the business condition that authorizes the send should be required. If a required field is missing, return a clear non-success response only when retrying could genuinely fix it; otherwise record the rejected event and alert the owner to correct the workflow or data source.

For sensitive notifications, add a schema-validation layer with explicit rules. It should reject unexpected recipient arrays, invalid addresses, excessively long values, and unknown event types. Validation is not just a programming nicety—it prevents a marketing-data issue from becoming an email incident.

Deliverability and consent boundaries

A technically successful API response does not guarantee inbox placement. The Volanea sender domain should have the DNS authentication required by your account, and the visible From address should match the identity recipients expect for this type of message.

Separate campaign and transactional purposes even if the same person appears in both systems. A receipt, security alert, or account-access message may have a different legal basis and different urgency from a promotional campaign. Do not use a transactional webhook as a workaround for sending marketing content to contacts who are suppressed or unsubscribed from marketing.

Your handler should also respect the logic that makes a send appropriate. A welcome email can be triggered from a documented signup event. A sales message should not be transformed into a “transactional” send just to bypass a contact’s marketing preferences.

Build content for operational email

Include a text alternative as well as HTML, use a real reply-capable address where appropriate, and make the subject accurately describe the event. Personalization values must be HTML-escaped before insertion into markup; a contact’s first name is external input, not trusted HTML.

Keep the initial integration simple. One event, one approved sender, one template, one narrowly defined audience, and one persistent audit trail are far easier to test than a generic endpoint that can send any content on behalf of any automation.

Test the complete path before enabling it

End-to-end testing should cover more than whether a message appears in an inbox. Test the full business and operational path: contact event, automation execution, webhook delivery, endpoint validation, API acceptance, and email rendering.

Use a seed address at a domain you control. Add a distinctive test marker to the subject while you are testing, and log the webhook event identifier alongside the Volanea response identifier. Those two values make correlation much faster when investigating a delay or duplicate.

A practical pre-launch checklist is:

• Confirm the intended list event—and only that event—starts the automation.
• Inspect a real resolved webhook payload from a seed contact.
• Verify that the endpoint rejects an unknown list or event type.
• Test a missing optional name and a missing required email address.
• Deliver the same event_id twice and verify only one send request is accepted.
• Simulate a Volanea 5xx response and verify that the event is retried or queued safely.
• Confirm the API key is present only in server-side secret configuration.
• Check the rendered HTML and text message in major mailbox providers.

Test an old contact as well as a newly created one. Historical contact records are where empty custom fields, unexpected encodings, and legacy subscription states most often appear.

Observability, support, and audit records

Log structured identifiers, not message bodies or unnecessary personal data. At a minimum, retain the Ongage event ID, Ongage contact ID, event type, workflow/list identifier, your idempotency key, Volanea response status, provider message ID, and timestamps.

Do not routinely log API keys, full authorization headers, raw HTML, or a full webhook body containing more contact data than a support investigation needs. Redact recipient addresses where possible in broad operational logs, while retaining a secure audit path for authorized support staff.

Create alerts for sustained failures rather than every individual transient error. A short provider outage may create a few retries; a growing queue, repeated authentication failures, or a sudden increase in rejected payloads requires action. Metrics should distinguish events received, events rejected by validation, duplicate events, API requests accepted, and final delivery outcomes where available.

This is also where the middleware approach pays off. You can measure failures at each boundary rather than seeing only that an automation “ran” or that an API “was called.”

Alternatives when a webhook is not the right fit

An outbound webhook is a strong choice when you need immediate event handling and can run a small endpoint. It is not the only architecture.

If your team cannot operate a server-side endpoint, an automation service can receive an Ongage event and make an authenticated HTTP request to a service you control. However, do not move the Volanea production API key into client-side code merely to avoid middleware. A managed automation account still needs strict access control, secret handling, and duplicate protection.

If the event is actually generated by your own application—for example, a completed checkout or password reset—it is usually cleaner to call Volanea directly from that application. Writing contact data to Ongage can remain a parallel marketing synchronization task. That removes a round trip and makes the system of record for the transactional event unambiguous.

For teams comparing provider costs while choosing where to centralize application sends, review transactional email pricing alongside sending limits, support needs, and the operational cost of any middleware you plan to run.

Conclusion

To send email from Ongage with Volanea, use the automation’s contact/list event to invoke an outbound webhook, not a fictional native plug-in. Route the request through a server-side handler that validates the payload, applies your business rules, deduplicates retries, and sends a controlled Volanea API request.

The crucial engineering decisions are not the HTTP POST alone. They are defining a narrow trigger, making the payload contract explicit, keeping the API key out of Ongage contact data and browser code, and treating retries as normal. With those controls in place, the integration can support reliable event-driven messaging without turning an audience automation into an uncontrolled sending surface.

FAQ

Does Volanea have a native Ongage integration?

No native Ongage marketplace app or plug-in is assumed in this setup. The connection uses Ongage’s outbound webhook capability and a server-side middleware endpoint that calls Volanea.

What Ongage event should trigger the Volanea email?

Use the specific contact event that starts your automation, such as a contact being added or subscribed to a dedicated signup list. Avoid broad lists that can be populated by imports or unrelated synchronization jobs.

Where should the Volanea API key be stored?

Store it as a server-side deployment secret used by your middleware. Do not place it in a webhook body, URL, Ongage custom field, browser application, or public source repository.

How do I prevent duplicate emails after a webhook retry?

Use the Ongage event identifier as an idempotency key and store it in a durable shared database or cache. When the same event arrives again, return success without sending a second email.

What happens if an Ongage contact does not have a first name?

Treat nonessential personalization fields as optional and use a safe fallback such as “there.” Require the recipient email and an event identifier, because those are necessary to authorize and deduplicate the send.