Groundmail for Shopware 6

The official Groundmail plugin for Shopware 6.6 and 6.7. It sends every email your shop sends (order confirmations, shipping and status updates, invoices and other documents, customer accounts, password resets, contact forms) through the Groundmail email API over HTTPS.

• No SMTP and no MAILER_DSN changes: switch it on in the plugin settings
• Settings per sales channel: on/off, API key and email category
• Attachments such as invoices and delivery notes, CC, BCC, Reply-To and custom headers
• Each email is tagged with the Shopware event that sent it (shopware_event, for example checkout.order.placed), so you can find it in Groundmail
• A Send test email button in the settings, and bin/console groundmail:test
• When it's off, or no API key is set, your shop sends email exactly as before

Requires Shopware 6.6.2 or later (6.6 and 6.7) and PHP 8.2 or later. Licensed MIT.

Install

From the Shopware Store: open Extensions > Store in the Administration, search for Groundmail and install it.

With Composer:

composer require groundmail/shopware
bin/console plugin:refresh
bin/console plugin:install --activate GroundmailMail
bin/console cache:clear

Or upload GroundmailMail.zip under Extensions > My extensions > Upload extension, then install and activate it.

Set up

1. In Groundmail, verify your sending domain and create an API key under API keys. A "Send only" key is enough.
2. Make sure your shop's email address (Settings > Shop > Basic information) is on that domain. Shopware sends from it.
3. Open Extensions > My extensions, find Groundmail and choose Configure.
4. Paste the API key, switch on Send shop email through Groundmail and save.
5. Under Test email, send one to delivered@simulator.groundmail.dev. It checks the setup without emailing anyone.

To keep the key out of the database, leave the field empty and set an environment variable in .env.local or your host's environment:

GROUNDMAIL_API_KEY=gm_your_key

Every setting can differ per sales channel. Pick the sales channel at the top of the settings page; empty fields inherit from All Sales Channels.

Email category

Groundmail sends transactional, product and newsletter email on separate IPs. Shop email is transactional by default, which is right for orders and accounts. Pick Product or Newsletter only for a sales channel that sends that kind of email. Newsletter sending needs an approved Groundmail account.

Test from the command line

bin/console groundmail:test delivered@simulator.groundmail.dev
bin/console groundmail:test you@yourdomain.com --sales-channel=<sales-channel-id> --from=orders@yourdomain.com

The test uses the saved settings and sends even before sending is switched on.

How it works

Shopware builds its mail transport from MAILER_DSN, or from Settings > System > Mailer. The plugin wraps whichever transport that is. For each email it reads the settings of the email's sales channel: when Groundmail is on and has a key, the email goes to the Groundmail API; otherwise your own mailer sends it, unchanged. Shopware adds order documents and other attachments before the email reaches the plugin, so they are sent as well.

If Groundmail rejects an email (for example, the sender is not on a verified domain), the send fails and Shopware logs it under Settings > System > Event logs, the same as an SMTP error. The plugin never resends it through your own mailer.

The plugin logs each send (email ID, Shopware event and sales channel, no addresses or content) to var/log/groundmail_<environment>-<date>.log, kept for 14 days.

What the plugin sends

Only to https://api.groundmail.dev, and only after you switch sending on and add an API key, or when you send a test email: each email's sender, recipients, subject, content, attachments and custom headers, to POST /emails. See the terms and privacy policy.

Troubleshooting

Emails still go through my old mailer. Check Send shop email through Groundmail is on and an API key is set for that sales channel. Shopware applies saved settings once its cache refreshes, which can take a few minutes; bin/console cache:clear applies them at once.

"This API key may only send from …" or a From address error. The sender must be on a domain you verified in Groundmail. Shopware sends from the shop email address under Settings > Shop > Basic information, per sales channel.

"Groundmail API key must start with gm_". Paste an API key, not an SMTP password (gmsmtp_…).

Order emails are delayed. Shopware sends some emails from its message queue, so make sure the message consumer (or the admin worker) runs.

Development

composer install
composer test            # PHPUnit
composer phpstan         # PHPStan, level 8
bin/build-admin.sh       # copies the Administration script for 6.6 and 6.7
bin/build-zip.sh         # dist/GroundmailMail.zip, the files that ship