Webhooks Overview
Webhooks allow SMTP2GO to notify your web service via an HTTP or HTTPS POST request whenever an email event happens in your account. For example, you can choose to be instantly notified if an email bounces, when an open occurs or if a spam complaint is recorded.
Slack
If your notification needs are simple, consider using our Slack integration instead.
The setup of Webhooks is handled on the "Settings > Webhooks" page in the SMTP2GO App or via the API.
View the Setup a Webhook page for the steps involved.
Webhooks can be set for selected SMTP Users, API Keys or Authenticated IPs.
Webhook Events
The events you can select to be notified of include:
| Event | Description |
|---|---|
| Processed | The email was received by our incoming servers and is being processed for delivery. If multiple delivery attempts are occurring and not yet successful, the email will remain in the Processed status. |
| Delivered | The email was successfully delivered to the recipient and this is confirmed when the recipient server provides a “250” response. |
| Open | The email was opened by the recipient. A new open event can be triggered each time the recipient opens the email. For full details regarding open tracking and its limitations, view our open tracking article. |
| Click | The recipient clicked a tracked link in the email. A new click event can be triggered each time the recipient clicks on a link. |
| Bounce | The email was bounced by the recipient server when delivery was attempted. Bounces are classified as Soft or Hard depending on the response from the recipient server. |
| Spam | The recipient marked an email as spam or manually moved it to their spam folder. When this occurs, it triggers a spam complaint and the recipient email address is indefinitely added to your Suppressions page. The address can be managed on the “Reports > Suppressions” page in the App or via the API. If delivery is attempted to a suppressed address, it will be rejected. |
| Unsubscribe | A recipient unsubscribed from receiving your emails using the Unsubscribe Footer. When this occurs, the address will be indefinitely added to your account’s Suppressions page. It can be managed on the “Reports > Suppressions” page in the App or via the API. If delivery is attempted to a suppressed address, it will be rejected. |
| Resubscribe | A recipient went to the unsubscribe link they previously unsubscribed via and resubscribed or the address has been removed from the Suppressions page. |
| Reject | An email will be rejected if you attempt to send it to an address that is listed on the account’s "Reports > Suppressions" page or if sending is attempted from an unverified sender, or the SMTP User/Authenticated IP/API Key status is set to Sandboxed. |
Webhook Parameters
The Webhook URL will receive an HTTP or HTTPS POST request with the following parameters:
| Parameter | Description |
|---|---|
| event | What happened: "processed", "delivered", "open", "click", "bounce", "spam", "unsubscribe", "resubscribe", or "reject". |
| time | UTC timestamp of when the event happened. |
| sendtime | UTC timestamp of when the email was sent to our server. |
| sender | The 'envelope-from' email address. |
| from | The email address the email was sent from. |
| rcpt | The email address the email was addressed to. |
| recipients | The email addresses the email was sent to. |
| auth | The SMTP Username, API Key or IP Address used to send the email. |
| host | The recipient server that bounced the message (bounce only). |
| message | The error message we got (where available). |
| context | Contains additional information on the event (where available). |
| email_id | An identifier that uniquely identifies the email, which can be used to retrieve further details of the email delivery. |
| bounce | This parameter will be included for a bounce event, and will be either hard or soft, depending on how we classify the bounce type. |
| subject | The subject of the email. |
| user-agent | The "User-Agent" header of the device that opened the email (where applicable) |
| read-secs | The number of seconds an email was open - in five second increments up to a maximum of 30 (where applicable). |
| client | The reported client that clicked/opened the link (based on the User-Agent). |
| client-device | The reported device type of the User-Agent associated with the open/click event (where available). |
| client-os | The reported device operating system of the User-Agent associated with the open/click event (where available). |
| geoip-continent | A 2 character continent code based on a geoip lookup of the IP address associated with the open/click event (where available). |
| geoip-country | A 2 character country code based on a geoip lookup of the IP address associated with the open/click event (where available). |
| geoip-city | The name of the city based on a geoip lookup of the IP address associated with the open/click event (where available). |
| srchost | The IP address of the end-user associated with an open/click event (where available) or the IP address that submitted the email (for processed events). |
Webhook Request
SMTP2GO sends a POST (not a GET) request to your URL with the data application/x-www-form-urlencoded in the body.
If you would prefer the webhook request in JSON, please contact our support team who can have that enabled for the particular webhook.
URL Format
Each 'URL of web service' that you enter must follow the URI standard.
E.g.
PROTOCOL "://" USER ":" PASSWORD "@" HOST "/" PATH "?" QUERY "#" FRAGMENT
with most parts of that being optional.
PROTOCOL can be either HTTP or HTTPS.
USER and PASSWORD are only required if you choose to password protect your web service.
Secure the URL
You can optionally secure your public URL with a username/password, with formats such as the following (the URLs given below are just examples):
https://USERNAME:[email protected]/webhook/smtp2go
https://host.yourdomain.com/webhook/smtp2go?p=PASSWORD
or simply make the name of the endpoint hard to guess:
https://host.yourdomain.com/webhook/smtp2go_PASSWORD
Secure the Endpoint
You can optionally further secure your endpoint with our webhook delivery IP addresses by using the A record for "webhooks.smtp2go.com".
Optional Email Headers
Custom email headers can optionally be reported along with the standard data above. You can specify the headers you wish to receive for the specific Webhook on the “Settings > Webhooks” page in the App or via the API.
any_custom_header
any custom header that is sent in your emails.
You can add multiple headers to be returned.
Webhook Retries and Timeout
Webhook failures will retry for up to 48 hours, a maximum of 35 times with the following timings:
- 5 times in the first 30 minutes
- Every hour for the next 24 hours
- Every 6 hours for the next 24 hours
- Every 12 hours for the next 24 hours
- Once final attempt after 24 hours
Failures can be seen in the App on the "Settings > Webhooks > Failed Notifications" section where you can view, retry, and cancel any failed notification attempts. You can delve into specific failures to see a summary, request data and all attempts.
The default timeout for a Webhook is 10 seconds. A timeout will occur if we do not receive any response headers in that timeframe.
Number of Webhooks
A maximum of 10 webhooks can be configured per account.
Testing Webhooks
A good way to start testing is to deploy a local version of RequestBin, which will let you see exactly what data we send to you. Another option to try is Beeceptor.
Updated 8 days ago