GroundmailDocs
Markdown

Shopware email with Groundmail

Send Shopware 6 store email through Groundmail. Order confirmations, order status and delivery updates, customer registration and password recovery emails, and every other mail template then go out from your own domain.

Updated Nov 14, 20263 min read

There are two ways to connect:

  • SMTP, set in the admin or in MAILER_DSN. Nothing to install.
  • The API, with the groundmail/symfony-mailer transport and a groundmail+api:// DSN. Use it if your host blocks outbound SMTP ports.

Prerequisites

  • A Groundmail account with a verified sending domain.
  • For SMTP: an SMTP credential. In the Groundmail dashboard, open SMTP and choose Create SMTP credential. The password (gmsmtp_…) is shown once, so copy it. See SMTP relay.
  • For the API: an API key (gm_…) from API keys, and shell access to run Composer.
  • Admin access to Shopware.

Everything the store sends through Groundmail goes out as transactional email, so use it for order, account and notification email. Never send cold email.

Option 1: SMTP in the admin

  1. In the Shopware admin, go to Settings, then System, then Mailer.
  2. Under Preferred email agent, choose SMTP server, and fill in:
Shopware field Value
Host smtp.groundmail.dev
Port 587
Username groundmail
Password Your SMTP credential (gmsmtp_…)
Encryption TLS
Sender address An address on your verified domain, for example orders@yourdomain.com
  1. Click Save.

Encryption set to TLS upgrades the connection on port 587 with STARTTLS, which is what the relay expects. Don't choose SSL or port 465, and don't choose No encryption: in Shopware it also turns off certificate checks.

Option 2: SMTP with MAILER_DSN

To keep the credential out of the admin, set it in .env.local (or your host's environment):

Terminal
MAILER_DSN=smtp://groundmail:gmsmtp_your_credential@smtp.groundmail.dev:587

Then go to Settings, System, Mailer and choose Use environment's configuration. Any other choice there overrides MAILER_DSN. If your password contains characters such as @, : or /, URL-encode them in the DSN.

Option 3: The API with groundmail/symfony-mailer

Shopware sends email with Symfony Mailer, so the Groundmail transport plugs in with a DSN.

  1. Install the transport in your Shopware project:
Terminal
composer require groundmail/symfony-mailer
  1. Register its factory so Symfony Mailer knows the groundmail+api scheme:
YAML
# config/services.yaml
services:
  Groundmail\Symfony\Transport\GroundmailTransportFactory:
    tags: ['mailer.transport_factory']
  1. Set the DSN in .env.local:
Terminal
MAILER_DSN=groundmail+api://gm_your_key_here@default
  1. Clear the cache (bin/console cache:clear), then go to Settings, System, Mailer and choose Use environment's configuration.

Use a Send only API key here. See Symfony Mailer for the transport's headers and options.

Match the sender

Every option needs the sender on your verified domain. With the admin SMTP option, that's Sender address. Otherwise Shopware sends from the shop's email address under Settings, Shop, Basic information. Set it to an address on your verified domain.

Test it

Groundmail's simulator addresses never reach a real inbox. Register a customer, or place a test order in the storefront, with the email:

delivered@simulator.groundmail.dev

Then confirm in Groundmail: open Emails in the dashboard, or run:

Terminal
curl "https://api.groundmail.dev/emails?limit=5" \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY"

The email appears with the status delivered and "test": true. Use bounce@simulator.groundmail.dev to see a hard bounce. The full list is in Testing.

Shopware sends some emails from its message queue, so make sure the message consumer (or the admin worker) is running.

Troubleshooting

MAILER_DSN is ignored. Check Preferred email agent is Use environment's configuration, and clear the cache after changing .env.local.

The "groundmail+api" scheme is not supported. The factory isn't registered. Check step 2 of Option 3 and clear the cache.

Authentication failed. Over SMTP, the username must be exactly groundmail and the password must be the SMTP credential (gmsmtp_…), not an API key. Over the API, the DSN needs an API key (gm_…).

Connection timed out or refused. Check the host is smtp.groundmail.dev and the port is 587. If your host blocks outbound port 587, use 2525, or switch to the API (Option 3).

The message is rejected because of the From address. The sender must use a verified domain on your account. Until then you can only send from the sandbox sender, and only to your own account email.

A recipient never receives the email. The address may be on your suppression list, usually after a hard bounce. See Suppressions, and create a webhook for email.bounced to get notified.

Sends are deferred. A new account has a daily ramp-up limit, and the Free plan has a daily limit. See Sending limits.

Was this page helpful?