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)

SendGrid accepts a message for delivery

Identified by event field in the body Resource delivery

sendgrid-processed.json
[
  {
    "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

Send example to Inspect → View as JSON

delivered

documented from SendGrid docs (example)

Receiving mail server accepts the message

Identified by event field in the body Resource delivery

sendgrid-delivered.json
[
  {
    "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

Send example to Inspect → View as JSON

bounce

documented from SendGrid docs (example)

Receiving server refuses the message, as a hard bounce or a block

Identified by event field in the body Resource delivery

sendgrid-bounce.json
[
  {
    "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

Send example to Inspect → View as JSON

deferred

documented from SendGrid docs (example)

Receiving server temporarily refuses the message

Identified by event field in the body Resource delivery

sendgrid-deferred.json
[
  {
    "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

Send example to Inspect → View as JSON

dropped

documented from SendGrid docs (example)

SendGrid drops the message, for example for a previously bounced address

Identified by event field in the body Resource delivery

sendgrid-dropped.json
[
  {
    "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

Send example to Inspect → View as JSON

engagement

open

documented from SendGrid docs (example)

HTML message is opened, including Apple Mail Privacy Protection opens

Identified by event field in the body Resource engagement

sendgrid-open.json
[
  {
    "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

Send example to Inspect → View as JSON

click

documented from SendGrid docs (example)

Recipient clicks a tracked link

Identified by event field in the body Resource engagement

sendgrid-click.json
[
  {
    "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

Send example to Inspect → View as JSON

unsubscribe

documented from SendGrid docs (example)

Recipient opts out of all your email

Identified by event field in the body Resource engagement

sendgrid-unsubscribe.json
[
  {
    "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

Send example to Inspect → View as JSON

spamreport

documented from SendGrid docs (example)

Recipient reports the message as spam

Identified by event field in the body Resource engagement

sendgrid-spamreport.json
[
  {
    "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

Send example to Inspect → View as JSON

group_unsubscribe

documented from SendGrid docs (example)

Recipient leaves a single unsubscribe group

Identified by event field in the body Resource engagement

sendgrid-group-unsubscribe.json
[
  {
    "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

Send example to Inspect → View as JSON

group_resubscribe

documented from SendGrid docs (example)

Recipient rejoins a single unsubscribe group

Identified by event field in the body Resource engagement

sendgrid-group-resubscribe.json
[
  {
    "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

Send example to Inspect → View as JSON

Other SendGrid events

account_status_change

documented from SendGrid docs (example)

Compliance action changes your SendGrid account's status

Identified by event field in the body

sendgrid-account-status-change.json
[
  {
    "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

Send example to Inspect → View as 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.

Not affiliated with SendGrid. Facts are compiled from public sources and linked inline.