Knock email with Groundmail

Send Knock email notifications through Groundmail by adding an SMTP Relay channel in Knock, and get real delivery and bounce events from Groundmail webhooks, because Knock cannot track delivery on SMTP channels.

Knock's documentation says SMTP Relay channels can't track deliverability, so every email sent over one shows as "Sent" in the Knock messages log and never "Delivered". Groundmail knows what happened after the hand-off, so use its webhooks for delivered, delayed, bounced and complained.

Prerequisites

• A Groundmail account with 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.
• A Knock account with at least one workflow that has an email step.

1. Add the 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:

4. Leave SSL off (under Advanced). Port 587 starts unencrypted and upgrades the connection with STARTTLS, which is not the same as a connection that is encrypted from the first byte.
5. Click Save changes.

Knock configures each environment separately, so repeat the step for each environment that should send through Groundmail (development and production, for example).

Then select this channel in the email step of your workflow, the same way you would select any email channel.

2. Test it

Groundmail's simulator addresses work over SMTP and never reach a real inbox. In Knock, trigger a workflow for a recipient whose email is:

delivered@simulator.groundmail.dev

Then check the result in 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. In Knock the same message shows as "Sent". To rehearse a bounce, use bounce@simulator.groundmail.dev. The full list of outcomes is in Testing.

3. Get delivery events in your own code

Create a webhook endpoint for the events you care about:

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. See Webhooks for every event and the payload shapes.

Troubleshooting

Knock reports an authentication error. 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 or times out. Check that the port is 587 and that SSL is off.

Messages are rejected 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, which sends to your own account email.

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.

Knock still says "Sent". That is expected. Knock marks SMTP messages "Sent" and cannot update them. Use the webhooks above for delivery status.

Related

• SMTP relay
• Webhooks
• Testing
• Errors
• Courier and Novu