groundmail / craft-plugin
Send Craft CMS email through the Groundmail API
Package info
github.com/Groundmail/groundmail-craft
Type:craft-plugin
pkg:composer/groundmail/craft-plugin
Requires
- php: ^8.2
- craftcms/cms: ^5.0.0
- groundmail/symfony-mailer: ^0.8.4 || ^0.9
Requires (Dev)
- phpunit/phpunit: ^10.5 || ^11.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Groundmail for Craft CMS
Send Craft's email through the Groundmail API over HTTPS: account activation, password resets, Craft Commerce order email, form notifications and anything else your site sends with Craft's mailer.
Requirements
Craft CMS 5.0 or later and PHP 8.2 or later.
Installation
composer config repositories.groundmail-craft vcs https://github.com/Groundmail/groundmail-craft composer require groundmail/craft-plugin php craft plugin/install groundmail
Setup
-
In Groundmail, verify your sending domain and create an API key under API Keys. A send-only key is enough.
-
Add the key to your
.envfile:GROUNDMAIL_API_KEY=gm_your_key
-
In Craft, go to Settings > Email. Set System Email Address to an address on your verified domain.
-
Change Transport Type to Groundmail, and set API Key to
$GROUNDMAIL_API_KEY. Using the environment variable keeps the key out of your project config. -
Click Test to send a test email, then Save. To check the connection without emailing a real inbox, send the test to
delivered@simulator.groundmail.dev:php craft mailer/test --to=delivered@simulator.groundmail.dev
Email category
Groundmail sends transactional, product and newsletter email from separate IPs, so other mail never slows down your password resets. Email category sets the stream for the email Craft sends:
- Transactional (default): account email, password resets, order and form notifications.
- Product: email about your product to its users, such as onboarding tips. Recipients can opt out of product email and keep getting transactional email.
A single message can choose its own category with an X-Groundmail-Category header (transactional, product, or newsletter once your account is approved for newsletters) and add tags with X-Groundmail-Tag: name=value:
Craft::$app->getMailer()->compose() ->setTo($user->email) ->setSubject('Your order has shipped') ->setHtmlBody($html) ->addHeader('X-Groundmail-Tag', 'order=' . $order->number) ->send();
Groundmail sends email to people who asked for it. Newsletters need your account approved (email support@groundmail.dev) and an opt-in list. Don't use Groundmail for cold email or for purchased, rented or scraped lists.
What the plugin sends
Only to https://api.groundmail.dev: each email Craft sends (sender, recipients, subject, content, attachments, custom headers) with its category. See the terms and privacy policy.
Development
composer install vendor/bin/phpunit
tests/e2e/run.py runs the plugin in a real Craft site, against the Groundmail API or a local mock of it; see the top of that file.
Support
Open an issue or email support@groundmail.dev. Docs ยท Sign up free