Let SendGrid, Mailgun, Postmark, Brevo or your own tool report delivered, bounced and spam events back into the CRM-NG SMTP email log.

Delivery webhooks let your mail service tell your site what happened to each email after it was sent: delivered, bounced, deferred, dropped or reported as spam. CRM-NG SMTP records the result on the matching log entry. This article explains the shared secret, the webhook address for each provider, and how events are matched. It is for administrators who want proof of delivery or a quick way to spot bounces.

How it works

1. You choose a shared secret in CRM-NG SMTP.
2. In your mail service, you add a webhook that points at your site and includes that secret.
3. Each time something happens to a message, the service sends an event to your site.
4. CRM-NG SMTP checks the secret, reads the event and updates the Delivery status of the matching log entry.

The email log must be on. See Setting up the email log.

Step 1: Set a shared secret

1. Open the Alerts tab

   Go to CRM-NG SMTP → Settings → Alerts and scroll to Delivery and Bounce Webhooks.

2. Choose a secret

   Make up a long random string, at least 32 letters and numbers, and type it into Shared secret. A password manager's generator works well.

3. Save

   Press Save Alert Settings. The box then shows Secret saved.

4. Keep a copy

   The secret is stored encrypted and not shown again. Keep it somewhere safe; you need it in the next step.

Step 2: Build the webhook address

The address is your site's home page with one query parameter that names the provider:

https://www.example.com/?crmng-smtp-local-delivery=<provider>

Use one of these provider values:

Provider	Value	Address
SendGrid	sendgrid	https://www.example.com/?crmng-smtp-local-delivery=sendgrid
Mailgun	mailgun	https://www.example.com/?crmng-smtp-local-delivery=mailgun
Postmark	postmark	https://www.example.com/?crmng-smtp-local-delivery=postmark
Brevo	brevo	https://www.example.com/?crmng-smtp-local-delivery=brevo
Anything else	generic	https://www.example.com/?crmng-smtp-local-delivery=generic

The Alerts tab shows the SendGrid version for your own site under the Shared secret box. Change the last word for other providers.

Step 3: Send the secret with each event

The help text reads: Send the secret in the X-CRMNG-SMTP-Webhook-Key header. A key query parameter is also accepted for providers that cannot set headers.

• If your provider lets you add custom headers: add a header named X-CRMNG-SMTP-Webhook-Key with your secret as its value. This is the safer choice, because headers do not appear in server logs.
• If it does not: add &key= and your secret to the end of the address, for example https://www.example.com/?crmng-smtp-local-delivery=mailgun&key=YOUR-SECRET.

Requests with a missing or wrong secret are refused with a "403 Forbidden" answer.

Step 4: Add the webhook at your provider

In your provider's dashboard, look for a page whose current name is similar to "Webhooks", "Event Webhook" or "Event notifications". Paste the address, add the secret as above, and choose which events to send. Pick delivery, bounce, deferral, drop and spam complaint events. Open and click events are ignored, because CRM-NG SMTP counts those itself. See Open and click tracking.

Most providers have a "send test" button. A successful test answers with a small JSON message such as {"success":true,"data":{"processed":1,"matched":0}}. matched is 0 for test events because their addresses were never logged.

Events CRM-NG SMTP records

Event name sent by the provider	Shown as
delivered, delivery	delivered
processed	processed
bounce, bounced, hard_bounce	bounced
deferred	deferred
dropped	dropped
spamreport, spamcomplaint, complaint	complained

Any other event name is skipped. Provider event names vary: for example, an event a provider calls "failed" or "soft_bounce" is not one of the names above and does not change the log.

The generic format

For your own tools, or a provider without a built-in format, send a POST with a JSON body like this to the generic address:

{ "email": "jane@example.com", "status": "delivered", "log_id": 0 }

status must be one of the event names in the table. log_id is optional; set it to a log entry's number if you know it.

How events are matched to log entries

The help text explains: Events without crmng_smtp_log_id are correlated to the latest log for the recipient. CRM-NG SMTP does not add a log ID to outgoing messages itself, so in practice events are matched by address: the newest logged email whose To list contains the recipient gets the update. CC and BCC recipients are not matched. Each new event replaces the previous value.

See the result by opening an entry on the Email Log tab and reading Delivery status. For what each value means, see Understanding delivery status.

Related

• Understanding delivery status
• Viewing the email log
• SendGrid
• Mailgun
• Postmark
• Brevo (formerly Sendinblue)