How to Send Email from ReferralHero with Volanea

Send email from ReferralHero without exposing an email API key or relying on a marketplace plugin. ReferralHero can notify your backend when a campaign event occurs; your backend can validate that event, map the subscriber data, and call Volanea’s REST API to send a transactional message.

This is a webhook-to-email integration, not a native ReferralHero app. That distinction matters: ReferralHero sends an outbound webhook to an endpoint you control, then your server makes the authenticated request to Volanea. The result is a flexible path for welcome emails, referral milestones, reward notices, internal alerts, and follow-ups that use the data ReferralHero already tracks.

What this ReferralHero and Volanea integration does

ReferralHero runs referral, affiliate, contest, and waitlist campaigns around lists and subscribers. A subscriber is the person who joins a list or campaign, receives a referral code, may be referred by another subscriber, and can later generate referrals of their own.

For this integration, the practical trigger is a subscriber successfully subscribing to a ReferralHero list. ReferralHero’s webhook documentation uses that event as its example: when a user successfully subscribes to a list, ReferralHero sends a notification to registered webhooks. Your endpoint receives the subscriber information and decides whether to send an email.

A typical flow looks like this:

1. A person submits your ReferralHero signup form, widget, or a custom form connected to ReferralHero.
2. ReferralHero creates the subscriber in the relevant list.
3. ReferralHero delivers a webhook notification to your HTTPS endpoint.
4. Your endpoint validates and normalizes the subscriber payload.
5. Your endpoint sends a personalized transactional email with Volanea at POST https://api.volanea.com/v1/send.
6. Volanea queues the message through its sending pipeline while your application records the result for audit and support.

This lets you control the message rather than depending on a fixed campaign email. For example, you can send a welcome message with the subscriber’s referral code, tell a referrer that their friend joined, notify an internal team when a high-value referral arrives, or trigger a product onboarding sequence in your own application.

Why use a server-side relay instead of calling Volanea directly

ReferralHero has outbound webhooks, but it is not a client-side email transport. The secure integration pattern is therefore:

ReferralHero webhook → your server-side endpoint → Volanea REST API

Do not attempt to place a Volanea secret key in a public ReferralHero widget, browser JavaScript, a landing-page form, or any client-visible configuration. A Volanea secret key authorizes email sends. Anyone who obtains it can potentially send mail through your account, consume sending capacity, damage deliverability, or create a security incident.

Your relay can be a small route in an existing app, a serverless function, or a worker. It needs only three responsibilities:

• receive ReferralHero’s webhook over HTTPS;
• decide whether the event should cause an email;
• call Volanea using a server-only secret.

This is also where you add rules that ReferralHero alone cannot know. You may want to suppress messages for internal test addresses, choose a localized template, avoid messaging users who opted out of a nonessential category, or include data from your CRM before sending.

ReferralHero’s own API documentation makes the same general security point for its API token: keep privileged tokens out of public code and use backend-only code. Apply that discipline to both platforms’ credentials.

The concrete ReferralHero trigger: a subscriber joins a list

The most dependable starting point is the subscriber-created path: a person successfully subscribes to one of your ReferralHero lists. In ReferralHero terminology, a list is also the campaign where subscribers are stored and managed.

Use this trigger when the message is intended for the newly added participant. Common examples include:

• a referral-program welcome email;
• a “your personal referral link is ready” email;
• a waitlist confirmation;
• a contest-entry confirmation;
• an invitation to complete another onboarding action;
• an internal lead alert when a new subscriber is referred.

ReferralHero subscriber data includes fields such as the subscriber’s numeric id, name, email, code, whether they were referred, referred_by information, their people_referred count, and campaign-specific data such as extra_field, extra_field_2, referral_value, referral_category, and transaction_id where applicable.

Not every campaign or signup source populates every field. An email-based campaign may provide email; a campaign configured around a different unique identifier may not. A webhook handler must treat optional fields as optional rather than assuming that every subscriber has a name, referrer, transaction, or referral value.

Choose the email moment deliberately

A subscriber-created webhook is a good choice for acknowledging a signup. It is not necessarily the right event for a reward email.

If your program has multiple conversion steps, ReferralHero can represent referral progress with statuses such as Pending, Unconfirmed, and Confirmed. A welcome email when a person signs up should not promise a reward that requires a later purchase, qualification, or confirmation. Keep the email tied to the actual business event that occurred.

For example:

• New subscriber: “Welcome—your referral code is ready.”
• Referred subscriber: “You joined through Alex’s referral link. Here is what happens next.”
• Confirmed conversion: “Your referral is confirmed.”
• Reward unlocked: “Your reward is available.”

Use a dedicated webhook or a server-side polling/reconciliation process for downstream events if the subscriber-created webhook does not represent the outcome you need. Do not send an incentive email merely because a record exists.

Understand the ReferralHero webhook payload before mapping it

ReferralHero’s subscriber object is the basis for the webhook data you should expect to work with. The fields below reflect the documented subscriber shape, with values that vary by campaign configuration and subscriber history:

{
  "id": 123456,
  "name": "Taylor Morgan",
  "email": "taylor@example.com",
  "extra_field": "Pro plan",
  "extra_field_2": "United States",
  "code": "TAYLOR25",
  "position": "42",
  "referred": true,
  "referral_value": 0,
  "referral_category": "waitlist",
  "transaction_id": null,
  "referred_by": {
    "id": 998877,
    "name": "Jordan Lee",
    "email": "jordan@example.com",
    "code": "JORDAN10"
  },
  "people_referred": 3
}

Treat this as a data contract to inspect, not a reason to hard-code assumptions. Capture a real test webhook from your own ReferralHero campaign before you enable production sends. Your particular payload can differ according to campaign settings, the enabled unique identifier, the event type, and whether a field exists for that subscriber.

The minimal mapping for a welcome email is usually straightforward:

Do not use name as a fallback email address. Do not render an undefined referral code. Do not reveal a referrer’s email address to the new subscriber unless that disclosure is intentional and appropriate for your program.

Validate before you send

A webhook is input from another system. Validate it as you would any external request:

• Confirm the request has the expected content type and parses as JSON.
• Confirm that email exists and is a syntactically usable address before sending a recipient email.
• Trim whitespace from names and codes before rendering them.
• Escape dynamic values before inserting them into HTML.
• Treat referred_by as optional.
• Keep webhook payloads out of public logs, because they can contain personal data.

For an additional pre-send check in flows where address quality is uncertain, use an email address verification tool before adding the address to a high-value or long-lived messaging workflow. Verification should complement—not replace—your consent and suppression practices.

Build the webhook relay and Volanea send request

The following Node.js example uses an Express route. It receives a ReferralHero subscriber webhook, checks for an email address, creates a stable idempotency key from the subscriber ID, and sends a personalized email through Volanea.

The example intentionally keeps VOLANEA_API_KEY on the server as an environment variable. It is not stored in browser code, ReferralHero form markup, a public repository, or a query string.

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

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

const VOLANEA_API_KEY = process.env.VOLANEA_API_KEY;
const FROM_EMAIL = process.env.FROM_EMAIL; // e.g. referrals@example.com

if (!VOLANEA_API_KEY || !FROM_EMAIL) {
  throw new Error("VOLANEA_API_KEY and FROM_EMAIL must be configured");
}

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

app.post("/webhooks/referralhero/subscriber", async (req, res) => {
  // ReferralHero subscriber fields supplied by the webhook payload.
  const subscriber = req.body;
  const email = typeof subscriber.email === "string"
    ? subscriber.email.trim().toLowerCase()
    : "";

  if (!email || !email.includes("@")) {
    // Acknowledge intentionally ignored events so the webhook is not retried
    // forever for a record that cannot receive this message.
    return res.status(204).end();
  }

  const subscriberId = String(subscriber.id ?? "unknown");
  const referralCode = String(subscriber.code ?? "").trim();
  const firstName = String(subscriber.name ?? "there").trim() || "there";
  const referrerName = String(subscriber.referred_by?.name ?? "").trim();
  const referred = subscriber.referred === true;

  // Stable for the same logical welcome email. Store this key in your database
  // if you need protection that survives deployments or handler changes.
  const idempotencyKey = crypto
    .createHash("sha256")
    .update(`referralhero-subscriber-welcome:${subscriberId}`)
    .digest("hex");

  const referralSentence = referred && referrerName
    ? `<p>You joined through ${escapeHtml(referrerName)}’s referral. ` +
      `Your own code is <strong>${escapeHtml(referralCode)}</strong>.</p>`
    : `<p>Your referral code is <strong>${escapeHtml(referralCode)}</strong>.</p>`;

  const textReferralSentence = referred && referrerName
    ? `You joined through ${referrerName}'s referral. Your own code is ${referralCode}.`
    : `Your referral code is ${referralCode}.`;

  const volaneaResponse = await fetch("https://api.volanea.com/v1/send", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${VOLANEA_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey
    },
    body: JSON.stringify({
      from: {
        email: FROM_EMAIL,
        name: "Acme Referrals"
      },
      to: [{
        email,
        name: subscriber.name || undefined
      }],
      subject: "Welcome—your referral code is ready",
      html: `
        <h1>Welcome, ${escapeHtml(firstName)}</h1>
        <p>Thanks for joining our referral program.</p>
        ${referralSentence}
        <p>Share your code with friends when you are ready.</p>
      `,
      text: `Welcome, ${firstName}.\n\n` +
        `Thanks for joining our referral program.\n\n` +
        `${textReferralSentence}\n\n` +
        `Share your code with friends when you are ready.`,
      tags: ["referralhero", "subscriber-welcome"],
      metadata: {
        referralhero_subscriber_id: subscriberId,
        referralhero_referral_code: referralCode,
        referralhero_referred: referred
      }
    })
  });

  const responseBody = await volaneaResponse.text();

  if (!volaneaResponse.ok) {
    console.error("Volanea send failed", {
      status: volaneaResponse.status,
      subscriberId,
      responseBody
    });

    // Return a failure so ReferralHero can treat this delivery as unsuccessful.
    // The stable Idempotency-Key protects the send if the webhook is delivered again.
    return res.status(502).json({ error: "Email provider request failed" });
  }

  console.info("Volanea email accepted", {
    subscriberId,
    status: volaneaResponse.status
  });

  return res.status(200).json({ ok: true });
});

app.listen(3000, () => {
  console.log("Listening on port 3000");
});

This is the core field mapping: ReferralHero’s subscriber.email becomes Volanea’s recipient address, subscriber.name becomes the recipient name and greeting, subscriber.code becomes the referral code, and subscriber.id becomes part of the idempotency key and metadata.

Consult the email API reference and setup guides when adapting this to templates, attachments, scheduled sends, webhooks, or your preferred runtime.

Configure ReferralHero without inventing a direct Volanea connection

There is no native ReferralHero-to-Volanea marketplace app required for this setup. Configure ReferralHero to send its outbound webhook to the HTTPS URL of your relay, such as:

https://api.example.com/webhooks/referralhero/subscriber

Create the registered webhook in ReferralHero for the subscriber event you want to react to. Start with a staging endpoint if you have one, then make a real test subscription through the same form, widget, or API path your users will use.

Before turning on production email, inspect these items:

1. The received JSON body. Confirm where the subscriber fields appear in your actual event.
2. The recipient address. Confirm the field is an email address for the campaign you chose.
3. The referral code. Confirm it is populated at the point you send the message.
4. The response status. Your relay should return a prompt 2xx response only after it has safely accepted or completed the work.
5. The Volanea result. Confirm the message appears in your sending activity and reaches a test inbox.

If you use a custom signup form, make sure the event is created only once. Double-submitting the form, calling both a ReferralHero widget and a JavaScript API on the same page, or running duplicate frontend handlers can create duplicate subscriber records before webhooks are even involved.

Keep the Volanea API key out of ReferralHero and the browser

The Volanea API key belongs in a server-side secret store. Depending on where your relay runs, that could be an environment variable in your application host, a cloud secret manager, a serverless-function secret, or a worker secret.

The correct security boundary is simple:

ReferralHero knows your webhook URL.
Your server knows the Volanea secret key.
The browser knows neither privileged server secret.

Do not place the Volanea key in a ReferralHero custom field, subscriber field, campaign copy, URL parameter, frontend environment variable prefixed for public exposure, or automation note. A key placed in any client-visible location should be considered compromised and rotated.

Separate authentication from event verification

Volanea authentication proves that your relay is authorized to send email. It does not prove that an incoming HTTP request came from ReferralHero.

If your ReferralHero webhook setup supports a secret or custom header, validate that value at the edge before processing the payload. Store the shared value as a server-side secret and compare it in a timing-safe manner. If you cannot configure a signing secret or shared header, make the endpoint difficult to discover, restrict it through network controls where feasible, and validate every payload conservatively.

Avoid using the Volanea key itself as the inbound webhook secret. Credentials should be scoped to a single purpose. An inbound secret authenticates the webhook source; an outbound Volanea key authorizes email sending.

Design the message for referral-program reality

A referral email often has two audiences: the person who has just joined and the existing participant who referred them. The payload tells you which context you have, but your copy should remain accurate even when optional fields are empty.

Welcome email to a new subscriber

For a new subscriber, prioritize orientation:

• confirm they joined;
• show their referral code or link if appropriate;
• explain the next action;
• state the reward condition precisely;
• include a support path.

Do not overcomplicate the first email. The recipient may have encountered your brand through a friend’s link and may not understand the rules yet. One primary action is usually better than a collection of unrelated links.

Referred-participant email

When referred is true and referred_by.name is available, you can acknowledge the relationship without oversharing. “You joined through Jordan’s referral” is generally more useful than exposing the referrer’s email address or internal account details.

If the program has qualification requirements, state them plainly. For example, “Your referral status is pending until you complete your first purchase” is safer than “Your reward is on its way” when no reward has been earned.

Internal operations alert

The same webhook can also send an internal message to a sales or community team. In that case, route the email to a fixed internal address and include the subscriber ID, campaign category, referral code, and referrer information. Still use idempotency: internal alerts can be just as disruptive when duplicated.

When this breaks: retries, timeouts, duplicates, and missing fields

A webhook integration is not a single guaranteed handoff. It is a chain of network operations: ReferralHero delivers an event, your endpoint receives and processes it, then your endpoint calls Volanea. Production reliability comes from handling the uncertain states between those steps.

ReferralHero retries can create duplicate send attempts

If ReferralHero does not receive a successful response from your endpoint—for example, because your server returns a 5xx error, crashes, or times out—it can attempt delivery again. From your application’s perspective, assume the event may arrive more than once.

The dangerous case is an ambiguous outcome:

1. Your endpoint calls Volanea.
2. Volanea accepts the email.
3. The connection fails before your endpoint records the result or responds to ReferralHero.
4. ReferralHero retries the webhook.
5. Your endpoint attempts the same email again.

The Idempotency-Key header in the example is the protection against that scenario. Use one stable key for one logical email, and reuse it for retries of that same send. Do not generate a random key each time the webhook handler runs; doing that turns a retry into a new email request.

For a welcome email, a key based on the subscriber ID and message purpose is sensible:

referralhero-subscriber-welcome:<subscriber-id>

For a milestone email, include the milestone or event identifier so a legitimate future event can still send:

referralhero-referral-milestone:<subscriber-id>:first-referral

Webhook timeouts can make success look like failure

A webhook sender can time out before your endpoint finishes a slow operation. Do not make the webhook request wait on unnecessary work such as CRM enrichment, analytics fan-out, image generation, or a large database report.

For high-volume or business-critical programs, use a durable queue pattern:

1. Receive and validate the ReferralHero payload.
2. Calculate a deduplication key.
3. Store the event or queue job durably.
4. Return a 2xx response quickly.
5. Have a worker call Volanea with the same idempotency key.
6. Record the provider response and retry transient failures safely.

This pattern prevents webhook delivery time from becoming the duration of your full email workflow. It also gives you a place to inspect failed jobs, replay a specific event, and avoid losing a send during a deployment.

Payload fields may be missing for some campaigns or plans

Do not assume all ReferralHero fields are available in every configuration. Some campaigns use a unique identifier other than email. Some have no name field. A person may not have a referrer. Optional custom fields may be blank. A transaction-linked field will not exist for a simple waitlist signup.

Build explicit behavior for incomplete data:

• If there is no usable email, do not send recipient email; acknowledge or route the event based on your business policy.
• If there is no name, use a neutral greeting such as “Welcome.”
• If there is no referral code yet, avoid sending an email whose central promise is a code.
• If referred_by is absent, use generic welcome copy.
• If a custom field controls segmentation, give it a default branch rather than failing the whole request.

A missing optional field is not automatically an integration error. It becomes an error only when your chosen message requires that field.

Volanea errors need different handling than invalid events

Separate permanent validation failures from retryable infrastructure failures.

A missing recipient email is a permanent data problem for that message. Retrying it will not create an address. A 429 response, temporary 5xx response, or networking error may be transient. In the latter cases, retry using the same idempotency key and a bounded backoff strategy.

Record enough context to diagnose the issue without storing entire message bodies or unnecessary personal data. At minimum, log the ReferralHero subscriber ID, the logical message type, the idempotency key, the Volanea HTTP status, and a request correlation ID from your own system.

Test the complete path before enabling live sends

Testing only the Volanea API call is not enough. Testing only that ReferralHero can reach a URL is not enough. Test the entire event path with a real campaign configuration.

Use this checklist:

• Create a non-production ReferralHero campaign or identify a safe internal test list.
• Point its webhook at a test relay endpoint.
• Subscribe using a real inbox you can inspect.
• Capture the received payload and compare it to the field mappings in your code.
• Confirm that the Volanea API request includes the expected recipient, subject, text, HTML, tags, and metadata.
• Submit the same logical event again to confirm idempotency prevents a second message.
• Remove or blank optional fields in a controlled test to verify your fallback copy.
• Force a temporary Volanea failure and confirm your retry behavior does not duplicate the send.
• Review the delivered email on desktop and mobile clients.

Use a verified sender identity and an authenticated sending domain before production. A technically correct API call is not a complete deliverability strategy. Your From address, domain authentication, content, recipient expectations, and complaint rate all influence whether the email reaches the inbox.

Practical alternatives when direct webhooks are not the right fit

A direct webhook relay is the strongest option when you need control, security, observability, and predictable duplicate handling. It is not the only option.

Use Make for low-code orchestration

ReferralHero has a Make integration with modules for actions such as creating subscribers, confirming referrals, listing subscribers, and making custom API calls. Make can work well when your workflow needs to enrich a subscriber from another SaaS system before calling an HTTP endpoint.

Even in a low-code workflow, keep the Volanea key in Make’s protected connection or secret handling rather than putting it in mapped data. Confirm how the automation platform handles retries, execution replays, and error recovery, then carry a stable event identifier into Volanea’s idempotency header where the tool supports custom headers.

Use Zapier as middleware for simple workflows

Zapier’s Webhooks trigger can receive a webhook URL from ReferralHero and parse a posted body. You can then use an HTTP action to call Volanea. This is appropriate for simple, lower-volume workflows where the operational trade-offs are acceptable.

The limitation is control. A custom server gives you better validation, durable queues, custom authentication, database-backed deduplication, and detailed observability. If a welcome email is part of a critical referral funnel, the server-side relay is usually the more durable architecture.

Use ReferralHero’s own automation emails when custom logic is unnecessary

If the email is a straightforward campaign email and ReferralHero’s built-in automation meets the requirement, native campaign automation may be simpler. Use Volanea when you need a central sending layer, custom templates, application data, shared suppression handling, message-level metadata, a unified email API, or a workflow that extends beyond ReferralHero.

Conclusion: make the webhook event the source of truth

To send email from ReferralHero with Volanea, use the subscriber signup event as the starting signal, receive the ReferralHero webhook at a server-side endpoint, map the subscriber fields into a Volanea send request, and protect the operation with a stable idempotency key.

The critical implementation choices are not the HTTP call alone. They are keeping the Volanea key off the client, acknowledging only events your system has handled safely, treating webhook delivery as at-least-once, and writing messages that remain accurate when optional referral fields are absent.

Start with one useful transactional message—usually a welcome email with the subscriber’s referral code—then add milestone, referral-confirmation, reward, and internal notification flows once the basic pipeline is observable and reliable.

FAQ

Does ReferralHero have a native Volanea integration?

No. This setup uses ReferralHero outbound webhooks plus a server-side relay that calls the Volanea REST API. It does not require or assume a ReferralHero marketplace plugin.

What ReferralHero event should trigger the first email?

Use the event where a user successfully subscribes to your ReferralHero list for a welcome or referral-code email. Use a later confirmation, qualification, or reward event for messages that depend on a completed conversion.

Where should I store the Volanea API key?

Store it only in a server-side environment variable or secret manager used by your webhook relay. Never put it in client-side JavaScript, ReferralHero form configuration, public repositories, or URL parameters.

How do I prevent duplicate emails after webhook retries?

Create one deterministic Idempotency-Key for each logical message, such as a subscriber ID plus message type, and reuse that key for every retry of the same event.

What if the ReferralHero payload has no email address?

Do not attempt a recipient email send. Some campaign setups can use a unique identifier other than email, and optional fields can be absent. Return an intentional response, log the condition safely, or route the record into a separate follow-up process.