How to Send Email From Whatagraph With Volanea

Send email from Whatagraph with Volanea by treating Whatagraph report automation and your email-sending workflow as two coordinated systems—not as a direct native integration. Whatagraph does not document an outbound webhook, automation builder, Zapier trigger, Make app, or marketplace connector that can post a report-delivery event to Volanea.

That distinction matters. A working integration should not pretend that a Whatagraph report can trigger arbitrary HTTP requests when the product’s documented automation is designed to send reports directly to recipients. Instead, use Whatagraph for report generation and scheduling, then use a small server-side scheduler or middleware service to send the related notification through Volanea.

The short answer: there is no direct Whatagraph-to-Volanea webhook

Whatagraph is a reporting and marketing-intelligence platform. Its documented Public API is built for the opposite direction: pushing custom-source data into Whatagraph so it can be visualized in reports. It is not a general outbound automation API for sending arbitrary event payloads to third-party services.

Whatagraph’s report automation is also purpose-built. In the report editor, the documented flow is to open Automation, select a sending frequency, delivery day, time, time zone, issue-handling behavior, and report recipients, then automate the report. Whatagraph can send the report itself, including PDF or Excel attachments where configured.

So there is no native Volanea app to install, no Whatagraph marketplace plugin, and no documented outbound HTTP configuration where you can paste https://api.volanea.com/v1/send. There is also no authentic “Whatagraph webhook payload” to map into an email request, because Whatagraph does not document an outgoing report-delivery webhook.

The correct architecture is therefore:

1. Configure the report and its schedule in Whatagraph.
2. Create a server-side scheduled job with the same intended cadence.
3. Have that job construct a notification payload from data you control, such as the report name, reporting period, recipient list, and secure report URL.
4. Send that notification through Volanea’s POST /v1/send endpoint.
5. Use a stable idempotency key so a scheduler retry cannot create duplicate email.

This does not replace Whatagraph’s own report delivery. It gives you control over the accompanying transactional email—for example, a branded “your report is ready” message, an internal approval alert, or a customer-specific notification that links to the report.

The real Whatagraph trigger: scheduled report automation

The concrete Whatagraph event closest to an email trigger is a scheduled automated report delivery. The report is configured in the right-side Automation menu. You select the sending frequency, delivery day, delivery time, time zone, and issue handling, then add recipients and activate automation.

For reports that require human approval, Whatagraph describes a sequence of stages: data gathering, review, ready for sending, and then delivery. If the automation is configured for review, the report does not go out until the reviewer confirms it. If it is configured to send without review, the scheduled delivery continues automatically unless issue handling prevents it.

That means the business trigger should be modeled carefully:

• Automatic route: “It is the scheduled report-delivery time for client X.”
• Reviewed route: “A reviewer has approved the report and it is ready to send.”
• Exception route: “The report was held because issue handling requires review.”

Only the first of these can be reproduced reliably by an independent scheduler without a Whatagraph outbound event. The second and third are states inside Whatagraph’s own report automation flow, not webhook events exposed to your service.

If the purpose is simply delivering the actual report attachment, use Whatagraph’s native automated email delivery. If the purpose is sending a separately branded notification, a report link, an internal reminder, or a status alert through Volanea, use your own scheduled trigger and make that trigger explicit in your architecture.

Whatagraph does not send an outbound JSON payload

A direct-integration tutorial would normally show the JSON posted by the source platform. In this case, that would be misleading: Whatagraph does not document an outbound report-automation webhook payload, because it does not document an outbound report-automation webhook.

Its Public API instead accepts data sent to Whatagraph. The documented model is based on defining dimensions and metrics, then posting daily-granularity data points to Whatagraph’s custom-source endpoints. Authentication uses a bearer token obtained from the Whatagraph interface. That API is useful when you want your product data to appear in a Whatagraph dashboard; it is not a mechanism for receiving “report sent” events.

Therefore, the payload below is not presented as a Whatagraph webhook. It is the payload your own scheduler sends to your middleware at the same time your Whatagraph report automation is scheduled. That explicit boundary prevents a dangerous operational assumption: receiving a successful request at your middleware does not prove Whatagraph has generated, reviewed, or delivered the report.

A useful scheduler payload looks like this:

{
  "event": "whatagraph.report.delivery_window",
  "reportKey": "acme-weekly-performance",
  "reportName": "Acme Weekly Performance Report",
  "clientName": "Acme",
  "periodLabel": "October 6–12, 2026",
  "scheduledFor": "2026-10-13T14:00:00Z",
  "recipients": [
    { "email": "marketing@acme.example", "name": "Acme Marketing" }
  ],
  "reportUrl": "https://reports.example.com/acme/weekly/2026-10-12",
  "runId": "acme-weekly-performance:2026-10-13T14:00:00Z"
}

Every value is controlled by your scheduler or application. runId is especially important: it represents one intended notification, not one HTTP attempt. If a job runner tries the same job twice after a timeout, the runId must remain identical.

Recommended architecture: Whatagraph plus a server-side scheduler

The safest setup uses a small application, serverless function, worker, or scheduled automation service. The scheduler should run at the desired frequency, generate a notification request, validate it, and call Volanea from a trusted server environment.

The flow is:

Whatagraph report schedule ──> native Whatagraph report delivery
                                  │
                                  │ same agreed schedule
                                  ▼
Scheduled job / worker ──> middleware validation ──> Volanea POST /v1/send
                                                          │
                                                          ▼
                                                   notification recipient

The schedule can be implemented with a platform-native cron facility, such as a cloud scheduler, a queue worker, or a serverless scheduled function. Use one authoritative time zone. If Whatagraph is configured for a client’s time zone but the job is configured in UTC without a conversion strategy, report and notification timing will drift during daylight-saving transitions.

The middleware should not scrape the Whatagraph interface, inspect a recipient inbox, or assume that a report exists because a clock reached a certain time. Those shortcuts are brittle and can expose report data. Instead, have the middleware send a truthful message such as “Your scheduled report is available in Whatagraph” only when your operating process makes that statement accurate.

If you need strict proof that a report was delivered, use Whatagraph’s own delivery history and report automation records as the system of record. The Volanea notification should be treated as a separate message stream with separate acceptance and delivery telemetry.

Working middleware code: map a scheduled payload to Volanea

The example below is a Node.js server endpoint. A trusted scheduler posts the scheduler payload to /jobs/whatagraph-report-notification; the endpoint validates it, escapes dynamic values before placing them into HTML, creates one Volanea message per recipient, and uses the supplied runId to prevent duplicates.

The Volanea API key is read only from the server environment. The request calls POST https://api.volanea.com/v1/send with a secret key, a verified sender address, recipient address, subject, HTML body, text fallback, and Idempotency-Key header.

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

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

const VOLANEA_API_KEY = process.env.VOLANEA_API_KEY;
const JOB_SHARED_SECRET = process.env.WHATAGRAPH_JOB_SHARED_SECRET;
const FROM_EMAIL = "reports@example.com"; // Must use a verified Volanea domain.
const FROM_NAME = "Example Analytics";

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

function isEmail(value) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
}

app.post("/jobs/whatagraph-report-notification", async (req, res) => {
  if (req.get("x-job-secret") !== JOB_SHARED_SECRET) {
    return res.status(401).json({ error: "Unauthorized job request" });
  }

  const {
    event,
    reportKey,
    reportName,
    clientName,
    periodLabel,
    scheduledFor,
    recipients,
    reportUrl,
    runId
  } = req.body;

  if (event !== "whatagraph.report.delivery_window") {
    return res.status(400).json({ error: "Unexpected event" });
  }

  if (!reportKey || !reportName || !periodLabel || !reportUrl || !runId) {
    return res.status(400).json({ error: "Missing required report fields" });
  }

  if (!Array.isArray(recipients) || recipients.length === 0) {
    return res.status(400).json({ error: "At least one recipient is required" });
  }

  const safeReportName = escapeHtml(reportName);
  const safeClientName = escapeHtml(clientName || "your team");
  const safePeriodLabel = escapeHtml(periodLabel);
  const safeReportUrl = escapeHtml(reportUrl);

  const results = [];

  for (const recipient of recipients) {
    if (!recipient?.email || !isEmail(recipient.email)) {
      results.push({ email: recipient?.email ?? null, skipped: "invalid_email" });
      continue;
    }

    const recipientName = escapeHtml(recipient.name || recipient.email);
    const idempotencyKey = crypto
      .createHash("sha256")
      .update(`${runId}:${recipient.email.toLowerCase()}`)
      .digest("hex");

    const subject = `${reportName}: ${periodLabel}`;
    const text = [
      `Hello ${recipient.name || recipient.email},`,
      "",
      `${reportName} for ${periodLabel} is available for ${clientName || "your team"}.`,
      `Open the report: ${reportUrl}`,
      "",
      `Scheduled notification time: ${scheduledFor || "not supplied"}`
    ].join("\n");

    const html = `
      <p>Hello ${recipientName},</p>
      <p><strong>${safeReportName}</strong> for ${safePeriodLabel} is available for ${safeClientName}.</p>
      <p><a href="${safeReportUrl}">Open the report</a></p>
      <p style="color:#666;font-size:12px">Scheduled notification time: ${escapeHtml(scheduledFor || "not supplied")}</p>
    `;

    const response = 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({
        fromEmail: FROM_EMAIL,
        fromName: FROM_NAME,
        to: [recipient.email],
        subject,
        html,
        text,
        headers: {
          "X-Report-Key": reportKey,
          "X-Report-Run-ID": runId
        }
      })
    });

    const responseBody = await response.text();

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

    results.push({ email: recipient.email, accepted: true });
  }

  return res.status(202).json({ runId, results });
});

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

The to field is deliberately an array, even though this example sends a separate request for each recipient. Sending individual messages avoids exposing recipients to one another and allows an idempotency key to be scoped to one recipient and one report run.

Before production, verify the sender domain in Volanea and use a sender address on that domain. Review the email API reference and setup guides for the current send schema, authentication behavior, domain verification steps, message status details, and webhook options.

Field mapping: scheduler values to an email message

A reliable integration documents every mapping. This prevents report labels, dates, and recipient data from becoming mystery values embedded inside an email template.

Do not put a Whatagraph access token, report password, or other credential in reportUrl. Prefer a secure report-sharing URL designed for the intended audience, and configure report permissions carefully. If your link has an expiration policy, make the notification copy say so.

Authentication: where the Volanea API key belongs

The Volanea secret key belongs in a server-side secret store or environment variable on the middleware side. In the example, it is stored as VOLANEA_API_KEY. A scheduler authenticates to the middleware with a separate shared secret, shown as WHATAGRAPH_JOB_SHARED_SECRET.

This is intentional separation of duties:

• The scheduler proves it is allowed to request a notification.
• The middleware decides whether the input is valid and safe.
• Only the middleware can read the Volanea sending credential.
• Volanea receives the credential only over HTTPS from the trusted server.

Do not put the Volanea key in a public report URL, browser JavaScript, a client-visible dashboard configuration, a shared spreadsheet, or a generic webhook field visible to non-administrators. A secret sending key can be abused to send mail from your account, consume quota, damage domain reputation, or generate a security incident.

Whatagraph’s documented Custom API access token is also not a substitute for a Volanea key. It is used to authenticate requests that push custom data into Whatagraph. It should be managed separately, scoped to its purpose, and never repurposed as an email credential.

For a lower-code implementation, a workflow platform can hold Volanea credentials in its encrypted connection or secret facility. But do not treat that as a direct Whatagraph integration. The trigger must still come from a separate source that can actually start the workflow, such as a scheduled trigger. Store the Volanea credential in the workflow platform’s secret mechanism—not inside a visible request body or a URL parameter.

Build the scheduled middleware route

A practical implementation plan has two schedules that should be intentionally coordinated: the Whatagraph report automation schedule and the scheduler that calls your middleware. Start with a non-production recipient list and a test sender domain.

1. Build and validate the Whatagraph report. Choose a pre-made or rolling date range that works with report automation.
2. In the report’s Automation settings, configure delivery frequency, delivery day, time, time zone, issue handling, and report recipients.
3. Decide whether Whatagraph itself should deliver the report. If yes, keep that recipient list focused on the people who need the PDF, Excel file, or native report email.
4. Deploy the middleware endpoint shown above behind HTTPS. Set VOLANEA_API_KEY, WHATAGRAPH_JOB_SHARED_SECRET, and the sender address as environment variables.
5. Create a scheduled job that posts the scheduler payload to the middleware on the agreed schedule. Use a stable runId generated from report key plus scheduled timestamp.
6. Send a test notification to an internal address. Confirm that the sender domain is verified, the report link is accessible to the intended audience, and the plain-text fallback is readable.
7. Turn on production scheduling only after you have observed both the Whatagraph automated report and the Volanea notification at least once.

The scheduler should use a unique run record in a database or durable key-value store. A simple schema can include run_id, report_key, scheduled_for, recipient_email, status, volanea_message_id, attempt_count, and last_error. That record is more useful than relying on application logs when a client asks why an expected report notification did not arrive.

When this breaks

The failure modes in this integration are specific to the hop between a scheduler or middleware and Volanea—not an imaginary Whatagraph webhook. Designing for them up front makes the behavior predictable.

Duplicate sends after retries

A scheduler can time out while the middleware is still processing. It may retry the same job even though Volanea accepted the email. Network failures can create the same ambiguity: the client does not know whether the API received the request, so it retries.

Use the same idempotency key for every retry of the same intended message. In the example, the key is derived from runId and the normalized recipient address. Do not generate a random idempotency key for every attempt, because that turns retries into new sends.

Also persist run state. Idempotency is protection at the API action layer; a durable run record protects the business workflow. Together, they let you answer whether a duplicate was requested, accepted, or merely displayed twice in a dashboard.

Webhook or request timeouts

There is no Whatagraph outbound webhook timeout to tune here. The relevant timeout is between your scheduler and middleware, and then between middleware and Volanea.

Keep the middleware response fast. Validate input, send the message, store the result, and return a concise status. For higher-volume sends, accept the scheduler request, enqueue the work, and return 202 Accepted; a background worker can then call Volanea with controlled retry policy.

Retries should use exponential backoff for transient network errors and 5xx responses. Do not blindly retry validation failures, malformed recipient addresses, or sender-domain configuration errors. Those need a configuration fix, not more attempts.

Fields missing on some plans or report configurations

Because Whatagraph does not provide an outbound report-event payload, no Whatagraph plan can guarantee the custom JSON fields shown in this guide. The middleware payload is yours to define, which is an advantage: make every field explicit and validate it.

Whatagraph plan and integration availability can affect the sources and report features you use, while report automation configuration can affect whether a report waits for review or is blocked by issue handling. Do not assume that a report is ready based only on a calendar tick. If the email must refer to a specific report state, add an internal approval step or send the notification only after a human-controlled release action.

Report links that recipients cannot open

The email may be delivered successfully while the report link fails for the recipient. This usually happens when the URL requires an account login, the recipient lacks access to the relevant Space, a password was omitted, or a shared link was disabled.

Test using a recipient account with the same level of access as the actual audience. Do not test only as an administrator, because administrators can mask permission mistakes. If a secure shared report needs a password, distribute that password through a separate approved channel rather than embedding it in the notification.

Sender-domain or suppression failures

Volanea can accept a request but skip a recipient for conditions such as suppression or subscription status, depending on the message type and recipient record. A successful HTTP response is not the same as an inbox placement guarantee.

Use a verified sender domain, preserve a plain-text version of the message, and monitor Volanea’s send logs and events. If you are estimating volume or need to choose a sending tier before enabling notifications for many client reports, review transactional email pricing alongside your expected recipient count and schedule.

Alternatives that fit different requirements

Not every reporting-email requirement needs custom middleware. The right option depends on what must be sent and who needs to control the sender experience.

Use Whatagraph automation alone

Choose this when the main need is delivering the actual report, especially when PDF or Excel attachments matter. It is the simplest route because the report platform owns generation, timing, review status, recipients, and attachment behavior.

This is also the best approach when an account manager needs to review the report in Whatagraph before release. Adding an independent notification service may create timing discrepancies unless your operating process includes a deliberate approval handoff.

Use Volanea for a separate notification

Choose this when the email itself needs application-level control: a custom sender identity, a branded HTML layout, internal routing, dynamic recipient logic, tracking conventions, or links to multiple resources. This is the architecture described in this guide.

It works especially well for “report window open” messages, internal reminders, client success workflows, or notifications that reference—but do not impersonate—the native Whatagraph report delivery.

Use a workflow platform as the scheduler

Choose a workflow platform when your team does not want to operate a server. Start the workflow with a scheduler, prepare the payload, and use an HTTP request action to invoke a small secure relay or Volanea directly from a protected credential store.

The limitations remain the same: the trigger is scheduled, not a Whatagraph outbound event. Build deduplication into the workflow with a persistent data store if the platform can rerun failed jobs.

Operational checklist before going live

Use this checklist to make the implementation supportable:

• Confirm the Whatagraph report automation time zone and the scheduler time zone match.
• Decide whether the Volanea email supplements native Whatagraph delivery or replaces only an internal notification.
• Verify the Volanea sender domain before enabling the job.
• Keep VOLANEA_API_KEY only in server-side or workflow-secret storage.
• Require authentication on the middleware endpoint; do not expose it as a public anonymous webhook.
• Use a stable per-recipient idempotency key derived from an immutable run ID.
• Escape all dynamic values inserted into HTML, including report names and client names.
• Validate every recipient address before sending.
• Test report-link permissions as a non-admin recipient.
• Record the run ID, recipient, response status, and any Volanea message identifier returned by the API.
• Alert on repeated failures, but avoid notifying the end recipient repeatedly for the same failed run.

Conclusion

To send email from Whatagraph with Volanea, do not invent a direct webhook that Whatagraph does not provide. Whatagraph’s real automation trigger is a scheduled automated report delivery configured in the report’s Automation settings, while its Public API is designed for data flowing into Whatagraph.

The dependable integration is a coordinated middleware route: leave native report delivery to Whatagraph when you need the actual report, then use a server-side schedule and Volanea’s REST API for a separate controlled notification. With protected credentials, explicit payload ownership, report-link access checks, and stable idempotency keys, the result is more reliable than a fictional one-click connector.

FAQ

Can Whatagraph directly call the Volanea API?

Not through a documented native Volanea connector or documented outbound report webhook. Whatagraph’s documented Public API is for pushing custom data into Whatagraph, while report automation sends reports to configured email recipients.

What event starts the Volanea email?

In this architecture, a server-side scheduled job starts the Volanea email at the same delivery window as the Whatagraph automated report. The corresponding Whatagraph feature is scheduled report automation configured through the report’s Automation settings.

Does Whatagraph provide a webhook payload when a report is sent?

No documented outbound report-delivery webhook payload is available to map. Define and validate your own middleware payload rather than claiming that it came from Whatagraph.

Where should I store the Volanea API key?

Store it in a server-side environment variable or a workflow platform’s protected secret store. Never include it in browser JavaScript, a public report configuration, a URL, or any client-visible field.

How do I avoid duplicate notifications?

Create one immutable runId for each scheduled report window and recipient, then derive the same Idempotency-Key whenever that exact message is retried. Combine that with a durable job record so retries are observable and controlled.