GroundmailDocs
Markdown

Sylius email with Groundmail

Send Sylius store email through Groundmail. Sylius sends with Symfony Mailer, so you connect it with one MAILER_DSN. Order and shipment confirmations, account registration and verification, password reset and contact requests then go out from your own domain. These steps are for Sylius projects that use Symfony Mailer, as Sylius-Standard 1.14 and 2.x do.

Updated Nov 14, 20263 min read

There are two ways to connect:

  • SMTP, with the Groundmail SMTP relay. 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.

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

Sylius-Standard ships with MAILER_DSN=null://null, which sends nothing. Set it in .env.local (or your host's environment):

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

On port 587 the smtp scheme upgrades the connection with STARTTLS, which is what the relay expects. If your password contains characters such as @, : or /, URL-encode them in the DSN.

Option 2: The API with groundmail/symfony-mailer

  1. Install the transport:
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

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

Set the sender

Sylius sends from no-reply@example.com until you change it, and that address will be refused. Set the sender to an address on your verified domain:

YAML
# config/packages/sylius_mailer.yaml
sylius_mailer:
  sender:
    name: Your Store
    address: orders@yourdomain.com

Clear the cache after changing .env.local or the config: bin/console cache:clear.

Test it

Groundmail's simulator addresses never reach a real inbox. Register a customer, or place a test order in the shop, 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.

If your project routes email through Symfony Messenger, the messenger consumer must be running for email to go out.

Troubleshooting

Nothing is sent and there's no error. Check MAILER_DSN isn't still null://null in the environment the app runs in, and clear the cache.

The "groundmail+api" scheme is not supported. The factory isn't registered. Check step 2 of Option 2 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 2).

The message is rejected because of the From address. The sylius_mailer 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?