Webhooks

Webhooks are an advanced feature that allows us to notify your own web service whenever an event happens in your SMTP2GO account (for emails or SMS messages). For example, you can choose for your own server to be instantly notified whenever an email bounce occurs.

The setup and management of webhooks are handled on the "Settings > Webhooks" page in your SMTP2GO account or via the API.

When a particular event listed for the webhook happens, our server will contact your server and provide details of the event. The webhook output can be JSON or Form encoded.

Accounts on the free plan are limited to 1 webhook and accounts on paid plans can create up to 10.

Add a Webhook (in the App)

To add a webhook, on the "Settings > Webhooks > Manage Webhooks" section click the "Add Webhook" button on the right side of the page.

On the "Add Webhook > Settings" section, enter and select the webhook's details including:

URL - Enter the URL where the data will be POSTed to.
Authorization header - Optionally include a bearer or basic authorization header.
Users - Select the users the Webhook will trigger for (these are your SMTP Users, API Keys or Authenticated IPs (IP Authentication).
Output type - Select the output type of either JSON or Form encoded.
Email events to include - Select the email events you'd like the webhooks to trigger for.
Email headers - Enter any custom email headers you would specifically like sent in the event data.
SMS events to include - Select the SMS events you'd like the webhooks to trigger for.

Click "Save changes" to save the Webhook and optionally click the "Test this webhook" button to test the webhook for your selected events.

The "Failed Notifications" section on the Webhooks page will allow you to view, retry, and cancel any failed notification attempts.

Standard Reported Data - Email

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. It is also encountered if sending is attempted from an unverified sender.

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 display name (where available) and email address the email was sent from.

from_address

The email address the email was sent from.

from_name

The display name set to accompany the email address (where available).

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.
message: The received error message or response from the recipient server.
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.
id: The unique id for the webhook.
message-id: The unique id from the sender.
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 (only available with Open Tracking enabled).
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 two character continent code based on a geoip lookup of the IP address associated with the open/click event (where available).
geoip-country: A two 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).

Standard Reported Data - SMS

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

event: What happened: "sms_submitted", "sms_delivered", "sms_rejected", "sms_sending", or "sms_failed".
destination_number: The number the SMS is being sent to.

email_subject: The subject of the email (if email to SMS).
id: The unique id for the webhook.
message_content: The body content of the SMS message.

message_id: The unique id for the SMS.

received_timestamp: UTC timestamp of the event.
region: The destination based on the number's country code.
retry_count: The number of attempts to send the SMS.
sender_email: The From email address.
source_number: The pool/number the SMS was delivered from.
status_code: The status code of the SMS.
submitted_timestamp: UTC timestamp of when the sms was submitted to the downstream provider.

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 in the settings section.

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 "Email headers" field:

Webhook Retries

A failing webhook will retry up to a maximum of 35 times over 48 hours at the following intervals:

0-5 times > once every 6 minutes.
6-29 times > once every 1 hour.
30-33 times > once every 6 hours.
34 > 12 hours later.
Finally, 35 is 24 hours later.

If all retries fail it will delete after 48 hours (you can retry the webhook before that point which will reset the retry counter to 0 starting the retry process again).

Notes

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.