How to Send Email from Mailcoach with Volanea

Mailcoach is built to run newsletters, subscriber journeys, and automations; Volanea is built to deliver application and campaign email through SMTP and an API. To send email from Mailcoach with Volanea without exposing credentials or relying on a marketplace plugin, connect a Mailcoach automation webhook to a small server-side relay that calls the Volanea REST API.

There is an important constraint up front: Volanea does not ship a native Mailcoach app, marketplace listing, or one-click connector. The dependable integration is therefore a webhook-based one, where Mailcoach emits an automation event and your server translates that event into a Volanea send request.

What this integration does—and what it does not do

This pattern is useful when a Mailcoach subscriber action should cause a separate email to be sent through Volanea. Examples include alerting an account owner when a high-value subscriber joins a list, sending an operational handoff message after a subscriber reaches a journey step, or notifying an internal team when a subscriber receives a tag.

It is not the same thing as replacing Mailcoach's normal campaign mailer. Mailcoach can send campaigns and automation mail through its configured mailer. A webhook relay is most valuable when the event must leave Mailcoach and become a separately controlled API send, with its own sender, template logic, audit trail, and delivery handling.

The route looks like this:

1. A subscriber meets a Mailcoach automation trigger.
2. Mailcoach reaches a Webhook action in that automation and posts subscriber context to your HTTPS endpoint.
3. Your endpoint verifies that the request is genuinely from your Mailcoach installation.
4. The endpoint maps the received fields into Volanea's email-send payload.
5. The endpoint makes the authenticated Volanea API request.
6. It records the result and returns a fast success or failure response to Mailcoach.

That separation matters. Mailcoach owns the subscriber and automation state; the relay owns transformation, secrets, idempotency, and the outbound Volanea call.

The concrete Mailcoach trigger: an automation subscriber event

Mailcoach automations are subscriber-centric. The event that starts the flow is an automation trigger associated with a subscriber, such as a subscriber joining an email list or a subscriber being given a tag. The outgoing HTTP request itself happens later, when that subscriber reaches the automation's Webhook action.

For a practical first implementation, use a subscriber-joins-list trigger. It is easy to test, has a clear business meaning, and gives the Webhook action a subscriber record to work with.

A typical sequence is:

1. Create or open the Mailcoach automation for the relevant email list.
2. Choose the trigger for a subscriber subscribing to that list.
3. Add any delay, condition, or tag checks that should happen before the external send.
4. Add a Webhook action.
5. Point that action at an endpoint you control, such as https://email-relay.example.com/mailcoach/volanea.
6. Publish or activate the automation, then subscribe a test address.

The key distinction is that “a form was submitted” is not usually the outbound integration event in Mailcoach. A form may create or update a subscriber, but your integration should key off the automation event Mailcoach records: the subscriber entered the automation and subsequently reached the Webhook action.

Choose a trigger that is stable enough to retry

A subscribe trigger is appropriate for welcome-like operational sends. A tag-added trigger is often better for sales or lifecycle handoffs, because it lets another system decide when the subscriber is qualified before Mailcoach begins the external action.

For example, an automation could start when a subscriber receives the request-demo tag. A condition can then check that an email address exists and that a required custom attribute, such as company, is present. Only then should the Webhook action call the relay.

Avoid treating every subscriber update as a send trigger unless you have a strict deduplication strategy. Profile edits, imports, and repeated form submissions can otherwise produce multiple nearly identical outbound messages.

Why a relay is the recommended connection point

It may seem simpler to put a Volanea API key directly in the Mailcoach Webhook action and post to Volanea from Mailcoach. In practice, a relay is safer and more maintainable.

First, a Mailcoach subscriber payload is not automatically an email-send payload. Mailcoach knows fields such as subscriber email, name, tags, and custom attributes; Volanea needs fields such as recipient, sender, subject, and HTML or text content. The relay is the appropriate place to create that mapping.

Second, a webhook URL and headers are integration configuration, not a secure template system. If you place a long-lived Volanea credential in a broadly accessible admin setting, export, screenshot, or configuration store, it becomes harder to control who can send from your domain. The API key should stay in a server-side secret store or environment variable, where it is never returned to a browser or included in a Mailcoach payload.

Third, the relay can implement protections that an outbound webhook alone cannot reliably provide:

• Verify a shared webhook secret before doing any work.
• Reject malformed or incomplete subscriber data.
• Deduplicate retries with an idempotency key.
• Separate development and production senders.
• Log Volanea response IDs without logging full email content.
• Return quickly enough that Mailcoach does not consider a successful send attempt timed out.

If you need API syntax, authentication details, or domain setup guidance while building the relay, keep the email API reference and setup guides next to the implementation rather than guessing at production credentials or endpoint behavior.

The payload Mailcoach posts to the relay

The Webhook action runs in the context of the subscriber progressing through the automation. The meaningful data is the subscriber record and its attributes. Your relay should expect a subscriber object, but it should also validate the actual body received from your Mailcoach installation before promoting the workflow to production.

A representative subscriber-focused payload used by a relay looks like this:

{
  "subscriber": {
    "id": 4812,
    "uuid": "d0fb96c3-0d34-4ef2-82d5-4c3ec753a510",
    "email": "ada@example.net",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "extra_attributes": {
      "company": "Analytical Engines Ltd",
      "plan": "team"
    },
    "tags": [
      { "name": "request-demo" }
    ],
    "subscribed_at": "2026-10-08T10:21:48+00:00",
    "unsubscribed_at": null
  }
}

The fields you should treat as essential are the subscriber email and an event identifier you can use for idempotency. The subscriber UUID is usually a better stable identity than a database ID because numeric IDs can differ between environments. However, a subscriber identity alone is not enough to identify one send: one subscriber may legitimately reach the same webhook more than once.

Inspect a real test delivery before finalizing the mapper

Do not assume every attribute is populated. first_name, last_name, tags, and extra_attributes can be absent, empty, or shaped differently depending on the subscriber's origin and the Mailcoach version or configuration. Imported subscribers in particular may have no first name, and custom attributes only exist when your data collection process supplied them.

During setup, point the Webhook action temporarily to a request inspector you control or to a development endpoint that stores only a redacted sample. Subscribe a test recipient, then compare the observed JSON to the mapper below. This is how you catch differences such as a missing subscriber wrapper, an empty attributes object, or tags represented as strings rather than objects.

Never use an untrusted custom attribute directly in HTML without escaping it. Subscriber profile data can originate from a public form, CRM sync, or CSV import. The relay should encode dynamic text before adding it to an HTML email.

Working relay code: Mailcoach fields to a Volanea email request

The following Node.js example uses Express. It accepts the Mailcoach webhook, validates a shared secret supplied in an HTTP header, maps subscriber fields, and calls the Volanea REST email endpoint. The Volanea key is read from the server environment, never from Mailcoach or client-side JavaScript.

import express from "express";
import crypto from "node:crypto";

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

const {
  MAILCOACH_WEBHOOK_SECRET,
  VOLANEA_API_KEY,
  VOLANEA_API_URL = "https://api.volanea.com/v1/emails",
  VOLANEA_FROM = "Lifecycle <lifecycle@updates.example.com>",
  INTERNAL_ALERT_TO = "sales@example.com"
} = process.env;

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

app.post("/mailcoach/volanea", async (req, res) => {
  // Configure this same secret as a header value on the Mailcoach Webhook action.
  const suppliedSecret = req.get("x-mailcoach-webhook-secret") || "";
  if (!MAILCOACH_WEBHOOK_SECRET || !
      crypto.timingSafeEqual(
        Buffer.from(suppliedSecret.padEnd(MAILCOACH_WEBHOOK_SECRET.length)),
        Buffer.from(MAILCOACH_WEBHOOK_SECRET)
      )) {
    return res.status(401).json({ error: "unauthorized webhook" });
  }

  const subscriber = req.body?.subscriber ?? req.body;
  const email = subscriber?.email?.trim().toLowerCase();
  const firstName = subscriber?.first_name?.trim() || "there";
  const company = subscriber?.extra_attributes?.company?.trim() || "Unknown";
  const subscriberUuid = subscriber?.uuid || subscriber?.id;

  if (!email || !subscriberUuid) {
    return res.status(422).json({ error: "subscriber email and identity are required" });
  }

  // In production, persist this key with a unique constraint before sending.
  // Include the automation/webhook execution ID too when Mailcoach provides one.
  const idempotencyKey = `mailcoach-demo-alert:${subscriberUuid}:request-demo`;

  const volaneaPayload = {
    from: VOLANEA_FROM,
    to: [INTERNAL_ALERT_TO],
    reply_to: email,
    subject: `Demo request from ${firstName}`,
    text: `${firstName} (${email}) requested a demo. Company: ${company}.`,
    html: `<p><strong>${escapeHtml(firstName)}</strong> requested a demo.</p>
           <p>Email: <a href="mailto:${escapeHtml(email)}">${escapeHtml(email)}</a><br>
           Company: ${escapeHtml(company)}</p>`
  };

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

  const responseBody = await response.text();
  if (!response.ok) {
    console.error("Volanea send failed", {
      status: response.status,
      subscriberUuid,
      responseBody
    });
    return res.status(502).json({ error: "email provider request failed" });
  }

  console.info("Volanea email accepted", { subscriberUuid, responseBody });
  return res.status(202).json({ accepted: true });
});

app.listen(3000, () => console.log("Webhook relay listening on port 3000"));

This example intentionally sends an internal alert rather than sending back to the subscriber. To email the subscriber, change to: [INTERNAL_ALERT_TO] to to: [email], choose a verified Volanea sender, and make the subject and content match the automation's consent and expectations.

The important field mapping is explicit:

Configure authentication without exposing the Volanea key

On the Mailcoach side, configure only the relay URL and a webhook-specific shared secret header, for example X-Mailcoach-Webhook-Secret: <random-value>. That secret lets the relay reject random internet traffic before it considers sending email.

The Volanea API key does not live in Mailcoach in this recommended design. It lives in the relay's server-side secret manager or environment configuration as VOLANEA_API_KEY. On a hosted platform, use that platform's encrypted environment-variable facility. In a container deployment, inject it at runtime. In a Laravel or Node deployment, do not commit it to .env.example, source control, frontend bundles, or a Mailcoach custom-attribute field.

Treat the shared webhook secret and Volanea API key as separate credentials with separate jobs:

• The Mailcoach webhook secret authenticates Mailcoach to your relay.
• The Volanea API key authenticates the relay to Volanea.
• Neither secret should be included in an email body, URL query string, browser request, or client-visible configuration.

Rotate the webhook secret if an administrator leaves or a configuration export may have exposed it. Rotate the Volanea key immediately if it reaches a repository, browser log, support ticket, or public incident channel. A narrow-scope key is preferable when the provider supports scoped credentials.

Build the email deliberately, not as an accidental webhook dump

Mailcoach data is valuable context, but it is not automatically email content. Decide what the Volanea message is supposed to accomplish before mapping every available field into it.

For an internal handoff, concise content is usually best: who triggered the event, what happened, and a safe link to the system where the team can act. For a subscriber-facing message, keep it aligned with consent, sender identity, and the message the subscriber reasonably expects after joining a list or receiving a tag.

Sender identity and reply handling

Use a verified sender domain in the Volanea from field. Do not set from to the subscriber's address merely to make a message look as though it came from them; that can conflict with authentication and is a poor deliverability practice. For an internal alert, use your own authenticated sender and put the subscriber address in reply_to.

A common pattern is:

{
  "from": "Demo requests <requests@updates.example.com>",
  "to": ["sales@example.com"],
  "reply_to": "ada@example.net",
  "subject": "Demo request from Ada"
}

That preserves a valid authenticated sender while allowing the sales recipient to reply directly to the subscriber.

Consent and audience boundaries

A person subscribing to a newsletter may have consented to newsletter mail, not necessarily to a new class of promotional messages. Conversely, an internal notification does not create a subscriber-consent issue but still needs appropriate access controls because it may include personal data.

If this integration sends to subscribers, ensure the automation trigger and content match the list's stated purpose. Honor unsubscribed status before creating a promotional send. A relay that receives a subscriber payload should not assume that an email address alone authorizes every type of email.

When this breaks: failure modes in the Mailcoach-to-Volanea hop

The difficult part of this integration is not making one successful test request. It is defining what happens when the webhook and API call are slow, repeated, partially populated, or temporarily unavailable.

Mailcoach retries can create duplicate sends

A webhook sender may retry when it receives a timeout, a connection failure, or a non-success HTTP response. The dangerous case is a relay that successfully sends through Volanea but fails before returning its success response to Mailcoach. Mailcoach can retry, and the second attempt can send the same email again.

Do not solve this by assuming a subscriber UUID is globally unique per send. Persist a dedicated idempotency record before or during processing. A robust key includes the automation execution or webhook event identifier when present. If that identifier is not available, combine subscriber UUID, automation purpose, and a bounded time or workflow state in a way that permits legitimate future sends while blocking immediate retries.

The strongest workflow is an inbox/outbox pattern:

1. Receive and authenticate the webhook.
2. Store an event record with a unique idempotency key.
3. Return an acknowledgement after the event is durably accepted.
4. Have a worker call Volanea.
5. Save the provider response and final status.

That design is more work than sending inline, but it prevents a transient request failure from becoming a silent lost event or duplicate email.

Webhook timeouts create ambiguous outcomes

Mailcoach expects an HTTP response from the Webhook action. If the relay waits for a slow provider call, a network delay can cause Mailcoach to treat the request as failed even if Volanea later accepts it. Keep the synchronous path short.

At a minimum, apply a timeout to the Volanea request, as in the example. Better still, enqueue the normalized event and return a 2xx response once it is safely stored. Your worker can retry provider failures with controlled backoff, while your database preserves whether a send is pending, accepted, or failed.

Never return success before you have either queued the event durably or completed the Volanea call. A fast but premature 200 response turns an outage into lost email.

Payload fields can be missing on particular records

Mailcoach automations can include subscribers from forms, imports, API syncs, and manual additions. That means first_name, tags, and custom attributes are not guaranteed. Some installations may also expose different payload details based on the Mailcoach version, automation configuration, or available feature set.

Code defensively:

• Require only the fields truly necessary for the send.
• Use safe fallbacks for optional personalization.
• Reject impossible recipient addresses before making an API call.
• Record a redacted validation failure with the field names that were missing.
• Do not include a raw payload in logs if it contains subscriber data.

For subscriber-directed email, address validation can reduce obvious typos before a workflow reaches the sending layer. A separate email address verification tool can be useful during list cleanup, but it does not replace consent checks or your normal bounce handling.

Volanea rejects the request

A 4xx response usually indicates a request that should be corrected rather than blindly retried: an invalid sender, malformed recipient, missing content, or unauthorized credential. A 5xx response or network failure is more likely transient and can enter a bounded retry queue.

Record the HTTP status, a redacted provider error, the internal event ID, and any provider message ID. Do not log API keys, raw Authorization headers, or full HTML content. Alert on sustained failures so an expired key or broken sender-domain configuration does not silently block an entire automation.

Testing the complete flow safely

Test from the Mailcoach trigger forward, not only by posting hand-written JSON to the relay. A manual request proves the API mapper; a real subscriber test proves that the automation trigger, webhook configuration, payload shape, authentication, and response handling all work together.

Use a staged checklist:

1. Create a development endpoint using a non-production Volanea sender and a controlled recipient inbox.
2. Configure a dedicated test automation and its Webhook action.
3. Subscribe a test contact or apply the test tag that starts the automation.
4. Confirm the webhook reached the relay and passed authentication.
5. Confirm the relay created exactly one idempotency record.
6. Inspect the Volanea request outcome and delivered email.
7. Repeat the webhook or simulate a timeout to verify that duplicate protection works.
8. Test subscribers with no name, no company, and unusual Unicode characters.
9. Move the endpoint and secrets to production only after the expected behavior is documented.

Avoid testing with a real customer address until your sender, reply handling, suppression behavior, and automation conditions have been reviewed. A test environment should also use a separate webhook secret so an accidental production payload cannot be accepted by a development relay.

Operational choices: direct sends, queued sends, and middleware platforms

A small custom relay is not the only operational shape, but it gives you the most control. If your team already runs serverless functions, the endpoint can be a serverless HTTP handler backed by a durable queue or database. If you run Laravel alongside Mailcoach, the relay can be a route that dispatches a queued job after request validation.

No-code middleware can be useful for a prototype when it supports receiving a webhook, securely storing the Volanea key, transforming JSON, and making an authenticated HTTP request. However, verify its retry semantics carefully. A middleware scenario that retries a completed send without an idempotency mechanism can create duplicates just as easily as custom code.

Use a custom relay when you need any of the following:

• Deterministic duplicate prevention.
• Conditional content based on several custom attributes.
• Internal audit records tied to subscriber and automation state.
• Strict data residency or log-redaction controls.
• Queue-backed retries and observability.

Use a middleware platform only when its secret handling, request history, data processing terms, and retry controls meet your requirements. In either case, the Mailcoach trigger remains the same: a subscriber reaches the automation Webhook action.

Conclusion

To send email from Mailcoach with Volanea, use Mailcoach where it is strongest—subscriber lists, tags, and automations—and use Volanea where it is strongest—authenticated email delivery. The connection between them should be a secure webhook relay, not an invented native plugin and not a browser-exposed API key.

Start with one clear automation trigger, such as a subscriber joining a list or receiving a tag. Post the subscriber event to a relay, validate it, map only the fields your message needs, and call Volanea with a server-side key. Then add idempotency and queueing before the workflow becomes business-critical. Those safeguards are what make an integration dependable when a webhook is retried, a provider is slow, or a subscriber record is incomplete.

FAQ

Does Volanea have a native Mailcoach plugin?

No. This integration uses Mailcoach's automation Webhook action and a server-side relay that calls the Volanea API. There is no marketplace installation step to rely on.

What starts the Volanea send in Mailcoach?

A subscriber first meets an automation trigger, such as subscribing to a list or receiving a tag. The send is initiated when that subscriber reaches the automation's Webhook action.

Where should the Volanea API key be stored?

Store it only in the relay's server-side secret manager or environment variables. Mailcoach should store the relay URL and a separate webhook-authentication secret, not the Volanea key.

How do I prevent duplicate email when Mailcoach retries a webhook?

Create and persist an idempotency key before sending. Prefer an automation or webhook execution identifier when available; otherwise combine the subscriber identity with the specific workflow action and a carefully defined event boundary.

Can the webhook send directly to a subscriber?

Yes, the relay can map subscriber.email to Volanea's recipient field. Before doing so, verify that the automation's trigger and content match the subscriber's consent and that the subscriber is still eligible to receive the message.