Event Webhook Reference
Security Features
We recommend securing the Event Webhook data using our Signed Event Webhook, OAuth 2.0, or both. For more information about Event Webhook security, see Getting Started with the Event Webhook Security Features.
Security features are not required for setup, but they are highly recommended for any use of the Event Webhook beyond initial testing.
Categories and Unique Arguments will be stored as a “Not PII” field and may be used for counting or other operations as SendGrid runs its systems. These fields generally cannot be redacted or removed. You should take care not to place PII in this field. SendGrid does not treat this data as PII, and its value may be visible to SendGrid employees, stored long-term, and may continue to be stored after you have left SendGrid’s platform.
Events
Events are generated when email is processed by SendGrid and email service providers. There are 2 types of events - delivery and engagement events. Delivery events indicate the status of email delivery to the recipient. Engagement events indicate how the recipient is interacting with the email.
Here is an event response that includes an example of each type of event:
[
{
"email": "example@test.com",
"timestamp": 1513299569,
"smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
"event": "processed",
"category": "cat facts",
"sg_event_id": "sg_event_id",
"sg_message_id": "sg_message_id"
},
{
"email": "example@test.com",
"timestamp": 1513299569,
"smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
"event": "deferred",
"ip": "168.1.1.1",
"category": "cat facts",
"sg_event_id": "sg_event_id",
"sg_message_id": "sg_message_id",
"response": "400 try again later",
"attempt": "5"
},
{
"email": "example@test.com",
"timestamp": 1513299569,
"smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
"event": "delivered",
"ip": "168.1.1.1",
"category": "cat facts",
"sg_event_id": "sg_event_id",
"sg_message_id": "sg_message_id",
"response": "250 OK"
},
{
"email": "example@test.com",
"timestamp": 1513299569,
"smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
"event": "open",
"sg_machine_open": false,
"category": "cat facts",
"sg_event_id": "sg_event_id",
"sg_message_id": "sg_message_id",
"useragent": "Mozilla/4.0 (compatible; MSIE 6.1; Windows XP; .NET CLR 1.1.4322; .NET CLR 2.0.50727)",
"ip": "255.255.255.255"
},
{
"email": "example@test.com",
"timestamp": 1513299569,
"smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
"event": "click",
"category": "cat facts",
"sg_event_id": "sg_event_id",
"sg_message_id": "sg_message_id",
"useragent": "Mozilla/4.0 (compatible; MSIE 6.1; Windows XP; .NET CLR 1.1.4322; .NET CLR 2.0.50727)",
"ip": "255.255.255.255",
"url": "http://www.sendgrid.com/"
},
{
"email": "example@test.com",
"timestamp": 1513299569,
"smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
"bounce_classification":"invalid",
"event": "bounce",
"ip": "168.1.1.1",
"category": "cat facts",
"sg_event_id": "sg_event_id",
"sg_message_id": "sg_message_id",
"reason": "500 unknown recipient",
"status": "5.0.0"
},
{
"email": "example@test.com",
"timestamp": 1513299569,
"smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
"event": "dropped",
"category": "cat facts",
"sg_event_id": "sg_event_id",
"sg_message_id": "sg_message_id",
"reason": "Bounced Address",
"status": "5.0.0"
},
{
"email": "example@test.com",
"timestamp": 1513299569,
"smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
"event": "spamreport",
"sg_event_id": "sg_event_id",
"sg_message_id": "sg_message_id"
},
{
"email": "example@test.com",
"timestamp": 1513299569,
"smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
"event": "unsubscribe",
"category": "cat facts",
"sg_event_id": "sg_event_id",
"sg_message_id": "sg_message_id"
},
{
"email": "example@test.com",
"timestamp": 1513299569,
"smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
"event": "group_unsubscribe",
"category": "cat facts",
"sg_event_id": "sg_event_id",
"sg_message_id": "sg_message_id",
"useragent": "Mozilla/4.0 (compatible; MSIE 6.1; Windows XP; .NET CLR 1.1.4322; .NET CLR 2.0.50727)",
"ip": "255.255.255.255",
"url": "http://www.sendgrid.com/",
"asm_group_id": 10
},
{
"email": "example@test.com",
"timestamp": 1513299569,
"smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
"event": "group_resubscribe",
"category": "cat facts",
"sg_event_id": "sg_event_id",
"sg_message_id": "sg_message_id",
"useragent": "Mozilla/4.0 (compatible; MSIE 6.1; Windows XP; .NET CLR 1.1.4322; .NET CLR 2.0.50727)",
"ip": "000.000.000.000",
"url": "http://www.sendgrid.com/",
"asm_group_id": 10
}
]
Delivery events
Delivery events include processed, dropped, delivered, deferred, and bounce.
Engagement events
Engagement events include open, click, spam report, unsubscribe, group unsubscribe, and group resubscribe.
Events such as deferrals and bounces may or may not have an IP included in their post. For example, an internal deferral occurs when we have already determined an issue at a specific MX record and are waiting for that issue to clear before trying to deliver more mail. Because no action is taken during an internal deferral, no IP can be logged taking an action. A delayed bounce occurs when mail is initially accepted for delivery but then rejected after the SMTP conversation is over. Because the SMTP conversation is no longer happening, a new conversation is started where much of the previous context is lost. This results in delayed bounces not having an IP and other information.
Event objects
| Processed | Dropped | Delivered | Deferred | Bounce | Opened | Clicked | Spam Report | Unsubscribe | Group Unsubscribe | Group Resubscribe | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| X | X | X | X | X | X | X | X | X | X | X | |
| timestamp | X | X | X | X | X | X | X | X | X | X | X |
| event | X | X | X | X | X | X | X | X | X | X | X |
| smtp-id | X | X | X | X | X | ||||||
| useragent | X | X | X | X | |||||||
| ip | X | X | X | X | X | X | X | ||||
| sg_event_id | X | X | X | X | X | X | X | X | X | X | X |
| sg_message_id | X | X | X | X | X* | X | X | X | X | X | X |
| reason | X | X | X | ||||||||
| status | X | ||||||||||
| response | X | ||||||||||
| tls | X | X | |||||||||
| url | X | ||||||||||
| category | X | X | X | X | X | X | X | X | X | ||
| asm_group_id | X | X | X | X | X | X | X | X | X | ||
| unique_args | X | X | X | X | X | X | X | X | X | X | X |
| marketing_campaign_id | X | X | X | X | X | X | X | X | X | X | X |
| marketing_campaign_name | X | X | X | X | X | X | X | X | X | X | X |
| attempt | X | ||||||||||
| pool | X | ||||||||||
| sg_machine_open | X | ||||||||||
| bounce_classification | X |
* In the case of a delayed or asynchronous bounce, the message ID will be unavailable.
JSON objects
email- the email address of the recipienttimestamp- the UNIX timestamp of when the message was sentevent- the event type. Possible values are processed, dropped, delivered, deferred, bounce, open, click, spam report, unsubscribe, group unsubscribe, and group resubscribe.smtp-id- a unique ID attached to the message by the originating system.useragent- the user agent responsible for the event. This is usually a web browser. For example, "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1500.95 Safari/537.36".ip- the IP address used to send the email. Foropenandclickevents, it is the IP address of the recipient who engaged with the email.sg_event_id- a unique ID to this event that you can use for deduplication purposes. These IDs are up to 100 characters long and are URL safe.sg_message_id- a unique, internal SendGrid ID for the message. The first half of this ID is pulled from thesmtp-id. The message ID will be included in most cases. In the event of an asynchronous bounce, the message ID will not be available. An asynchronous bounce occurs when a message is first accepted by the receiving mail server and then bounced at a later time. When this happens, there is less information available about the bounce.reason- any sort of error response returned by the receiving server that describes the reason this event type was triggered.status- status code string. Corresponds to HTTP status code - for example, a JSON response of 5.0.0 is the same as a 500 error response.response- the full text of the HTTP response error returned from the receiving server.tls- indicates whether TLS encryption was used in sending this message. For more information about TLS, see the TLS Glossary page.url- the URL where the event originates. For click events, this is the URL clicked on by the recipient.url_offset- Indicates the location of a link in the email's HTML code. Indices are set starting from top to bottom in the HTML, meaning the first link read from top to bottom will be at index 0. Theurl_offsetis provided so that you may identify a link when reviewing metrics such as clicks. For example, if the same link appears twice in your email, once in the intro copy and once at the bottom in a call to action, you can identify which link was clicked by its index. The first link, appearing earlier in the HTML, will have a lower index.
The indices are assigned consecutively and determined entirely by the link's location in the HTML and not by the link URL itself. For example, if the links in your email appear in the following order:example.com,example2.com,example.com,example3.com,example.com, each link will have an index relative to the links appearing before and after it regardless of the link URL. This means the indices forexample.comwill be 0, 2, and 4 in the previous example list. The index forexample2.comwill be 1, and the the index forexample3.comwill be 3.
| Link URL | Index |
|---|---|
| example.com | 0 |
| example2.com | 1 |
| example.com | 2 |
| example3.com | 3 |
| example.com | 4 |
attempt- the number of times SendGrid has attempted to deliver this message.category- Categories are custom tags that you set for the purpose of organizing your emails. If you send single categories as an array, they will be returned by the webhook as an array. If you send single categories as a string, they will be returned by the webhook as a string.type- indicates whether the bounce event was a hard bounce (type=bounce) or block (type=blocked)-
sg_machine_open- A new boolean field that indicates whether or not an open event has been generated by Apple Mail Privacy Protection (MPP). When this field is set totrue, it means that SendGrid has received signals indicating that a recipient with MPP enabled has triggered an open event. When this field isfalse, it indicates that the event was triggered by a conventional open. This field was added as a response to the anonymization of some open event tracking caused by Apple Mail Privacy Protection. -
bounce_classification- Twilio SendGrid conveniently buckets SMTP failure messages into classifications by mapping each unique response to one of seven groups: Invalid Address, Technical, Content, Reputation, Frequency/Volume, Mailbox Unavailable, or Unclassified. See our Bounce Classifications documentation to understand each classification.
String categories:
[
{
"email": "john.doe@sendgrid.com",
"timestamp": 1337966815,
"category": "newuser",
"event": "open"
},
{
"email": "jane.doe@sendgrid.com",
"timestamp": 1337966815,
"category": "olduser",
"event": "open"
}
]
Array:
[
{
"email": "john.doe@sendgrid.com",
"timestamp": 1337966815,
"category": ["newuser", "transactional"],
"event": "open"
},
{
"email": "jane.doe@sendgrid.com",
"timestamp": 1337966815,
"category": "olduser",
"event": "open"
}
]
asm_group_id- The ID of the unsubscribe group the recipient's email address is included in. ASM IDs correspond to the ID that is returned when you create an unsubscribe group.unique_argsorcustom_args
Unique Arguments and Custom Arguments
Events generated by SendGrid can include unique arguments or custom arguments.
Unique arguments and custom arguments essentially have the same function. However, unique arguments are used in the SMTP API or V2 Mail Send, and custom arguments are used in the V3 Mail Send.
Unique Arguments
To define and receive unique arguments when sending email with the SMTP API or the v2 Mail Send endpoint, use the unique_args parameter in the X-SMTPAPI header. For example, if you have an application and want to receive custom parameters such as the userid and the email template, you would submit them with the X-SMTPAPI header, as described here.
For example, if you include the following unique arguments in your x-smtpapi header for an email sent via the v2 Mail Send endpoint:
{
"unique_args": {
"userid": "1123",
"template": "welcome"
}
}
You will receive the same unique argument included with the data posted to your Event Webhook:
[
{
"sg_message_id": "sendgrid_internal_message_id",
"email": "john.doe@sendgrid.com",
"timestamp": 1337966815,
"event": "click",
"url": "https://sendgrid.com",
"userid": "1123",
"template": "welcome"
}
]
You can create unique arguments with the same words as reserved keys, such as "event" or "email". However, SendGrid will default to the reserved key and NOT your unique argument for events that contain a reserved key as an object. See the example below.
Reserved Keys in Unique Arguments
//for this example, assume we're sending to john.doe@sendgrid.com
{
"unique_args": {
"customerAccountNumber": "55555",
"activationAttempt": "1",
"New Argument 1": "New Value 1",
"email": "jane.doe@sendgrid.com",
"event": "SendEmail"
}
}
The resulting webhook call
[
{
"event": "Processed",
"timestamp": "123456789",
"customerAccountNumber": "55555",
"activationAttempt": "1",
"New Argument 1": "New Value 1",
"email": "john.doe@sendgrid.com"
}
]
You will notice that the unique arguments, "event" and "email", were overwritten because they are reserved keys for SendGrid's values.
Custom Arguments
Any custom arguments that you include with an email sent through v3 Mail Send gets added to your Event Webhook response.
For example, if you were to include the following custom arguments in a personalization in your payload to the v3 Mail Send endpoint:
{
"personalizations": [
{
"to": [
{
"email": "example@example.com"
}
],
"subject": "Hello, World!",
"custom_args": {
"userid": "1123"
}
}
],
"from": {
"email": "from_address@example.com"
},
"content": [
{
"type": "text/plain",
"value": "Hello, World!"
}
]
}
The Event Webhook response:
[
{
"userid": "1123"
}
]
For emails sent through our Marketing Campaigns feature, we add Marketing Campaigns specific parameters to the Event Webhook.
Example event from a Single Send:
[
{
"category": [],
"email": "email@example.com",
"event": "open",
"ip": "127.0.0.1",
"mc_stats": "singlesend",
"phase_id": "send",
"send_at": "1591726752372",
"sg_content_type": "html",
"sg_event_id": "sendgrid_internal_event_id",
"sg_message_id": "sendgrid_internal_message_id",
"sg_template_id": "sendgrid_template_id",
"sg_template_name": "sendgrid_template_name",
"singlesend_id": "sendgrid_singlesend_id",
"singlesend_name": "Example Single Send",
"template_hash": "sendgrid_template_hash",
"template_id": "sendgrid_template_id",
"template_version_id": "sendgrid_template_version_id",
"timestamp": 1591726752372,
"useragent": "Mozilla/4.0 (compatible; MSIE 6.1; Windows XP; .NET CLR 1.1.4322; .NET CLR 2.0.50727)"
}
]
Example event from a standard (non-A/B test) campaign send:
{
"category": [],
"email": "email@example.com",
"event": "processed",
"marketing_campaign_id": 12345,
"marketing_campaign_name": "campaign name",
"post_type": "event",
"sg_event_id": "sendgrid_internal_event_id",
"sg_message_id": "sendgrid_internal_message_id",
"sg_user_id": 12345,
"smtp-id": "",
"timestamp": 1442349428
}
Example event from an A/B Test:
marketing_campaign_version is displayed in the event data for emails sent as part of an A/B Test. The value for marketing_campaign_version are returned as A, B, C, etc.
{
"category": [],
"email": "tadpole_0010@stbase-018.sjc1.sendgrid.net",
"event": "processed",
"marketing_campaign_id": 23314,
"marketing_campaign_name": "unique args ab",
"marketing_campaign_version": "B",
"marketing_campaign_split_id": 13471,
"post_type": "event",
"sg_event_id": "qNOzbkTuTNCdxa1eXEpnXg",
"sg_message_id": "5lFl7Fr1Rjme_EyzNNB_5A.stfilter-015.5185.55F883172.0",
"sg_user_id": 939115,
"smtp-id": "<5lFl7Fr1Rjme_EyzNNB_5A@stismtpd-006.sjc1.sendgrid.net>",
"timestamp": 1442349848
}
Example event from the winning phase of an A/B Test:
{
"category": [],
"email": "tadpole_0001@stbase-018.sjc1.sendgrid.net",
"event": "delivered",
"marketing_campaign_id": 23314,
"marketing_campaign_name": "unique args ab",
"post_type": "event",
"response": "250 Ok ",
"sg_event_id": "X2M1IUfMRhuAhWM0CbmFqQ",
"sg_message_id": "fPJrJPIRTxC_obpgfTy74w.stfilter-015.5185.55F883564.0",
"sg_user_id": 12345,
"smtp-id": "",
"timestamp": 1442349911
}
Legacy Marketing Email Unsubscribes
For emails sent through our Legacy Marketing Email tool, unsubscribes look like the following example:
[
{
"email": "nick@sendgrid.com",
"timestamp": 1380822437,
"newsletter": {
"newsletter_user_list_id": "10557865",
"newsletter_id": "1943530",
"newsletter_send_id": "2308608"
},
"category": ["Tests", "Newsletter"],
"event": "unsubscribe"
}
]
Pool
pool - For emails sent with a specified IP Pool, you can view the IP Pool in the event data for a processed event.
[
{
"email": "john.doe@sendgrid.com",
"smtp-id": "<14c583da911.2c36.1c804d@ismtpd-073>",
"timestamp": 1427409578,
"pool": {
"name": "new_MY_test",
"id": 210
},
"sg_event_id": "RHFZB1IrTD2Y9Q7bUdZxUw",
"sg_message_id": "14c583da911.2c36.1c804d.filter-406.22375.55148AA99.0",
"event": "processed"
}
]
Click
| event | url | category | |
|---|---|---|---|
| click | Message recipient | URL Clicked | The category you assigned |
[
{
"sg_event_id": "sendgrid_internal_event_id",
"sg_message_id": "sendgrid_internal_message_id",
"ip": "255.255.255.255",
"useragent": "Mozilla/5.0 (iPhone; CPU iPhone OS 7_1_2 like Mac OS X) AppleWebKit/537.51.2 (KHTML, like Gecko) Version/7.0 Mobile/11D257 Safari/9537.53",
"event": "click",
"email": "email@example.com",
"timestamp": 1249948800,
"url": "http://yourdomain.com/blog/news.html",
"url_offset": {
"index": 0,
"type": "html"
},
"unique_arg_key": "unique_arg_value",
"category": ["category1", "category2"],
"newsletter": {
"newsletter_user_list_id": "10557865",
"newsletter_id": "1943530",
"newsletter_send_id": "2308608"
},
"asm_group_id": 1
}
]
Additional Resources
Need some help?
We all do sometimes. Get help now from the Twilio SendGrid Support Team.
Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.
