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.

Processed

Message has been received and is ready to be delivered.

Example webhook response
[
  {
      "email": "example@test.com",
      "timestamp": 1513299569,
      "pool": {
            "name": "new_MY_test",
            "id": 210
      },
      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
      "event": "processed",
      "category": "cat facts",
      "sg_event_id": "rbtnWrG1DVDGGGFHFyun0A==",
      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.000000000000000000000"
  }
]

Dropped

You may see the following drop reasons: Invalid SMTPAPI header, Spam Content (if Spam Checker app is enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota

Example webhook response
[
  {
      "email": "example@test.com",
      "timestamp": 1513299569,
      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
      "event": "dropped",
      "category": "cat facts",
      "sg_event_id": "zmzJhfJgAfUSOW80yEbPyw==",
      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
      "reason": "Bounced Address",
      "status": "5.0.0"
  }
]

Delivered

Message has been successfully delivered to the receiving server.

Example webhook response
[
   {
      "email": "example@test.com",
      "timestamp": 1513299569,
      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
      "event": "delivered",
      "category": "cat facts",
      "sg_event_id": "rWVYmVk90MjZJ9iohOBa3w==",
      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
      "response": "250 OK"
   }
]

Deferred

Receiving server temporarily rejected the message.

Example webhook response
[
   {
      "email": "example@test.com",
      "timestamp": 1513299569,
      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
      "event": "deferred",
      "category": "cat facts",
      "sg_event_id": "t7LEShmowp86DTdUW8M-GQ==",
      "sg_message_id": " 14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
      "response": "400 try again later",
      "attempt": "5"
   }
]

Bounce

Receiving server could not or would not accept mail to this recipient permanently. If a recipient has previously unsubscribed from your emails, the message is dropped.

Example webhook response
[
   {
      "email": "example@test.com",
      "timestamp": 1513299569,
      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
      "bounce_classification": "invalid",
      "event": "bounce",
      "category": "cat facts",
      "sg_event_id": "6g4ZI7SA-xmRDv57GoPIPw==",
      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
      "reason": "500 unknown recipient",
      "status": "5.0.0",
      "type": "bounce"
   }
]

Blocked

Receiving server could not or would not accept the message temporarily. If a recipient has previously unsubscribed from your emails, the message is dropped.

Example webhook response
[
   {
      "email": "example@test.com",
      "timestamp": 1513299569,
      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
      "bounce_classification": "invalid",
      "event": "bounce",
      "category": "cat facts",
      "sg_event_id": "6g4ZI7SA-xmRDv57GoPIPw==",
      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
      "reason": "500 unknown recipient",
      "status": "5.0.0",
      "type": "blocked"
   }
]

NOTE: bounce_classification can have the following values: Content, Frequency or Volume Too High, Invalid Address, Mailbox Unavailable, Reputation, Technical Failure, Unclassified. Please see this reference for more information on each of these.

Engagement events

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

Open

Recipient has opened the HTML message. Open Tracking needs to be enabled for this type of event.

Example webhook response
[
   {
      "email": "example@test.com",
      "timestamp": 1513299569,
      "event": "open",
      "sg_machine_open": false,
      "category": "cat facts",
      "sg_event_id": "FOTFFO0ecsBE-zxFXfs6WA==",
      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
      "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"
   }
]

Click

Recipient clicked on a link within the message. Click Tracking needs to be enabled for this type of event.

Example webhook response
[
   {
      "email": "example@test.com",
      "timestamp": 1513299569,
      "event": "click",
      "category": "cat facts",
      "sg_event_id": "kCAi1KttyQdEKHhdC-nuEA==",
      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
      "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/"
   }
]

Spam Report

Recipient marked message as spam.

Example webhook response
[
   {
      "email": "example@test.com",
      "timestamp": 1513299569,
      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
      "event": "spamreport",
      "sg_event_id": "37nvH5QBz858KGVYCM4uOA==",
      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0"
   }
]

Unsubscribe

Recipient clicked on the 'Opt Out of All Emails' link (available after clicking the message's subscription management link). Subscription Tracking needs to be enabled for this type of event.

Example webhook response
[
   {
      "email": "example@test.com",
      "timestamp": 1513299569,
      "event": "unsubscribe",
      "category": "cat facts",
      "sg_event_id": "zz_BjPgU_5pS-J8vlfB1sg==",
      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0"
   }
]

Group Unsubscribe

Recipient unsubscribed from a specific group either by clicking the link directly or updating their preferences. Subscription Tracking needs to be enabled for this type of event.

Example webhook response
[
   {
      "email": "example@test.com",
      "timestamp": 1513299569,
      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
      "event": "group_unsubscribe",
      "category": "cat facts",
      "sg_event_id": "ahSCB7xYcXFb-hEaawsPRw==",
      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
      "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
   }
]

Group Resubscribe

Recipient resubscribed to a specific group by updating their preferences. Subscription Tracking needs to be enabled for this type of event.

Example webhook response
[
   {
      "email": "example@test.com",
      "timestamp": 1513299569,
      "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
      "event": "group_resubscribe",
      "category": "cat facts",
      "sg_event_id": "w_u0vJhLT-OFfprar5N93g==",
      "sg_message_id": "14c5d75ce93.dfd.64b469.filter0001.16648.5515E0B88.0",
      "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
   }
]

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.

In the following table, IP is not included as part of the json return for a deferral or bounce.

Event objects

Processed Dropped Delivered Deferred Bounce Opened Clicked Spam Report Unsubscribe Group Unsubscribe Group Resubscribe
email 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
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 recipient
  • timestamp - the UNIX timestamp of when the message was sent
  • event - 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. For open and click events, it is the IP address of the recipient who engaged with the email. The IP address will not be available in the response json for certain events such as deferral and bounce.
  • 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 the smtp-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. The url_offset is 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 for example.com will be 0, 2, and 4 in the previous example list. The index for example2.com will be 1, and the the index for example3.com will 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 to true, it means that SendGrid has received signals indicating that a recipient with MPP enabled has triggered an open event. When this field is false, 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_args or custom_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.

  • singlesend_id
  • singlesend_name

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)"
  }
]
  • marketing_campaign_id
  • marketing_campaign_name

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 email 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

Rate this page:

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.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

thanks-feedback-gif