Webhooks Overview

Webhooks allow SMTP2GO to notify your web service via an HTTP or HTTPS POST request whenever an email event happens in your SMTP2GO 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.

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.

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 Webhooks 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.