Use Groundmail with any tool that has SMTP settings

Notification platforms, CMS plugins and auth providers often send email through an SMTP form: a host, a port, a username and a password. Fill that form with the values below and the tool sends through Groundmail. Your templates and routing in the tool keep working.

This page covers the settings every tool needs, then the details for Knock, Courier and Novu. For WordPress and WooCommerce, see WordPress.

Before you start

• A verified sending domain.
• An SMTP credential: in the dashboard, open SMTP and choose Create SMTP credential. The password (gmsmtp_…) is shown once, so copy it. See SMTP relay.

The values

What the fields are called

Tools label the same settings differently. Here is how to read them:

The From address

The From address must be on a verified domain on your account, or the message is refused. Until your domain is verified you can only test from the sandbox sender, and only to your own account email. If the tool or another plugin can override the sender, set it to the same address so they don't disagree.

Test it

Groundmail's simulator addresses work over SMTP and never reach a real inbox. Send from the tool to:

delivered@simulator.groundmail.dev

Then check Groundmail: open Emails in the dashboard, or list recent sends.

curl "https://api.groundmail.dev/emails?limit=5" \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY"

The email appears with "test": true and the status delivered. Send to bounce@simulator.groundmail.dev to rehearse a hard bounce. The full list is in Testing.

Get delivery status with webhooks

SMTP only tells the tool that Groundmail accepted the message. Most tools can't show what happened after that, so they stop at "sent". Groundmail knows whether the message was delivered, delayed, bounced or marked as spam, and reports it with webhooks:

curl -X POST https://api.groundmail.dev/webhooks \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/groundmail",
    "events": ["email.delivered", "email.delivery_delayed", "email.bounced", "email.complained"]
  }'

Copy the secret from the response (it is returned once) and verify each request with the Node SDK:

import express from 'express'
import { verifyWebhookSignature } from 'groundmail'

const app = express()

app.post('/webhooks/groundmail', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8')
  const ok = verifyWebhookSignature(
    process.env.GROUNDMAIL_WEBHOOK_SECRET,
    rawBody,
    req.get('groundmail-signature'),
  )
  if (!ok) return res.sendStatus(400)

  const event = JSON.parse(rawBody)
  if (event.data.test) return res.sendStatus(200) // simulated mail

  // event.type is e.g. "email.bounced"; event.data has to, subject, status
  console.log(event.type, event.data.to, event.data.subject)
  res.sendStatus(200)
})

Each event carries the recipient (data.to), the subject and the Groundmail email id (data.email_id). Match events to your own records by recipient and subject, or look up one email with GET /emails/{id}. Hard bounces are added to your suppression list automatically.

Knock

Add an SMTP Relay channel in Knock:

1. In the Knock dashboard, open account settings and go to Channels and sources.
2. Create a new SMTP Relay channel.
3. Under Environment configurations, open the environment you want to configure and enter the host, username, password, port 587 and a From email address on your verified domain.
4. Leave SSL off (under Advanced).
5. Click Save changes.

Knock configures each environment separately, so repeat this for each environment that should send through Groundmail (development and production, for example). Then select the channel in your workflow's email step.

Knock can't track delivery on SMTP Relay channels, so every message shows as "Sent" in the Knock messages log and never "Delivered". That is expected. Use the webhooks above for delivery status.

Courier

Open the SMTP integration in the Courier app (Integrations catalog, then SMTP), fill in the host, username, password and a From Address on your verified domain, and save.

Courier's dashboard lists only those four fields, so confirm the integration uses port 587 with STARTTLS. Courier describes this as the transport settings port: 587 and requireTLS: true. If you can't set the port, Courier supports a per-message override on message.providers.smtp.override.config in your Send API call:

{
  "message": {
    "providers": {
      "smtp": {
        "override": {
          "config": { "port": 587, "requireTLS": true }
        }
      }
    }
  }
}

To test, send to a simulator address through Courier's Send API:

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "email": "delivered@simulator.groundmail.dev" },
      "content": {
        "title": "Groundmail test",
        "body": "If you can see this in Groundmail, the SMTP integration works."
      },
      "routing": { "method": "single", "channels": ["email"] }
    }
  }'

Courier checks the SMTP connection before each send and does not send the message if the check fails. If that happens, re-enter the username and password, then confirm port 587 with STARTTLS.

Novu

1. In the Novu dashboard, open Integrations and select Add a provider, then Custom SMTP.
2. Enter the host (hostname only), port 587, User groundmail, the password, a From email address on your verified domain, and a Sender name.
3. Set Secure off and Require TLS on. Leave Ignore TLS off and the DKIM fields empty.
4. Switch the integration from Disabled to Active, then select Update.

Novu only authenticates when both User and Password are set. With Secure on, port 587 fails with a TLS error, because Secure is for port 465. Keep certificate checks enabled in TLS options.

To test, trigger a workflow for a subscriber whose email is a simulator address:

curl -X POST https://api.novu.co/v1/events/trigger \
  -H "Authorization: ApiKey $NOVU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "your-workflow-identifier",
    "to": {
      "subscriberId": "test-subscriber-1",
      "email": "delivered@simulator.groundmail.dev"
    },
    "payload": {}
  }'

If you have several email integrations, Novu lets you force one for a trigger. Novu documents overrides.email as deprecated, so check Novu's current API reference for how to select an integration.

Troubleshooting

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

The connection fails, times out or reports a TLS error. Check the port is 587 (or 2525) and that SSL or Secure is off. Some hosts block outgoing port 587; try 2525.

The message is refused because of the From address. The domain must be a verified domain on your account.

A recipient never gets the email and the send shows as suppressed. The address is on your suppression list, usually after a hard bounce. List suppressions with GET /suppressions (needs a full-access API key) and remove the address if it is safe to mail. See Suppressions.

Mail is deferred or refused because of a limit. New accounts ramp up their daily volume, and the Free plan has a daily limit. Mail over the limit is deferred or refused with a reply that says which limit applied. See Sending limits.

Related

• SMTP relay
• WordPress and WooCommerce
• Webhooks
• Testing
• Errors