How to Send Email From PagerDuty With Volanea

PagerDuty can send email from PagerDuty through a direct outbound HTTP step, but the correct implementation is not a native Volanea app or marketplace installation. Instead, use a PagerDuty Incident Workflow with its Send a Webhook POST action to call Volanea’s POST /v1/send endpoint when a PagerDuty incident is created and meets your chosen conditions. (support.pagerduty.com)

This approach is useful when the people who need an incident notification are not PagerDuty responders: customer-success leaders, account owners, executives, an internal service desk, or a tightly controlled external stakeholder list. PagerDuty remains the system that detects and coordinates the incident; Volanea becomes the transactional delivery layer that sends an email with your authenticated domain, content controls, and delivery visibility.

What this integration does—and does not do

Volanea does not provide a native PagerDuty app, PagerDuty Marketplace listing, or one-click plugin for this workflow. The integration is a configured HTTP call from PagerDuty to Volanea.

PagerDuty’s Incident Workflows include a Send a Webhook POST action that can make an HTTPS POST request with a custom body and headers. The action supports field references, so incident data can be inserted into the JSON body at run time. PagerDuty documents that this action is available on Business and Enterprise for Incident Management pricing plans. (support.pagerduty.com)

The resulting architecture is deliberately simple:

1. A service integration creates a PagerDuty incident.
2. A conditional PagerDuty Incident Workflow starts when that incident is created and matches your policy.
3. The workflow’s Send a Webhook POST action sends a JSON request to Volanea.
4. Volanea accepts the request at https://api.volanea.com/v1/send and queues the stakeholder email.
5. PagerDuty records whether the webhook action received a successful HTTP response; Volanea provides the sending-side record and delivery lifecycle.

This is not the same as subscribing to PagerDuty’s generic V3 webhooks. Generic Webhooks are designed to send PagerDuty event payloads to your receiver, which would require middleware to transform the event into an email request. Incident Workflows are the better direct route here because the action lets you create the Volanea request body in PagerDuty and keep the integration to one HTTP hop. PagerDuty’s current generic webhook version is V3, but V3 subscriptions use a destination URL plus event subscriptions rather than a purpose-built email request body. (developer.pagerduty.com)

The concrete PagerDuty trigger: an incident is created

The trigger that starts this send is a PagerDuty Conditional Trigger on an Incident Workflow. Configure it to run when an incident is created, then optionally add conditions that limit sending to incidents that should create a stakeholder email.

PagerDuty describes Incident Workflows as having triggers, actions, and Workflow Integrations. Its Conditional Triggers can start a workflow whenever an incident is created, either with no condition or only if a condition evaluates true at creation time. (support.pagerduty.com)

For a production notification workflow, do not send on every incident by default. PagerDuty is often intentionally noisy at the alert layer, and email has a higher social and operational cost than an internal alert. A safer first policy is one of these:

• Send only when a P1 incident is created.
• Send when an incident is created for a customer-facing service.
• Send when an incident is created with high urgency.
• Send when an incident belongs to a dedicated incident type, such as Customer impact or Major incident.
• Send a manual workflow only after an incident commander confirms there is an externally meaningful impact.

PagerDuty supports Incident Type, Conditional, Manual, and API workflow triggers. For this integration, a Conditional Trigger is the practical automatic option because it can evaluate incident criteria at creation time. (support.pagerduty.com)

Recommended first trigger policy

Start with an automatic workflow limited to P1 incidents for customer-facing services. This gives responders a predictable rule: a major incident creates a stakeholder email, while routine alerts stay inside PagerDuty and your responder channels.

If your incident process assigns priority only after responders review the issue, use a manual trigger instead. A manual workflow avoids an incorrect early email, but it trades speed for reviewer judgment. PagerDuty supports manual Incident Workflow triggers from its incident experience and related surfaces; use that route when wording must be approved before it reaches stakeholders. (pagerduty.com)

Why “incident created” matters

PagerDuty incident status is distinct from an incoming monitoring alert. An incident is the PagerDuty object created on a service and then managed through triggered, acknowledged, and resolved states. That makes the creation event a stable business moment for the first stakeholder notification: a defined incident exists, a URL exists, ownership can be assigned, and responders have a common record to update. (support.pagerduty.com)

Do not confuse this with sending one email per alert. A PagerDuty incident may contain grouped alerts, escalations, notes, and responder activity. Anchor your stakeholder email to the incident, not to every alert that contributed to it.

Prerequisites before you configure the workflow

Set up the mail side before you build the PagerDuty action. The integration is much easier to test when the sender identity and recipient policy are already settled.

You need:

• A Volanea account and a secret API key beginning with sk_ or sk_test_.
• A verified sending domain and an approved from address on that domain.
• A PagerDuty account with Incident Workflows and the Send a Webhook POST action available. PagerDuty lists that action for Business and Enterprise for Incident Management plans. (support.pagerduty.com)
• Permission to create or edit the needed Incident Workflow and its trigger.
• A controlled destination address or distribution list for testing.
• A decision about who owns the content, recipient list, and stop conditions.

Volanea’s REST base URL is https://api.volanea.com, and its send endpoint is POST /v1/send. The endpoint supports sending one message to one address or up to 50 recipients, and it supports the Idempotency-Key header for safe retries. (volanea.com)

Before sending to customers, authenticate the sending domain and use an address such as status@updates.example.com or incident-communications@example.com. Avoid using a personal responder address as the sender: it makes reply routing unclear, creates leave-of-absence problems, and weakens the distinction between a company communication and an individual update.

For sender setup, message fields, API authentication, and response handling, keep the email API reference and setup guides available while you configure the workflow.

Create the secure Volanea credential in PagerDuty

The Volanea API key belongs in PagerDuty’s secure workflow credential mechanism, not in the workflow’s visible JSON body or a regular custom-header text field.

In the Send a Webhook POST action, PagerDuty provides an Authentication Headers input. PagerDuty instructs users to select a Workflow Integration or create a new Web API Connection there, and explicitly warns not to put sensitive headers into the ordinary Headers field. (support.pagerduty.com)

Create a Web API Connection that supplies this header:

Authorization: Bearer sk_your_volanea_secret_key

Then select that connection in the action’s Authentication Headers setting. Add only non-secret request headers in the action’s plain Headers field:

Content-Type: application/json
Idempotency-Key: pagerduty-{{incident.id}}-initial

The exact key value must be your actual Volanea secret key; do not paste it into a shared runbook, a browser-visible configuration export, a source repository, an incident note, or the webhook body.

Why this must be treated as a server-side secret

A Volanea API key authorizes email sending. Anyone who obtains it may be able to send messages from your configured account, consume quota, create support burden, or damage sender reputation. The principle is the same as protecting a payment-provider token: a secret used to authorize server-to-server work must never be shipped to a client application or embedded in a public configuration artifact.

PagerDuty’s guidance is especially relevant here. Its workflow action separates Authentication Headers from generic headers and says sensitive headers should be created through a Web API Credentials Connection instead of being entered in the standard header list. (support.pagerduty.com)

Use a narrowly scoped operational process too:

• Let only the workflow owner and a backup administrator manage the connection.
• Rotate the Volanea key when an administrator leaves, a key is exposed, or your security policy requires it.
• Maintain separate test and production keys.
• Use a test sender and an internal recipient list while proving the workflow.
• Record the credential owner, sender domain, and recipient list in your incident-communications runbook.

Configure the PagerDuty Incident Workflow

Create a new Incident Workflow in PagerDuty and give it an unambiguous name, such as Email stakeholders for new P1 customer incident.

Add a Conditional Trigger. Choose the behavior that runs the workflow when an incident is created, then limit it to the intended services and incident criteria. PagerDuty supports associating workflow triggers with services or all services, so keep the scope tight unless every PagerDuty service truly has the same stakeholder-email policy. (developer.pagerduty.com)

Next, add the Send a Webhook POST action. Configure these inputs:

PagerDuty requires HTTPS URLs for the webhook POST action. Its action output includes the response status, whether the status was successful, response headers, response time, a result value, a result summary, and an error field. Those outputs make the workflow execution record the first place to check when an email did not start as expected. (support.pagerduty.com)

Use field references, not copied incident text

PagerDuty Workflow fields that support references expose a {+} picker; PagerDuty also documents entering {{ to select a reference. Common incident references include {{incident.id}}, {{incident.title}}, and {{incident.url}}. (support.pagerduty.com)

Field references are important because the request body must be generated separately for every workflow run. A hard-coded title would make every email refer to the same incident. A copied incident URL would lead stakeholders to the wrong event. Use references for incident-specific values and literal strings only for stable elements such as your sender address, recipient list, and email template structure.

The payload PagerDuty sends to Volanea

With an Incident Workflow, the payload is not PagerDuty’s generic V3 webhook envelope. It is the exact JSON you enter in the Body field of the Send a Webhook POST action, after PagerDuty resolves the incident field references.

Use the following body as a starting point. Replace the example sender and recipient addresses with your own verified sender and controlled stakeholder list.

{
  "from": "Incident Communications <status@updates.example.com>",
  "to": [
    "customer-success@example.com",
    "executive-on-call@example.com"
  ],
  "subject": "[P1] {{incident.title}}",
  "html": "<h1>Active incident</h1><p><strong>{{incident.title}}</strong></p><p>A PagerDuty incident has been created and the response team is investigating.</p><p><a href=\"{{incident.url}}\">Open the PagerDuty incident</a></p><p><small>Incident ID: {{incident.id}}</small></p>",
  "text": "Active incident\n\n{{incident.title}}\n\nA PagerDuty incident has been created and the response team is investigating.\n\nOpen the incident: {{incident.url}}\n\nIncident ID: {{incident.id}}"
}

When PagerDuty runs the workflow for an example incident, the rendered request has the same shape but contains concrete values. For example:

{
  "from": "Incident Communications <status@updates.example.com>",
  "to": [
    "customer-success@example.com",
    "executive-on-call@example.com"
  ],
  "subject": "[P1] Checkout API elevated error rate",
  "html": "<h1>Active incident</h1><p><strong>Checkout API elevated error rate</strong></p><p>A PagerDuty incident has been created and the response team is investigating.</p><p><a href=\"https://example.pagerduty.com/incidents/PABC123\">Open the PagerDuty incident</a></p><p><small>Incident ID: PABC123</small></p>",
  "text": "Active incident\n\nCheckout API elevated error rate\n\nA PagerDuty incident has been created and the response team is investigating.\n\nOpen the incident: https://example.pagerduty.com/incidents/PABC123\n\nIncident ID: PABC123"
}

The matching Volanea request is an authenticated POST /v1/send call. This curl example is useful for testing the Volanea side independently before connecting PagerDuty:

curl --request POST \
  --url https://api.volanea.com/v1/send \
  --header "Authorization: Bearer $VOLANEA_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: pagerduty-PABC123-initial" \
  --data '{
    "from": "Incident Communications <status@updates.example.com>",
    "to": [
      "customer-success@example.com",
      "executive-on-call@example.com"
    ],
    "subject": "[P1] Checkout API elevated error rate",
    "html": "<h1>Active incident</h1><p><strong>Checkout API elevated error rate</strong></p><p>A PagerDuty incident has been created and the response team is investigating.</p><p><a href=\"https://example.pagerduty.com/incidents/PABC123\">Open the PagerDuty incident</a></p><p><small>Incident ID: PABC123</small></p>",
    "text": "Active incident\n\nCheckout API elevated error rate\n\nA PagerDuty incident has been created and the response team is investigating.\n\nOpen the incident: https://example.pagerduty.com/incidents/PABC123\n\nIncident ID: PABC123"
  }'

Volanea’s send endpoint accepts one message to one address or up to 50 recipients and runs the send through its normal sending pipeline. The endpoint also supports Idempotency-Key, which is essential for this PagerDuty-to-email hop. (volanea.com)

Field mapping explained

The mapping is intentionally small:

Do not send the full raw alert payload to a broad distribution list. Alert custom details can contain infrastructure names, stack traces, tenant references, hostnames, customer identifiers, or secrets accidentally included by an upstream monitor. A minimal incident title plus a controlled incident link is safer for the first notification.

Design the email for incident communications, not alert forwarding

A technically successful API call can still produce a poor operational message. Stakeholders should be able to answer three questions within a few seconds: what happened, whether the response team is acting, and where approved staff can find the current source of truth.

A first notification should normally include:

• A clear severity marker only if it has meaning to the recipients.
• The incident title in plain language.
• A statement that investigation is underway.
• A link to the PagerDuty incident for recipients who are authorized to access it.
• The incident ID for support, audit, and correlation.
• A monitored reply path only if you are prepared to handle replies.

Avoid promising resolution times before responders have evidence. Avoid pasting unreviewed monitoring output into email. Avoid exposing the PagerDuty incident URL to external users unless you know the URL is appropriate for them and their account permissions.

For customer-facing communication, many teams use this direct email only for internal stakeholders and use a reviewed status-page workflow for customers. If you do send externally, use a customer-safe template with no internal links, no service topology, no responder names unless approved, and language that matches your legal and communications policy.

Idempotency and duplicate-send control

PagerDuty-to-Volanea delivery is an at-least-once style integration boundary. A request can reach Volanea even if PagerDuty does not receive the response because of a network failure, timeout, or interrupted connection. Retrying without a stable idempotency key can turn one incident into duplicate stakeholder emails.

Volanea supports safe retries through the Idempotency-Key header. (volanea.com) Use a key that is deterministic for the exact communication event.

For the initial message, this is a good default:

Idempotency-Key: pagerduty-{{incident.id}}-initial

That design means every retry of the initial-notification workflow for the same incident presents the same identity to Volanea. It should not be reused for a materially different communication. For example, if you later add a separate resolved message, give it a different key such as:

Idempotency-Key: pagerduty-{{incident.id}}-resolved

One workflow run should equal one communication purpose

Separate first notification, resolution notification, and manually approved executive update into different workflow actions or workflows. Do not make one generic “send incident email” workflow whose content changes unpredictably based on informal responder behavior.

This separation creates a useful operational invariant:

• initial means the first notification for a newly created qualifying incident.
• resolved means a closure message after the incident reaches the resolved state.
• executive-update-1 means a specifically approved update, not an automatic retry.

PagerDuty provides a Wait for Status to Change workflow action that can wait until an incident reaches Resolved; PagerDuty says the status is polled every 10 minutes and that Resolved is currently the supported status for that action. This is useful for an optional closure email, but the polling cadence means it should not be treated as a second-by-second customer-notification mechanism. (support.pagerduty.com)

When this breaks

The integration has two independent systems and one network hop. Diagnose it in order: did PagerDuty start the workflow, did it successfully make the HTTP request, did Volanea accept the message, and did the intended recipient receive it?

PagerDuty retries create duplicate emails

Symptom: Stakeholders receive the same initial incident email more than once.

Likely cause: The workflow action was attempted again after a transient delivery failure or uncertainty about whether the receiver got the request. A retry can be legitimate at the HTTP layer even when the original request reached Volanea.

Fix: Set a stable Idempotency-Key based on the PagerDuty incident ID and communication purpose. Do not generate a timestamp, random UUID, or changing field in the key. A changing key makes every retry look like a new email request.

Also check whether you accidentally configured multiple workflows with overlapping triggers, such as one workflow for every high-urgency incident and another for every P1 incident. Idempotency protects repeated requests with the same key; it cannot fix two different workflows deliberately using two different keys for the same audience.

The webhook action times out or reports failure

Symptom: PagerDuty’s workflow execution shows Failed, a non-2XX response, or an error in the Send a Webhook POST action.

Likely causes: The URL is malformed, the request is not HTTPS, the Volanea key is invalid, the sender is not permitted, JSON is malformed, or an intermediary network policy blocks the outbound call.

Fix: Confirm the URL is exactly https://api.volanea.com/v1/send. Confirm that Content-Type: application/json is in the standard headers and Authorization: Bearer … is held in the secure Web API Connection. PagerDuty’s action exposes response status, response time, result, result summary, and error details, so capture those values before changing the workflow. (support.pagerduty.com)

If you operate a proxy or egress restriction, do not assume PagerDuty workflow actions originate from a fixed IP range. PagerDuty specifically says Incident Workflows webhook actions do not use a static IP list and recommends authentication headers rather than source-IP validation. (support.pagerduty.com)

A field is blank or malformed in the email

Symptom: The subject says [P1], the incident link is empty, or the email contains an unresolved-looking template token.

Likely cause: The body references a field that is unavailable in that workflow context, the field is not populated for that incident, or the reference was typed incorrectly instead of selected through PagerDuty’s field-reference control.

Fix: Use the {+} field-reference picker in the action body where possible and test against a real non-production incident. Keep the first template limited to known base incident properties: ID, title, and URL. PagerDuty documents {{incident.id}} as the default incident reference in several actions, while documented workflow examples use {{incident.title}} and {{incident.url}}. (support.pagerduty.com)

Do not assume custom fields, alert details, priority, or service metadata are universally populated. Their availability depends on how incidents are created, what product capabilities are enabled, whether Event Orchestration enriches the incident, and whether your workflow trigger runs before a responder adds additional context. Build a useful minimal email first; add optional fields only after testing your real incident sources.

The workflow never starts

Symptom: A qualifying incident exists, but there is no outbound request or email.

Likely cause: The trigger is scoped to different services, its conditional rule does not match at creation time, the workflow is unpublished or disabled, or the action is not available on the current PagerDuty plan.

Fix: Check the workflow’s trigger scope and reproduce the exact creation conditions in a test service. PagerDuty notes that Conditional Triggers evaluate conditions when the incident is created, so a priority added later may not satisfy a creation-time rule. (support.pagerduty.com) If your process assigns priority after creation, switch to a manual workflow or redesign the trigger around an incident type that is present at creation.

Volanea accepts the request but no email arrives

Symptom: PagerDuty reports a successful 2XX webhook response, but the recipient does not see the message.

Likely causes: The recipient address is suppressed or unsubscribed, the mailbox filtered the message, the sender domain has not been fully authenticated, or the recipient list is wrong.

Fix: Inspect the Volanea message record and delivery events, then verify the recipient address. Before adding new stakeholder addresses, use the free email address verification tool to catch obvious address-quality problems. Keep operational notification lists maintained by an accountable team rather than copied manually into multiple workflows.

Testing without causing a real incident communication

Treat this as an incident-response change, not just an email-template change. Test the complete path with a dedicated PagerDuty service, a non-production Volanea key where appropriate, a verified test sender, and internal addresses.

Use this sequence:

1. Call Volanea directly with the curl request above and verify that sender, recipients, content, and authentication work.
2. Create a non-production PagerDuty Incident Workflow with a narrow Conditional Trigger or a Manual Trigger.
3. Set the action URL, secure authorization header, JSON body, and idempotency key.
4. Trigger a test incident whose title is visibly synthetic, such as TEST — do not action — checkout alert.
5. Inspect the PagerDuty workflow execution result, HTTP status, and action error fields.
6. Inspect Volanea’s send record and then the received plain-text and HTML versions.
7. Retry the same workflow or recreate the transport condition deliberately only if you can safely validate idempotency.
8. Promote the configuration to production only after communications, security, and on-call owners approve the recipient group and wording.

A meaningful test must cover more than “an email arrived.” Check that the subject renders correctly, the URL points to the correct incident, the text alternative is readable, the sender is recognizable, and retries do not create duplicates.

Direct workflow versus generic webhook middleware

Use the direct Incident Workflow route when your message can be built from PagerDuty fields and static content. It is the fewest moving parts: PagerDuty calls Volanea directly, and the Volanea key is stored in PagerDuty’s workflow credential connection.

Use generic PagerDuty V3 webhooks plus middleware when you need substantial transformation or policy logic. Examples include recipient routing based on account ownership in your CRM, pulling an approved status message from an internal system, redacting incident details, looking up a customer’s locale, enforcing quiet hours, or producing one email per unique customer rather than one email per incident.

PagerDuty V3 webhooks support event subscriptions such as incident.triggered, incident.acknowledged, and incident.resolved, and can be scoped by service, team, or account. They also include webhook-signature support through V3 headers. (developer.pagerduty.com) In that architecture, your middleware verifies the PagerDuty webhook, applies business rules, and then calls Volanea with its server-side key.

The trade-off is control versus operational surface area. Middleware gives you richer rendering and audience logic, but it introduces another service to deploy, observe, secure, and recover during an incident. Start direct if the requirements are simple; add middleware when the communication policy genuinely requires it.

Operational recommendations for a durable setup

The technical setup should support an incident-communications policy, not replace one. Decide in advance who is allowed to alter the recipient list, who approves customer-visible language, who receives replies, and how responders can stop a mistaken notification.

A mature setup usually has:

• A clearly named first-notification workflow with a strict trigger.
• A different workflow for resolution or a manual customer update.
• A small number of owned distribution lists rather than individual addresses in workflow JSON.
• An authenticated sender domain dedicated to operational communications.
• Stable idempotency keys for every automatic message type.
• A test service and test recipient group for change validation.
• A runbook with the PagerDuty workflow name, Volanea sender, API credential owner, and rollback procedure.

Keep email content compact. The on-call team needs to remediate the issue; they should not have to manage a sprawling email campaign from the incident timeline. Use the email to establish awareness and direct recipients to an approved source of truth.

Conclusion

The reliable way to send email from PagerDuty with Volanea is a direct HTTP integration: a PagerDuty Incident Workflow starts when an incident is created, its Send a Webhook POST action renders incident field references into Volanea’s POST /v1/send payload, and a secure PagerDuty Web API Connection supplies the Volanea bearer token.

The implementation succeeds when it is intentionally narrow. Send only for incidents that deserve stakeholder email, use a verified sender, keep the first payload limited to safe incident context, use stable idempotency keys, and test failure modes before relying on it during a real outage. If your routing or redaction rules become complex, move to a verified generic-webhook-and-middleware design rather than forcing business logic into a static workflow body.

FAQ

Does Volanea have a native PagerDuty integration?

No. Volanea does not ship a native PagerDuty app, Marketplace listing, or plugin for this use case. The supported pattern is to use PagerDuty’s outbound Send a Webhook POST Incident Workflow action to call Volanea’s REST API.

What PagerDuty event starts the email?

In the direct setup, a PagerDuty Conditional Trigger starts an Incident Workflow when an incident is created. You can narrow it by service, urgency, incident type, or another supported condition. (support.pagerduty.com)

Where should the Volanea API key be stored?

Store it in PagerDuty’s secure Web API Connection / Workflow Integration used by the action’s Authentication Headers setting. Do not put the bearer token in the visible request body, regular header list, browser code, or repository. (support.pagerduty.com)

How do I prevent duplicate PagerDuty emails?

Send a stable Volanea Idempotency-Key, such as pagerduty-{{incident.id}}-initial, for the initial notice. Reuse that exact key for retries of the same message, and use a different fixed suffix for a different event such as resolution. (volanea.com)

Can I send a resolution email too?

Yes. Add a separate workflow path using PagerDuty’s Wait for Status to Change action and send a new Volanea request after the incident reaches Resolved. Use a separate idempotency key such as pagerduty-{{incident.id}}-resolved. PagerDuty notes that this action polls for resolution every 10 minutes. (support.pagerduty.com)