How to Send Email from Topol.io with Volanea

Send email from Topol.io by treating Topol as the email design and template-event source, then passing the saved template HTML through a small server-side relay to Volanea. This is not a native Topol.io app or marketplace integration: Topol PRO can send a webhook when a template is saved, and your relay converts that webhook into a secure Volanea API request.

Topol is fundamentally an email and landing-page editor. Its Topol PRO webhook sends the template data that was designed or updated; it does not act as a customer database, campaign scheduler, or transactional sending engine. That distinction determines the right architecture: Topol supplies the HTML and template metadata, your application supplies the recipient and business rules, and Volanea supplies the authenticated email-delivery API.

What this Topol.io and Volanea integration does

The integration has one clear job: whenever a Topol PRO email template is saved, Topol POSTs the template payload to an HTTPS endpoint you control. That endpoint verifies the request, validates the template fields, decides who should receive the message, and calls Volanea’s POST /v1/send endpoint.

The resulting flow is:

1. A teammate edits an email in Topol PRO.
2. The teammate saves the template, or manually triggers the webhook from the template preview.
3. Topol PRO sends an HTTP POST to your webhook URL.
4. Your server receives the template name, HTML, design JSON, status, and update time.
5. Your server chooses a recipient from trusted application data or a server-side routing rule.
6. Your server sends the HTML through Volanea using a secret API key and an idempotency key.
7. Volanea accepts the message for its transactional sending pipeline.

This is intentionally different from an integration where a form submission, CRM record creation, or deal-stage change is the trigger. Topol PRO’s documented outbound event is template-oriented: the webhook can run automatically when a template is saved, or can be manually triggered from template preview. The meaningful trigger for this integration is therefore a Topol email template save.

That makes this pattern especially useful for:

• Sending a newly approved template to an internal reviewer or QA mailbox.
• Delivering a current Topol-designed message to a controlled test recipient.
• Copying the current HTML into an application-owned notification workflow.
• Publishing a design update from Topol into your own system, where a separate business event later determines when and to whom to send it.
• Keeping a Topol editing workflow separate from delivery credentials and recipient policy.

It is not the right pattern for automatically emailing every person who appears in a mailing list merely because someone clicked Save in Topol. A template save is a content-management event, not proof of subscriber consent, a purchase, or a customer action. Keep audience selection and send authorization in your application.

The important limitation: there is no native Volanea app for Topol.io

Volanea does not ship a native Topol.io app, Topol marketplace listing, or one-click plugin. Do not look for an installation flow inside a Topol app marketplace, because there is no supported native connector to install.

Topol PRO does, however, provide the building block needed for a direct integration: outbound webhooks. In the Topol editor, the documented configuration location is Editor Settings → Webhooks. You provide a URL for your application that accepts POST requests and returns a 2xx status when it has received the event.

That direct webhook route is preferable to forcing the template through browser JavaScript or copying HTML by hand. The server-to-server boundary lets you:

• Verify Topol’s webhook signature before taking action.
• Keep the Volanea secret key outside Topol and outside the browser.
• Apply recipient rules that users editing a template cannot alter.
• Produce a stable idempotency key when Topol retries a delivery.
• Log the source template, update time, recipient decision, and Volanea response together.
• Reject malformed or inactive templates before a message reaches an inbox.

Topol also provides an embeddable editor product for software teams. If you use that version, its editor can call endpoints you provide for features such as autosaves, feeds, products, and storage. Those editor API endpoints are not a substitute for a secure mail-sending endpoint. They run as part of your editor integration and should never contain a client-visible Volanea key.

What triggers the send in Topol PRO

The concrete event is a template being saved in Topol PRO.

When configuring the webhook, Topol says you can choose to trigger it automatically whenever a template is saved. That is the normal option when your application needs the latest version of a design. Topol also supports manually triggering the webhook from the template preview when you want a deliberate publish or test action.

Choose the trigger based on the meaning of your email:

Automatic send on template save

Use automatic delivery when the webhook updates your own template store, rendering cache, test mailbox, or preview environment. A save may happen repeatedly during normal editing, so automatic delivery is usually best for synchronization rather than customer-facing sends.

For example, an internal product team could save a template called October release notes. Each save updates a stored HTML record in the application. A test email may go to email-qa@example.com, but production recipients should not be emailed just because the design changed.

Manual webhook trigger from template preview

Use Topol’s manual trigger when a marketer needs an explicit handoff. This is appropriate for a review loop: the designer finishes the template, opens the preview, triggers the webhook, and the server sends the rendered HTML to a fixed review group.

Manual triggering still does not make Topol a campaign sender. Your webhook receiver should treat the event as a request to process a template, then enforce its own rules for recipient addresses, send limits, and approval state.

What Topol does not supply in this webhook

Topol’s documented webhook payload has template content and metadata, but no recipient address, sender address, email subject field, campaign audience, or customer event ID. Those omissions are expected because Topol is sending template data.

Your relay must supply those values. In the example below:

• The recipient is read from TOPOL_REVIEW_TO, a server-side environment variable.
• The sender is read from EMAIL_FROM, an address on a verified Volanea sending domain.
• The subject is built from the Topol template name.
• The HTML body comes from Topol’s html field.
• A plain-text fallback is generated by the relay.
• The idempotency key is derived from Topol’s name, updated_at, and HTML hash.

For production notifications, replace the fixed review recipient with a trusted lookup in your own database. For example, your system can map a template name such as order-confirmation to an approved template record and send only after a paid-order event occurs.

The real Topol webhook payload and field mapping

Topol PRO documents the webhook body with these fields:

• name: the template name.
• json: the template definition in JSON format.
• html: the generated HTML content of the template.
• status: the template’s current status.
• updated_at: the last-updated time in ISO 8601 format.

A representative payload shape is:

{
  "name": "October release notes",
  "json": "{...Topol template definition...}",
  "html": "<!doctype html><html><body><h1>October news</h1></body></html>",
  "status": "active",
  "updated_at": "2026-10-15T14:30:00.000Z"
}

The values above are example values, but the property names and their meanings follow Topol’s documented webhook structure. In particular, do not confuse json with the final email body. The json field is the editable Topol template definition. Send the html field to an inbox, and store json only if you need to preserve the design source for your own workflow.

Here is the mapping used by the relay:

Build the secure webhook-to-Volanea relay

Use a server, serverless function, or worker you control. The important requirements are an HTTPS endpoint, access to raw request bytes for signature validation, a secret store, and outbound HTTPS access to https://api.volanea.com.

The following Node.js example uses Express. It does four things in the correct order:

1. Reads the raw body so the Topol HMAC signature can be validated.
2. Parses and validates the documented Topol payload shape.
3. Creates an idempotency key that remains stable for Topol retries of the same template revision.
4. Sends from, to, subject, text, and html to Volanea’s transactional send endpoint.

import "dotenv/config";
import express from "express";
import crypto from "node:crypto";

const app = express();

// Keep raw bytes: Topol signs the request content, not a re-serialized object.
app.post("/webhooks/topol", express.raw({ type: "application/json" }), async (req, res) => {
  try {
    const rawBody = req.body;
    const signature = req.get("Signature");

    if (!signature) {
      return res.status(401).json({ error: "Missing Topol Signature header" });
    }

    // Topol documents an HMAC-SHA-256 over the request content using the
    // Signature Secret Key shown when the webhook is created. Confirm the
    // header encoding against a real Topol test delivery before deployment.
    const expectedSignature = crypto
      .createHmac("sha256", process.env.TOPOL_WEBHOOK_SIGNING_SECRET)
      .update(rawBody)
      .digest("hex");

    const supplied = Buffer.from(signature, "utf8");
    const expected = Buffer.from(expectedSignature, "utf8");

    if (
      supplied.length !== expected.length ||
      !crypto.timingSafeEqual(supplied, expected)
    ) {
      return res.status(401).json({ error: "Invalid Topol webhook signature" });
    }

    const topol = JSON.parse(rawBody.toString("utf8"));
    const { name, json, html, status, updated_at } = topol;

    if (
      typeof name !== "string" ||
      typeof json !== "string" ||
      typeof html !== "string" ||
      typeof status !== "string" ||
      typeof updated_at !== "string"
    ) {
      return res.status(422).json({ error: "Topol payload is missing required template fields" });
    }

    if (!html.trim()) {
      return res.status(422).json({ error: "Topol payload has no HTML to send" });
    }

    // Optional workflow guard: adapt allowed statuses to the values used in
    // your Topol workspace after observing a test webhook.
    if (status.toLowerCase() !== "active") {
      return res.status(202).json({ skipped: true, reason: `Template status is ${status}` });
    }

    const htmlHash = crypto.createHash("sha256").update(html).digest("hex");
    const idempotencyKey = `topol:${name}:${updated_at}:${htmlHash}`;
    const plainText = html
      .replace(/<style[\s\S]*?<\/style>/gi, "")
      .replace(/<script[\s\S]*?<\/script>/gi, "")
      .replace(/<[^>]+>/g, " ")
      .replace(/\s+/g, " ")
      .trim();

    const volaneaResponse = await fetch("https://api.volanea.com/v1/send", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.VOLANEA_API_KEY}`,
        "Content-Type": "application/json",
        "Idempotency-Key": idempotencyKey
      },
      body: JSON.stringify({
        from: process.env.EMAIL_FROM,
        to: process.env.TOPOL_REVIEW_TO,
        subject: `Topol preview: ${name}`,
        text: plainText || `Open the HTML version of ${name}.`,
        html
      })
    });

    const responseBody = await volaneaResponse.text();

    if (!volaneaResponse.ok) {
      console.error("Volanea send failed", volaneaResponse.status, responseBody);
      return res.status(502).json({ error: "Volanea rejected the email request" });
    }

    // A successful response tells Topol the webhook was handled.
    return res.status(200).type("application/json").send(responseBody);
  } catch (error) {
    console.error("Topol webhook processing failed", error);
    return res.status(500).json({ error: "Webhook processing failed" });
  }
});

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

The relay’s environment should look like this:

TOPOL_WEBHOOK_SIGNING_SECRET=the-secret-shown-when-you-create-the-topol-webhook
VOLANEA_API_KEY=sk_live_replace_with_your_secret_key
EMAIL_FROM=notifications@example.com
TOPOL_REVIEW_TO=email-qa@example.com

Before using a live Volanea key, verify the sender domain used by EMAIL_FROM. A valid-looking address is not enough; the domain must be verified in Volanea or the API can refuse the message. The email API reference and setup guides are the right place to confirm the latest sending schema, domain setup, and response behavior before shipping.

Configure Topol PRO without exposing email credentials

In Topol PRO, go to Editor Settings → Webhooks and enter the public HTTPS URL of the relay, such as:

https://app.example.com/webhooks/topol

Choose automatic triggering on template saves if your goal is synchronization, or use the manual trigger in template preview if your workflow requires an explicit publish or review action. Configure the webhook only after the endpoint is deployed and can return a 2xx response.

When you create the Topol webhook, Topol provides a Signature Secret Key. Store that value in the same server-side secret manager as other integration secrets. It is not the Volanea API key. Its job is to let your endpoint determine whether the incoming webhook was signed by Topol and was not modified after Topol generated it.

Where the Volanea API key belongs

The Volanea API key lives nowhere on the Topol.io side. It should not be pasted into a Topol template, a custom HTML block, a browser-side editor configuration, a webhook URL query string, or a Topol user-facing setting.

Store VOLANEA_API_KEY only in the secret store available to the relay runtime: for example, encrypted server environment variables, a cloud secret manager, or a platform-managed function secret. The relay adds the Authorization: Bearer ... header only when it makes the server-to-server request to Volanea.

This separation matters because a secret key authorizes email delivery. If it appears in HTML, client-side JavaScript, browser network requests, a public repository, or any editable Topol configuration, a user or attacker can extract it and send email from your account.

Topol’s editor documentation also distinguishes between keys intended for public editor configuration and secret keys used for server-side calls. Apply the same discipline here: browser code can render or edit templates, but only a controlled backend should be able to send through Volanea.

Choose a recipient policy before you automate

The most dangerous mistake in a template-to-email connection is assuming the designer’s template should decide its own audience. It should not.

Because the documented Topol webhook does not carry a recipient list, your backend has an opportunity to make recipient selection explicit and auditable. Start with a narrow policy, then expand only when the business event and consent model are clear.

Safe patterns for early deployments

A fixed test recipient is the simplest route. TOPOL_REVIEW_TO=email-qa@example.com ensures every template-save event is visible to a controlled internal mailbox. This is useful while validating email-client rendering, sender authentication, unsubscribe treatments where applicable, and the overall webhook behavior.

A second option is a server-side allowlist. Your application can read approved recipients from a database table, such as template_reviewers, based on the saved template name. The Topol payload stays content-only; the relay owns who may receive it.

A third option is asynchronous publishing. The webhook stores the Topol html, json, name, status, and updated_at as a new revision. Then a separate workflow—an order confirmation, user invitation, account alert, or approved campaign—reads that revision and calls Volanea. This is normally the best design for customer-facing mail because the actual business event creates the delivery decision.

Patterns to avoid

Do not scrape recipient addresses from the template HTML. A text block could be changed accidentally, copied from a prior version, or manipulated by an editor user. It is also difficult to validate and audit.

Do not accept a recipient passed in a URL query parameter on the Topol webhook endpoint. URLs are routinely exposed in logs, browser history, monitoring systems, and proxy telemetry. Recipient and sender policy should be server-side configuration or database data.

Do not send to every contact in a database after every save. A Topol save can happen many times during normal work. It is a design revision, not an intentional bulk campaign launch.

Make template revisions reliable with idempotency

Topol expects the webhook receiver to respond with a 2xx status after successful receipt. Like other webhook systems, delivery can be retried when the receiver times out, returns an error, or experiences an interrupted connection. That is good for eventual delivery of the event, but dangerous if one webhook delivery directly creates an email each time it arrives.

Volanea’s POST /v1/send supports the Idempotency-Key header. Reusing the same key for the same logical send lets Volanea recognize a retry rather than generating another email. The relay example creates this key from:

topol:<template name>:<updated_at>:<sha256 of html>

That choice has useful properties:

• The same Topol payload retried after a timeout generates the same key.
• A later save with a new updated_at value creates a different key.
• A changed HTML body produces a different key even if a timestamp anomaly occurs.
• The key is deterministic, so logs can correlate Topol deliveries with Volanea requests.

For a review-mail workflow, this is usually enough. For a customer-facing workflow, make the idempotency key represent the business action too. For example, an order receipt should use an immutable order ID and message type, such as receipt:order_12345, rather than a template update timestamp. The email template revision can change, but one paid order should not receive multiple receipts because an upstream webhook was repeated.

If you need higher sending volume, multiple recipient-specific messages, or lifecycle messages that are separate from this template webhook, review transactional email pricing alongside your expected send rate and architecture.

When this breaks

Every integration has failure modes. The relevant failures here occur at the Topol-to-relay hop and the relay-to-Volanea hop, so troubleshoot those boundaries separately.

Topol retries create duplicate sends

Symptom: The same review email appears twice or more.

Cause: Your endpoint may have sent the email but failed to return a 2xx response before Topol considered the webhook delivery successful. Topol can then retry. A manual trigger can also be run more than once by a user.

Fix: Keep the same Idempotency-Key for the same template revision. Persist a delivery record keyed by the same value if you need your own audit trail. Do not generate a random UUID for every attempt, because that tells Volanea every retry is a new logical send.

Also separate receiving from expensive downstream work when necessary. For a high-volume workflow, validate and persist the webhook event first, return a fast 2xx, then process the queue with the same idempotency key. Do not return success before the event is durably stored.

The Topol webhook times out

Symptom: Topol reports failure or repeat deliveries even though your logs show some successful processing.

Cause: Slow HTML processing, database lookups, cold starts, a stalled Volanea request, or a network problem can keep the endpoint from returning promptly.

Fix: Keep webhook processing lean. Verify the signature, validate required fields, write the event to durable storage or a queue, and return a 2xx after it is safely accepted. A worker can make the Volanea call afterward. If you keep the synchronous example, set a short outbound request timeout and log both the Topol receipt time and Volanea response time.

Never respond with 200 before you have either completed the Volanea request or stored a job that guarantees later processing. Otherwise, Topol will not retry and the email request can be lost.

A payload field is absent or not what your code expects

Symptom: The relay returns 422, or an email arrives with an empty body or an unhelpful subject.

Cause: The receiver assumed fields not present in Topol’s documented webhook structure, used the design json as if it were HTML, or accepted a field with an unexpected type. Workspace configuration and plan access can matter too: Topol documents webhooks as a Topol PRO feature, so a workspace without the Webhooks setting cannot provide this direct event path.

Fix: Validate all five documented fields—name, json, html, status, and updated_at—before sending. Treat html as the deliverable content and json as design data. Do not build workflow logic on undeclared fields such as recipient, subject, or templateId; Topol’s webhook documentation does not list them.

If the Editor Settings → Webhooks option is absent, confirm that the workspace has the required Topol PRO access rather than trying to simulate an outbound webhook from client-side code. Client-side simulation would expose credentials and is not a dependable integration path.

Signature checks fail for every delivery

Symptom: Every request returns 401 Invalid Topol webhook signature.

Cause: The most common cause is hashing parsed and re-serialized JSON rather than the exact raw request bytes. Other causes include a copied or rotated Signature Secret Key, an incorrect header name, or an incorrect assumption about the signature encoding.

Fix: Read the raw application/json body before JSON parsing, use the Signature header Topol documents, calculate HMAC-SHA-256 with the webhook’s Signature Secret Key, and use a constant-time comparison. Capture a controlled test delivery and confirm the representation of the signature header before making the example verification code your production implementation.

Do not disable verification permanently to get past a test. Without signature validation, anyone who discovers the endpoint URL can submit arbitrary HTML to your relay and cause emails to be sent.

Volanea rejects the request

Symptom: Your relay returns 502, and logs show a non-2xx response from POST /v1/send.

Cause: Common possibilities include an invalid or revoked key, a sender address outside a verified domain, a missing required request field, malformed JSON, a suppressed recipient, or a request that does not match the current API schema.

Fix: Log the status code and provider response body securely, without logging the Authorization header. Confirm that the API key is present in the runtime secret store, that EMAIL_FROM uses a verified domain, that TOPOL_REVIEW_TO is a valid address, and that the payload has from, to, subject, text, and html.

Because Volanea rejects unknown JSON fields rather than silently accepting them, keep the request minimal and explicit. Add advanced fields only after verifying their current syntax in the API documentation.

Test the complete path before production use

Use a dedicated internal mailbox for the first tests. The goal is not only to see a message arrive; it is to verify that the correct Topol revision was used, the signature was checked, retries do not duplicate delivery, and the sender is authenticated.

A practical test checklist is:

1. Create a Topol PRO webhook pointing to a staging HTTPS endpoint.
2. Store the Topol Signature Secret Key and Volanea API key as separate staging secrets.
3. Set TOPOL_REVIEW_TO to an inbox you control.
4. Save a Topol template with clear marker text, such as Topol webhook test revision A.
5. Confirm the relay received name, html, status, and updated_at.
6. Confirm the Volanea request used the verified sender and the expected subject.
7. Save the template again with a new marker, then verify that a new revision can send.
8. Re-deliver the same captured webhook request in a test environment and verify that the idempotency key prevents another logical send.
9. Change the webhook signing secret temporarily and confirm the endpoint rejects the request.
10. Review the received email in multiple inboxes before treating the template as production-ready.

Keep staging and production separate. Use separate webhook URLs, separate Volanea keys where available, separate sender identities when appropriate, and separate recipient allowlists. This reduces the chance that a designer testing a template accidentally reaches real customers.

A better long-term architecture for customer email

The direct Topol webhook is excellent for synchronizing a template or initiating a controlled review email. For transactional customer messages, use Topol as the content editor and your application as the system of record for delivery decisions.

A durable architecture looks like this:

Topol template saved
        ↓
Signed webhook to your template service
        ↓
Store HTML + design JSON + revision metadata
        ↓
Business event occurs: order paid, invite created, password reset requested
        ↓
Application selects approved template revision and recipient
        ↓
Volanea POST /v1/send with business-event idempotency key

This structure gives content editors control over visual design without giving them access to sender credentials, customer audiences, or transactional event logic. It also makes rollback possible: if a revised template has a rendering problem, the application can point back to the last approved stored revision without waiting for a new business deployment.

For example, an order system can use a stored order-confirmation Topol template. When an order reaches paid status, the application loads the approved HTML revision, substitutes only trusted order data through its own rendering logic where applicable, and sends once with an idempotency key based on the order ID. The Topol save event updates available content revisions; it does not itself send every order email.

That division of responsibilities makes duplicate protection, consent handling, observability, and incident response much easier as email volume grows.

Conclusion

To send email from Topol.io with Volanea, use Topol PRO’s template-save webhook and a secure server-side relay. The trigger is a Topol template save—or a manually triggered send from template preview—not a contact event or native marketplace integration.

Topol sends the template name, design json, rendered html, status, and updated_at. Your relay verifies Topol’s Signature header, supplies the sender and recipient from trusted server-side configuration, derives a stable idempotency key, and calls Volanea’s POST /v1/send endpoint with the rendered HTML.

Keep the Volanea API key entirely out of Topol and out of the browser. Use a fixed internal recipient while testing, then move customer delivery decisions into your application where consent, business events, and duplicate prevention can be enforced reliably.

FAQ

Does Volanea have a native Topol.io integration?

No. There is no native Volanea Topol.io app, marketplace plugin, or one-click installation flow. The supported route is a Topol PRO webhook sent to an endpoint you control, followed by a server-side Volanea API call.

What Topol.io event starts the email send?

The event is a Topol PRO email template save. Topol can trigger the webhook automatically whenever a template is saved, or you can manually trigger it from template preview.

Can I send Topol’s webhook directly to Volanea?

Not as a complete production integration. Topol’s documented webhook payload contains template data, not the Volanea authentication header, verified sender, recipient policy, or a business-safe idempotency strategy. Use a relay so those values remain under your control.

Where should I store the Volanea API key?

Store it only in the server-side secret manager or encrypted environment variables used by your webhook relay. Do not put it in Topol settings, custom template HTML, browser-side JavaScript, or a public repository.

Why do I need an idempotency key?

Webhook deliveries can be repeated when an endpoint times out or fails after processing an event. A stable Volanea Idempotency-Key lets a retry represent the same logical email instead of creating a duplicate send.