Event Webhook Reference

(warning)

Secure Event Webhook data in production

To secure the Event Webhook data, use the Signed Event Webhook, OAuth 2.0, or both.

Twilio stores categories and unique arguments in a field that shouldn't include personally identifiable information (PII). Twilio might use these categories and arguments for counting or other operations as SendGrid runs its systems. You can't redact or remove these fields. Never place PII in this field. Twilio SendGrid doesn't treat this data as PII. Twilio employees could see these values. These values get stored long-term even if you leave the Twilio SendGrid platform.

To learn more about Event Webhook security, see Getting Started with the Event Webhook Security Features.

Events

When Twilio SendGrid and email service providers process email messages, these messages generate events that Twilio logs. Twilio tracks three types of events: delivery, engagement, and account.

Delivery events that indicate the status of email delivery to the recipient.
Engagement events that indicate how the recipient is interacting with the email.
Account change events that indicate changes and impacts to your account.

Delivery events

Delivery events cover messages that were bounced, delivered, deferred, dropped, or processed.

Expected properties for delivery events

The following table identifies the properties each delivery type returns:

Property	Bounce	Delivered	Deferred	Dropped	Processed
`asm_group_id`	X	X	X	X	X
`bounce_classification`	X
`attempt`			X
`category`	X	X	X	X	X
`email`	X	X	X	X	X
`event`	X	X	X	X	X
`ip`		X
`marketing_campaign_id`	X	X	X	X	X
`marketing_campaign_name`	X	X	X	X	X
`pool`					X
`reason`	X		X	X
`response`		X
`sg_event_id`	X	X	X	X	X
`sg_message_id`	X*	X	X	X	X
`smtp-id`	X	X	X	X	X
`status`	X
`timestamp`	X	X	X	X	X
`tls`	X	X
`unique_args`	X	X	X	X	X

* In the case of a delayed or asynchronous bounce, Twilio doesn't return the message ID.

Bounce and blocked events

Events can return two types of bounces: a bounce, a permanent delivery denial, or a block, a temporary delivery denial.

Bounce type of Bounce event

The receiving server doesn't accept mail sent to this recipient. Twilio refers to this Bounce event type as a hard bounce ("type": "bounce"). If a recipient unsubscribed from your emails, Twilio SendGrid drops the message.

Example bounced event webhook response

1[
2   {
3      "email": "alex@example.com",
4      "timestamp": 1513299569,
5      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
6      "bounce_classification": "Invalid Address",
7      "event": "bounce",
8      "category": "cat facts",
9      "sg_event_id": "6g4ZI7SA-xmRDv57GoPIPw==",
10      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
11      "reason": "500 unknown recipient",
12      "status": "5.0.0",
13      "type": "bounce"
14   }
15]

Blocked type of Bounce event

The receiving server can't accept the message at this time. Twilio refers to this Bounce event type as a soft bounce ("type": "blocked"). The receiving server might accept the blocked message at a later time.

Example webhook response for blocked events

1[
2   {
3      "email": "alex@example.com",
4      "timestamp": 1513299569,
5      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
6      "bounce_classification": "Invalid Address",
7      "event": "bounce",
8      "category": "cat facts",
9      "sg_event_id": "6g4ZI7SA-xmRDv57GoPIPw==",
10      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
11      "reason": "500 unknown recipient",
12      "status": "5.0.0",
13      "type": "blocked"
14   }
15]

Bounce classifications

The bounce_classification property accepts the following values:

To learn the details about these values, see Bounce and Block Classifications.

Delivered events

Twilio SendGrid succeeded in delivering the message to the receiving server.

Example delivered event webhook response

1[
2   {
3      "email": "alex@example.com",
4      "timestamp": 1513299569,
5      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
6      "event": "delivered",
7      "category": "cat facts",
8      "sg_event_id": "rWVYmVk90MjZJ9iohOBa3w==",
9      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
10      "response": "250 OK"
11   }
12]

Deferred events

The receiving server rejected the message temporarily.

Example deferred event webhook response

1[
2   {
3      "email": "alex@example.com",
4      "domain": "example.com",
5      "from": "test@example.com",
6      "timestamp": 1513299569,
7      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
8      "event": "deferred",
9      "category": "cat facts",
10      "sg_event_id": "t7LEShmowp86DTdUW8M-GQ==",
11      "sg_message_id": " 14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
12      "response": "400 try again later",
13      "attempt": "5"
14   }
15]

Dropped events

Twilio SendGrid dropped the message for one of the following reasons:

Invalid SMTPAPI header
Spam Content (if you turned on the Spam Checker app)
Unsubscribed Address
Bounced Address
Spam Reporting Address
Invalid Address
Recipient List over Package Quota

Example dropped event webhook response

1[
2  {
3      "email": "alex@example.com",
4      "timestamp": 1513299569,
5      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
6      "event": "dropped",
7      "category": "cat facts",
8      "sg_event_id": "zmzJhfJgAfUSOW80yEbPyw==",
9      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
10      "reason": "Bounced Address",
11      "status": "5.0.0"
12  }
13]

Processed events

Twilio SendGrid accepted and can deliver the message.

Example processed event webhook response

1[
2  {
3      "email": "alex@example.com",
4      "timestamp": 1513299569,
5      "pool": {
6            "name": "new_MY_test",
7            "id": 210
8      },
9      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
10      "event": "processed",
11      "category": "cat facts",
12      "sg_event_id": "rbtnWrG1DVDGGGFHFyun0A==",
13      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.000000000000000000000"
14  }
15]

Engagement events

Engagement events include open, click, spam report, unsubscribe, group unsubscribe, and group resubscribe.

Expected properties for engagement events

The following table identifies the properties each engagement event type returns:

Property	Opened	Clicked	Spam report	Unsubscribe	Group unsubscribe	Group resubscribe
`asm_group_id`	X	X			X	X
`category`	X	X	X	X
`email`	X	X	X	X	X	X
`event`	X	X	X	X	X	X
`ip`	X	X			X	X
`marketing_campaign_id`	X	X	X	X	X	X
`marketing_campaign_name`	X	X	X	X	X	X
`sg_event_id`	X	X	X	X	X	X
`sg_machine_open`	X
`sg_message_id`	X	X	X	X	X	X
`timestamp`	X	X	X	X	X	X
`url`		X
`url_offset`		X
`useragent`	X	X			X	X
`unique_args`	X	X	X	X	X	X

Click events

Recipient clicked on a link within the message. To track clicks, turn on Click Tracking.

Example webhook response for click events

1[
2  {
3    "sg_event_id": "sendgrid_internal_event_id",
4    "sg_message_id": "sendgrid_internal_message_id",
5    "ip": "255.255.255.255",
6    "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",
7    "event": "click",
8    "email": "email@example.com",
9    "timestamp": 1249948800,
10    "url": "http://example.com/blog/news.html",
11    "url_offset": {
12      "index": 0,
13      "type": "html"
14    },
15    "unique_arg_key": "unique_arg_value",
16    "category": ["category1", "category2"],
17    "newsletter": {
18      "newsletter_user_list_id": "10557865",
19      "newsletter_id": "1943530",
20      "newsletter_send_id": "2308608"
21    },
22    "asm_group_id": 1
23  }
24]

Open events

Recipient has opened the HTML message. To track opens, turn on Open Tracking.

Example webhook response for open events

1[
2   {
3      "email": "alex@example.com",
4      "timestamp": 1513299569,
5      "event": "open",
6      "sg_machine_open": false,
7      "category": "cat facts",
8      "sg_event_id": "FOTFFO0ecsBE-zxFXfs6WA==",
9      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
10      "useragent": "Mozilla/4.0 (compatible; MSIE 6.1; Windows XP; .NET CLR 1.1.4322; .NET CLR 2.0.50727)",
11      "ip": "255.255.255.255"
12   }
13]

Spam report events

Recipient marked message as spam.

Example webhook response for spam report events

1[
2   {
3      "email": "alex@example.com",
4      "timestamp": 1513299569,
5      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
6      "event": "spamreport",
7      "sg_event_id": "37nvH5QBz858KGVYCM4uOA==",
8      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0"
9   }
10]

Unsubscribe events

Recipient clicked on the Opt Out of All Emails link. To track subscriptions, turn on Subscription Tracking.

Example webhook response for unsubscribe events

1[
2   {
3      "email": "alex@example.com",
4      "timestamp": 1513299569,
5      "event": "unsubscribe",
6      "category": "cat facts",
7      "sg_event_id": "zz_BjPgU_5pS-J8vlfB1sg==",
8      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0"
9   }
10]

Group resubscribe events

Recipient resubscribed to a specific group by updating their preferences. To track subscriptions, turn on Subscription Tracking.

Example webhook response for group resubscribe events

1[
2   {
3      "email": "alex@example.com",
4      "timestamp": 1513299569,
5      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
6      "event": "group_resubscribe",
7      "category": "cat facts",
8      "sg_event_id": "w_u0vJhLT-OFfprar5N93g==",
9      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
10      "useragent": "Mozilla/4.0 (compatible; MSIE 6.1; Windows XP; .NET CLR 1.1.4322; .NET CLR 2.0.50727)",
11      "ip": "255.255.255.255",
12      "url": "http://www.example.com/",
13      "asm_group_id": 10
14   }
15]

Group unsubscribe events

Recipient unsubscribed from a specific group. The recipient clicked an unsubscribe link or updated their preferences. To track subscriptions, turn on Subscription Tracking.

Example webhook response for group unsubscribe events

1[
2   {
3      "email": "alex@example.com",
4      "timestamp": 1513299569,
5      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
6      "event": "group_unsubscribe",
7      "category": "cat facts",
8      "sg_event_id": "ahSCB7xYcXFb-hEaawsPRw==",
9      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
10      "useragent": "Mozilla/4.0 (compatible; MSIE 6.1; Windows XP; .NET CLR 1.1.4322; .NET CLR 2.0.50727)",
11      "ip": "255.255.255.255",
12      "url": "http://www.example.com/",
13      "asm_group_id": 10
14   }
15]

Account status change events

Your account status changed because of issues related to compliance with the Twilio SendGrid terms of service. This can happen when Twilio SendGrid identifies abnormal activity such as phishing, elevated spam rates, or other bad behavior.

Expected properties for account status change events

The following table identifies the properties each account status change event returns:

Property	Account status change
`event`	X
`sg_event_id`	X
`timestamp`	X
`type`	X

Example webhook response for account status change events

1[
2   {
3      "event":"account_status_change", 
4      "sg_event_id":"MjEzNTg5OTcyOC10ZXJtaW5hdGUtMTcwNzg1MTUzMQ",
5      "timestamp":1709142428,
6      "type":"compliance_suspend"
7   }
8]

To learn more about account statuses, see Account Under Review.

Property descriptions

Property	Type	Description
`asm_group_id`	String	Unique ID attached to the unsubscribe group. It includes the recipient's email address.
`attempt`	Integer	Number of times Twilio SendGrid attempted to deliver this message.
`bounce_classification`	String	Grouping of Simple Mail Transfer Protocol (SMTP) failure messages into classifications. Expects: Invalid Address, Technical, Content, Reputation, Frequency/Volume, Mailbox Unavailable, or Unclassified.
`category`	String	Custom tags set to organize your emails. If you send single categories as an array, the webhook returns them as an array. If you send single categories as a string, the webhook returns them as a string.
`email`	String	Email address to which Twilio SendGrid sent the message.
`event`	Enum(String)	Type of occurrence that triggered this event. Expects: `processed`, `dropped`, `delivered`, `deferred`, `bounce`, `open`, `click`, `spam report`, `unsubscribe`, `group_unsubscribe`, and `group_resubscribe`.
`ip`	String	IP address used to send the email. For open and click events, the IP address of the recipient who engaged with the email. Certain events don't return the IP address in the response.
`reason`	String	Error response that the receiving server returned. The response describes what occurrence triggered this event.
`response`	String	Full text of the HTTP response error returned from the receiving server.
`status`	String	Three digits, formatted as string `X.Y.Z`, that corresponds to HTTP status code `XYZ`.
`sg_event_id`	String	Unique ID that Twilio attached to this event. These URL-safe IDs can be no more than 100 characters long. Use this ID for deduplication purposes.
`sg_machine_open`	Boolean	Flag that indicates whether or not Apple Mail Privacy Protection (MPP) generated an open event.
`sg_message_id`	String	Unique ID that Twilio attached to this message.
`smtp-id`	String	Unique ID that the originating system attached to the message.
`timestamp`	String	Date and time when the event occurred, expressed as a UNIX timestamp.
`tls`	Boolean	Flag that indicates whether the message was sent with TLS encryption.
`type`	String	Defines the kind of bounce and account status change events.
`url`	String	URL where the event originates. For click events, this is the URL clicked on by the recipient.
`url_offset`	Integer	Zero-based index for the location of a link in the message's HTML code. Each duplicate URL has a unique index number.
`useragent`	String	User agent or program that generated the event.
`unique_args`	Object	SMTP API or v2 Mail Send use unique arguments.
`custom_args`	Object	v3 Mail Send uses custom arguments.

`asm_group_id` property

ID of the unsubscribe group that includes the recipient's email address. When you create an unsubscribe group, Advanced Suppression Management (ASM) Group IDs correspond to the ID returned.

`attempt` property

Number of times Twilio SendGrid attempted to deliver this message.

`bounce_classification` property

Grouping of SMTP failure messages into classifications. Expected values include Invalid Address, Technical, Content, Reputation, Frequency/Volume, Mailbox Unavailable, or Unclassified.

To learn more about these classifications, see Bounce and Block Classifications.

`category` property

To organize your emails, set these custom tags. If you send single categories as an array, the webhook returns them as an array. If you send single categories as a string, the webhook returns them as a string.

Category as string

1[
2  {
3    "email": "alex@example.com",
4    "timestamp": 1337966815,
5    "category": "newuser",
6    "event": "open"
7  },
8  {
9    "email": "bobby@example.com",
10    "timestamp": 1337966815,
11    "category": "olduser",
12    "event": "open"
13  }
14]

Category as array

1[
2  {
3    "email": "alex@example.com",
4    "timestamp": 1337966815,
5    "category": ["newuser", "transactional"],
6    "event": "open"
7  },
8  {
9    "email": "bobby@example.com",
10    "timestamp": 1337966815,
11    "category": "olduser",
12    "event": "open"
13  }
14]

`email` property

Email address to which Twilio SendGrid sent the message.

`event` property

Type of occurrence that triggered this event. This property expects: bounce, click, deferred, delivered, dropped, group_resubscribe, group_unsubscribe, open, processed, spam report, and unsubscribe

`ip` property

IP address used to send the email.

The open and click events return the IP address of the recipient who engaged with the email.
The bounce and deferral events don't return the IP address.
- During an internal deferral, Twilio takes no action. Without an action, Twilio logs no IP. When Twilio SendGrid determines an issue at a specific MX record, an internal deferral occurs. Before trying to deliver more mail, the service awaits the issue resolution.
- When Twilio accepts a message for delivery but rejects it after the SMTP conversation ends, a delayed bounce occurs. Without the SMTP conversation, another conversation starts without much of the previous context. Therefore, delayed bounces lack an IP address and other data.

`pool` property

If Twilio sends messages from a specified IP Pool, the webhook returns the IP Pool for a processed event.

1[
2  {
3    "email": "alex@example.com",
4    "smtp-id": "<14c583da911.2c36.1c804d@ismtpd-073>",
5    "timestamp": 1427409578,
6    "pool": {
7      "name": "new_MY_test",
8      "id": 210
9    },
10    "sg_event_id": "RHFZB1IrTD2Y9Q7bUdZxUw",
11    "sg_message_id": "14c583da911.2c36.1c804d.filter-406.22375.55148AA99.0",
12    "event": "processed"
13  }
14]

`reason` property

Error response that the receiving server returned. The response describes what occurrence triggered this event.

`response` property

Full text of the HTTP response error returned from the receiving server.

`sg_event_id` property

Unique ID that Twilio attached to this event. These URL-safe IDs can exceed 100 characters. Use this ID for deduplication purposes.

`sg_machine_open` property

Boolean flag that indicates whether or not Apple Mail Privacy Protection (MPP) generated an open event.

When set to true, indicates a recipient with MPP turned on triggered an open event.
When set to false, a conventional open triggered an open event. Twilio added this field as a response to Apple Mail Privacy Protection-anonymization of some open event tracking.

`sg_message_id` property

Unique ID that Twilio attached to this message. The first half of this ID comes from the smtp-id. The events include the message ID except in delayed or asynchronous bounces.

`smtp-id` property

Unique ID that the originating system attached to the message.

`status` property

Three digits, formatted as string X.Y.Z, that corresponds to HTTP status code XYZ.

`timestamp` property

Date and time when the event occurred, expressed as a UNIX timestamp.

`tls` property

Flag that indicates whether the message was sent with TLS encryption.

`type` property

Defines the kind of bounce and account status change event.

In a bounce event

Indicates the kind of the bounce event, either a hard bounce ("type": "bounce") or block ("type": "blocked").

In an account status change event

Kind of event that triggered a status change for a user for compliance reasons. When a user account changes to a particular status type, the actions that get triggered display in the following table.

Twilio SendGrid action based on `type`	`compliance_suspend`	`compliance_deactivate`	`compliance_ban`	`reactivate`
Blocks delivery of user messages	X	X	X
Queues messages, but bounces at delivery time	X
Rejects mail queues		X	X
Deletes queued messages		X	X
Bans user after 48 hours		X
Removes access to the Twilio SendGrid console			X
Cancels billing			X
Removes assigned IP addresses			X
Restores user account to active status				X

`url` property

URL where the event originates. For click events, the recipient clicked this URL.

`url_offset` property

Zero-index integer that identifies the order in which a URL occurs in the message's HTML code. The first link has an index value of 0. To help identify a link when reviewing metrics like clicks, Twilio provides the url_offset. This allows you to identify each instance of one link. The one closer to the top have a lower url_offset value. Twilio assigns the index based on the link location in the HTML and not based on the link URL.

(information)

How url_offset works

Consider when the links in your email occur in the following order: example.com, example.net, example.com, example.org, example.com. Each link has an index relative to the links appearing before and after it without regard to the link URL. This sets the index values for example.com to 0, 2, and 4. The index value for example.net gets set to 1 and the index value for example.org gets set to 3.

Link URL	Index value
`example.com`	0
`example.net`	1
`example.com`	2
`example.org`	3
`example.com`	4

`useragent` property

User agent or program that generated the event. The typical agent is a web browser.

For example:

Chrome on macOS: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36
Safari on macOS: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0.1 Safari/605.1.15

Unique argument and custom argument properties

The events that Twilio SendGrid generates can include unique arguments or custom arguments. Unique arguments and custom arguments serve the same function.

The SMTP API or v2 Mail Send resource uses unique arguments (unique_args).
The v3 Mail Send resource uses custom arguments (custom_args).

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: To receive custom parameters such as the userid and the email template, submit them with the X-SMTPAPI header.

(information)

Example of unique arguments in v2 Mail Send API call

If you include the following unique arguments in your X-SMTPAPI header for an email sent using the v2 Mail Send endpoint:

Example of unique arguments in the v2 Mail Send API call

1{
2  "unique_args": {
3    "userid": "1123",
4    "template": "welcome"
5  }
6}

You receive the same unique argument included with the data posted to your Event Webhook.

Example of unique arguments returned in Webhook

1[
2  {
3    "sg_message_id": "sendgrid_internal_message_id",
4    "email": "alex@example.com",
5    "timestamp": 1337966815,
6    "event": "click",
7    "url": "https://example.com",
8    "userid": "1123",
9    "template": "welcome"
10  }
11]

(warning)

Example of unique arguments using reserved keys

Though you can create unique arguments with the same words as reserved keys, Twilio SendGrid uses the reserved key value and not your unique argument value.

Reserved keys in unique arguments

1// for this example, assume we're sending to alex@example.com
2{
3  "unique_args": {
4    "customerAccountNumber": "55555",
5    "activationAttempt": "1",
6    "New Argument 1": "New Value 1",
7    "email": "alex@example.com",
8    "event": "SendEmail"
9  }
10}

Events webhook call with unique arguments

1[
2  {
3    "event": "Processed",
4    "timestamp": "123456789",
5    "customerAccountNumber": "55555",
6    "activationAttempt": "1",
7    "New Argument 1": "New Value 1",
8    "email": "alex@example.com"
9  }
10]

This overwrites the unique arguments, event and email, because they're reserved keys for Twilio SendGrid values.

Custom arguments

To define and receive custom arguments when sending email with the v3 Mail Send, use the custom_args parameter. These values get added to your Event Webhook response.

Example payload for the v3 Mail Send

1{
2  "personalizations": [
3    {
4      "to": [
5        {
6          "email": "alex@example.com"
7        }
8      ],
9      "subject": "Hello, World!",
10      "custom_args": {
11        "userid": "1123"
12      }
13    }
14  ],
15  "from": {
16    "email": "from_address@example.com"
17  },
18  "content": [
19    {
20      "type": "text/plain",
21      "value": "Hello, World!"
22    }
23  ]
24}

Event Webhook response

1[
2  {
3    "userid": "1123"
4  }
5]

Marketing Campaign parameters to the Event Webhook

For emails sent through Marketing Campaigns, add Marketing Campaigns specific parameters to the Event Webhook.

Single Send custom parameters

Single Send can include singlesend_id and singlesend_name. These parameters accept any string value you want to identify this message.

Example of Marketing Campaigns single send event

1[
2  {
3    "category": [],
4    "email": "alex@example.com",
5    "event": "open",
6    "ip": "127.0.0.1",
7    "mc_stats": "singlesend",
8    "phase_id": "send",
9    "send_at": "1591726752372",
10    "sg_content_type": "html",
11    "sg_event_id": "sendgrid_internal_event_id",
12    "sg_message_id": "sendgrid_internal_message_id",
13    "sg_template_id": "sendgrid_template_id",
14    "sg_template_name": "sendgrid_template_name",
15    "singlesend_id": "sendgrid_singlesend_id",
16    "singlesend_name": "Example Single Send",
17    "template_hash": "sendgrid_template_hash",
18    "template_id": "sendgrid_template_id",
19    "template_version_id": "sendgrid_template_version_id",
20    "timestamp": 1591726752372,
21    "useragent": "Mozilla/4.0 (compatible; MSIE 6.1; Windows XP; .NET CLR 1.1.4322; .NET CLR 2.0.50727)"
22  }
23]

Standard Marketing Campaign send custom properties

A Marketing Campaign send can include marketing_campaign_id and marketing_campaign_name. These parameters accept any string value you want to identify this campaign.

Example event from a standard (non-A/B test) campaign send

1{
2  "category": [],
3  "email": "alex@example.com",
4  "event": "processed",
5  "marketing_campaign_id": 12345,
6  "marketing_campaign_name": "campaign name",
7  "post_type": "event",
8  "sg_event_id": "sendgrid_internal_event_id",
9  "sg_message_id": "sendgrid_internal_message_id",
10  "sg_user_id": 12345,
11  "smtp-id": "",
12  "timestamp": 1442349428
13}

A/B test custom property

If you use an A/B test, you can use the marketing_campaign_version parameter. Its value returns a capital Latin character, starting with A, B, C, and so on.

Example event from an A/B Test

1{
2  "category": [],
3  "email": "tadpole_0010@stbase-018.sjc1.sendgrid.net",
4  "event": "processed",
5  "marketing_campaign_id": 23314,
6  "marketing_campaign_name": "unique args ab",
7  "marketing_campaign_version": "B",
8  "marketing_campaign_split_id": 13471,
9  "post_type": "event",
10  "sg_event_id": "qNOzbkTuTNCdxa1eXEpnXg",
11  "sg_message_id": "5lFl7Fr1Rjme_EyzNNB_5A.stfilter-015.5185.55F883172.0",
12  "sg_user_id": 939115,
13  "smtp-id": "<5lFl7Fr1Rjme_EyzNNB_5A@stismtpd-006.sjc1.sendgrid.net>",
14  "timestamp": 1442349848
15}

Example event response from the winning phase of an A/B Test

1{
2  "category": [],
3  "email": "tadpole_0001@stbase-018.sjc1.sendgrid.net",
4  "event": "delivered",
5  "marketing_campaign_id": 23314,
6  "marketing_campaign_name": "unique args ab",
7  "post_type": "event",
8  "response": "250 Ok",
9  "sg_event_id": "X2M1IUfMRhuAhWM0CbmFqQ",
10  "sg_message_id": "fPJrJPIRTxC_obpgfTy74w.stfilter-015.5185.55F883564.0",
11  "sg_user_id": 12345,
12  "smtp-id": "",
13  "timestamp": 1442349911
14}

Legacy Marketing email unsubscribes

For emails sent through the Twilio Legacy Marketing Email tool, unsubscribe webhook resembles the following example:

Example of Legacy Marketing unsubscribe

1[
2  {
3    "email": "nick@sendgrid.com",
4    "timestamp": 1380822437,
5    "newsletter": {
6      "newsletter_user_list_id": "10557865",
7      "newsletter_id": "1943530",
8      "newsletter_send_id": "2308608"
9    },
10    "category": ["Tests", "Newsletter"],
11    "event": "unsubscribe"
12  }
13]