groundmail / module-magento2
Groundmail for Magento 2 and Adobe Commerce: send every store email through the Groundmail email API
Package info
github.com/Groundmail/groundmail-magento2
Type:magento2-module
pkg:composer/groundmail/module-magento2
Requires
- php: ~8.1.0||~8.2.0||~8.3.0||~8.4.0
- ext-json: *
- magento/framework: ^103.0.6
- magento/module-backend: ^102.0.6
- magento/module-config: ^101.2.6
- magento/module-email: ^101.1.6
- magento/module-store: ^101.1.6
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
The official Groundmail module for Magento Open Source, Mage-OS and Adobe Commerce 2.4.6 and later. It sends every email your store sends through the Groundmail email API over HTTPS, from your own domain:
- Order, invoice, shipment and credit memo emails, including asynchronous sending from cron
- New account, password reset and other customer account emails
- Contact form, wishlist sharing, newsletter and admin notification emails
- HTML and plain text, CC, BCC, Reply-To and custom headers
- Attachments and inline images, such as invoice PDFs added by other modules
- API key stored encrypted, optional sender override and category, and a test email button
Switched off, or without an API key, the module does nothing and Magento sends email the way it did before. Disable Email Communications still stops all email.
Requires Magento Open Source, Mage-OS or Adobe Commerce 2.4.6 or later, and PHP 8.1 to 8.4. Licensed MIT.
Install
With Composer, from your Magento root:
composer require groundmail/module-magento2 bin/magento module:enable Groundmail_Mail bin/magento setup:upgrade bin/magento cache:flush
In production mode, also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy.
Set up
- In Groundmail, verify your sending domain and create an API key under API Keys. A send-only key is enough.
- In the Magento admin, open Stores > Configuration > Advanced > Groundmail.
- Set Send Email Through Groundmail to Yes, paste the API key and click Save Config.
- Under Test Email, click Send Test Email.
delivered@simulator.groundmail.devchecks the connection without emailing a real inbox.
Every sender your store uses must be on your verified domain. Set them under Stores > Configuration > General > Store Email Addresses, or fill in Sender Email to send every email from one address. With a sender override, an email that had its own From (the contact form puts the customer's address there) and no Reply-To keeps that address as its Reply-To, so replies still reach the customer.
All settings can be set per website or store view. From the command line (the key is encrypted either way; --lock-env keeps it in app/etc/env.php instead of the database):
bin/magento config:set groundmail/general/enabled 1 bin/magento config:set --lock-env groundmail/general/api_key gm_your_key
Settings
| Setting | What it does |
|---|---|
| Send Email Through Groundmail | Sends store email through Groundmail. No sends it the way Magento did before. |
| API Key | Your Groundmail API key (gm_…), stored encrypted. |
| Category | Not set sends as transactional, Groundmail's default. Product sends lifecycle and notification email on its own stream, with category opt-out and managed unsubscribe. |
| Log Every Send | Writes the email id (msg_…), subject and recipients of each send to var/log/system.log. Failed sends are always written to the log. |
| Sender Email, Sender Name | Optional. Replace the From of every email. |
| Send To, Send Test Email | Sends a test email with the saved settings of the scope you are viewing. |
When a send fails
If Groundmail doesn't accept an email (an unverified sender, a suspended key, the API out of reach), the module raises the same mail error Magento's own transport does and writes the reason to var/log/system.log. Magento then handles it as it always does: with asynchronous sending on, the order email is retried on the next cron run. Recipients Groundmail holds back while sending to the rest (suppressed after a hard bounce, for example) are logged as a warning.
What the module sends
Only to https://api.groundmail.dev, and only once it's switched on with an API key: each email (sender, recipients, subject, content, attachments, custom headers) to POST /emails, and the test email when you click the button. See the terms and privacy policy.
Support
Docs · support@groundmail.dev · Issues
Development
cd Test composer install composer test # unit tests, no Magento install needed cd .. bin/build-zip.sh # dist/groundmail-module-magento2-<version>.zip for the Adobe Commerce Marketplace