Sending email from Mantle does not require a native marketplace app: you can send email from Mantle by subscribing to a Mantle webhook and routing that event through a small server-side endpoint that calls Volanea’s REST API. This pattern keeps your email credentials private, gives your application control over message content, and makes retries safe.

Mantle is the event source in this setup. Volanea is the delivery layer. Your own serverless function, API route, or lightweight service sits in between, receives the Mantle webhook, decides whether an email should be sent, maps the customer data into an email payload, and makes POST https://api.volanea.com/v1/send.

There is one important constraint to state upfront: Volanea does not provide a native Mantle app, Mantle marketplace listing, or one-click plugin. Do not look for an “install Volanea” flow inside Mantle. The supported integration route is Mantle’s webhook capability, which can notify an external HTTPS endpoint about relevant app activity such as customer and plan activity.

The architecture for sending email from Mantle

The reliable version of this integration has four pieces:

A Mantle webhook subscription for the business event that should start the email.
A private HTTPS endpoint you operate, such as /api/webhooks/mantle.
A decision and mapping layer that validates the event, selects recipients, and builds the email.
A Volanea REST API request that dispatches the message with an idempotency key.

The request flow is deliberately simple:

Mantle event
  → Mantle webhook POST
    → your server-side webhook endpoint
      → event validation + recipient checks + deduplication
        → Volanea POST /v1/send
          → inbox provider

This is preferable to putting email-sending logic into browser code. Mantle’s app-facing API credentials and Volanea secret keys are server credentials. A customer can inspect browser JavaScript, network requests, local storage, and build artifacts. Any secret placed there should be considered exposed.

A small middleware hop also gives you a durable place to implement rules that should not live in a generic automation: only welcome real customers, skip test accounts, avoid sending to missing or malformed addresses, choose a locale, attach an internal event identifier, and handle an uncertain network result without sending the same message twice.

Choose the Mantle trigger that should start the email

The concrete trigger for a common welcome-email implementation is a Mantle customer installation event. Mantle’s notifications and webhook capabilities cover app events including installs, subscription changes, billing events, reviews, affiliate activity, and custom usage events. For an onboarding email, subscribe to the customer-install activity rather than trying to infer installation from a later usage event.

That event is a good fit for a message such as:

“Welcome—here is how to get started.”
“Your app account is connected.”
“Complete these three setup steps.”
“Your trial has started.”

For lifecycle email, choose the event that represents the actual business transition. A plan change should trigger a plan-change email. A subscription cancellation should trigger a cancellation confirmation or recovery sequence. A custom usage event should trigger a product-specific message only when that event is intentionally part of your customer communication policy.

Avoid using a dashboard action as an email trigger

A dashboard action is not necessarily a customer lifecycle event. For example, an internal teammate editing a note, revisiting a customer record, or changing a reporting filter should not cause a customer email. Configure the Mantle webhook around the actual app event: installation, a subscription transition, billing activity, or a custom usage event.

This distinction prevents a costly category of automation error: a message that appears correct in testing but sends unexpectedly when staff use the dashboard in normal operations.

Start with one event and one message

For the first release, make the integration intentionally narrow:

One Mantle event type.
One recipient: the customer email address supplied by Mantle.
One sender domain that is authenticated in Volanea.
One message purpose.
One stable idempotency key per source event.

Once that works in production, extend the handler to cover plan upgrades, cancellations, failed payments, or product milestones. A narrow first integration makes it much easier to inspect raw webhook traffic and confirm what customer data is actually present for your app.

Configure Mantle to deliver a webhook

In your Mantle app, create a webhook subscription for the app-install event or the specific subscription/customer event you selected. Mantle’s webhook setup documentation describes this as configuring a webhook for your app so Mantle can deliver activity notifications to an external endpoint.

Use a production HTTPS URL you control, for example:

https://app.example.com/api/webhooks/mantle

For local development, use a secure tunnel only while testing. Do not leave a temporary debugging endpoint configured for production customer events. Webhook payloads can contain customer and subscription information, and an abandoned public request-inspector URL is not an acceptable production destination.

Your handler must return a successful response quickly. Treat receiving a webhook and sending an email as separate responsibilities. The receiver should validate and persist or enqueue the event, then return success. A background worker can perform slower work if your application architecture supports one.

Capture a real Mantle delivery before finalizing field mappings

Mantle publicly documents that it delivers webhooks for customer and plan-related activity, but your integration should use a captured test delivery as the contract for your selected event. This matters because the availability of customer fields depends on the source platform, the event type, and what your application supplied when identifying the customer.

For the integration below, the required business fields are intentionally minimal:

{
  "customer": {
    "id": "customer identifier",
    "email": "customer@example.com",
    "name": "Customer name"
  }
}

Those are the customer properties your sending logic needs. Mantle’s JavaScript client documentation shows customer objects with identifiers, names, email addresses, custom fields, plans, subscriptions, features, and usage data. Do not assume every one of those properties is present in every webhook or for every customer. In particular, plan and subscription data are context-dependent; an install event can occur before a paid subscription exists.

The safest implementation does two things: it logs a redacted test payload during setup, and it extracts only fields that your message truly requires. The code below accepts the two practical envelope locations commonly handled by webhook middleware—customer directly or a data.customer wrapper—but rejects an event when the required email address cannot be found. Adjust the extraction function to the exact body in your captured Mantle delivery before production deployment.

Map Mantle customer data to a Volanea email

The mapping is not a hand-wavy “send customer email” step. You need to choose how each source field becomes a sending field.

Mantle customer data	Volanea email field	Why it is needed
`customer.email`	`to[0].email`	The recipient mailbox.
`customer.name`	`to[0].name` and message greeting	Optional personalization; fall back safely when absent.
`customer.id`	custom event identifier and idempotency key	Associates one logical email with one Mantle customer event.
event identifier or webhook delivery identifier	`Idempotency-Key`	Stops webhook retries from creating duplicate email sends.
subscription or plan data, when present	subject/body conditional content	Lets you tailor email content without making it required.

Keep the email recipient separate from the email sender. Your authenticated sender is an address on a domain you own, such as hello@updates.example.com. The customer’s address belongs in to, never in from.

Before sending, authenticate the sender domain in Volanea and use an address on that authenticated domain. Authentication is a deliverability requirement, not merely a dashboard setup task: recipients and mailbox providers need a consistent, authorized sender identity.

For endpoint details, request format, and additional sending options, see the email API reference and setup guides.

Working webhook-to-Volanea code

This Node.js example is an HTTP handler suitable for adapting to a framework API route, a serverless function, or an Express application. It shows the full hop: parse the Mantle webhook, locate the customer, validate the recipient, create a deterministic idempotency key, and call Volanea.

The code intentionally reads VOLANEA_API_KEY from server-side environment configuration. It does not accept a Volanea key from Mantle’s payload, a browser request, or a client-visible environment variable.

import crypto from "node:crypto";

const VOLANEA_SEND_URL = "https://api.volanea.com/v1/send";

function getMantleCustomer(payload) {
  // Confirm the selected event's exact envelope with a captured Mantle test
  // delivery. These two branches keep the mapping explicit and fail closed.
  return payload?.customer ?? payload?.data?.customer ?? null;
}

function getEventIdentity(payload, requestId) {
  // Prefer the stable delivery/event ID from the actual Mantle payload when
  // available. The fallback is deterministic for this welcome-email example.
  return (
    payload?.id ??
    payload?.eventId ??
    payload?.data?.id ??
    requestId ??
    null
  );
}

function makeIdempotencyKey({ eventIdentity, customerId, eventName }) {
  const logicalOperation = [
    "mantle",
    eventName || "customer-install",
    eventIdentity || customerId,
    "welcome-email-v1",
  ].join(":");

  return crypto
    .createHash("sha256")
    .update(logicalOperation)
    .digest("hex");
}

export async function handleMantleWebhook(req, res) {
  // In Express, configure JSON parsing before this handler. In frameworks that
  // provide a Request object, replace req.body with await request.json().
  const payload = req.body;
  const customer = getMantleCustomer(payload);

  if (!customer?.id) {
    return res.status(400).json({ error: "Mantle customer id is required" });
  }

  if (!customer?.email || !customer.email.includes("@")) {
    // Return a successful acknowledgment only if you deliberately want to
    // discard events with no contactable recipient. Otherwise queue for review.
    return res.status(202).json({
      skipped: true,
      reason: "Mantle event has no usable customer email",
    });
  }

  const eventName = payload?.event ?? payload?.type ?? "customer-install";
  const eventIdentity = getEventIdentity(payload, req.get?.("x-request-id"));
  const idempotencyKey = makeIdempotencyKey({
    eventIdentity,
    customerId: customer.id,
    eventName,
  });

  const firstName = customer.name?.trim()?.split(/\s+/)[0] || "there";

  const volaneaPayload = {
    from: {
      email: "hello@updates.example.com",
      name: "Example App",
    },
    to: [
      {
        email: customer.email,
        name: customer.name || undefined,
      },
    ],
    subject: "Welcome to Example App",
    html: `
      <h1>Welcome, ${escapeHtml(firstName)}!</h1>
      <p>Your account is connected and ready to use.</p>
      <p><a href="https://app.example.com/get-started">Complete your setup</a></p>
    `,
    text: `Welcome, ${firstName}! Your account is connected and ready to use. Complete your setup: https://app.example.com/get-started`,
  };

  const response = await fetch(VOLANEA_SEND_URL, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.VOLANEA_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify(volaneaPayload),
  });

  const responseBody = await response.text();

  if (!response.ok) {
    console.error("Volanea send failed", {
      status: response.status,
      customerId: customer.id,
      eventName,
      responseBody,
    });

    // Return a retryable failure only after deciding how Mantle handles failed
    // webhook deliveries in your configuration. The same idempotency key makes
    // a repeated Volanea request safe for this logical email.
    return res.status(502).json({ error: "Email provider send failed" });
  }

  return res.status(200).json({
    accepted: true,
    customerId: customer.id,
    eventName,
  });
}

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

What the Volanea request does

The request is a POST to https://api.volanea.com/v1/send. It supplies:

A sender in from.
One recipient in to.
Both HTML and plain-text message versions.
A human-readable subject.
An Authorization header with the secret Volanea API key.
An Idempotency-Key that represents this one welcome-email operation.

Volanea’s single-message send endpoint supports one recipient or multiple recipients, scheduling, and idempotency protection. For a customer lifecycle message, send one recipient at a time unless the event is genuinely a multi-recipient notification. One-customer-per-send makes suppression, personalization, auditing, and troubleshooting clearer.

Keep the Volanea API key on the server

The Volanea API key belongs in a server-side secret store or environment variable attached to the service receiving Mantle’s webhook. Typical names include VOLANEA_API_KEY, VOLANEA_SECRET_KEY, or a managed secret named for the production environment.

Do not store it in any of these places:

Browser JavaScript or frontend environment variables.
A Mantle custom field that can be exposed to customer-facing application code.
A public webhook URL query string.
Source control, example .env files committed to a repository, or screenshots.
A client-side automation configuration visible to users of your app.

The reason is straightforward: the Volanea API key authorizes email sending. Anyone who obtains it may be able to send mail as your authenticated domain, consume sending capacity, damage sender reputation, or access API behavior that should remain private.

Your Mantle webhook URL may need its own verification mechanism as well. If Mantle provides a webhook secret or signature for the subscription, verify that signature against the raw request body before parsing and acting on the payload. Do not invent a header name or hashing scheme—use the signature format shown in your Mantle webhook configuration and documentation for the specific subscription.

If the webhook setup does not provide a signature secret, put a high-entropy secret in an HTTPS path segment or another private server-side validation layer, restrict accepted request methods to POST, and rate-limit the endpoint. This is weaker than a signed request, so prefer an official Mantle signing mechanism when available.

Make retries safe with idempotency

Webhooks are not an exactly-once delivery mechanism. A source platform can retry because your endpoint timed out, returned a non-success status, experienced a network interruption, or completed work but lost the response connection. Your handler may also retry the Volanea request after an uncertain failure.

Without protection, this failure sequence sends two welcome emails:

Mantle posts an installation event.
Your handler sends the email successfully.
The connection closes before Mantle sees your successful acknowledgment.
Mantle retries the webhook.
Your handler sends the email again.

The Idempotency-Key header addresses the Volanea side of that problem. Use the same key for every retry of the same logical email operation. Do not generate a random UUID inside a function each time the webhook arrives; that would make every retry appear new.

A strong idempotency key is derived from a stable Mantle event or delivery identifier. If your selected Mantle event does not include a stable delivery ID, store a deduplication record in your database keyed by a combination such as customer ID, event name, and a business transition identifier. Be cautious with using only customer ID: a customer can legitimately install, cancel, and return later, and those can deserve different emails.

Persist your own event record for critical flows

For revenue, billing, or compliance messages, add a small database table or queue before calling Volanea. Store at least:

The Mantle event identity, if provided.
The customer identifier.
The event type.
The exact idempotency key.
The intended message type or template version.
Processing state: received, queued, sent, skipped, or failed.
The Volanea response identifier when available.

That record is more useful than application logs alone. It lets you answer operational questions quickly: Was the event received? Did it have an email address? Was it intentionally skipped? Did Volanea accept the send? Did a retry reuse the same idempotency key?

Test the integration before using it for customer messaging

Do not begin with a real customer installation. Use a test customer or sandbox-like app environment and confirm the entire route in stages.

Configure Mantle to post the chosen event to a temporary secured inspection endpoint.
Trigger the actual event, such as an app installation.
Save a redacted copy of the payload and confirm where customer ID, name, and email appear.
Point Mantle at your server-side handler.
Log only safe metadata: event type, customer ID hash, recipient domain, and response status.
Send to a mailbox you control.
Trigger the same event or replay the captured request to test duplicate protection.
Confirm the message is rendered correctly in HTML and plain text.
Confirm the authenticated sender domain aligns with the displayed sender address.
Switch to production only after the output and idempotency behavior are verified.

Test more than the happy path. Use a customer record with no name, no email, a non-ASCII name, a subscription with no plan, and a test or internal account. Those are normal data conditions in SaaS systems, not edge cases that can be ignored forever.

When this breaks

This integration has a specific failure boundary: Mantle delivers an outbound webhook, your endpoint processes it, then your endpoint calls Volanea. Debug the hop where the failure occurs instead of treating “email did not arrive” as one undifferentiated problem.

Mantle retries create duplicate sends

A duplicate email usually means the webhook was delivered more than once or your handler retried after an ambiguous response. It does not necessarily mean Mantle malfunctioned. At-least-once delivery is a normal pattern for event integrations.

Use a stable Idempotency-Key derived from the source event identity. If you maintain a database record, enforce a unique constraint on the logical message key as a second line of defense. Keep the message version in the key or record so a deliberate new version of an email can be sent intentionally rather than being mistaken for a retry.

Your webhook endpoint times out

A timeout can happen before Volanea is called, while Volanea is called, or after Volanea accepts the message but before your endpoint responds to Mantle. The last case is the dangerous one because the email may be sent even though Mantle sees a failed delivery.

Keep the synchronous webhook handler small. Validate the event, write an event record or enqueue a job, return promptly, and have a worker send the email. If you choose to send synchronously, set conservative outbound timeouts and preserve the same idempotency key on retry.

Payload fields are missing for some customers or plans

Do not assume a customer record always has a subscription, an active plan, a name, or even an email suitable for the message you want to send. Mantle customer data can vary by source platform, lifecycle state, and what your app supplied during customer identification.

Treat customer.id and customer.email as separate requirements. A customer may be identifiable but not contactable. Treat plan and subscription data as optional unless the selected event specifically guarantees it. If an upgrade email requires a plan name, skip or queue the event for review when the required plan field is absent rather than sending a misleading generic message.

The sender is rejected or messages land in spam

Check that the exact from.email domain is authenticated in Volanea and that your message content matches the event that caused it. A welcome message sent after an installation is expected; a promotional email triggered by a billing failure is not. Also verify that you are not retrying and sending multiple nearly identical messages within a short period.

Recipient quality matters too. For flows where email is entered manually or comes from a less trusted source, verify addresses before sending. Volanea provides a free address verification tool for checking whether an address is likely usable before it enters a transactional flow.

A change in payload shape breaks the handler

Fail closed. If the handler cannot locate the required customer ID or email, do not construct a request with undefined recipient data. Return a controlled status, record enough redacted diagnostics to investigate, and update the mapping based on an actual recent Mantle delivery.

Avoid brittle deep property chains throughout your code. Centralize extraction in one function, as in getMantleCustomer(), and cover it with unit tests using saved, sanitized webhook fixtures.

Direct webhook versus an automation intermediary

A direct Mantle webhook to your service is the recommended route when you can deploy even a small serverless handler. It keeps the Volanea API key in infrastructure you control, gives you full control over idempotency, and lets you log or queue events under your own retention policy.

An automation intermediary can be useful when your team cannot operate a server endpoint. For example, Mantle can post to a webhook-capture trigger in an automation platform, which can then make an authenticated API request to Volanea. However, check carefully how that platform stores credentials and whether everyone who can edit the workflow can view the key.

The direct route is usually better for production customer lifecycle email because it makes the integration boundary explicit:

Mantle owns the lifecycle event.
Your service owns validation, policy, and deduplication.
Volanea owns email sending and deliverability infrastructure.

That separation also makes later changes easier. You can change email content, switch to templates, add a queue, or branch by plan without reworking the Mantle event subscription.

Production checklist

Before enabling this workflow for real customers, verify each item below.

Conclusion

To send email from Mantle with Volanea, use Mantle as the event source and Volanea as the delivery API. Configure a Mantle webhook for a real lifecycle event such as a customer installation, receive that webhook at your own private endpoint, validate the customer data, and send the resulting message through POST /v1/send.

The implementation succeeds or fails on a few practical details: keep the Volanea key server-side, map only fields you have confirmed in a real Mantle payload, authenticate your sender domain, and reuse a stable idempotency key when Mantle or your own code retries. Those details turn a basic event-to-email connection into a reliable production workflow.

FAQ

Does Volanea have a native Mantle integration?

No. Volanea does not ship a native Mantle marketplace app or plugin. The integration uses Mantle webhooks and Volanea’s REST API through a server-side endpoint you control.

What Mantle event should send a welcome email?

Use the Mantle customer installation event for a welcome or onboarding email. Use a subscription-change event only when the message is specifically about a plan, upgrade, downgrade, cancellation, or billing transition.

Where should I store the Volanea API key?

Store it in the server-side environment or a managed secret store for the webhook handler. Never expose it in frontend code, browser-visible configuration, public URLs, or customer-facing application data.

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

Send the same Idempotency-Key header for every retry of the same logical Mantle event. Derive that key from a stable event or delivery identifier when available, and add your own database deduplication record for critical workflows.

What if the Mantle webhook has no customer email address?

Do not send. Record the event as skipped or queue it for review. A customer ID alone is not a deliverable email recipient, and plan or subscription fields should also be treated as optional unless confirmed for your selected event.

How to Send Email From Mantle With Volanea