How to Send Email from SurveySparrow with Volanea

Survey responses are most valuable while the context is fresh. This guide shows how to send email from SurveySparrow with Volanea after a respondent completes a survey, without exposing an email API key or pretending there is a native SurveySparrow marketplace app.

SurveySparrow can send an outbound webhook when a survey response is recorded. Your server receives the response data, validates that it came from your SurveySparrow setup, maps the selected fields into an email, and calls Volanea's REST API. That small middleware hop is intentional: it protects the Volanea secret key, gives you a place to validate data, and makes duplicate prevention practical.

What this integration does—and does not do

There is no native Volanea app, listing, or marketplace plugin for SurveySparrow. The connection is a webhook-to-API integration:

1. A respondent submits a SurveySparrow survey.
2. SurveySparrow records the response and sends an HTTP request to your public HTTPS endpoint.
3. Your endpoint checks an authentication header and validates the payload.
4. Your endpoint sends a transactional email through POST https://api.volanea.com/v1/send.
5. It returns a quick successful response to SurveySparrow after Volanea accepts the send.

For ordinary survey webhooks, the concrete trigger is a completed survey submission. SurveySparrow's API configuration identifies this as the submission_completed event type for a survey object. In the product UI, SurveySparrow describes the behavior more simply: every new survey response triggers a request to the configured webhook URL. Opening a survey alone does not trigger it; a response must be recorded first.

This setup fits confirmation emails, support acknowledgements, high-score review requests, low-NPS recovery messages, lead-routing notices, and internal alerts. It is not a replacement for a bulk campaign system. A response event should cause a relevant one-to-one operational message, not add someone to an unrelated promotional mailing stream.

Why use a middleware endpoint instead of calling Volanea directly

It may be tempting to configure a SurveySparrow webhook to call Volanea's /v1/send endpoint directly. Do not do that with a production secret key.

SurveySparrow's webhook configuration can send a request body and custom request headers. That is useful for authenticating the webhook to your endpoint, but it means any Volanea Authorization: Bearer sk_... credential entered there becomes an integration secret stored in a third-party configuration surface. It also removes the best place to apply business rules before an email goes out.

A server-side endpoint gives you important controls:

• Secret isolation: the Volanea API key stays in a server environment variable or managed secret store, not in a browser-visible application, survey JavaScript, or a copied webhook payload.
• Payload validation: you can reject a blank, malformed, or untrusted email address before attempting delivery.
• Conditional logic: only send a follow-up for responses that meet your chosen criteria, such as an NPS score of 0–6.
• Idempotency: use a stable response identifier to make webhook retries safe.
• Auditability: store the SurveySparrow response ID, Volanea message ID, and outcome together.
• Content safety: escape respondent-provided text before placing it in HTML.

This is a small amount of code, but it separates survey collection from email infrastructure cleanly. It is also portable: the same endpoint can be called from another form or workflow later without moving the Volanea key.

Prerequisites before you send email from SurveySparrow

Have these pieces ready before configuring the webhook:

1. A SurveySparrow survey with an email field. The email should be required if sending the follow-up email is essential. If the survey permits anonymous responses, your integration must safely skip those responses.
2. A public HTTPS endpoint. SurveySparrow's outgoing-webhook documentation requires an endpoint that is publicly accessible over HTTPS, accepts HTTP POST, and returns a 200 or 204 status. For local development, use a secure tunnel only for testing.
3. A Volanea account, API key, and verified sending domain. Volanea's sending API uses Bearer authentication. A production sender should use a verified domain rather than an arbitrary From address.
4. A deployment location for the middleware. A Node server, serverless function, container, or worker is suitable as long as it can receive the webhook and has secure server-side environment variables.
5. A webhook authentication secret. Use a separate random value for SurveySparrow-to-your-server authentication. It is not the Volanea API key.

If you still need to create a sending key or verify the sending domain, use the email API reference and setup guides before wiring the survey event. Verify the domain first; otherwise your webhook can work perfectly while the email request is refused because the sender is not authorized.

The SurveySparrow trigger and payload model

SurveySparrow supports survey webhooks whose event type is submission_completed. A survey webhook configuration includes a destination URL, HTTP method, optional headers, a payload, and an option to include partial submissions. For this integration, use POST, set Content-Type: application/json, and leave partial-submission handling disabled unless you deliberately want messages before completion.

An important implementation detail: SurveySparrow does not impose one universal response JSON document that every recipient receives. Its survey webhook configuration lets you construct the payload and insert survey-response placeholders. The body you receive is therefore the JSON shape you configure. This is helpful because your middleware only needs a small, stable contract instead of needing to understand every question in a survey.

Design a minimal webhook contract

Configure the webhook Content body with JSON containing these conceptual values, inserting the appropriate SurveySparrow placeholders with the picker for your survey:

• response_id: the unique response/submission identifier.
• respondent_email: the answer to the required email question.
• respondent_name: the answer to a name question, if collected.
• score: the answer to an NPS, rating, or satisfaction question.
• comment: the answer to an open-text feedback question.
• survey_name: useful context for logs and internal messages.

After SurveySparrow substitutes the chosen placeholders for one completed response, the real HTTP request body received by your endpoint should have this shape:

{
  "response_id": "123456789",
  "respondent_email": "ada@example.com",
  "respondent_name": "Ada Lovelace",
  "score": "6",
  "comment": "The checkout flow was confusing on mobile.",
  "survey_name": "Post-purchase feedback"
}

The values and field names shown above are your integration contract. The literal placeholder token syntax is selected from SurveySparrow's picker and can vary with the survey question and product UI, so do not manually guess a token name from an example on another account. Build the JSON shell, use the picker to insert the exact response placeholders, submit a test survey, and inspect the webhook log plus your endpoint logs before enabling the automation for real respondents.

Avoid sending every question by default. Survey responses can include personal data, free-form text, or sensitive feedback. Transmit only the fields needed to determine whether to send and to personalize the email.

Configure the SurveySparrow webhook

For a survey-level response webhook, SurveySparrow's support flow is: open the survey, select Integrate, open Webhooks, add a webhook, enter the callback URL, choose response placeholders, and save the details. SurveySparrow also provides webhook logs for checking whether it successfully delivered the request.

Use these settings as the baseline:

For an account using SurveySparrow's Developer Portal outgoing-webhook flow, create a new webhook from Settings → Apps and Integrations → Developer Portal, then choose the Webhook tab. SurveySparrow's Developer Portal supports endpoint authentication methods, while the REST webhook model also supports custom request headers. Either route can protect the connection to your server.

Add a separate webhook authentication header

Set a request header such as:

X-SurveySparrow-Webhook-Token: a-long-random-value-created-for-this-webhook

Store the same value in your middleware environment as SURVEYSPARROW_WEBHOOK_TOKEN. This header proves that a request has the secret configured for this webhook. Use HTTPS, compare the values safely on the server, and rotate the token if it is exposed.

Do not place the Volanea API key in this header. The Volanea key belongs only in the server environment where the outbound email request is made. A survey respondent never needs it, a browser never needs it, and SurveySparrow never needs it.

Working Node.js receiver and Volanea field mapping

The following Express endpoint receives the deliberately small SurveySparrow payload shown above, validates the webhook token, checks the email, escapes untrusted text, and sends a Volanea email. It uses response_id as the Idempotency-Key, so a retry of the same completed response does not create another email send.

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

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

const {
  VOLANEA_API_KEY,
  SURVEYSPARROW_WEBHOOK_TOKEN,
  VOLANEA_FROM = "Feedback Team <feedback@example.com>",
} = process.env;

if (!VOLANEA_API_KEY || !SURVEYSPARROW_WEBHOOK_TOKEN) {
  throw new Error("Missing VOLANEA_API_KEY or SURVEYSPARROW_WEBHOOK_TOKEN");
}

function safeEqual(a = "", b = "") {
  const left = Buffer.from(a);
  const right = Buffer.from(b);
  return left.length === right.length && crypto.timingSafeEqual(left, right);
}

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

function isEmail(value) {
  return typeof value === "string" &&
    /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim());
}

app.post("/webhooks/surveysparrow", async (req, res) => {
  const suppliedToken = req.get("X-SurveySparrow-Webhook-Token") || "";

  if (!safeEqual(suppliedToken, SURVEYSPARROW_WEBHOOK_TOKEN)) {
    return res.status(401).json({ error: "Unauthorized webhook" });
  }

  const {
    response_id,
    respondent_email,
    respondent_name = "there",
    score,
    comment = "",
    survey_name = "survey",
  } = req.body || {};

  if (!response_id || !isEmail(respondent_email)) {
    // Return a clear client error: do not send to an empty or malformed address.
    return res.status(422).json({ error: "response_id and respondent_email are required" });
  }

  const name = escapeHtml(respondent_name);
  const feedback = escapeHtml(comment);
  const rating = escapeHtml(score ?? "not provided");
  const survey = escapeHtml(survey_name);

  // Stable response IDs make SurveySparrow delivery retries safe.
  const idempotencyKey = `surveysparrow-response-${response_id}`;

  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: VOLANEA_FROM,
      to: respondent_email.trim(),
      subject: "Thanks for sharing your feedback",
      text: `Hi ${respondent_name},\n\nThanks for completing ${survey_name}. We received your score (${score ?? "not provided"}) and feedback.\n\n— Feedback Team`,
      html: `<p>Hi ${name},</p><p>Thanks for completing <strong>${survey}</strong>.</p><p>We received your score (<strong>${rating}</strong>) and feedback.</p>${feedback ? `<blockquote>${feedback}</blockquote>` : ""}<p>— Feedback Team</p>`,
    }),
  });

  const result = await volaneaResponse.json().catch(() => ({}));

  if (!volaneaResponse.ok) {
    console.error("Volanea send failed", {
      responseId: response_id,
      status: volaneaResponse.status,
      result,
    });
    return res.status(502).json({ error: "Email provider rejected the request" });
  }

  console.info("Survey follow-up accepted", {
    responseId: response_id,
    recipient: respondent_email,
    volanea: result,
  });

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

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

The field mapping in that endpoint is explicit:

The Volanea request uses Authorization: Bearer <secret-key> and POST /v1/send. A send may address one recipient or up to 50 recipients, but a survey follow-up should normally remain one response to one recipient. That keeps consent, personalization, suppression behavior, and message history straightforward.

Make the email logic appropriate to the survey outcome

The example sends a generic acknowledgement. In production, the most useful workflow often branches on the response.

Low-score recovery

For an NPS or satisfaction score below your threshold, send an immediate acknowledgement with a direct path to help. Do not claim that someone will call unless you have an actual ticketing or support workflow behind it. A safe message is: “Thanks for telling us. We have shared your feedback with the team, and you can reply to this email if you would like help.”

Your endpoint can conditionally change the subject and template when Number(score) <= 6. You can also send an internal alert to a support mailbox, but make that a distinct message with a distinct idempotency key, such as surveysparrow-response-123456789-internal-alert.

High-score review invitation

For highly positive feedback, you may invite the respondent to leave a review or share a testimonial. Treat this as a marketing or consent question rather than silently assuming permission from a satisfaction response. Use clear wording, avoid aggressive repeated reminders, and honor applicable email-consent rules.

Lead or onboarding follow-up

A qualification survey can trigger a practical next step: confirmation of a demo request, an onboarding checklist, or a routing email to a sales representative. Put only the information needed for the recipient in the email. A public reply address should be monitored; a no-reply sender is a poor fit for a message that asks for further feedback.

Authentication and secret handling

There are two independent authentication boundaries in this integration.

First, SurveySparrow authenticates to your middleware endpoint. Use a separate webhook token in a custom header, Basic Authentication if that is your chosen available configuration, or SurveySparrow's configured outgoing-webhook authentication option. Your endpoint verifies the value before it processes the body or makes an outbound email request.

Second, your middleware authenticates to Volanea using the Volanea secret key in the Authorization header. Put that key in a server-side secret manager or environment variable named VOLANEA_API_KEY. Do not put it in:

• Survey JavaScript embedded on a public page.
• A SurveySparrow survey question, custom variable, or response payload.
• A frontend environment variable exposed during browser builds.
• A client-side Zapier/Make code step that users can inspect or duplicate without access controls.
• Source control, screenshots, ticket comments, or application logs.

The practical answer to “where does the Volanea API key live on the SurveySparrow side?” is: nowhere. It should not live on the SurveySparrow side at all. SurveySparrow only holds the destination URL and the independent secret it uses to authenticate to that URL. Your server holds the Volanea key and makes the Volanea call.

Rotate keys and tokens independently. If the SurveySparrow webhook token leaks, replace it in SurveySparrow and the middleware. If the Volanea key leaks, revoke or rotate it in Volanea, update the server secret, redeploy, and review send logs for unexpected activity.

Prevent duplicate sends with idempotency

Webhooks are delivery notifications, not a guarantee of exactly-once business processing. A sender can retry after a timeout, a network interruption can hide a successful response, and deployments can produce transient failures. If every inbound webhook blindly sends another message, the same person can receive duplicate acknowledgements.

Volanea supports safe retries through the Idempotency-Key request header. Use a deterministic key built from an immutable SurveySparrow response identifier, not a random UUID created per request. The example uses:

Idempotency-Key: surveysparrow-response-123456789

That ties exactly one confirmation email to response 123456789. If SurveySparrow attempts delivery again because it did not receive your first 200 response, the repeated Volanea request carries the same idempotency key.

Idempotency protects the outbound provider call, but it does not replace your own state for complex workflows. If you send multiple message types per response, store a database record keyed by response_id and message purpose. That record can track whether the respondent acknowledgement, internal alert, CRM update, and ticket creation each succeeded.

When this breaks

Every integration has failure modes. The following problems are specific to the SurveySparrow-to-middleware-to-Volanea hop and are worth designing for before launch.

SurveySparrow retries and duplicate email risk

If SurveySparrow sends the webhook, your server sends the email, and the connection closes before SurveySparrow sees your success response, SurveySparrow may retry. Without idempotency, the same completed response can generate two emails.

Use response_id as the stable idempotency input. If your configured survey payload does not include a response ID placeholder, add it before production. Also ensure partial submissions are off unless your intended business rule explicitly supports multiple response states.

Webhook timeouts

SurveySparrow expects the endpoint to return a successful HTTP response. Do not perform long database reports, file generation, AI analysis, or several unrelated API calls in the synchronous webhook request path. Keep the receiver focused: authenticate, validate, submit the email request, record essential state, and return 200.

For work that can take longer, persist a job first and acknowledge the webhook promptly. A background worker can then perform the longer work. If the email itself is mission-critical, make the job durable before returning success so a process crash does not silently lose the event.

Missing fields or plan/configuration differences

Survey questions may be optional, hidden by logic, unavailable in a share type, or absent for an anonymous response. The email field may be blank even though a test submission had a value. SurveySparrow's own API guidance notes that requests can fail when an expected email value is empty.

Validate every field at the receiver. A missing respondent_email should produce no outbound email. Log the response ID and reason, but avoid logging unnecessary survey content. For optional values such as name, score, and comment, provide safe defaults or omit them from the template.

Incorrect placeholder mapping

Because the survey webhook payload is configured with selected placeholders, changing a question, duplicating a survey, or selecting the wrong field can change the data your endpoint receives. A payload that is valid JSON can still be semantically wrong—for example, a company name arriving where an email address is expected.

Test with known answers after every survey edit. Keep a small automated contract test that posts a representative payload to a non-production version of the endpoint and verifies the expected recipient, subject, and idempotency key.

Authentication failures

A 401 from your endpoint usually means the SurveySparrow webhook token header is missing or does not match. Check the configured header name and value, but do not paste secrets into shared logs. A 401 or 403 from Volanea usually points to an invalid API key, a disabled key, or a sender/domain authorization issue.

Keep the two credentials separate in your mental model and monitoring. The SurveySparrow token only proves a request may enter your endpoint. The Volanea key only authorizes email sending from your server.

Volanea accepts the request but the message is not delivered

An accepted send is not the same thing as inbox placement. A recipient can be suppressed, unsubscribed where applicable, invalid, or later rejected by the receiving mailbox provider. Verify your sending domain, use a real From identity, include a usable plain-text part, and observe delivery, bounce, and complaint events in your email operations process.

For pre-send hygiene on addresses collected in surveys, consider checking addresses with the free email address verification tool. It is especially useful when an email question is optional or free-form, though verification should not be treated as consent to send unrelated mail.

Testing the complete flow

Do not begin with a production survey audience. Use a duplicate survey or a controlled test audience and test the whole chain in this order:

1. Deploy the endpoint with a test Volanea API key where appropriate and a test sender configuration.
2. Configure the SurveySparrow webhook with the exact payload fields you intend to rely on.
3. Add the independent webhook authentication header.
4. Submit a response with a known email address, name, score, and comment.
5. Confirm SurveySparrow's webhook logs report successful delivery.
6. Confirm your middleware logs show a validated response_id and the expected mapped recipient.
7. Confirm Volanea accepted the send and inspect the content received in the test inbox.
8. Submit the same webhook payload again manually and verify that the stable idempotency key prevents a second message from being created.
9. Test blank email, missing response ID, malformed JSON, wrong webhook token, and a score branch.

Use a staging endpoint and a staging SurveySparrow webhook for changes. If you deploy a new version directly on the production URL, a syntax error can turn every new response into a failed webhook event until it is corrected.

Operational guidance for reliable follow-up email

A survey-triggered email should feel like a continuation of the respondent's action. Mention the survey or context in the subject and opening line. A vague “Thank you for your submission” may look suspicious if the person completed a branded survey minutes earlier.

Keep the sender recognizable, avoid attaching raw survey data to emails, and do not quote sensitive free-text feedback in a message that might be forwarded. If the survey is about health, employment, financial information, or another sensitive subject, send only an acknowledgement unless the respondent specifically asked for a copy of their response.

Monitor three layers:

• SurveySparrow webhook logs for whether SurveySparrow reached your endpoint.
• Application logs and metrics for authentication failures, validation skips, latency, retries, and provider errors.
• Volanea sending and event records for accepted sends, delivery outcomes, bounces, complaints, and suppressions.

That separation shortens incident response. If SurveySparrow reports success but there is no Volanea request, the problem is your middleware. If the Volanea request was accepted but the person did not receive the message, investigate sender authorization, suppression status, and delivery events rather than repeatedly re-triggering the survey webhook.

Conclusion

To send email from SurveySparrow with Volanea, use SurveySparrow's completed-response webhook as the trigger, send only a minimal configured JSON payload to a server endpoint, and let that endpoint call Volanea's POST /v1/send API. This is more secure than putting an email key in survey configuration and more reliable than treating a webhook retry as a new event.

The essential production decisions are simple: require or validate the respondent email, keep the Volanea API key only on the server, authenticate SurveySparrow separately, use the response ID as an idempotency key, and test the exact placeholder mappings for every survey version. With those controls in place, feedback can trigger a timely, personal email without turning a survey integration into a source of duplicate or unsafe sends.

FAQ

Does SurveySparrow have a native Volanea integration?

No. This setup uses SurveySparrow's outbound webhook capability and a middleware endpoint that calls Volanea's REST API. There is no native SurveySparrow marketplace installation flow to use for Volanea.

What SurveySparrow event should trigger the email?

Use a completed survey response. In SurveySparrow's webhook API model, the event type is submission_completed for a survey. Opening a survey without recording a response does not trigger the normal response webhook.

Can I put the Volanea API key directly in the SurveySparrow webhook headers?

Technically a webhook can send headers, but you should not do this for production. Put the Volanea key in your server-side secret store and have the middleware make the Volanea request. Configure SurveySparrow with a separate token used only to authenticate to your middleware.

How do I stop duplicate emails if SurveySparrow retries a webhook?

Include the SurveySparrow response ID in the webhook payload and use it to create a stable Volanea Idempotency-Key, such as surveysparrow-response-123456789. Do not generate a new random key for each retry.

What happens if the response has no email address?

Your endpoint should skip the send and return a clear validation response or record the case for review. Make the email survey question required when an acknowledgement is required, and always validate the value server-side before calling Volanea.