Magento Open Source and Adobe Commerce 2.4.6 and later have SMTP settings in the admin. On older versions, or if you already use an SMTP extension (such as the Mageplaza or MagePal SMTP modules), enter the same host, port, username and password in that extension's settings.
Prerequisites
- A Groundmail account with a verified sending domain.
- 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. - Admin access to Magento, with permission to change Stores configuration.
Everything the store sends through the relay goes out as transactional email, so use it for order, account and notification email. Send opt-in newsletters through the API with category: "newsletter" once your account is approved, and never send cold email.
Set the SMTP transport
- In the Magento admin, go to Stores, then Settings, then Configuration.
- Open Advanced, then System, and expand Mail Sending Settings.
- Set Disable Email Communications to No, then fill in:
| Magento field | Value |
|---|---|
| Transport | SMTP |
| Host | smtp.groundmail.dev |
| Port | 587 |
| Username | groundmail |
| Password | Your SMTP credential (gmsmtp_…) |
| Auth | LOGIN |
| SSL | TLS |
- Leave Set Return-Path on No, and click Save Config.
SSL set to TLS upgrades the connection on port 587 with STARTTLS, which is what the relay expects. Don't choose SSL or port 465. If you configure from the command line, store the password with bin/magento config:set or in app/etc/env.php rather than in version control.
Match the sender
Go to Stores, Settings, Configuration, General, Store Email Addresses. Magento has five sender identities (General Contact, Sales Representative, Customer Support, Custom Email 1 and 2). Set Sender Email on each one your store uses to an address on your verified domain, such as orders@yourdomain.com. Order emails use the identity chosen in Stores, Configuration, Sales, Sales Emails (for example New Order Confirmation Email Sender).
Asynchronous sending
If Sales Emails, General Settings, Asynchronous sending is enabled, Magento sends order, invoice, shipment and credit memo emails from cron jobs. Make sure Magento's cron is running, or those emails wait in the queue.
Test it
Magento has no test button for the SMTP settings, so send a real store email to one of Groundmail's simulator addresses. They work over SMTP and never reach a real inbox.
- Place a test order on the storefront with the email
delivered@simulator.groundmail.dev. - Or open an existing test order in the admin under Sales, Orders, and click Send Email to resend its confirmation.
Then confirm in Groundmail: open Emails in the dashboard, or run:
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. Send errors are written to var/log/exception.log and var/log/system.log.
Troubleshooting
Nothing arrives and nothing is logged. Check Disable Email Communications is No, the specific email is Enabled under Sales Emails, and, with asynchronous sending on, that cron is running.
Authentication failed. The username must be exactly groundmail, and the password must be the SMTP credential (gmsmtp_…), not an API key (gm_…).
Connection timed out or the TLS handshake fails. Check the host is smtp.groundmail.dev, the port is 587 and SSL is TLS. If your host blocks outbound port 587, use 2525 with the same settings.
The message is rejected because of the From address. Every sender identity your store uses must be on 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. The relay replies with a temporary error and a retry time. See Sending limits.