GroundmailDocs

WordPress email with Groundmail

Send WordPress email through Groundmail by pointing an SMTP plugin at the Groundmail SMTP relay. This works with WP Mail SMTP and FluentSMTP, and covers password resets, comment notifications and anything else your site sends with wp_mail(). For store emails, see WooCommerce.

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 the WordPress site, with WP Mail SMTP or FluentSMTP installed.

Groundmail is for transactional mail. Use it for account, order and notification email, not for newsletters or cold email.

Option 1: WP Mail SMTP

  1. In WordPress, go to WP Mail SMTP, then Settings, and open the General tab.
  2. Set From Email to an address on your verified domain, for example wordpress@yourdomain.com, and check Force From Email so every message uses it. The from address must be on a verified domain.
  3. Set From Name to your site or brand name.
  4. Choose Other SMTP as the Mailer, then fill in:
WP Mail SMTP field Value
SMTP Host smtp.groundmail.dev
Encryption TLS
SMTP Port 587
Authentication On
SMTP Username groundmail
SMTP Password Your SMTP credential (gmsmtp_…)
  1. Click Save Settings.

WP Mail SMTP describes port 587 as the TLS option. That is the STARTTLS connection Groundmail expects. Don't choose SSL or port 465.

Option 2: FluentSMTP

  1. In WordPress, go to Settings, then FluentSMTP. If you already have a connection, open Settings and choose Add Another Connection.
  2. Select Other SMTP as the method.
  3. Under sender settings, set From Email to an address on your verified domain and set From Name.
  4. Under SMTP server settings, enter smtp.groundmail.dev as the host and 587 as the port, and choose STARTTLS (labelled TLS in most plugins) for encryption. Turn Authentication on, then enter groundmail as SMTP Username and your SMTP credential (gmsmtp_…) as SMTP Password.
  5. Click Save Connection Settings.

FluentSMTP's documentation for this method names the sender and authentication fields but not the host, port and encryption fields, so match those to the labels you see. FluentSMTP stores credentials encrypted in the database by default (Store Access Keys in DB), or reads them from constants in wp-config.php if you choose Access Keys in Config File.

Test it

Groundmail's simulator addresses work over SMTP and never reach a real inbox. In WP Mail SMTP, go to WP Mail SMTP, then Tools, and open the Email Test tab. Enter this in Send To and click Send Email:

delivered@simulator.groundmail.dev

WP Mail SMTP shows a success message when the server accepts the message. 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. Finally, send a test to your own address to check how it lands in a real inbox.

Troubleshooting

Authentication failed. The username must be exactly groundmail, and the password must be the SMTP credential (gmsmtp_…), not an API key (gm_…). Create a new credential in the dashboard under SMTP if you lost it.

Connection timed out or refused. Check the host is smtp.groundmail.dev, the port is 587 and encryption is TLS, not SSL. Some hosts block outgoing SMTP connections; ask your host to allow port 587 if the test fails to connect.

The message is rejected because of the From address. The From Email 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. Turn on Force From Email if another plugin overrides the sender.

A recipient never receives the email. The address may be on your suppression list, usually after a hard bounce. List suppressions with GET /suppressions (needs a full-access API key) and see Suppressions. To get notified about bounces, create a webhook.

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, and your site's SMTP client keeps trying. See Sending limits.