How to Send Email from Convertful with Volanea

Convertful email integration does not require a browser-side mail script or an exposed provider key. The reliable pattern is to send a Convertful form submission to a server-side webhook, validate and map the lead data there, then call Volanea’s email API.

Convertful does not provide a native Volanea app or marketplace plugin. That is usually a good reason to use a small integration layer rather than trying to force a client-side connection: Convertful remains responsible for capturing consent and lead fields, while your application remains responsible for business logic, secrets, recipient selection, and transactional delivery.

What this integration does

The concrete event that starts this flow is a form submission in a Convertful widget. A visitor completes a Convertful form—for example, an ebook signup, waitlist, coupon reveal, or lead magnet form—and Convertful sends the captured lead values to the webhook URL configured for that form’s Webhooks integration.

Your webhook then decides whether an email should be sent. For an immediate lead confirmation, it can send a welcome or download email to the submitted address. For an internal notification, it can email your sales or support inbox with the lead details. It can also do both, but those are different message types and should be modeled separately.

The full path is:

1. A visitor submits a Convertful form.
2. Convertful posts the submission fields to an HTTPS endpoint you control.
3. Your endpoint verifies the request shape, normalizes the data, and records an idempotency key.
4. Your endpoint calls Volanea’s REST email endpoint with a server-side API key.
5. Volanea accepts the message for delivery, and your endpoint records the provider response.

This is not a generic “email every lead” recipe. It is an event-driven email integration. The difference matters because a form submit is an external event that can be repeated, malformed, abandoned, retried, or submitted by a bot. A relay gives you a deliberate place to handle each of those cases.

Why a webhook relay is the right Convertful connection

Convertful’s Webhooks integration is the outbound HTTP capability that makes a direct server-to-server workflow possible. Configure it on the relevant Convertful form integration, point it at a public HTTPS URL, and use the fields collected by that specific form as the outgoing data.

The webhook is not a place to put an email provider credential. It is merely the handoff from Convertful to your backend. A web browser can inspect page JavaScript, network requests, embedded widget configuration, and environment values bundled into frontend code. Any Volanea API key placed there should be treated as compromised.

A relay also solves practical problems that a simple point-to-point connection cannot:

• It can reject missing or malformed email addresses before attempting delivery.
• It can distinguish a marketing opt-in from a request for a transactional confirmation.
• It can render a personalized template without trusting arbitrary submitted HTML.
• It can prevent duplicate emails when an upstream webhook is retried.
• It can alert your team without exposing recipient addresses or provider responses in the browser.
• It can change delivery providers or message templates without editing a Convertful widget.

For a production Convertful email integration, host the relay in the environment where you already run application code: a serverless function, container service, API route, worker, or conventional web server. The endpoint must be publicly reachable over HTTPS. It does not need to be large; the example below is intentionally small enough to understand and substantial enough to make the important safeguards visible.

Set up the Convertful form submission webhook

Start with the actual form that captures the lead. Before configuring delivery, make the form field names useful and stable. A field labeled “Email” should have a predictable email field key, and custom fields should avoid names that collide with your internal data model.

In Convertful, open the widget that contains the form, then configure its form integration to use Webhooks. Add the publicly reachable HTTPS URL for your relay, such as https://app.example.com/webhooks/convertful. Use the POST request option and configure the form data to be sent to that endpoint.

The values Convertful can send originate in the fields on that form. For a form with fields named email, first_name, last_name, and company, the useful webhook payload is a flat set of submitted field values like this:

{
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "company": "Analytical Engines Ltd"
}

That shape is important: Convertful forms are not one universal CRM object with a guaranteed nested contact structure. The keys reflect the fields configured on the specific form. If your widget uses firstname rather than first_name, your relay must map firstname. If the form only asks for an email address, the other keys will not exist.

Make the field contract explicit

Write down the contract before deploying. For the confirmation-email example, the required field is email; first_name is optional. Keep the form schema and the relay mapping together in your code repository or integration runbook.

A sensible contract might be:

Do not infer marketing consent merely because someone entered an email address. A request to receive a download link or confirmation email can be fulfilled as a transactional message; ongoing promotional messaging requires the consent and suppression handling appropriate to your program and jurisdiction.

Test the form, not only the endpoint

Submit the live or staging Convertful form using a test address you control. Inspect what arrives at the relay before enabling sending. This catches the most common integration mistake: building code for a field name that looks right in a design mockup but is different in the deployed form.

If you modify a Convertful field later, treat it as an API-contract change. Update the relay mapping, test it, and only then publish the widget. This is especially important when several widgets use superficially similar forms but have different field keys.

Store the Volanea API key on the server

The Volanea API key belongs only in the server-side environment that runs your webhook relay. In a traditional deployment, add it as a protected environment variable such as VOLANEA_API_KEY. In a serverless deployment, use the host’s encrypted secret store. In either case, the value should never be copied into Convertful custom JavaScript, a page tag manager variable, frontend build output, or a public repository.

Your relay needs two categories of configuration:

VOLANEA_API_KEY=server-side-secret
VOLANEA_FROM_EMAIL=hello@example.com
VOLANEA_FROM_NAME=Example Team
CONVERTFUL_WEBHOOK_TOKEN=long-random-shared-token

The API key authorizes Volanea sending. The sender address must be an address or domain you have configured and authenticated in your Volanea account. The separate webhook token protects the inbound Convertful endpoint. It is not a replacement for proper request validation, but it stops casual or accidental requests from invoking your mail workflow.

Put the inbound token in the webhook URL rather than in frontend configuration, for example:

https://app.example.com/webhooks/convertful?token=long-random-shared-token

Treat that URL as sensitive operational configuration. Rotate the token if it is exposed in logs, screenshots, or a copied widget configuration. Your endpoint should also rate-limit requests and should avoid logging raw email addresses unnecessarily.

For the endpoint URL, configure Convertful with the tokenized URL. For the Volanea credential, configure only the server environment. There is no scenario in this integration where a visitor’s browser needs the Volanea API key.

Map a Convertful submission to a Volanea API email

The following Node.js example is a complete mapping layer for the form payload shown above. It accepts JSON or URL-encoded form submissions, checks the shared URL token, validates the submitted email, builds safe HTML from plain-text fields, and sends a message using Volanea’s REST API.

Before using it, confirm the current endpoint and message schema in the email API reference and setup guides, and set the sender to one of your authenticated sending identities. The example uses the common email-resource request shape: a from object, a to array, plus subject, html, and text content.

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

const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: false }));

const {
  VOLANEA_API_KEY,
  VOLANEA_FROM_EMAIL,
  VOLANEA_FROM_NAME = "Example Team",
  CONVERTFUL_WEBHOOK_TOKEN
} = process.env;

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

function validEmail(value) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(value || ""));
}

// Replace this in-memory Set with Redis, a database, or durable KV storage in production.
const sentEvents = new Set();

app.post("/webhooks/convertful", async (req, res) => {
  if (!crypto.timingSafeEqual(
    Buffer.from(req.query.token || ""),
    Buffer.from(CONVERTFUL_WEBHOOK_TOKEN || "")
  )) {
    return res.status(401).json({ error: "unauthorized" });
  }

  // Convertful sends the values captured by the configured form fields.
  const { email, first_name: rawFirstName = "" } = req.body;
  const recipient = String(email || "").trim().toLowerCase();
  const firstName = String(rawFirstName || "").trim().slice(0, 80);

  if (!validEmail(recipient)) {
    return res.status(422).json({ error: "A valid email field is required" });
  }

  // Convertful form submissions do not inherently provide a universal event ID.
  // Build a short-lived idempotency key from stable event values; use durable storage in production.
  const eventKey = crypto.createHash("sha256")
    .update(`convertful:welcome:${recipient}:${new Date().toISOString().slice(0, 10)}`)
    .digest("hex");

  if (sentEvents.has(eventKey)) {
    return res.status(200).json({ status: "duplicate_ignored" });
  }

  const greeting = firstName ? `Hi ${escapeHtml(firstName)},` : "Hi,";
  const message = {
    from: {
      email: VOLANEA_FROM_EMAIL,
      name: VOLANEA_FROM_NAME
    },
    to: [{ email: recipient, name: firstName || undefined }],
    subject: "Thanks for signing up",
    html: `<p>${greeting}</p><p>Thanks for signing up. Your requested resource is ready:</p><p><a href="https://example.com/download">Download it here</a></p>`,
    text: `${firstName ? `Hi ${firstName},` : "Hi,"}\n\nThanks for signing up. Your requested resource is ready: https://example.com/download`
  };

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

  const result = await response.json().catch(() => ({}));
  if (!response.ok) {
    console.error("Volanea send failed", response.status, result);
    return res.status(502).json({ error: "email_provider_rejected_request" });
  }

  sentEvents.add(eventKey);
  console.info("Convertful confirmation accepted", {
    providerMessageId: result.id,
    eventKey
  });
  return res.status(202).json({ status: "accepted", id: result.id });
});

app.listen(3000);

The code intentionally keeps company out of the customer-facing email. Even though Convertful can collect it, a lead’s company is not needed to deliver a signup confirmation. Data minimization reduces the risk of accidentally exposing details in a template or in provider metadata.

Use templates for real production messages

Inline HTML is useful for showing the mapping, but production emails are usually easier to manage as templates. The relay can select a template based on the widget, campaign, or product selected, then pass a small set of safe variables such as firstName and downloadUrl.

Avoid using arbitrary Convertful input as raw HTML, a subject line, a reply-to address, or an outbound URL. Escape text values, constrain field lengths, and generate destination URLs on the server. These controls prevent a form value from changing email content in ways you did not intend.

Choose the email type before you automate it

A Convertful form can be the beginning of several different email flows. Treating them all as the same “autoresponder” produces poor consent handling and confusing operational metrics.

Transactional confirmation

Use a transactional confirmation when the visitor has taken an action that requires a direct response: a requested download link, account-interest acknowledgment, event registration receipt, or passwordless access step. The email should be tightly connected to the form action and should not be delayed by marketing segmentation.

The example above is this type of message. Its purpose is to fulfill a specific request from a specific visitor.

Internal lead alert

An internal alert goes to your team, not to the visitor. Map the Convertful email, name, company, selected service, page URL, and campaign information into an alert sent to a shared sales inbox or ticketing workflow. Use an allowlisted fixed recipient, not an address submitted in the form.

Internal alerts benefit from a deduplication window as well. A visitor retrying a submission should not create five nearly identical sales emails.

Marketing enrollment

A marketing enrollment is different. It should normally add the person to your consent-aware contact system and trigger a campaign or journey only when the form includes the appropriate permission. Sending promotions directly from the webhook can bypass unsubscribe, frequency-cap, preference-center, and suppression logic.

If your goal is ongoing newsletters, keep Volanea’s immediate send limited to transactional confirmation and hand the consented contact to the marketing system that owns subscription state.

Deliverability details that affect this flow

An API acceptance response means Volanea accepted the message for processing; it is not the same as an inbox placement guarantee. Good results depend on a verified sending domain, correct authentication, relevant content, reliable list practices, and a predictable sending pattern.

Authenticate the domain used in VOLANEA_FROM_EMAIL before turning the flow on. Domain authentication typically involves DNS records for SPF and DKIM, with DMARC providing a policy and alignment framework for the domain. Use the exact DNS values supplied in your Volanea domain setup rather than copying generic records from another provider.

Keep the From domain aligned with the domain visitors recognize from the Convertful landing page. A visitor who signs up on example.com is more likely to trust mail from hello@example.com than a sudden message from an unrelated domain.

Other practical safeguards include:

• Send to the exact address the visitor submitted; do not silently substitute a CRM address.
• Use a readable From name and a monitored reply-to path for messages that invite replies.
• Keep confirmation content concise and clearly tied to the form action.
• Do not add purchased, scraped, or unverified addresses to the workflow.
• Monitor bounces, complaints, deferrals, and provider rejection responses.
• Consider checking addresses before expensive downstream workflows with a free email address verification tool.

The second-order effect of a clean confirmation flow is useful: people who mistype an address will not receive the requested resource, but repeatedly sending to syntactically broken or non-deliverable addresses damages your sending data and can make future important messages less reliable.

When this breaks: Convertful-to-API failure modes

Every hop has failure modes. Design the relay assuming that a successful visitor experience and a successful email API request do not always happen in the same instant.

Retries can create duplicate sends

Webhook systems may retry when they do not receive a timely successful response. A retry is correct behavior from the sender’s perspective, but without deduplication it can produce duplicate welcome emails.

Convertful form data may not contain a universal provider event identifier that you can use as an idempotency key. Create one in your relay from the workflow name, normalized recipient, and an appropriate time or submission identifier. Store it in durable storage with a time-to-live. The sample uses a per-day key only to illustrate the concept; your production key should match your business rule. For example, a downloadable asset might allow one confirmation email every 15 minutes, while a registration receipt should have a permanent event identifier from your own database.

Webhook timeouts create ambiguous outcomes

If your relay waits for a slow email-provider response, Convertful may time out and retry even though Volanea later accepts the first send. Return a success response as quickly as your architecture permits.

For higher-volume or business-critical flows, split the work in two: validate and persist the webhook event, return a 2xx response, then send from a queue worker. The persisted event record becomes the source of truth for retries, auditing, and duplicate prevention.

If you keep the synchronous approach, set a conservative outbound timeout and log whether a failure occurred before or after the request was sent. Never blindly retry an ambiguous send without an idempotency strategy.

Fields can be missing or named differently

A form field may be optional, hidden by conditional logic, removed in a widget revision, or unavailable in the plan and integration configuration you expected. The result is usually not a dramatic system error; it is a payload with an absent property.

Require only what the message truly needs. For a confirmation email, reject an empty email with a clear 422 response. For first_name, use a neutral greeting. For fields such as company, campaign, or consent, choose a safe default or route the submission to review rather than producing a malformed email.

Keep an integration test submission for each Convertful form. It should verify the payload field names, your relay response, and the resulting Volanea message without using a real customer address.

Invalid requests and bot submissions

A public form can receive automated submissions. Convertful’s own anti-spam controls and your site-level protections are useful, but your relay should still impose limits. Validate lengths and formats, rate-limit by source characteristics where possible, and avoid treating a large free-text field as trusted message content.

A bot that submits a thousand random addresses can create cost, noisy metrics, and unwanted mail. A relay is the right layer to cap sends, flag anomalies, and refuse requests that do not match the expected form contract.

Provider rejection is not a reason to lose the lead

Volanea can reject a request when authentication, sender identity, payload format, or account-level limits are not valid. Save a minimal event record before sending: received time, normalized recipient hash, form name or workflow, idempotency key, send status, and provider message ID when available.

Do not store full submission payloads forever by default. Retain only the information needed for support, consent records, and troubleshooting, according to your privacy policy and retention requirements.

Operational monitoring and testing

A Convertful email integration is easiest to operate when you can answer four questions quickly: Did Convertful reach us? Did we accept the event? Did Volanea accept the send? What happened after delivery processing?

At minimum, log structured events at these points:

1. Webhook received, with a request correlation ID and form/workflow identifier.
2. Validation passed or failed, without printing full personal data in ordinary logs.
3. Duplicate suppressed, accepted for processing, or queued.
4. Volanea request accepted or rejected, with the provider message ID where available.

Use a controlled test address and test the whole path after changes to the Convertful widget, webhook endpoint, sender domain, template, or server environment. A unit test for the API request is helpful, but it cannot reveal a renamed Convertful form field or a changed widget configuration.

Separate development, staging, and production where possible. A staging Convertful widget should post to a staging endpoint and send only to an allowlisted test inbox. This avoids accidental production email while a designer experiments with form fields.

Alternatives when a custom relay is not available

A small endpoint is usually the most controllable option, but it is not the only architecture. If your team cannot deploy server-side code, use an automation platform as the protected middle layer rather than exposing a Volanea credential in Convertful.

A typical no-code route is Convertful form submission to an automation service webhook, followed by a server-side HTTP request action to the Volanea API. Store the Volanea key in that automation platform’s protected connection or secret configuration, not in a browser-visible field. Build the same validation, duplicate prevention, and consent decisions as far as the platform permits.

The trade-offs are clear:

Do not use Convertful custom JavaScript to call Volanea directly from a visitor’s browser. Even if a prototype appears to work, it exposes credentials and lets any visitor attempt sends under your account.

A production rollout checklist

Before publishing the widget, verify the entire integration rather than only the happy path.

• Confirm the Convertful form’s Webhooks integration posts to the intended HTTPS endpoint.
• Confirm the deployed payload contains the field names your relay expects.
• Keep the Volanea API key in server-side secret storage only.
• Use a verified Volanea sender identity and follow the domain setup values in your account.
• Require and validate the recipient email field.
• Escape all submitted text used in HTML and never use submitted values as raw markup.
• Add durable idempotency protection for retries and repeated submissions.
• Set a bounded request timeout and record provider acceptance or failure.
• Test missing optional fields, invalid emails, repeated submissions, and provider-error handling.
• Confirm consent, unsubscribe, and suppression ownership before adding promotional mail.

Once this is in place, the workflow is simple for visitors: submit a Convertful form and receive the expected response. Behind the scenes, it remains secure, observable, and adaptable as your forms and email programs grow.

FAQ

Does Convertful have a native Volanea integration?

No. Convertful does not provide a native Volanea marketplace app or plugin. Use Convertful’s Webhooks form integration to send form-submission data to a server-side relay, then have that relay call Volanea’s API.

What triggers the email in this Convertful email integration?

The trigger is a Convertful form submission. The submitted form fields are posted to the webhook URL configured on that form, and your relay decides whether and what email to send.

Can I put a Volanea API key in Convertful custom code?

No. Browser-visible code and configuration can be inspected by visitors. Keep the API key in a server environment variable, secret manager, or protected automation-platform credential.

How do I stop duplicate welcome emails?

Use idempotency in the relay. Persist a key derived from a stable submission or business event identifier before sending, and return a successful webhook response for recognized duplicates. This protects against retries and repeated form submissions.

What if a Convertful form does not include a first name?

Treat first name as optional. Validate the required email field, then use a neutral greeting such as “Hi,” when first_name is absent. Do not fail a transactional confirmation because a nonessential personalization field is missing.