Webhooks

Webhooks are an advanced feature that allow us to notify your own web service whenever an event happens in your SMTP2GO account.

For example, you can choose for your own server to be instantly notified whenever a bounce occurs.

Setup of webhooks can be done on the "Settings > Webhooks" page in your SMTP2GO control panel.

When a particular event listed on that page happens, our server will contact your server and provide it with details of the event.

Standard Reported Data

The listed URL will receive an HTTP (or HTTPS) post request with the following parameters:

event

what happened: "processed", "delivered", "open", "click", "bounce", "spam", "unsubscribe", "resubscribe", or "reject".

An unsubscribe event happens if a recipient clicks on an unsubscribe link that you have inserted using the Unsubscribe Footer feature.
If a recipient decides to resubscribe (using the link shown to them on the unsubscribe confirmation page), a resubscribe event will occur.
A reject event happens if you attempt to send an email to a recipient that has previously hard-bounced, made a spam complaint, or unsubscribed.

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 )

Securing the URL

You can optionally secure the URL with a username/password, with formats such as the following.
The URLs given below are just examples.

https://USERNAME:PASSWORD@host.yourdomain.com/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

Securing Endpoint

Optionally, you can further secure your endpoint with our webhook delivery IP addresses by using the A record for webhooks.smtp2go.com). MXToolbox is a good resource for viewing the IP addresses.

Testing

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.

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 on the settings page.

any_custom_header: any custom header that is sent in your emails.

You can add multiple headers to be returned by pressing "Tab" in between each entry in the "Headers" field:

Each 'URL of web service' that you enter must follow the URI standard.
i.e.
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.

We send a POST (not a GET) request to your URL with the data
application/x-www-form-urlencoded in the body.