SendGrid webhook events
12 SendGrid event types in 2 resources, plus Other SendGrid events. 12 have sample payloads.
These pages cover the Event Webhook, which reports on email you send. Inbound Parse, which posts email you receive as multipart/form-data, has no event types and is covered in the Production guide.
Every event here can also reach agents as an MCP event through Hookdeck: MCP events →
delivery
processed
documented from SendGrid docs (example)
processed SendGrid accepts a message for delivery
Identified by event field in the body
Resource delivery
[
{
"email": "alex@example.com",
"timestamp": 1513299569,
"pool": { … },
"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"
}
] Key fields
| Field | Type | Example |
|---|---|---|
[0].timestamp | number | 1513299569 |
Full schema: 12 fields.
From SendGrid docs
-
Content type
application/json
delivered
documented from SendGrid docs (example)
delivered Receiving mail server accepts the message
Identified by event field in the body
Resource delivery
[
{
"email": "alex@example.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"
}
] Key fields
| Field | Type | Example |
|---|---|---|
[0].timestamp | number | 1513299569 |
Full schema: 10 fields.
From SendGrid docs
-
Content type
application/json
bounce
documented from SendGrid docs (example)
bounce Receiving server refuses the message, as a hard bounce or a block
Identified by event field in the body
Resource delivery
[
{
"email": "alex@example.com",
"timestamp": 1513299569,
"smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
"bounce_classification": "Invalid Address",
"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"
}
] Key fields
| Field | Type | Example |
|---|---|---|
[0].status | string | 5.0.0 |
[0].type | string | bounce |
[0].timestamp | number | 1513299569 |
Full schema: 13 fields.
From SendGrid docs
-
Content type
application/json
deferred
documented from SendGrid docs (example)
deferred Receiving server temporarily refuses the message
Identified by event field in the body
Resource delivery
[
{
"email": "alex@example.com",
"domain": "example.com",
"from": "test@example.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"
}
] Key fields
| Field | Type | Example |
|---|---|---|
[0].timestamp | number | 1513299569 |
Full schema: 13 fields.
From SendGrid docs
-
Content type
application/json
dropped
documented from SendGrid docs (example)
dropped SendGrid drops the message, for example for a previously bounced address
Identified by event field in the body
Resource delivery
[
{
"email": "alex@example.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"
}
] Key fields
| Field | Type | Example |
|---|---|---|
[0].status | string | 5.0.0 |
[0].timestamp | number | 1513299569 |
Full schema: 11 fields.
From SendGrid docs
-
Content type
application/json
engagement
open
documented from SendGrid docs (example)
open HTML message is opened, including Apple Mail Privacy Protection opens
Identified by event field in the body
Resource engagement
[
{
"email": "alex@example.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"
}
] Key fields
| Field | Type | Example |
|---|---|---|
[0].timestamp | number | 1513299569 |
Full schema: 11 fields.
From SendGrid docs
-
Content type
application/json
click
documented from SendGrid docs (example)
click Recipient clicks a tracked link
Identified by event field in the body
Resource engagement
[
{
"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://example.com/blog/news.html",
"url_offset": { … }
}
] Key fields
| Field | Type | Example |
|---|---|---|
[0].timestamp | number | 1249948800 |
Full schema: 21 fields.
From SendGrid docs
-
Content type
application/json
unsubscribe
documented from SendGrid docs (example)
unsubscribe Recipient opts out of all your email
Identified by event field in the body
Resource engagement
[
{
"email": "alex@example.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"
}
] Key fields
| Field | Type | Example |
|---|---|---|
[0].timestamp | number | 1513299569 |
Full schema: 8 fields.
From SendGrid docs
-
Content type
application/json
spamreport
documented from SendGrid docs (example)
spamreport Recipient reports the message as spam
Identified by event field in the body
Resource engagement
[
{
"email": "alex@example.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"
}
] Key fields
| Field | Type | Example |
|---|---|---|
[0].timestamp | number | 1513299569 |
Full schema: 8 fields.
From SendGrid docs
-
Content type
application/json
group_unsubscribe
documented from SendGrid docs (example)
group_unsubscribe Recipient leaves a single unsubscribe group
Identified by event field in the body
Resource engagement
[
{
"email": "alex@example.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"
}
] Key fields
| Field | Type | Example |
|---|---|---|
[0].timestamp | number | 1513299569 |
Full schema: 13 fields.
From SendGrid docs
-
Content type
application/json
group_resubscribe
documented from SendGrid docs (example)
group_resubscribe Recipient rejoins a single unsubscribe group
Identified by event field in the body
Resource engagement
[
{
"email": "alex@example.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"
}
] Key fields
| Field | Type | Example |
|---|---|---|
[0].timestamp | number | 1513299569 |
Full schema: 13 fields.
From SendGrid docs
-
Content type
application/json
Other SendGrid events
account_status_change
documented from SendGrid docs (example)
account_status_change Compliance action changes your SendGrid account's status
Identified by event field in the body
[
{
"event": "account_status_change",
"sg_event_id": "MjEzNTg5OTcyOC10ZXJtaW5hdGUtMTcwNzg1MTUzMQ",
"timestamp": 1709142428,
"type": "compliance_suspend"
}
] Key fields
| Field | Type | Example |
|---|---|---|
[0].type | string | compliance_suspend |
[0].timestamp | number | 1709142428 |
Full schema: 6 fields.
From SendGrid docs
-
Content type
application/json
Buffer SendGrid's batches before they reach your handler.
Event Gateway accepts each batched POST, queues it and retries to your service on your schedule, so a slow handler doesn't lose events.