A reliable AcyMailing Volanea integration is useful when an AcyMailing subscriber event should trigger a separate transactional message: a welcome email, an account-review notice, a sales handoff, or a confirmation generated by your application. Because AcyMailing does not provide a native Volanea marketplace app, the practical route is an AcyMailing automation webhook that calls a server-side endpoint, which then sends through the Volanea REST API.

This is deliberately a two-hop design. AcyMailing remains the system that knows when a subscriber enters a list or meets an automation condition; your bridge controls the decision to send, keeps the Volanea API key private, and translates AcyMailing fields into a transactional-email request. It is more secure and more observable than placing a sending key in browser code or trying to make a campaign platform behave like a public client-side API.

What this integration does—and does not do

AcyMailing is an email marketing extension for Joomla and WordPress. It manages subscribers, lists, campaigns, forms, and automations. Volanea is the sending layer in this setup: it accepts a request from your backend and delivers the resulting message through its email infrastructure.

The integration described here is event-driven. It is not a replacement for an AcyMailing newsletter campaign. Use AcyMailing’s normal campaign sending flow when the same campaign should go to a selected list or segment. Use the webhook-and-API path when one individual event needs one individually addressed message, often with application-specific content and a clear audit trail.

The architecture is:

  1. A person submits an AcyMailing subscription form or is otherwise added to a list.
  2. An AcyMailing automation whose trigger is User subscribes to a list runs.
  3. Its webhook action posts the selected subscriber fields to an endpoint you control.
  4. The endpoint validates the request, deduplicates it, and calls Volanea’s email-send endpoint.
  5. Volanea returns a message identifier that the bridge records for support and troubleshooting.

This distinction matters. A webhook is an HTTP notification, not proof that an email was accepted by a recipient mailbox. An API acceptance response means Volanea accepted the message for processing; delivery, bounces, complaints, and engagement should be handled through the appropriate sending events and reporting in your email platform.

The AcyMailing capability this setup uses

The relevant AcyMailing feature is its Automation system. In an automation, a trigger determines when a subscriber enters the workflow, and actions define what happens next. For this guide, the concrete trigger is User subscribes to a list. That is the event to select when a person is added through an AcyMailing subscription form, through an import, or by another supported subscriber-management path.

The outbound HTTP portion is the automation’s webhook action. Availability can depend on the AcyMailing edition and installed integrations, so confirm that your AcyMailing installation exposes a webhook action before designing production flows around it. If the action is unavailable in your plan, do not attempt to embed a Volanea key in a form or a Joomla/WordPress page. Use a middleware service such as Make or Zapier where available, or add a small server-side Joomla/WordPress extension that receives the relevant subscriber event.

Why the trigger should be list-specific

Choose a list whose membership represents a meaningful consent or lifecycle event. Examples include:

  • trial-signups for a product onboarding email.
  • downloaded-guide for a resource-delivery message.
  • partner-referrals for a partner-specific confirmation.
  • event-registrants for a registration acknowledgment.

Avoid using a broad master list as the trigger unless every subscriber should receive the message. Imports, manual edits, synchronization jobs, and list moves can all add a user. A narrow list makes the condition understandable to future administrators and limits accidental sends.

Also decide whether a person should receive the transactional email every time they are re-added. For a one-time welcome, record a send marker in your own database or use an event identifier to deduplicate. For a genuinely repeatable event, such as a request for a new download link, include a per-request identifier rather than deduplicating solely by email address.

Set up the AcyMailing automation webhook

Create an automation for the list that represents your event. In the automation configuration, select the User subscribes to a list trigger, choose the relevant list, and add the webhook action. The action should send an HTTPS POST request to an endpoint owned by your application, such as:

https://app.example.com/webhooks/acymailing/subscribed

Do not point AcyMailing directly at a public endpoint that trusts any request it receives. Add a shared webhook secret in a request header if the webhook action supports custom headers. If your installed webhook action cannot add a header, use a long, randomly generated path secret and restrict the endpoint with rate limits and request validation. A header is preferable because a secret embedded in a URL may appear in logs, analytics tools, browser histories, reverse-proxy logs, or support screenshots.

Configure a stable JSON event contract

AcyMailing’s webhook action should send only the fields the email needs, rather than a dump of every subscriber property. The precise substitutions available in the webhook body are determined by the AcyMailing automation editor and the custom fields configured on the site. Use its insert-variable control to select the subscriber email, name, ID, and list values rather than typing an unverified token by hand.

A practical payload contract is the following JSON document. This is the body your AcyMailing webhook should be configured to send; its shape is under your control, which makes downstream code predictable.

{
  "event": "user_subscribed_to_list",
  "subscriber_id": "{{subscriber id}}",
  "email": "{{subscriber email}}",
  "name": "{{subscriber name}}",
  "list": "trial-signups",
  "occurred_at": "{{current date}}"
}

In the AcyMailing editor, replace the human-readable placeholders above with the exact variables inserted by that editor. The important operational point is not the spelling of a template token; it is that the final outgoing HTTP request contains a JSON string with email, name, subscriber_id, and list. Test the action with a real test subscriber and inspect the request received by your endpoint before enabling it for a live list.

If the webhook action lets you set a content type, set Content-Type: application/json. Set a second header such as X-AcyMailing-Webhook-Secret to a random value stored only in AcyMailing’s server-side administration configuration and in your server’s secret manager. Never place either secret in JavaScript delivered to a visitor’s browser.

Build the secure Volanea API bridge

The bridge is a small backend route. It can live in a Node application, a serverless function, a Joomla/WordPress plugin endpoint, Laravel, Rails, or any environment that can accept HTTPS and make an outbound HTTPS request. Its responsibilities are intentionally narrow:

  • authenticate the webhook before doing any work;
  • validate and normalize the subscriber data;
  • prevent accidental duplicate sends;
  • construct the Volanea request;
  • record the result without logging secrets or full message bodies unnecessarily.

The Volanea API key belongs in a server environment variable or managed secret, for example VOLANEA_API_KEY. It does not belong in the AcyMailing form HTML, a browser-side configuration object, a mobile application, a public repository, or a URL query string. A browser-visible key can be extracted by anyone who loads the page and used to send mail under your account.

AcyMailing administration settings are server-side, but it is still better to keep the Volanea sending credential out of AcyMailing. The webhook’s shared secret permits only one narrowly defined action: notifying your bridge about an event. The Volanea key permits email sends and should be isolated to the service that makes those calls.

Working field mapping and send request

The following Node.js example accepts the configured AcyMailing JSON body and maps it into a Volanea email request. It assumes your bridge has VOLANEA_API_KEY, ACYMAILING_WEBHOOK_SECRET, and a verified FROM_EMAIL configured as environment variables. It also demonstrates the key mapping: AcyMailing’s email becomes the Volanea recipient, name becomes the recipient name, and the list and subscriber ID become metadata for diagnosis.

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

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

const sentEvents = new Set(); // Replace with Redis or a database in production.

app.post("/webhooks/acymailing/subscribed", async (req, res) => {
  const suppliedSecret = req.get("X-AcyMailing-Webhook-Secret");
  const expectedSecret = process.env.ACYMAILING_WEBHOOK_SECRET || "";

  if (!suppliedSecret || !expectedSecret ||
      !crypto.timingSafeEqual(
        Buffer.from(suppliedSecret),
        Buffer.from(expectedSecret)
      )) {
    return res.status(401).json({ error: "unauthorized webhook" });
  }

  const { event, subscriber_id, email, name, list, occurred_at } = req.body;

  if (event !== "user_subscribed_to_list") {
    return res.status(202).json({ ignored: true });
  }
  if (typeof email !== "string" || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
    return res.status(400).json({ error: "missing or invalid email" });
  }

  // Prefer a webhook delivery ID if your AcyMailing setup provides one.
  const idempotencyKey = crypto
    .createHash("sha256")
    .update(`${event}:${subscriber_id}:${list}:${occurred_at}`)
    .digest("hex");

  if (sentEvents.has(idempotencyKey)) {
    return res.status(200).json({ duplicate: true });
  }

  const firstName = typeof name === "string" && name.trim()
    ? name.trim().split(/\s+/)[0]
    : "there";

  const volaneaResponse = await fetch("https://api.volanea.com/v1/emails", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.VOLANEA_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      from: process.env.FROM_EMAIL,
      to: [{ email, name: typeof name === "string" ? name.trim() : undefined }],
      subject: "Welcome—your signup is confirmed",
      html: `<p>Hi ${escapeHtml(firstName)},</p><p>Thanks for signing up. Your subscription is confirmed.</p>`,
      text: `Hi ${firstName},\n\nThanks for signing up. Your subscription is confirmed.`,
      metadata: {
        source: "acymailing",
        acymailing_subscriber_id: String(subscriber_id || ""),
        acymailing_list: String(list || ""),
        idempotency_key: idempotencyKey
      }
    })
  });

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

  sentEvents.add(idempotencyKey);
  console.info("Volanea send accepted", { idempotencyKey, responseBody });
  return res.status(202).json({ accepted: true, idempotencyKey });
});

function escapeHtml(value) {
  return value.replace(/[&<>'"]/g, character => ({
    "&": "&amp;", "<": "&lt;", ">": "&gt;", "'": "&#39;", "\"": "&quot;"
  }[character]));
}

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

Before deploying, compare the endpoint, authorization scheme, and request properties in the code with the current email API reference and setup guides. API contracts evolve, and the send request should always match the version documented for your Volanea account.

The example intentionally escapes the first name before placing it in HTML. Subscriber fields are input, not trusted markup. Without escaping, a maliciously crafted name could alter the email HTML or produce a misleading message.

Authenticate and protect the integration

There are two credentials in this design, and they have different jobs. Treat them differently.

The AcyMailing webhook secret authenticates the first hop. Store it in the webhook action’s server-side configuration and in your bridge’s secret storage. Rotate it if an administrator account is compromised or if a configuration export may have exposed it. Your endpoint should reject requests with no secret, an incorrect secret, unsupported methods, unexpected content types, and bodies above a modest size limit.

The Volanea API key authenticates the second hop. Store it only in the environment where the bridge executes. Give deployment systems access through a secrets manager rather than committing a .env file. Restrict who can read production environment variables, and remove keys promptly when staff or vendors no longer need access.

Do not expose keys in client-visible configuration

A subscription form runs in a visitor’s browser. Its JavaScript, page source, network requests, and bundled configuration must be assumed public. Even if an API key appears obscured, minified, or encoded, it is exposed once delivered to the client.

Likewise, do not call Volanea directly from a browser after a form submission. Doing so gives an attacker a reusable sending credential and bypasses the controls that determine whether a request came from AcyMailing, a real subscriber, or a script. The bridge keeps authorization, throttling, input validation, and message templates in an environment you control.

Use a verified sender domain in Volanea and configure the required authentication records for that domain before sending production mail. A technically successful API call from an unverified or poorly authenticated domain is not a deliverability strategy. Separate marketing and transactional streams where appropriate, preserve clear consent records, and include unsubscribe handling for messages that are promotional rather than strictly transactional.

When this breaks: failure modes in this specific hop

An automation-to-webhook-to-API chain has more moving parts than an in-app campaign. Plan for its failures explicitly instead of relying on a happy-path test.

Retries can create duplicate emails

AcyMailing or an intermediary may retry a webhook if it receives a timeout, a network failure, or a non-success HTTP response. The most dangerous case is a timeout after the bridge successfully sent the Volanea request but before AcyMailing received the bridge’s response. A retry then reaches the bridge, which sends the same email again unless it recognizes the event.

Use an idempotency record in Redis or a database with a unique constraint. The example derives one from event data, but a delivery ID supplied by the webhook is better when available. Mark the record only after Volanea accepts the request, and retain it for a period that exceeds the sender’s retry window. For one-time welcomes, a database table keyed by subscriber ID and message type is usually clearer than an in-memory set.

Webhook timeouts can turn into false failures

AcyMailing’s webhook process expects a reasonably prompt HTTP response. If your route renders a complex template, calls several services, waits for a slow provider response, and then replies, the upstream can time out and retry.

Return quickly. For higher-volume flows, validate the webhook, write a durable job to a queue, return a 202 Accepted, and let a worker make the Volanea request. The queue worker can retry transient provider failures using bounded exponential backoff. This separates AcyMailing’s delivery time limit from the time needed to deliver an email job.

Do not return 200 OK before persisting the job. If the process crashes after acknowledging the webhook but before recording work, the event is silently lost. A durable queue or transactional outbox is the appropriate boundary between receipt and processing.

Subscriber fields may be absent or differently named

AcyMailing sites often have different custom-field schemas, and field availability can differ by edition, installed integrations, form configuration, or the method that created the subscriber. A form might collect email only; an import may omit a name; a synchronization plugin may use a field whose value is not exposed to the webhook action.

Make email the only required recipient field. Treat name, phone, organization, and custom data as optional. Validate the final body received at your bridge, log missing-field counts without logging sensitive values, and use safe defaults such as “there” rather than sending Hi undefined. If an email genuinely requires a field—an order number, for example—reject the event into a monitored exception queue rather than sending a confusing message.

API errors need classification

A 400 response usually means the bridge formed an invalid request and should not retry unchanged. A 401 or 403 points to authentication, permissions, or sender verification. A 429 means rate limiting and should be retried with backoff. A 5xx or network failure may be temporary, but it still needs a retry limit and an alert after repeated failures.

Record the AcyMailing subscriber ID, your idempotency key, status code, and Volanea message ID when available. Do not log the Volanea key, webhook secret, full recipient data, or rendered HTML in unrestricted application logs. Those records let support answer “was this sent twice?” without turning log storage into a collection of email content.

Test the full route before enabling real subscribers

Use a dedicated test list and a mailbox you control. Add a subscriber through the same AcyMailing form or subscriber flow that production users will use. This verifies more than the code: it verifies that the automation trigger actually fires for that method of subscription and that the webhook has the expected variables.

Run this checklist:

  1. Confirm that the webhook reaches the bridge over HTTPS and carries the expected content type.
  2. Confirm that an invalid or missing webhook secret receives 401 and never calls Volanea.
  3. Confirm that an invalid recipient receives 400 and becomes visible in monitoring.
  4. Add the same test subscriber or replay the event to prove the idempotency rule prevents a second send.
  5. Verify the From address is the intended authenticated domain and that reply handling works.
  6. Inspect the received HTML and plain-text alternatives on desktop and mobile mail clients.
  7. Force a temporary Volanea failure in a non-production environment and confirm the queue or retry policy behaves as intended.

Avoid testing by repeatedly submitting public forms without cleanup. Test events can create unexpected list records and may distort campaign statistics. A distinct list, a clearly labeled test sender, and an isolated environment are easier to audit.

Direct SMTP is an alternative for AcyMailing campaign sending

If the actual objective is to make AcyMailing send its own newsletters through Volanea, SMTP configuration may be a simpler fit than an event webhook. In that model, AcyMailing creates and schedules the campaign as usual, while its mailer sends through the provider’s SMTP relay. There is no REST mapping layer because AcyMailing owns the rendering and recipient loop.

The webhook approach remains the better choice when the email is triggered by a subscriber event but produced by your application logic. It permits conditional templates, app data lookups, idempotency, API-level metadata, and a cleaner separation between campaign operations and transactional operations.

Choose based on the message’s source of truth:

  • Use AcyMailing campaign sending for newsletters, broadcasts, and list-wide lifecycle series authored in AcyMailing.
  • Use the webhook bridge for one-to-one operational messages driven by AcyMailing events and application logic.
  • Use a queue-backed bridge for events that must not be lost or duplicated.
  • Use a direct application-to-Volanea API call when AcyMailing is not the system detecting the event at all.

Make and Zapier as middleware alternatives

If your AcyMailing plan or deployment does not expose the outgoing webhook action you need, middleware can provide the connection point. The pattern is still the same: an AcyMailing event or supported connector triggers a scenario or Zap; the scenario posts a structured payload to your secure bridge; the bridge calls Volanea.

Do not place the Volanea API key in a client-side form merely because a direct automation action is absent. A Make custom webhook, Zapier Webhooks step, or custom server-side plugin preserves the server-to-server boundary. For production transactional mail, a bridge you operate is often preferable even when middleware is used, because it centralizes validation, templates, deduplication, and observability.

Middleware introduces additional retry behavior and an additional billing and outage dependency. Include its execution ID in your logs where possible. If a scenario retries after Volanea already accepted a message, your idempotency logic must still prevent a duplicate. The bridge is therefore not redundant; it is the consistent control point between automation tooling and the sending API.

Deliverability and operational ownership

An API integration only solves the transport problem. Delivery quality depends on the sender identity, recipient expectations, message content, complaint rates, bounces, and how quickly the sending system removes or suppresses bad addresses.

Keep a distinction between AcyMailing subscription consent and transactional necessity. A receipt or password-reset email can have a different legal basis from a promotional offer. If the webhook triggers a promotional message, make sure the list membership reflects valid consent and that the message supports the unsubscribe expectations applicable to your audience.

Validate addresses at the point of collection when appropriate, especially for high-value forms and imported data. A quick pre-send check can reduce obvious typos before they enter an automation; Volanea’s email address verification tool can help assess an address without turning verification into a substitute for consent or bounce handling.

Finally, monitor the chain rather than only the final inbox. You need visibility into AcyMailing automation executions, webhook response rates, queued jobs, Volanea API responses, provider events, and user reports. The earliest failed hop tells you who owns the fix.

Conclusion

An AcyMailing Volanea integration works best as a deliberate server-to-server workflow: AcyMailing’s User subscribes to a list automation trigger sends a small, predictable webhook payload; your bridge authenticates and deduplicates it; Volanea sends the resulting message through its REST API. This design keeps the API key private, makes retries safe, and gives your team a clear place to inspect failures.

Start with one narrowly scoped list, one test message, and a durable idempotency rule. Once the event contract is stable, the same pattern can support onboarding, lead routing, event confirmations, download fulfillment, and other subscriber-driven messages without exposing credentials or sacrificing operational control.

FAQ

Does AcyMailing have a native Volanea plugin?

No. This integration does not rely on a native AcyMailing marketplace plugin. It uses an AcyMailing automation webhook and a server-side bridge that calls Volanea.

What AcyMailing trigger should start the send?

Use the Automation trigger User subscribes to a list and select the specific list that represents the event, such as trial-signups or event-registrants.

Where should the Volanea API key be stored?

Store it only in server-side environment variables or a secret manager used by your bridge. Never put it in an AcyMailing form, front-end JavaScript, browser-visible configuration, or a public repository.

How do I stop retries from sending duplicate welcome emails?

Persist an idempotency key based on a webhook delivery ID or a stable event combination such as subscriber ID, list, event type, and event time. Check that record before calling Volanea and retain it longer than the retry period.

Can I use this for newsletters instead of transactional emails?

You can, but AcyMailing’s own campaign flow and SMTP configuration are generally more natural for list-wide newsletters. The webhook bridge is most useful for individual event-driven messages that require backend logic or API-level control.