SendGrid · AsyncAPI Specification

SendGrid Event Webhook

Version 3.0.0

The SendGrid Event Webhook delivers near real-time event data about your email activity via HTTP POST requests. SendGrid batches events into arrays and sends them to your configured webhook URL. Events cover the full email lifecycle including delivery, engagement, and suppression actions. You can use this data to monitor deliverability, track recipient engagement, and maintain suppression lists.

View Spec View on GitHub EmailEmail APIMarketing EmailSMTPT1Transactional EmailEmail MarketingDeliverabilityMarketingAsyncAPIEventsWebhooks

Channels

/webhook/event
publish receiveEmailEvents
Receive batched email event notifications
SendGrid posts batched email event data to your configured webhook URL. Each POST request contains a JSON array of up to 1000 or more event objects. Events include delivery events (processed, dropped, delivered, deferred, bounce) and engagement events (open, click, spam report, unsubscribe, group unsubscribe, group resubscribe).

Messages

✉
ProcessedEvent
Processed Event
SendGrid accepted the message and will attempt delivery.
✉
DroppedEvent
Dropped Event
SendGrid dropped the message due to invalid headers, spam content, unsubscribed recipient, bounced address, or quota limits.
✉
DeliveredEvent
Delivered Event
SendGrid successfully delivered the message to the receiving mail server.
✉
DeferredEvent
Deferred Event
The receiving server temporarily rejected the message and SendGrid will retry delivery.
✉
BounceEvent
Bounce Event
The receiving server permanently or temporarily rejected the message.
✉
OpenEvent
Open Event
The recipient opened the HTML email message.
✉
ClickEvent
Click Event
The recipient clicked a link within the email message.
✉
SpamReportEvent
Spam Report Event
The recipient marked the email as spam.
✉
UnsubscribeEvent
Unsubscribe Event
The recipient unsubscribed from all emails.
✉
GroupUnsubscribeEvent
Group Unsubscribe Event
The recipient unsubscribed from a specific suppression group.
✉
GroupResubscribeEvent
Group Resubscribe Event
The recipient resubscribed to a specific suppression group.

Servers

https
customerEndpoint {webhookUrl}
The customer-configured HTTPS endpoint that receives webhook POST requests from SendGrid. You configure this URL in the SendGrid Event Webhook settings.

AsyncAPI Specification

Raw ↑ 
asyncapi: 2.6.0
info:
  title: SendGrid Event Webhook
  description: The SendGrid Event Webhook delivers near real-time event data about your email activity via HTTP POST requests. SendGrid batches events into arrays and sends them to your configured webhook
    URL. Events cover the full email lifecycle including delivery, engagement, and suppression actions. You can use this data to monitor deliverability, track recipient engagement, and maintain suppression
    lists.
  version: 3.0.0
  contact:
    name: Twilio SendGrid Support
    url: https://support.sendgrid.com/hc/en-us
  license:
    name: MIT
  termsOfService: https://www.twilio.com/legal/tos
servers:
  customerEndpoint:
    url: '{webhookUrl}'
    protocol: https
    description: The customer-configured HTTPS endpoint that receives webhook POST requests from SendGrid. You configure this URL in the SendGrid Event Webhook settings.
    variables:
      webhookUrl:
        description: Your webhook receiver URL
    security:
    - signedWebhook: []
    - oAuth2: []
channels:
  /webhook/event:
    description: SendGrid posts batched email event data to your configured webhook URL. Each POST request contains a JSON array of up to 1000 or more event objects. Events include delivery events (processed,
      dropped, delivered, deferred, bounce) and engagement events (open, click, spam report, unsubscribe, group unsubscribe, group resubscribe).
    publish:
      operationId: receiveEmailEvents
      summary: Receive batched email event notifications
      description: SendGrid sends HTTP POST requests containing a JSON array of event objects to your webhook URL. Each event object includes common fields such as the recipient email, timestamp, event
        type, and SendGrid message identifiers. Event-specific fields provide additional context such as bounce reasons, clicked URLs, or user agent strings.
      message:
        oneOf:
        - $ref: '#/components/messages/ProcessedEvent'
        - $ref: '#/components/messages/DroppedEvent'
        - $ref: '#/components/messages/DeliveredEvent'
        - $ref: '#/components/messages/DeferredEvent'
        - $ref: '#/components/messages/BounceEvent'
        - $ref: '#/components/messages/OpenEvent'
        - $ref: '#/components/messages/ClickEvent'
        - $ref: '#/components/messages/SpamReportEvent'
        - $ref: '#/components/messages/UnsubscribeEvent'
        - $ref: '#/components/messages/GroupUnsubscribeEvent'
        - $ref: '#/components/messages/GroupResubscribeEvent'
components:
  securitySchemes:
    signedWebhook:
      type: httpApiKey
      name: X-Twilio-Email-Event-Webhook-Signature
      in: header
      description: ECDSA signature for verifying the authenticity of webhook requests. Enable Signed Event Webhook in your SendGrid settings to use this verification method.
    oAuth2:
      type: oauth2
      description: OAuth 2.0 client credentials flow for authenticating webhook requests. Configure OAuth client ID, client secret, and token URL in your Event Webhook settings.
      flows:
        clientCredentials:
          tokenUrl: '{oauthTokenUrl}'
          scopes: {}
  messages:
    ProcessedEvent:
      name: Processed
      title: Processed Event
      summary: SendGrid accepted the message and will attempt delivery.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ProcessedEvent'
    DroppedEvent:
      name: Dropped
      title: Dropped Event
      summary: SendGrid dropped the message due to invalid headers, spam content, unsubscribed recipient, bounced address, or quota limits.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/DroppedEvent'
    DeliveredEvent:
      name: Delivered
      title: Delivered Event
      summary: SendGrid successfully delivered the message to the receiving mail server.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/DeliveredEvent'
    DeferredEvent:
      name: Deferred
      title: Deferred Event
      summary: The receiving server temporarily rejected the message and SendGrid will retry delivery.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/DeferredEvent'
    BounceEvent:
      name: Bounce
      title: Bounce Event
      summary: The receiving server permanently or temporarily rejected the message.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BounceEvent'
    OpenEvent:
      name: Open
      title: Open Event
      summary: The recipient opened the HTML email message.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/OpenEvent'
    ClickEvent:
      name: Click
      title: Click Event
      summary: The recipient clicked a link within the email message.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ClickEvent'
    SpamReportEvent:
      name: SpamReport
      title: Spam Report Event
      summary: The recipient marked the email as spam.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SpamReportEvent'
    UnsubscribeEvent:
      name: Unsubscribe
      title: Unsubscribe Event
      summary: The recipient unsubscribed from all emails.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/UnsubscribeEvent'
    GroupUnsubscribeEvent:
      name: GroupUnsubscribe
      title: Group Unsubscribe Event
      summary: The recipient unsubscribed from a specific suppression group.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/GroupUnsubscribeEvent'
    GroupResubscribeEvent:
      name: GroupResubscribe
      title: Group Resubscribe Event
      summary: The recipient resubscribed to a specific suppression group.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/GroupResubscribeEvent'
  schemas:
    BaseEvent:
      type: object
      description: Common fields present on all SendGrid Event Webhook events.
      required:
      - email
      - event
      - sg_event_id
      - sg_message_id
      - timestamp
      properties:
        email:
          type: string
          format: email
          description: The email address of the recipient.
        event:
          type: string
          description: The type of event that occurred.
        sg_event_id:
          type: string
          description: A unique identifier for this event generated by SendGrid.
        sg_message_id:
          type: string
          description: A unique identifier for the message associated with this event, generated by SendGrid.
        timestamp:
          type: integer
          description: The Unix timestamp of when the event occurred.
        smtp-id:
          type: string
          description: A unique identifier attached to the message by the originating SMTP server.
        category:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          description: Categories assigned to the message for tracking purposes. May be a single string or an array of strings.
        asm_group_id:
          type: integer
          description: The ID of the suppression group that the recipient is associated with.
        unique_args:
          type: object
          additionalProperties: true
          description: Custom key-value pairs passed with the message using unique_args (SMTP API / v2 Mail Send) or custom_args (v3 Mail Send).
        marketing_campaign_id:
          type: integer
          description: The ID of the Marketing Campaign that generated this event, if applicable.
        marketing_campaign_name:
          type: string
          description: The name of the Marketing Campaign that generated this event, if applicable.
    ProcessedEvent:
      description: Indicates that SendGrid has accepted the message and will attempt to deliver it.
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
      - type: object
        properties:
          event:
            type: string
            const: processed
          pool:
            type: object
            description: Information about the IP pool used for sending.
            properties:
              name:
                type: string
                description: The name of the IP pool.
              id:
                type: integer
                description: The ID of the IP pool.
    DroppedEvent:
      description: Indicates that SendGrid dropped the message and will not deliver it. Messages are dropped due to invalid headers, spam content, an unsubscribed recipient, a previously bounced address,
        or exceeding sending quotas.
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
      - type: object
        properties:
          event:
            type: string
            const: dropped
          reason:
            type: string
            description: The reason why the message was dropped.
          status:
            type: string
            description: The SMTP status code associated with the drop.
    DeliveredEvent:
      description: Indicates that the receiving mail server accepted the message for delivery to the recipient.
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
      - type: object
        properties:
          event:
            type: string
            const: delivered
          response:
            type: string
            description: The full SMTP response string from the receiving server, such as "250 OK".
    DeferredEvent:
      description: Indicates that the receiving server temporarily rejected the message. SendGrid will continue to retry delivery.
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
      - type: object
        properties:
          event:
            type: string
            const: deferred
          attempt:
            type: integer
            minimum: 1
            description: The number of delivery attempts SendGrid has made for this message.
          response:
            type: string
            description: The full response string from the receiving server explaining the deferral.
    BounceEvent:
      description: Indicates that the receiving server rejected the message. A hard bounce means the address is permanently invalid. A blocked bounce is a temporary or soft rejection.
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
      - type: object
        properties:
          event:
            type: string
            const: bounce
          bounce_classification:
            type: string
            enum:
            - Invalid Address
            - Technical
            - Content
            - Reputation
            - Frequency/Volume
            - Mailbox Unavailable
            - Unclassified
            description: The classification of the bounce indicating the general category of the rejection reason.
          reason:
            type: string
            description: The detailed rejection reason provided by the receiving server.
          status:
            type: string
            description: The SMTP status code associated with the bounce.
          type:
            type: string
            enum:
            - bounce
            - blocked
            description: The type of bounce. A value of "bounce" indicates a hard bounce (permanent failure). A value of "blocked" indicates a soft bounce (temporary failure).
    OpenEvent:
      description: Indicates that the recipient opened the HTML email message. Open tracking requires a transparent tracking pixel embedded in the HTML content.
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
      - type: object
        properties:
          event:
            type: string
            const: open
          sg_machine_open:
            type: boolean
            description: Indicates whether the open was detected as an automated or machine-generated open rather than a human interaction.
          useragent:
            type: string
            description: The user agent string of the client that opened the email.
    ClickEvent:
      description: Indicates that the recipient clicked on a link within the email message.
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
      - type: object
        properties:
          event:
            type: string
            const: click
          ip:
            type: string
            description: The IP address of the recipient who clicked the link.
          url:
            type: string
            format: uri
            description: The URL that was clicked by the recipient.
          url_offset:
            type: object
            description: The position and type of the clicked link within the message body.
            properties:
              index:
                type: integer
                minimum: 0
                description: The zero-based index of the link in the message.
              type:
                type: string
                enum:
                - html
                - text
                description: Whether the link was in the HTML or plain text body of the message.
          useragent:
            type: string
            description: The user agent string of the client that clicked the link.
    SpamReportEvent:
      description: Indicates that the recipient marked the email as spam using their email client.
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
      - type: object
        properties:
          event:
            type: string
            const: spamreport
    UnsubscribeEvent:
      description: Indicates that the recipient clicked the unsubscribe link and opted out of all future emails from the sender.
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
      - type: object
        properties:
          event:
            type: string
            const: unsubscribe
    GroupUnsubscribeEvent:
      description: Indicates that the recipient unsubscribed from a specific suppression group rather than all emails.
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
      - type: object
        properties:
          event:
            type: string
            const: group_unsubscribe
          asm_group_id:
            type: integer
            description: The ID of the suppression group the recipient unsubscribed from.
    GroupResubscribeEvent:
      description: Indicates that the recipient resubscribed to a specific suppression group after having previously unsubscribed.
      allOf:
      - $ref: '#/components/schemas/BaseEvent'
      - type: object
        properties:
          event:
            type: string
            const: group_resubscribe
          asm_group_id:
            type: integer
            description: The ID of the suppression group the recipient resubscribed to.
externalDocs:
  description: Event Webhook Reference
  url: https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/event

Work with this as data

Every AsyncAPI spec here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for asyncapi

4 MCP tools reach this
  • find_asyncapisBrowse and filter every AsyncAPI spec in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This AsyncAPI spec 
curl "https://apis.io/api/v1/asyncapis/sendgrid-event-webhook-asyncapi"
All asyncapi 
curl "https://apis.io/api/v1/asyncapis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.