Novu email with Groundmail

Send Novu email notifications through Groundmail with Novu's Custom SMTP provider. You add the provider in the Novu dashboard with the Groundmail SMTP settings, and Novu sends your workflow emails through it.

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.
• A Novu account with a workflow that has an email step.

1. Add the Custom SMTP provider in Novu

1. In the Novu dashboard, open the Integrations page and select Add a provider.
2. Select Custom SMTP.
3. Fill in the fields:

4. Leave Ignore TLS off. Leave the DKIM fields empty: Groundmail signs your mail with your domain's DKIM key once the domain is verified.
5. Switch the integration from Disabled to Active, then select Update.

Novu's documentation says port 587 requires Secure off and uses STARTTLS, and that Require TLS makes the send fail if STARTTLS is not offered. Groundmail offers STARTTLS on port 587.

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.

2. Send a test

Trigger a workflow for a subscriber whose email is a Groundmail simulator address, so nothing reaches a real inbox:

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": {}
  }'

Then check 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 "test": true and the status delivered. Send to bounce@simulator.groundmail.dev to rehearse a hard bounce. All outcomes are in Testing.

3. Track delivery with webhooks

Novu hands the message to Groundmail over SMTP. Groundmail webhooks report what happens after that: delivered, delayed, bounced or marked as spam.

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"]
  }'

Each event includes the recipient (data.to), the subject and the Groundmail email id (data.email_id). Verify the Groundmail-Signature header on every request; the Knock guide has a complete handler, and Webhooks lists every event.

Troubleshooting

Novu cannot authenticate. Novu only authenticates when both User and Password are set. Use the username groundmail and the SMTP credential (gmsmtp_…) as the password, not an API key (gm_…).

The send fails with a TLS error. Keep Secure off for port 587; Secure is for port 465, and the Groundmail relay uses 587. Keep certificate checks enabled in TLS options.

The message is refused because of the From address. The domain in From email address must be a verified domain on your account. Until then you can only test 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. List suppressions with GET /suppressions (needs a full-access API key) and see Suppressions.

Related

• SMTP relay
• Webhooks
• Testing
• Knock and Courier