Send email from Capsule CRM when a CRM event matters—not when someone remembers to copy a contact into another tool. With Capsule REST Hooks, a small server-side relay, and Volanea’s REST API, you can send a welcome email when a person is created, notify a contact after an opportunity moves, or acknowledge a completed process without exposing an email API key.

This is a developer integration, not a native Capsule CRM marketplace app. Capsule can notify an HTTPS endpoint through REST Hooks; your endpoint validates and maps the CRM event, then calls Volanea from a secure environment.

The integration architecture

The reliable pattern for sending email from Capsule CRM has three parts:

Capsule CRM REST Hook: Capsule emits an HTTPS POST when a subscribed event occurs, such as party/created or opportunity/moved.
Your relay endpoint: A serverless function, Worker, application route, or small service receives the event, validates it, selects recipients and content, prevents duplicate processing, and responds promptly.
Volanea: The relay makes a server-to-server POST /v1/send request to dispatch the transactional email.

That middle layer is intentional. A Capsule REST Hook is an event notification mechanism, not a programmable HTTP client where you can configure Volanea authorization headers, transform arbitrary request bodies, or safely keep a secret email credential. The relay is the boundary where business rules and secrets belong.

For a simple example, this guide uses Capsule’s party/created event. In Capsule’s API, a party is a person or organisation. When a new person is created and has an email address, the relay sends a welcome or acknowledgement message. This trigger is useful for leads captured by a form, contacts created by an integration, or contacts created manually by a sales team—provided you add rules that distinguish email-eligible contacts from internal records.

The same design applies to other supported REST Hook events. Capsule supports events for parties, projects, opportunities, tasks, and users. In particular, opportunity/moved is the event to use when an existing opportunity moves to a different milestone. Do not assume that an ordinary opportunity/updated event means a specific pipeline transition; use the explicit move event when the email should depend on a stage change.

What Capsule CRM actually provides

Capsule offers REST Hooks, its name for outbound webhooks. An account administrator using a registered OAuth application can subscribe an endpoint to an event. Capsule then sends JSON to the configured targetUrl when that event occurs.

That distinction matters for implementation planning:

There is no Volanea-native Capsule app to install.
There is no need to pretend that a Capsule automation builder can store and invoke a Volanea API key directly.
A direct Capsule-to-Volanea request is not the secure integration path because Volanea requires a secret API key and expects an email-specific request body.
The direct route is instead Capsule REST Hook → your relay → Volanea.

Capsule’s REST Hook subscriptions are limited to 20 per account and must be managed through a registered application authenticated with Capsule’s full OAuth flow. That makes hooks a good fit when you own the integration or have a developer maintaining it, rather than an ad hoc per-user configuration screen.

If you do not want to maintain a relay, Capsule also supports Zapier across all plans. Zapier offers Capsule triggers including new or updated contacts, projects, opportunities, and tasks. In that variation, Zapier becomes the middleware and can make a custom webhook request to your relay. It is still better to have your relay own the Volanea key, validation, and idempotency policy rather than placing a powerful send credential in a broadly editable automation step.

Choose a precise Capsule trigger before writing email copy

The most common integration failure is not an HTTP error. It is choosing an event that is too broad, then sending a customer-facing email every time a rep corrects a spelling mistake.

For this guide, the concrete trigger is:

Capsule event: party/created
Capsule record model: person party
Email condition: the created person has a valid primary email address and is intentionally eligible for the message
Volanea action: send one transactional email to that address

The party/created hook is a creation event, not a form-submission event. If a website form creates the Capsule person through Zapier, Make, or your own API integration, the hook fires once Capsule creates the person. If a team member manually creates a record, it can also fire. That is why eligibility should be explicit.

A practical approach is to apply a tag or custom field that your relay checks before emailing. For example, only send a welcome email when a person is created with a Website Lead tag, or only when a custom field such as Send onboarding email is true. Capsule REST Hooks can embed additional data such as fields and tags in the event payload when the subscription is configured with the appropriate embed value.

For a sales-stage email, subscribe to opportunity/moved instead. Your relay should inspect the moved opportunity’s milestone before sending. That extra condition prevents a message from firing when an opportunity moves backward, is corrected, or enters a stage that should trigger an internal notification rather than a prospect email.

Trigger selection checklist

Before enabling a hook, write down all of the following:

The exact Capsule event, such as party/created or opportunity/moved.
The record type that is allowed to cause an email.
The recipient source, such as the person’s first email address or the opportunity’s primary party.
The eligibility condition, such as a tag, custom field, milestone, or consent status.
The email purpose, such as welcome, acknowledgement, booking confirmation, or internal alert.
The idempotency identity for one logical send.

This turns an integration from “send something when Capsule changes” into a narrowly defined messaging workflow that can be tested and audited.

Subscribe Capsule to your relay endpoint

Create a public HTTPS endpoint first, for example:

https://email.example.com/hooks/capsule

Then register a Capsule application and complete the OAuth process required to manage REST Hook subscriptions. An administrator can create the subscription with Capsule’s REST Hook API. The following request subscribes the relay to the concrete party/created trigger:

curl -X POST "https://api.capsulecrm.com/api/v2/resthooks" \
  -H "Authorization: Bearer $CAPSULE_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "restHook": {
      "event": "party/created",
      "targetUrl": "https://email.example.com/hooks/capsule",
      "description": "Send an eligible new Capsule person a Volanea welcome email"
    }
  }'

The access token above is for Capsule subscription management. It is not a Volanea credential and should not be reused for email sending. The subscription is created and maintained by the registered Capsule application; build an operational process for renewing authorization and checking that the subscription remains active.

If the message requires a Capsule custom field or tags, configure the REST Hook subscription so the relevant data is embedded. Without the required embed data, a hook payload may contain the basic party record but not the custom values your routing rule expects. You can alternatively have the relay call Capsule’s API to retrieve the record, but that adds latency, failure modes, and API-rate-limit usage. Prefer embedding only the data the relay genuinely needs.

Do not point the hook directly at a browser app, static site, or endpoint that performs an email send synchronously and slowly. Capsule expects a response from the target endpoint. Your webhook receiver should validate, durably record or enqueue the work, and return a success response quickly. A separate worker can perform the Volanea request if email rendering, contact lookup, or queueing could make the request slow.

The actual Capsule REST Hook payload

For party/created, Capsule sends a JSON object with an event string and a payload array. The array shape is important: even when one party caused the event, your receiver should handle the payload as a list rather than assume one top-level person object.

A representative person payload has fields such as id, type, firstName, lastName, timestamps, and emailAddresses. This is the structure your relay should expect and map:

{
  "event": "party/created",
  "payload": [
    {
      "id": 11587,
      "type": "person",
      "about": null,
      "title": null,
      "firstName": "Scott",
      "lastName": "Spacey",
      "jobTitle": "Creative Director",
      "createdAt": "2015-09-15T10:43:23Z",
      "updatedAt": "2015-09-15T10:43:23Z",
      "organisation": null,
      "lastContactedAt": null,
      "addresses": [],
      "phoneNumbers": [],
      "websites": [],
      "emailAddresses": [
        {
          "id": 12134,
          "type": "Work",
          "address": "scott@example.com"
        }
      ]
    }
  ]
}

Treat this sample as an event contract, not as an invitation to blindly send email to every address in emailAddresses. A person can have no address, several addresses, a stale work mailbox, or an address that should not receive marketing. For transactional messaging, use a deterministic selection policy. A simple policy is “select the first non-empty email address only when the party is a person and carries the required eligibility tag.” If your business needs a primary-address concept, model it explicitly in Capsule rather than guessing based on the label Work or Home.

Also handle organisation parties. An organisation can be created through the same party/created event, but it does not have the same personal salutation fields. In this example, the relay skips every payload item whose type is not person.

Map Capsule fields to a Volanea send request

Volanea’s REST send endpoint is POST https://api.volanea.com/v1/send. It uses a secret sk_… or sk_test_… key and supports the Idempotency-Key header for safe retries. The following Node.js example processes the Capsule payload, selects a recipient, maps contact fields into the email, and makes the Volanea request.

The code deliberately includes both html and text, uses a stable idempotency value based on the Capsule party ID and message purpose, and avoids putting untrusted CRM text into HTML without escaping it.

import crypto from "node:crypto";

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

function displayName(party) {
  return [party.firstName, party.lastName].filter(Boolean).join(" ").trim();
}

export async function handleCapsuleHook(request, env) {
  const hook = await request.json();

  if (hook.event !== "party/created" || !Array.isArray(hook.payload)) {
    return new Response("ignored", { status: 200 });
  }

  for (const party of hook.payload) {
    // Field mapping: Capsule payload[].type → person-only workflow.
    if (party.type !== "person") continue;

    // Field mapping: Capsule payload[].emailAddresses[].address → recipient.
    const recipientEmail = party.emailAddresses
      ?.map((entry) => entry.address?.trim())
      .find(Boolean);

    if (!recipientEmail) continue;

    // Add your own tag/custom-field consent or workflow eligibility check here.
    const firstName = party.firstName?.trim() || "there";
    const name = displayName(party);

    // One stable key for one logical "new-party welcome" send.
    const idempotencyKey = crypto
      .createHash("sha256")
      .update(`capsule:party:${party.id}:welcome-v1`)
      .digest("hex");

    const volaneaPayload = {
      fromEmail: "hello@your-verified-domain.example",
      fromName: "Example Company",
      to: [{ email: recipientEmail, name: name || undefined }],
      replyTo: "support@your-verified-domain.example",
      subject: "Thanks for getting in touch",
      text: `Hi ${firstName},\n\nThanks for contacting Example Company. We received your details and will be in touch soon.\n\nExample Company`,
      html: `<p>Hi ${escapeHtml(firstName)},</p><p>Thanks for contacting Example Company. We received your details and will be in touch soon.</p><p>Example Company</p>`
    };

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

    if (!response.ok) {
      const details = await response.text();
      console.error("Volanea send failed", response.status, details, {
        capsulePartyId: party.id
      });
      return new Response("temporary email failure", { status: 500 });
    }
  }

  return new Response("ok", { status: 200 });
}

The relevant field mapping is concrete:

Capsule REST Hook field	Volanea send field	Purpose
`payload[].emailAddresses[].address`	`to[].email`	Recipient address
`payload[].firstName` and `payload[].lastName`	`to[].name`	Recipient display name
`payload[].firstName`	`text` and `html`	Personal greeting
`payload[].id`	`Idempotency-Key` input	Stable identity for one CRM-triggered send
event `party/created`	Subject and template choice	Determines the message purpose

The fromEmail and replyTo values must be addresses you control. Use a sender on a verified domain, not an individual salesperson’s consumer mailbox. Your sending domain needs the relevant DNS authentication configured before production sends. For endpoint details, required fields, and additional sending patterns, use the email API reference and setup guides.

Keep the Volanea API key out of Capsule and out of the browser

The Volanea secret key belongs in the relay’s server-side secret store, not in Capsule CRM, a front-end form, a static JavaScript bundle, or a client-visible Zap field.

With direct REST Hooks, Capsule does not hold the Volanea API key at all. Capsule only knows the HTTPS targetUrl of your relay. The relay reads VOLANEA_API_KEY from its protected runtime environment and adds the Authorization: Bearer … header when it calls Volanea.

This is safer for several reasons:

Anyone who can inspect browser network requests, front-end code, exported configuration, or a shared spreadsheet must not be able to send as your domain.
A sending key can create real-world side effects: emails may reach customers, affect sender reputation, and generate support work.
Keeping the key in one server-side secret manager makes rotation straightforward.
You can separate development and production by using a test key in a test environment and a live key only in production.

For a Cloudflare Worker, store the value as a Worker secret and expose it to code as an environment binding. For a serverless function, use the platform’s encrypted environment variables. For a container service, use a managed secret store or injected runtime secret. Do not log the authorization header, full environment object, or raw Volanea request body if it can include customer data.

If you use Zapier or Make as the middleware, the same principle holds: prefer a relay endpoint that owns the Volanea credential. A no-code HTTP module can send the CRM data to your endpoint using a limited webhook secret; the relay then handles Volanea authorization. That arrangement lets you rotate the email key without editing several automations and keeps sending logic version-controlled.

Build for duplicate delivery and fast acknowledgements

Webhooks provide at-least-once delivery behavior in practice. Your receiver must be prepared to see a valid Capsule event more than once.

Capsule retries failed REST Hook deliveries five times after delays of 5 seconds, 1 minute, 5 minutes, 15 minutes, and 15 minutes. If delivery continues to fail, Capsule marks the hook dead and unsubscribes it. This has two major implications.

First, respond quickly. If your receiver waits for a slow third-party call, database lock, or template-rendering task before sending a response, Capsule may regard delivery as failed. Decouple acknowledgment from slow work where possible: validate the event, write a durable job keyed by the event identity, return a 2xx response, then let a worker send the email.

Second, no retry should create an extra welcome message. The example derives the Volanea Idempotency-Key from the Capsule party ID and the specific message version:

capsule:party:11587:welcome-v1

Hashing that value is optional but useful when you want a fixed header-safe representation. The important property is stability: a retry of the same event must use the same key. Do not generate a new random UUID every time the hook handler runs, because that makes a retry look like a new email request.

There is a subtle trade-off. An idempotency key based solely on party.id and welcome-v1 intentionally allows only one welcome-v1 message per person. If your business wants to resend a revised welcome after a specific later action, use a different message purpose or version, such as welcome-v2, or include a separately stored qualifying event identifier. Make the business meaning explicit rather than relying on accidental retries.

When this breaks

A production email integration should have predictable failure behavior. The important question is not whether a webhook will ever fail; it is whether failure can create duplicate mail, silently drop a lead, or expose a secret.

Capsule retries cause duplicate sends

What happens: Your relay successfully calls Volanea, but crashes or times out before returning a 2xx response to Capsule. Capsule retries the same REST Hook delivery.

How to prevent it: Send the same Idempotency-Key for every attempt of that logical email. Also record the Capsule record ID, event, message purpose, Volanea response status, and resulting send identifier in durable logs. If the relay has a queue, deduplicate the job before enqueueing it as well.

What not to do: Do not solve this by turning off retries or returning success before you have durably recorded the event. That merely changes duplicate risk into silent-loss risk.

The webhook endpoint times out or returns an error

What happens: Capsule retries on non-successful delivery, then eventually marks the REST Hook dead and unsubscribes it after its retry schedule is exhausted.

How to prevent it: Keep the HTTP handler small. Parse JSON, reject irrelevant event types, verify the minimum required fields, persist the job, and return quickly. Move network-heavy enrichment, template assembly, CRM lookups, and sends to a queue consumer when volume or latency demands it.

Operational response: Alert on repeated non-2xx responses, queue backlog, and a missing stream of expected events. Regularly check that the Capsule subscription exists and that the registered OAuth application remains authorized.

Payload fields are missing or have an unexpected shape

What happens: A person has no emailAddresses, a party is an organisation rather than a person, a tag or custom field was not embedded, or a future API addition changes the payload by adding fields you did not expect.

How to prevent it: Validate optional arrays before reading them; skip records that do not meet your recipient policy; and design parsers to tolerate additional JSON properties. Do not assume firstName, lastName, custom fields, tags, or an email label always exists. If you depend on custom fields or tags, confirm your REST Hook subscription embeds them and test with records that have and lack those values.

Fallback option: Retrieve the current party from Capsule’s API using the party ID only when necessary. Cache or limit that enrichment, because each extra lookup adds latency and consumes API quota.

The CRM event is valid but should not send email

What happens: A manually created internal contact, test record, duplicate, or contact without the required consent triggers party/created.

How to prevent it: Put eligibility in the code and data model. Require a tag or custom field associated with the lead source or consent state. A CRM creation event means the record exists; it does not automatically mean that a customer-facing email is appropriate.

Volanea rejects or suppresses a message

What happens: The sender domain is not verified, the request body is invalid, the recipient is suppressed, or a provider-side delivery condition blocks the send.

How to prevent it: Check and log the Volanea HTTP response body without logging the API key. Use a verified sender domain, include both plain-text and HTML bodies, and treat a non-2xx response as a failed job that needs an intentional retry policy. Do not repeatedly retry permanent validation failures; fix the sender, payload, or recipient data first.

Test the full path before enabling live customer mail

A reliable test plan uses representative Capsule data rather than only a hand-written JSON request. Create test people that cover the edge cases your code is meant to handle.

Use at least these cases:

A person with first name, last name, and one email address who meets the eligibility rule.
A person with no email address.
An organisation party.
A person with multiple email addresses.
A person who does not have the required tag or custom field.
A repeated delivery of the same JSON payload.
A Volanea temporary failure or simulated network timeout.

For each case, inspect the relay logs and the email result. The first case should produce one message. The next four should produce no customer-facing email and a clear skip reason. The repeated payload should not produce a second message. A temporary failure should be visible and retryable without creating a duplicate.

Use a non-production Capsule account or carefully marked test records wherever possible. Send to internal addresses first. Confirm that the sender display name, reply-to address, plain-text part, HTML rendering, and recipient name are correct in multiple mail clients. Then validate the outcome in Volanea’s sending records and delivery events.

Keep email content separate from the hook mechanics. Your first deployment can use a simple hard-coded acknowledgement, but production systems are easier to maintain when the relay chooses a named template or message version based on an explicit CRM rule. That gives you a clean way to revise content without accidentally changing trigger semantics.

Alternatives: Zapier, Make, and a custom relay

The direct REST Hook route gives developers the most control. It is the best option when you need a precise idempotency policy, an auditable event log, custom content generation, or reliable handling of many CRM events.

Zapier is a reasonable alternative when the rule is simple and the team prefers a visual workflow. Capsule’s Zapier integration is available on all Capsule plans and includes triggers for new or updated contacts, projects, opportunities, and tasks. A Zap can send data to a webhook action, but keep the email key in a server-side relay rather than treating a general-purpose automation configuration as your long-term secret vault.

Make can play a similar role where its visual scenario builder and transformations fit your workflow. It can reduce custom code for routing and filtering, but it does not remove the underlying requirements: choose a precise trigger, protect the Volanea key, preserve an idempotency identity, and monitor failed runs.

A custom relay is usually the strongest long-term choice when sending email is customer-facing. It lets you:

Version the rules alongside application code.
Add a database-backed outbox or queue.
Retain audit records without exposing broad automation access.
Escape and validate CRM data before including it in HTML.
Apply per-event rate limits, consent checks, and recipient policies.
Use Volanea idempotency consistently across all sources.

The cost is ownership. You need to deploy, monitor, and secure one endpoint. For most engineering teams, that is a worthwhile trade when the integration sends from a company domain and must behave predictably under retries.

Production checklist

Before switching this Capsule CRM email workflow live, verify each item below:

Conclusion

To send email from Capsule CRM with Volanea, use Capsule REST Hooks as the event source and a secure relay as the email decision point. The concrete party/created trigger gives your application a structured payload containing the newly created person and their email addresses; the relay selects an eligible recipient, maps those values into POST /v1/send, and keeps the Volanea key safely on the server.

The implementation becomes dependable when you treat it as an event-processing system, not just an HTTP request. Choose an exact Capsule event, validate incomplete CRM data, respond promptly to webhooks, use an idempotency key that represents one business action, and monitor both Capsule delivery and Volanea send results. That foundation works equally well for welcome messages, sales-stage notifications, project updates, and internal alerts.

FAQ

Can I install a native Volanea app from the Capsule CRM marketplace?

No. This integration uses Capsule CRM REST Hooks and a secure middleware or relay service. There is no native Capsule marketplace installation flow required or assumed.

What Capsule CRM event should trigger a welcome email?

Use party/created when a new person record should be considered for a welcome or acknowledgement email. Add an eligibility rule, such as a specific tag or consent field, so manually created or internal contacts do not automatically receive mail.

Can Capsule CRM call Volanea directly?

Not safely through REST Hooks alone. Capsule notifies a configured URL with event JSON, while Volanea requires a secret API key and a send-specific request body. Put a server-side relay between the two services.

How do I avoid duplicate emails when Capsule retries a webhook?

Derive a stable Volanea Idempotency-Key from the Capsule record ID plus the message purpose and version. Reuse that exact key on every retry of the same logical email.

What happens if the Capsule webhook endpoint stays unavailable?

Capsule retries failed REST Hook deliveries five times over its retry schedule. If delivery still fails, the hook is marked dead and unsubscribed, so endpoint monitoring and subscription checks are essential.

How to Send Email from Capsule CRM with Volanea