Shopware Email Integration: Send Order Email with Volanea

Shopware email integration does not require a marketplace plugin: Shopware Flow Builder can send an outbound webhook when an order is placed, and that request can call Volanea’s email API directly or through a small middleware service. The important work is choosing the right event, mapping Shopware’s order data safely, and designing for retries before customers receive duplicate confirmations.

What this Shopware email integration uses

Volanea does not provide a native Shopware app or marketplace plugin. The integration route is Shopware’s Flow Builder, specifically its Send webhook action. A flow listens for a Shopware business event, then makes an HTTP request to a URL you configure.

For an order confirmation, the concrete Shopware trigger is Order placed, backed by Shopware’s checkout.order.placed event. This is the event to use when the business fact that an order exists should begin your email workflow. It is preferable to treating a browser checkout success page as the trigger: a customer can close that page, reload it, or use a different device, while the order event is handled on the server.

A typical flow is:

1. A customer completes checkout.
2. Shopware creates the order and dispatches the Order placed event.
3. Flow Builder evaluates the flow and runs its Send webhook action.
4. The webhook posts selected order fields to either Volanea or your middleware endpoint.
5. Volanea accepts the message for delivery and returns a response.

The webhook action is an outbound server-to-server request. That distinction matters for security. It is not JavaScript in the storefront, so shoppers do not receive the webhook configuration or the Volanea API key in their browser.

Before building, confirm that the Flow Builder and its webhook action are available in your Shopware version and commercial plan. Shopware capabilities can vary by version, edition, installed apps, and plan. If the Send webhook action is not available in the administration, use the middleware pattern described below and have a Shopware developer dispatch a request from the checkout.order.placed server-side event, rather than trying to expose a sending key in the storefront.

Choose the order event carefully

“Order confirmation” can mean several different things operationally. An order being placed, an order becoming paid, and an order being shipped are distinct state changes. Sending the same email at all three points is a common source of confusing customer communication.

For a standard receipt or confirmation, start with Order placed. In Flow Builder, create a new flow with that trigger and name it clearly, such as Volanea — order placed confirmation. Then add a condition if necessary. For example, a merchant may send this email only for orders with a particular sales channel, language, payment method, or delivery country.

Order placed versus payment and delivery states

Use the event that corresponds to the promise in the message:

• Order placed: “We received your order.” This is the right default for most confirmation emails.
• Transaction state changed to paid: “We received your payment.” This is useful where payment is asynchronous or manually captured.
• Delivery state changed to shipped: “Your order is on the way.” Include tracking data only when it actually exists.
• Customer registered: “Welcome” messages and account verification flows.
• Contact form submitted: acknowledgements or lead-routing messages, where available through the relevant form or extension workflow.

Do not treat an order placement as proof of a successful payment unless your payment method and business process make that true. For bank transfer, invoice, or delayed payment methods, an “order received” message is accurate; a “payment successful” message may not be.

Why Flow Builder is useful here

Flow Builder keeps the trigger close to the commerce event and gives non-developers an auditable visual place to see the business rule. It can also apply conditions before the outbound call. That reduces needless API traffic and helps avoid sending a customer email for internal, test, or manual orders.

However, Flow Builder is not a full integration runtime. It should not be asked to assemble a complicated line-item table, query external inventory systems, or decide whether a message has already been accepted by an email provider. Those responsibilities belong in a template system or middleware when they become complex.

Configure Shopware’s Send webhook action

In the Shopware Administration, open Settings, then Flow Builder, and create a flow based on the Order placed trigger. Add the Send webhook action. The action is where you set the destination URL, request method, headers, and body using Shopware’s data mapping values.

For a direct integration, configure the action as follows:

• Method: POST
• URL: Volanea’s email-send endpoint from your account documentation
• Content type: application/json
• Authorization header: a bearer token containing a restricted Volanea API key
• Body: valid JSON, with Shopware data mapping expressions inside JSON strings

The send action does not impose one universal payload on every webhook. The body is the payload you configure. That is useful because it lets you send a compact, purpose-built email request instead of posting an entire order object, including fields Volanea does not need.

The body below demonstrates a direct mapping. In Flow Builder, use the data mapping picker for your installed version to insert values rather than typing paths from memory. The values shown use the order context exposed by the Order placed event: order.id, order.orderNumber, and the associated order.orderCustomer fields.

{
  "from": "Acme Store <orders@example.com>",
  "to": [
    "{{ order.orderCustomer.email }}"
  ],
  "subject": "We received order {{ order.orderNumber }}",
  "html": "<p>Hi {{ order.orderCustomer.firstName }},</p><p>Thanks for your order <strong>{{ order.orderNumber }}</strong>.</p><p>We will send another email when it ships.</p>",
  "text": "Hi {{ order.orderCustomer.firstName }},\n\nThanks for your order {{ order.orderNumber }}. We will send another email when it ships.",
  "tags": [
    {
      "name": "event",
      "value": "shopware-order-placed"
    },
    {
      "name": "shopware_order_id",
      "value": "{{ order.id }}"
    }
  ]
}

The corresponding HTTP request is a Volanea REST API send call. Use the endpoint and field names published in the email API reference and setup guides for your account, particularly if your account uses a newer API version. Conceptually, the request looks like this:

curl --request POST 'https://api.volanea.com/v1/emails' \
  --header 'Authorization: Bearer VOLANEA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "from": "Acme Store <orders@example.com>",
    "to": ["customer@example.net"],
    "subject": "We received order 10042",
    "html": "<p>Hi Ada,</p><p>Thanks for your order <strong>10042</strong>.</p>",
    "text": "Hi Ada,\n\nThanks for your order 10042.",
    "tags": [
      {"name": "event", "value": "shopware-order-placed"},
      {"name": "shopware_order_id", "value": "018f2e8a-7c6c-7a1f-9a00-123456789abc"}
    ]
  }'

The first block is what Shopware generates after data mapping. The second is the same request after actual order data has been substituted. Test with a non-customer address first, and inspect the receiving request at a webhook inspection endpoint before pointing the flow at production.

Keep JSON valid after mapping

Webhook bodies fail more often from malformed JSON than from email API problems. Customer names, product names, and addresses can contain quotes, ampersands, line breaks, emoji, and non-Latin characters. If the Flow Builder mapping mechanism does not safely JSON-escape an inserted value in your version, do not interpolate that field into JSON directly.

A middleware endpoint avoids this class of problem because Shopware can send a small, simple payload and the middleware can serialize JSON using a real JSON encoder. It also makes it practical to render rich order summaries and line-item tables without putting HTML inside a Flow Builder text field.

Field mapping: what to send and what to leave out

An email provider needs surprisingly little information to accept a transaction message. The minimal direct mapping is a verified sender, recipient address, subject, and HTML or text body. Everything else should be deliberately included because it is useful for the message, troubleshooting, or suppression handling.

For an Order placed flow, map these fields where available:

Avoid putting payment details, full billing addresses, internal notes, or raw customer metadata into tags. Email tags are operational metadata, not a secure customer record. A tag named shopware_order_id is useful because it lets support staff find the relevant send; a tag holding an address, payment status, or customer phone number adds privacy risk without helping deliverability.

Line items need a different approach

Shopware orders can have multiple line items, custom products, discounts, promotions, shipping charges, and tax rules. A single Flow Builder mapping field is not a robust templating language for iterating through every one of those records. If the order confirmation must include a full line-item receipt, use middleware or a Volanea template with variables assembled by a server-side integration.

A sensible division is to use Flow Builder for the event and send a compact envelope containing the order ID and customer email to middleware. The middleware then reads the order through authenticated Shopware server-side APIs or receives a normalized payload from a custom Shopware subscriber. It can produce an accessible HTML table, calculate totals consistently with Shopware, and send both HTML and plain text alternatives.

Secure the Volanea API key

The Volanea API key is a credential with the ability to send mail as your verified sending domain. It must never be placed in storefront JavaScript, a theme setting rendered to visitors, a public app configuration endpoint, or a client-side tag manager.

In a direct Flow Builder configuration, the key belongs in the Authorization request header in the Send webhook action, formatted as Bearer YOUR_KEY. The flow is configured and executed on the Shopware server, so the header is not delivered to the customer’s browser. Limit access to Shopware Administration users who genuinely need to edit flows, and treat exports, database backups, screenshots, and support recordings containing the flow as sensitive.

Direct configuration is convenient, but it has a trade-off: the credential lives in a business-automation configuration. Some organizations require secrets to be held only in a dedicated secret manager, with rotation and access logging. In that case, use middleware and put the Volanea key in an environment variable or managed secret there instead.

Recommended middleware authentication model

With middleware, Shopware posts to an endpoint you control, for example https://email.example.com/shopware/order-placed. The endpoint authenticates Shopware using a separate shared secret or request signature scheme that you implement, then the service loads VOLANEA_API_KEY from its server-side secret store.

This separates two permissions:

1. Shopware may request a narrowly defined order-email operation.
2. Only the middleware may use the more powerful Volanea sending credential.

Rotate keys deliberately. Create a replacement key, update the flow or secret store, deploy or save the new configuration, run a test order, and only then revoke the previous key. Do not revoke first and hope the change reaches every environment immediately.

The recommended middleware route

Direct webhooks work for a basic confirmation. Middleware is the better production design when messages need line items, localization, idempotency, custom templates, or central secret management.

The Shopware webhook body can be intentionally small:

{
  "event": "checkout.order.placed",
  "orderId": "{{ order.id }}",
  "orderNumber": "{{ order.orderNumber }}",
  "email": "{{ order.orderCustomer.email }}",
  "firstName": "{{ order.orderCustomer.firstName }}"
}

Your middleware should validate the request, reject malformed data, derive a deterministic idempotency key from the Shopware order ID and message type, and call Volanea. This Node.js example shows the mapping explicitly. It uses fetch, server-only environment variables, and a database-backed idempotency check represented by alreadySent and recordSent.

import express from 'express';

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

app.post('/shopware/order-placed', async (req, res) => {
  if (req.get('x-shopware-webhook-secret') !== process.env.SHOPWARE_WEBHOOK_SECRET) {
    return res.sendStatus(401);
  }

  const { event, orderId, orderNumber, email, firstName } = req.body;
  if (event !== 'checkout.order.placed' || !orderId || !orderNumber || !email) {
    return res.status(400).json({ error: 'Invalid Shopware order payload' });
  }

  const idempotencyKey = `shopware:order-confirmation:${orderId}`;
  if (await alreadySent(idempotencyKey)) {
    return res.status(200).json({ status: 'already_sent' });
  }

  const response = await fetch('https://api.volanea.com/v1/emails', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.VOLANEA_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey
    },
    body: JSON.stringify({
      from: 'Acme Store <orders@example.com>',
      to: [email],
      subject: `We received order ${orderNumber}`,
      html: `<p>Hi ${escapeHtml(firstName || 'there')},</p><p>Thanks for your order <strong>${escapeHtml(orderNumber)}</strong>.</p>`,
      text: `Hi ${firstName || 'there'},\n\nThanks for your order ${orderNumber}.`,
      tags: [
        { name: 'event', value: 'shopware-order-placed' },
        { name: 'shopware_order_id', value: orderId }
      ]
    })
  });

  if (!response.ok) {
    const detail = await response.text();
    console.error({ orderId, status: response.status, detail });
    return res.status(502).json({ error: 'Email provider rejected send' });
  }

  await recordSent(idempotencyKey);
  return res.status(202).json({ status: 'accepted' });
});

In real code, escapeHtml must correctly escape dynamic HTML, and alreadySent must be atomic with recording the send state. A unique database constraint on the idempotency key is safer than an in-memory cache, especially when the service runs on multiple instances.

When this breaks: failures at the Shopware-to-email hop

The integration has at least two independent boundaries: Shopware to the webhook destination, then the destination to Volanea. A successful request at one boundary does not automatically prove success at the other. Design your logs and responses so that support can identify which boundary failed.

Retries can create duplicate emails

Webhook delivery is generally at-least-once, not exactly-once. If Shopware sends the webhook, the destination accepts it and sends to Volanea, but the connection closes before Shopware receives the success response, Shopware may retry. The second request can create a second customer email unless the receiver is idempotent.

Use the stable order.id, not the customer-visible order number alone, to construct an idempotency key. Include the message type as well. shopware:order-confirmation:<order-id> and shopware:shipping-notice:<order-id> are different operations, while two retries for the same confirmation are the same operation.

If you use a direct webhook, confirm the provider’s current idempotency support and exact request header in the API documentation. If you cannot use provider-level idempotency directly, middleware with a durable unique key is the reliable answer.

Webhook timeouts and slow work

Do not make Shopware wait while middleware fetches products, renders a PDF, calls a tax service, and sends an email. The longer the request takes, the more likely a timeout or retry becomes.

A robust endpoint validates the request, stores a job keyed by the event ID or order ID, responds promptly with a successful status when the job is safely persisted, and lets a worker perform the potentially slow Volanea send. The worker should retry transient network and 5xx failures with bounded exponential backoff. It should not blindly retry a 4xx response caused by a malformed recipient or unauthorized credential.

Missing payload fields and associations

The Order placed event has an order context, but the exact data exposed to Flow Builder’s data mapping can differ by Shopware version, action, installed extensions, and feature availability. Associated data such as line items, deliveries, custom fields, or a sales-channel-specific domain may not be present where you expect it.

Test with representative orders: guest checkout, registered customer, discount, multiple shipping methods, free order, digital product, and each supported language. If a mapped expression is empty, do not guess that the customer has no data. Inspect the flow’s available data mapping options and move enrichment into middleware when the association is not reliably exposed.

API validation and sender verification

A 401 or 403 response usually indicates an invalid, revoked, wrongly scoped, or incorrectly formatted Volanea credential. A sender-related validation response commonly means the from address or its domain is not verified. A 400 response often means invalid JSON, an empty to value, or an unsupported field shape.

Log the HTTP status and safe provider response detail, but do not log the API key or full email body. Include the Shopware order ID and provider message ID in structured logs where available. That gives support a traceable path from order to API request to delivery event.

Deliverability still applies to commerce email

An API call being accepted is only the beginning. Transactional messages need a verified sending domain, correctly configured SPF and DKIM authentication, and a sensible DMARC policy. Use a recognizable sender such as orders@yourdomain.example, not a free mailbox domain that you do not control.

Keep order confirmations transactional. Do not add promotional content that changes the message’s purpose without checking applicable consent and marketing rules. Separating marketing campaigns from operational order updates also makes reporting and customer expectations clearer.

Use plain-text content alongside HTML, avoid link shorteners in receipts, and keep the first email after checkout focused on the order. A customer who cannot find the order number, total, support route, or next expected step is more likely to mark the message as spam or contact support.

Before enabling production traffic, validate test and imported customer addresses with an email address verification tool. Verification does not replace consent or checkout validation, but it can help catch obvious syntax, domain, and mailbox-risk issues before an automated flow starts sending.

Testing and launch checklist

Treat the flow as a production integration, not an administration convenience. A small test plan prevents most failures from appearing first in customer inboxes.

Use this launch checklist:

1. Verify the From domain in Volanea and complete required DNS authentication.
2. Confirm that the Shopware Flow Builder installation exposes the Send webhook action.
3. Create the flow using the Order placed trigger and scope it to the intended sales channel.
4. Start with a test recipient or a condition that only permits a test order number.
5. Send the webhook to an inspection endpoint first and validate JSON after Shopware data mapping.
6. Test the Volanea request with the same final payload and a verified sender.
7. Add an idempotency strategy before enabling retries or production traffic.
8. Place test orders across payment methods, languages, guest checkout, promotions, and mobile checkout.
9. Check HTML and text rendering in major inboxes and confirm that order references are correct.
10. Remove the test-only condition only after delivery and logging are verified.

Also decide what Shopware’s built-in mail handling should do. If Shopware’s standard order confirmation remains enabled while Volanea sends a second confirmation, customers will receive duplicates even when the webhook is perfectly idempotent. Choose one authoritative confirmation path, then disable or adjust the other according to your Shopware configuration and legal requirements.

Operational reporting and future flows

Once the order confirmation works, the same architecture can support other high-value transactional events. Add them one at a time, with a separate flow name, template, idempotency key namespace, and test plan for each message type.

Good candidates include paid-order receipts, shipment notices, return-status updates, passwordless account notifications, and internal fraud-review alerts. Each has different recipient expectations and source-of-truth fields. A shipping flow, for example, should key idempotency to a shipment or delivery identifier when partial shipments are possible; using only the order ID would incorrectly suppress the second legitimate shipment notice.

Tag each message with a low-cardinality event name and a stable Shopware reference. That makes it possible to compare provider acceptance, bounces, complaints, and delivery behavior by message class. It also helps answer support questions without searching raw email content.

Conclusion

A dependable Shopware email integration starts with the server-side Order placed event and Shopware Flow Builder’s Send webhook action, not a browser-side checkout script or an invented plugin. For a simple confirmation, map the customer email and order reference directly into a Volanea REST request. For richer receipts and stronger operational controls, post a compact event to middleware and keep the Volanea credential, rendering logic, and idempotency layer there.

The details that make the integration trustworthy are unglamorous: a verified sender, a restricted API key, valid JSON, explicit mapping, fast webhook responses, and duplicate protection. Build those in before the first production order, and the same pattern can grow into a durable transactional email system.

FAQ

Does Volanea have a native Shopware plugin?

No. This integration uses Shopware Flow Builder’s outbound Send webhook action and Volanea’s REST email API. There is no marketplace-installation step in this approach.

What Shopware trigger should send an order confirmation?

Use the Order placed trigger, associated with Shopware’s checkout.order.placed event, for a “we received your order” email. Use transaction or delivery state triggers for payment and shipment messages instead.

Where should the Volanea API key be stored?

For a direct integration, place it only in the server-side Authorization header of the Shopware webhook action and restrict administration access. For stronger secret management, store it as a server-side environment secret in middleware, never in storefront code or public configuration.

How do I stop duplicate emails after webhook retries?

Use an idempotency key based on Shopware’s stable order.id plus the message type. Middleware should enforce it with durable storage, ideally a unique database constraint, before accepting or sending the email.

Can a Flow Builder webhook send an itemized order receipt?

It can send simple mapped values, but complex line-item rendering is usually better handled by middleware or a provider template. That approach also avoids fragile JSON and HTML interpolation in the flow configuration.