How to Send Email From Airbyte With Volanea

Airbyte is built to move data, not to run per-record marketing or transactional workflows. To send email from Airbyte reliably, use Airbyte’s workspace-level webhook notification for a completed sync, receive that notification in a small server-side relay, and let the relay call Volanea’s email API.

The important limitation comes first: Volanea does not have a native Airbyte destination, marketplace listing, or one-click Airbyte app. Airbyte can send a generic outbound webhook notification, but that notification cannot call Volanea’s email API directly because Volanea requires Bearer authentication and a purpose-built email payload. The relay is therefore not an unnecessary extra component—it is where authentication, payload mapping, validation, and duplicate protection belong.

What this Airbyte-to-email integration actually does

This integration sends an operational email when an Airbyte connection reaches a notification-worthy state. The most useful initial use case is a successful sync notification: a source-to-destination connection completes, Airbyte posts a webhook, and the relay emails a data team, client-success team, or other internal recipient.

That makes this a sync-status notification pattern, not a record-level automation pattern. Airbyte does not emit an outbound webhook for every contact created, form submitted, deal stage changed, or row loaded into a warehouse. Its standard notification model is centered on workspace and connection events.

A typical flow looks like this:

1. An Airbyte connection runs on its configured schedule or is started manually or through the Airbyte API.
2. The connection’s sync succeeds, fails, is queued, or produces another supported notification event.
3. Airbyte sends the configured workspace webhook notification to your relay endpoint.
4. The relay validates the incoming request, normalizes the notification text, and decides whether it should produce an email.
5. The relay calls Volanea’s POST /v1/send endpoint with a verified sender, recipient list, subject, HTML body, text fallback, and stable idempotency key.
6. Volanea queues the message through its transactional sending pipeline.

This division of responsibilities is healthy. Airbyte remains responsible for replicating data. Your relay converts a pipeline event into a deliberate notification. Volanea is responsible for the email send itself.

The real Airbyte trigger: a workspace notification after a sync

The concrete Airbyte trigger is Successful syncs, configured under workspace notifications. Airbyte documents notifications for events including successful syncs, failed syncs, connection updates, repeated failures, disabled syncs, and queued syncs. A successful-sync notification is emitted after a sync for one of the workspace’s connections completes successfully.

That wording matters. The trigger is not “a new record in Airbyte.” It is not “a destination row was created.” It is also not a generic workflow-builder event that can be filtered per source field. It is an Airbyte connection notification.

For an initial implementation, enable only the event you need:

• Successful syncs for a data freshness or completion message.
• Failed syncs for an operational alert.
• Warning - Repeated Failures for escalation rather than one email per failed job.
• Queued syncs only if capacity waiting is meaningful to your team; Airbyte marks these notifications off by default because queueing may be expected behavior.

Starting with successful syncs for every connection can create noise quickly. A workspace with hourly or more frequent connections can generate far more messages than a human team wants to read. It is usually better to route all Airbyte notifications to the relay, then apply an allowlist for the one or two connection names that deserve an email.

Where to configure the webhook in Airbyte

In Airbyte, workspace notification settings are configured at the workspace level. The documented UI path is Workspace settings > Notifications. Add the public HTTPS address of your relay as the webhook destination and enable the notification type you want, such as Successful syncs.

Airbyte Cloud can send notifications by email or webhook. Self-managed Airbyte can send webhook notifications but not Airbyte’s own email notifications. In both cases, the webhook option is the relevant transport for this Volanea integration.

Do not point this webhook at Volanea’s API endpoint. It will not work as a direct integration:

• Airbyte’s notification webhook is not an email-send form.
• Airbyte does not provide a place in this notification flow to attach Volanea’s Authorization: Bearer header.
• The incoming Airbyte body is a notification body, not the from, to, subject, html, and text structure Volanea expects.
• Putting a Volanea API key into a URL query string would expose a credential in logs, browser history, reverse proxies, and support screenshots.

The Airbyte webhook payload: use the notification body you actually receive

Airbyte’s webhook notification is an operational notification, not a stable record export. Recent Airbyte self-managed release notes specifically note that non-Slack webhook targets receive a text-only payload, while Slack targets continue to receive richer Slack-oriented payload fields. That is why a relay should treat the notification body as a transport message rather than assume it contains a durable, fully structured job schema.

For a generic webhook endpoint, design for this payload shape:

{
  "text": "Airbyte sync succeeded for Salesforce → Snowflake. This was for a sync started on Tuesday, September 29, 2026 at 14:00:00 UTC."
}

The exact wording can vary with the Airbyte notification type and deployment version. Do not write business logic that depends on parsing the source name, destination name, start timestamp, row count, or job identifier out of the text message. Those details are presentation content, not a contract for your email workflow.

Instead, map the one dependable notification field—the text—to a human-readable email. Add stable fields that you control in the relay: a fixed sender, an internal recipient list, a subject derived from the event class, and an idempotency key calculated from the incoming payload.

Field mapping from Airbyte to Volanea

The relay maps fields as follows:

A route-specific event name is more reliable than trying to infer the event from message wording. For example, configure one Airbyte workspace webhook endpoint for successful sync notifications:

https://alerts.example.com/hooks/airbyte/sync-succeeded?token=long-random-value

If you also need failed-sync emails, use a separate endpoint with a separate route or a route parameter that your relay validates:

https://alerts.example.com/hooks/airbyte/sync-failed?token=another-long-random-value

This lets the relay set the email subject from a value it controls rather than extracting it from free-form notification text.

Build the secure relay that calls Volanea

The following Node.js example uses Express and the built-in crypto module. It accepts the generic Airbyte notification payload, rejects unknown webhook URLs, avoids treating incoming text as HTML, and sends one transactional email through Volanea.

Set these server-side environment variables in your hosting provider, container platform, or secrets manager:

VOLANEA_API_KEY=replace-with-a-volanea-api-key
VOLANEA_FROM="Data Operations <alerts@updates.example.com>"
AIRBYTE_ALERT_TO="data-team@example.com,oncall@example.com"
AIRBYTE_WEBHOOK_TOKEN=replace-with-a-long-random-secret

Then install Express:

npm install express

Create server.mjs:

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

const app = express();

// Keep the raw body so the idempotency key is identical when Airbyte retries
// the same webhook delivery.
app.use(express.raw({ type: "application/json", limit: "256kb" }));

const {
  VOLANEA_API_KEY,
  VOLANEA_FROM,
  AIRBYTE_ALERT_TO,
  AIRBYTE_WEBHOOK_TOKEN,
} = process.env;

if (!VOLANEA_API_KEY || !VOLANEA_FROM || !AIRBYTE_ALERT_TO || !AIRBYTE_WEBHOOK_TOKEN) {
  throw new Error("Missing required relay environment variables");
}

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

function subjectFor(eventName) {
  if (eventName === "sync-failed") return "Airbyte sync failed";
  if (eventName === "sync-succeeded") return "Airbyte sync succeeded";
  return "Airbyte notification";
}

app.post("/hooks/airbyte/:eventName", async (req, res) => {
  const { eventName } = req.params;
  const { token } = req.query;

  // Airbyte notification webhooks do not provide a Volanea-style API-key field.
  // Keep a high-entropy route token in the webhook URL and reject invalid calls.
  if (typeof token !== "string" || token !== AIRBYTE_WEBHOOK_TOKEN) {
    return res.status(401).json({ error: "Unauthorized" });
  }

  if (!["sync-succeeded", "sync-failed"].includes(eventName)) {
    return res.status(404).json({ error: "Unknown Airbyte notification route" });
  }

  const rawBody = req.body.toString("utf8");
  let airbyte;

  try {
    airbyte = JSON.parse(rawBody);
  } catch {
    return res.status(400).json({ error: "Expected an application/json body" });
  }

  // Generic non-Slack Airbyte webhook notifications are handled as text-only.
  if (!airbyte || typeof airbyte.text !== "string" || airbyte.text.trim() === "") {
    return res.status(422).json({ error: "Missing Airbyte notification field: text" });
  }

  const notificationText = airbyte.text.trim();
  const bodyDigest = crypto
    .createHash("sha256")
    .update(`${eventName}:${rawBody}`)
    .digest("hex");

  const message = {
    from: VOLANEA_FROM,
    to: AIRBYTE_ALERT_TO.split(",").map((email) => email.trim()).filter(Boolean),
    subject: subjectFor(eventName),
    html: `
      <h1>${escapeHtml(subjectFor(eventName))}</h1>
      <p>Airbyte sent this workspace notification:</p>
      <pre style="white-space:pre-wrap;font-family:ui-monospace,monospace">${escapeHtml(notificationText)}</pre>
    `,
    text: `${subjectFor(eventName)}\n\n${notificationText}`,
  };

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

  const responseBody = await response.text();

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

    // A 5xx tells Airbyte that the relay did not complete successfully.
    // If Airbyte retries the delivery, the same idempotency key protects
    // against sending the same email twice.
    return res.status(502).json({ error: "Volanea send failed" });
  }

  console.info("Airbyte notification emailed", {
    eventName,
    idempotencyKey: `airbyte:${bodyDigest}`,
  });

  return res.status(202).json({ accepted: true });
});

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

This is a complete field mapping rather than a hand-waved “send an email” step. Airbyte’s text becomes both Volanea’s text fallback and safely escaped HTML message body. The relay supplies the sender, recipient list, subject, and authorization header because those values do not arrive in an Airbyte notification.

The Volanea request uses POST /v1/send, Bearer authentication, a JSON body, and an Idempotency-Key header. A single send can address one recipient or up to 50 recipients; for a small internal alert distribution list, the to array is appropriate.

For endpoint details, supported message fields, and sending-domain setup, use the Volanea API reference and setup guides.

Keep the Volanea API key on the relay, never in Airbyte-visible configuration

The Volanea key belongs in the relay’s server-side secret storage. In the sample, it is read from process.env.VOLANEA_API_KEY, which means the process obtains it at runtime without returning it to a browser or placing it in Airbyte’s notification UI.

The key must not sit in any client-visible configuration for several reasons:

• An API key authorizes email sends from your Volanea project.
• A webhook URL may be stored in application settings, logs, deployment histories, tickets, and screenshots.
• A browser-executed script can expose secrets through page source, network inspection, extensions, or bundled JavaScript.
• An Airbyte generic notification webhook is not a credential vault for arbitrary HTTP headers.
• Putting the key in a query string risks leaking it to load balancer logs, analytics tools, and HTTP referrer headers.

Use your platform’s native secret facility. On a container service, inject the key as an environment variable or mounted secret. On a serverless platform, use encrypted environment secrets. In a more mature deployment, place the key in a secret manager and grant the relay’s workload identity read access only to that one secret.

Protect the inbound Airbyte endpoint too

The query-token example above is a pragmatic baseline when the sending product cannot add a custom signature or authorization header. Treat that token as sensitive, rotate it if it is exposed, and avoid including it in operational emails or application logs.

For stronger protection, combine it with infrastructure controls:

• Require HTTPS and redirect or block plain HTTP before it reaches the app.
• Put the relay behind a web application firewall or API gateway.
• Rate-limit the route.
• Restrict source networks if your Airbyte deployment has stable egress addresses.
• Keep the handler narrow: accept only POST, only JSON, only recognized event routes, and only bodies under a reasonable size limit.
• Log an event hash and outcome, not the full notification body if it might contain sensitive source or destination names.

A secret URL token is not equivalent to a signed webhook. It is simply a compensating control for a notification transport that does not expose a place to configure a custom authentication header.

Configure Volanea before enabling Airbyte notifications

Before connecting Airbyte, create a sending identity in Volanea and verify the domain you plan to use. The from address in the relay must align with that verified identity. For example, use an operational mailbox such as alerts@updates.example.com, not an employee’s personal mailbox or an unverified domain.

Keep Airbyte operational mail separate from product mail where practical. Password resets, receipts, and account alerts generally need their own sending purpose and predictable content. Data-pipeline notifications can use a dedicated sender identity and recipient distribution list, making them easier to recognize, audit, and unsubscribe from internally if policies require it.

A sensible test sequence is:

1. Start with one internal recipient you control.
2. Configure only the Successful syncs event in Airbyte.
3. Run the relevant connection manually.
4. Confirm the relay receives a JSON body containing text.
5. Confirm Volanea accepts the send request.
6. Inspect the rendered HTML and plain-text version in the receiving inbox.
7. Add the production distribution list only after duplicate handling and alert volume look correct.

A clean recipient address is still worth checking before adding a large internal or customer-facing recipient group. Volanea’s email address verification tool is useful when an address has been imported from an external system or typed manually.

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

A webhook-to-email chain has two separate delivery hops: Airbyte to your relay, and your relay to Volanea. A successful HTTP response from one hop does not automatically prove the other completed. Design explicitly for each failure mode.

Airbyte retries can create duplicate emails

The classic duplicate scenario is an ambiguous outcome. Your relay sends the request to Volanea, Volanea accepts it, but the relay loses the response because of a network interruption or process restart. If the relay then returns a failure response to Airbyte, Airbyte may retry the webhook. Without idempotency, the second attempt can send a second email.

The sample avoids that by producing a stable Idempotency-Key from the event route and raw request body. A retry of the same payload produces the same digest and therefore the same idempotency key.

There is an important tradeoff: a text-only Airbyte notification does not give the relay a guaranteed unique job identifier. Two independently successful sync notifications with identical body text could theoretically hash to the same key. In practice, notification text normally includes timing or connection context, but you should not rely on wording for hard uniqueness.

For high-consequence notifications, improve the design in one of these ways:

• Store incoming event hashes with a short expiry window in Redis, DynamoDB, Postgres, or another durable store.
• Include a relay-generated received-at timestamp only after you have determined the delivery is not a retry.
• Use Airbyte’s API from the relay to look up the latest job details when your deployment and access model support it, then build a dedupe key from a real job ID.
• Send fewer notification categories and avoid treating an Airbyte sync notification as a customer-facing business event.

The point is not merely “turn on retries.” Retries are correct only when your idempotency strategy makes them safe.

Webhook timeouts make slow handlers unreliable

Your relay should acknowledge the incoming Airbyte webhook promptly. Do not use the request handler to perform unrelated warehouse queries, generate a report, call several third-party APIs, or wait for a long-running transform. Those tasks increase the odds that Airbyte sees a timeout and retries the notification.

For a lightweight internal alert, the direct relay-to-Volanea request can be fast enough. For anything more complex, accept the Airbyte event, persist it to a queue or database, return a successful response, and have a worker perform the email send. The worker can then retry Volanea-specific transient failures without asking Airbyte to replay the original webhook.

A durable queue also gives you observability: received time, normalized event type, delivery attempts, Volanea response status, final outcome, and dedupe key. That is much easier to debug than a single opaque webhook request.

Payload fields may be missing on some Airbyte deployments or targets

Do not assume every Airbyte webhook carries rich structured fields such as connection identifiers, job IDs, byte counts, rows synced, or attempt statistics. Airbyte’s release notes for self-managed 2.1 state that non-Slack webhook targets receive text-only payloads, while Slack endpoints receive full rich payloads. If you copied code from an older example that expects nested connection or job objects, it can fail with undefined values in a current generic webhook integration.

That is why the sample validates only airbyte.text. If it is absent, the relay returns 422 Unprocessable Entity and logs a controlled error rather than accidentally producing a vague email with blank fields.

If your workflow requires row counts, destination-table names, connection IDs, or an exact job URL, do not scrape them from the notification sentence. Fetch the relevant job or connection metadata through the Airbyte API using server-side credentials, or send an email from an orchestration layer that already owns those structured identifiers.

Volanea rejects the send request

A Volanea error is usually easier to categorize than an email-delivery outcome. Check these items first:

• Is VOLANEA_API_KEY present in the relay environment?
• Does the request use Authorization: Bearer <key> rather than a query parameter or a made-up header?
• Is the from address associated with a verified sending identity?
• Is to an array of valid recipient strings?
• Are both html and text present and non-empty?
• Is the relay preserving the same Idempotency-Key when retrying the same send?

Return a 5xx response from the relay only when the failure is truly temporary or when you want the upstream delivery to retry. For a permanent configuration failure—such as a missing environment variable—retrying Airbyte’s webhook will not fix the underlying issue and can create alert storms. Send that problem to application monitoring instead.

Choosing direct relay, Zapier, or Make

The direct relay is the most controlled option because you own the request validation, field mapping, secret storage, and idempotency behavior. It is also the best fit when the Airbyte notification is operational and recipients are internal.

A middleware automation service can still be useful when your team does not want to operate code. The architecture remains the same: Airbyte’s generic webhook notification goes to the automation tool’s webhook trigger, then the automation tool calls Volanea with a server-side stored credential. Do not confuse that with a native Airbyte-to-Volanea connection. It remains a webhook-to-middleware-to-email workflow.

Use a hosted automation layer when:

• The email is low-risk and internal.
• Your recipient list and content are simple.
• The automation product provides secure credential storage.
• You can configure retry behavior and avoid replaying sends blindly.
• You understand its task, run, and error-retention limits.

Use a custom relay when:

• Duplicate email prevention matters.
• You need a stable audit record.
• You need to fetch Airbyte job data before composing a message.
• You want custom routing by connection, environment, or event type.
• Notification text could contain sensitive operational metadata.
• You need stronger inbound controls than a public automation webhook provides.

Neither approach turns Airbyte into a per-record email engine. If your actual requirement is “send a customer an email after their CRM record changes,” trigger from the CRM, application backend, event bus, or workflow system that observes that change directly. Let Airbyte continue doing what it is designed to do: replicating the data into your analytics or operational destination.

Make the email useful instead of merely noisy

A sync-success message should help the recipient decide whether action is needed. A generic “sync complete” email for every pipeline may look healthy at first and then become ignored background noise.

A better subject convention is short and sortable:

• Airbyte sync succeeded — Salesforce to Snowflake
• Airbyte sync failed — billing export
• Airbyte repeated failures — production CRM pipeline

With text-only webhook payloads, you may not be able to reliably inject the source and destination names into the subject without parsing the prose. In that situation, a generic subject plus the unmodified notification in the body is more robust. If you need connection-specific subjects, create a separate route per important connection or enrich the event through Airbyte’s API before sending.

You should also decide whether success belongs in email at all. Many teams reserve email for failures, repeated-failure escalations, or daily summaries. Successful syncs can be logged to observability tooling or sent to a team chat channel, while email is reserved for a state that requires ownership.

Conclusion

To send email from Airbyte with Volanea, start with Airbyte’s real event model: a workspace notification such as Successful syncs or Failed syncs. Airbyte’s generic webhook is the trigger, but it is not a native email action and should not call Volanea directly.

Use a small authenticated relay between the two systems. Let it receive Airbyte’s text-oriented notification, validate the request, map that text into a Volanea email body, keep the Volanea API key in server-side secrets, and provide an idempotency key so webhook retries do not create duplicate sends.

That approach is explicit about the limits of the integration. It produces dependable operational email today without pretending that Airbyte emits record-level events or that a Volanea marketplace destination exists.

FAQ

Can Airbyte send an email directly through Volanea?

No. Airbyte can send a generic workspace notification webhook, but that webhook does not provide the Volanea Bearer authorization header or Volanea’s email-send request body. Use a relay or automation middleware to translate the notification into POST /v1/send.

What starts the email in this integration?

The trigger is an Airbyte workspace notification event, most commonly Successful syncs after an Airbyte connection completes successfully. It is not triggered by each individual source record.

Does the Airbyte webhook include a job ID and row count?

Do not assume it does. Generic non-Slack webhook targets may receive a text-only payload. If you need structured job fields, retrieve job details through the Airbyte API from server-side code rather than parsing notification prose.

Where should the Volanea API key be stored?

Store it only in server-side secrets for the relay or middleware, such as an encrypted environment variable or secret manager entry. Never put it in browser code, a public repository, Airbyte webhook URLs, or client-visible configuration.

How do I prevent duplicate Airbyte notification emails?

Use Volanea’s Idempotency-Key header and keep it stable across retries of the same webhook payload. For stronger guarantees, store a dedupe record in a durable database or queue and use a real Airbyte job identifier when structured job data is available.