Contact sales Start for free
Contact sales Start for free

Introducing Email Logs: Search, Filter, and Troubleshoot Email Events

Time to read:

November 04, 2025
Written by
Taylor Ferguson
Twilion
Kim Castings
Twilion
Reviewed by
Paul Kamp
Twilion

Introducing Email Logs: Search, Filter, and Troubleshoot Email Events

Troubleshooting the lifecycle of a single email is a challenge. Until now, developers and support teams often have to stitch together data from disparate systems, wait on delayed reports, or rely on technical resources to view event level details and understand why an email has bounced, been deferred, or been delivered.

That’s why we’re excited to introduce Email Logs, a new API that provides a fast and consistent way to search and retrieve event-level email data directly from Twilio SendGrid.

With Email Logs, you get observability into your email program: every event tied to an sg_message_id, accessible in near real-time, available in the Twilio SendGrid Console and API.

What you can do with Email Logs

Validate a delivery in seconds

When a consumer says, “I didn’t get the email…,” you can view the status easily and quickly in the SendGrid console and API.

Here’s a screenshot of what you’ll see in your Twilio SendGrid Console on the Email Logs tab:

SendGrid dashboard showing email logs including processed time, message ID, recipient emails, and statuses.

Example Email Logs API call and responses

Here’s an example of an API call you can make with the Email Logs product, and the response you could receive.

API call 

curl -X POST 'https://api.sendgrid.com/v3/logs' \
  -H 'Authorization: Bearer YOUR_SENDGRID_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "to_email = \"recipient@example.com\" AND status IN (\'delivered\')",
    "limit": 5
  }'

Sample response 

"messages": [
    {
      "from_email": "no-reply@exampleco.com",
      "sg_message_id": "aaa111.recvd-node-abc-1-00000000-00.0",
      "subject": "One-Time Passcode",
      "to_email": "recipient@example.com",
      "reason": "250 2.0.0 OK - Message accepted for delivery",
      "status": "delivered",
      "sg_message_id_created_at": "2025-09-17T19:36:34Z"
    },
    {
      "from_email": "no-reply@exampleco.com",
      "sg_message_id": "bbb222.recvd-node-def-1-00000000-00.0",
      "subject": "One-Time Passcode",
      "to_email": "recipient@example.com",
      "reason": "250 2.0.0 OK - Message accepted for delivery",
      "status": "delivered",
      "sg_message_id_created_at": "2025-09-17T19:33:56Z"
    },
    {
      "from_email": "no-reply@exampleco.com",
      "sg_message_id": "ccc333.recvd-node-ghi-1-00000000-00.0",
      "subject": "One-Time Passcode",
      "to_email": "recipient@example.com",
      "reason": "250 2.0.0 OK - Message accepted for delivery",
      "status": "delivered",
      "sg_message_id_created_at": "2025-09-17T19:33:14Z"
    },
    {
      "from_email": "no-reply@exampleco.com",
      "sg_message_id": "ddd444.recvd-node-jkl-1-00000000-00.0",
      "subject": "One-Time Passcode",
      "to_email": "recipient@example.com",
      "reason": "250 2.0.0 OK - Message accepted for delivery",
      "status": "delivered",
      "sg_message_id_created_at": "2025-09-17T19:29:39Z"
    },
    {
      "from_email": "no-reply@exampleco.com",
      "sg_message_id": "eee555.recvd-node-mno-1-00000000-00.0",
      "subject": "One-Time Passcode",
      "to_email": "recipient@example.com",
      "reason": "250 2.0.0 OK - Message accepted for delivery",
      "status": "delivered",
      "sg_message_id_created_at": "2025-09-17T19:28:21Z"
    }
  ]
}

Drill into ESP responses for deferrals, bounces, and blocks

When an email delivery fails, you can see the exact response and reason returned from the ESP.

Here’s an example of what you might see in your Twilio SendGrid Console:

Screenshot of SendGrid email details page showing message ID, subject, and event history.

Here’s an example of an API call you can make using a SendGrid Message ID.

API call 

curl -X GET 'https://api.sendgrid.com/v3/logs/{sg_message_id}' \
  -H 'Authorization: Bearer YOUR_SENDGRID_API_KEY' \
  -H 'Content-Type: application/json'

Sample response 

{
  "from_email": "example@yourdomain.com",
  "sg_message_id": "abc123.recvd-abcdef1234-node-1-00000000-00.1",
  "subject": "Welcome to ExampleCo!",
  "to_email": "recipient@example.com",
  "status": "bounced",
  "template_id": "d-11111111111111111111111111111111",
  "api_key_id": "",
  "events": [
    {
      "event": "received",
      "recv_msgid": "abc123",
      "sg_event_id": "received-event-id",
      "timestamp": 1759944197,
      "api_version": "3",
      "client_ip": "203.0.113.10",
      "protocol": "HTTP",
      "recipient_count": 1,
      "useragent": "sendgrid-smtpapi",
      "v3_payload_details": {
        "recipient_count": 1,
        "sender_count": 1,
        "text/plain": 1,
        "text/html": 1,
        "attachments_bytes": 0
      }
    },
    {
      "event": "processed",
      "email": "recipient@example.com",
      "sg_message_id": "abc123.recvd-abcdef1234-node-1-00000000-00.1",
      "sg_event_id": "processed-event-id",
      "timestamp": 1759944198,
      "smtp-id": "<abc123@sendgrid-smtp.example>",
      "category": ["welcome"],
      "custom_args": {
        "template_id": "d-11111111111111111111111111111111",
        "automation_id": "auto-flow-001",
        "automation_name": "Welcome Series"
      }
    },
    {
      "event": "delivered",
      "email": "recipient@example.com",
      "sg_message_id": "abc123.recvd-abcdef1234-node-1-00000000-00.1",
      "sg_event_id": "delivered-event-id",
      "timestamp": 1759944199,
      "ip": "198.51.100.25",
      "response": "250 2.0.0 Message accepted for delivery",
      "tls": 1,
      "category": ["welcome"]
    },
    {
      "event": "bounce",
      "email": "recipient@example.com",
      "sg_message_id": "abc123.recvd-abcdef1234-node-1-00000000-00.1",
      "sg_event_id": "bounce-event-id",
      "timestamp": 1759944200,
      "category": ["welcome"],
      "bounce_classification": "Invalid Address",
      "reason": "The email account you tried to reach does not exist. Check the recipient address for typos or spaces.",
      "status": "5.1.3",
      "type": "bounce",
      "custom_args": {
        "template_id": "d-11111111111111111111111111111111",
        "automation_id": "auto-flow-001",
        "automation_name": "Welcome Series"
      }
    }
  ],
  "client_ip": "203.0.113.10",
  "category": ["welcome"],
  "custom_args": {
    "template_id": "d-11111111111111111111111111111111",
    "automation_id": "auto-flow-001",
    "automation_name": "Welcome Series"
  },
  "outbound_ip": "198.51.100.25",
  "outbound_ip_type": "dedicated"
}

Get started with Email Logs, today

Email Logs is available today for all Twilio SendGrid customers. To start exploring your data in the UI:

  1. Navigate to your SendGrid Console
  2. Click on Email Logs in the side panel

Or, access it via API:

  1. Generate a new API key or use an existing key
  2. Ensure the Email Activity permission scope is enabled for your API Key
  3. Call the Email Logs endpoint: POST https://api.sendgrid.com/v3/logs or GET https://api.sendgrid.com/v3/logs/{sg_message_id}

Here’s an example of the permissions you’ll want to set for the API Key, in order to access Email Logs:

Better visibility leads to better deliverability. With Email Logs you’ll always know what happened to your messages and why – get started with Email Logs, today!

Taylor Ferguson is a Product Manager on Twilio’s Channels Data team, shaping the platform foundations that power data consistency, observability, and insights across Twilio’s communication channels.

Kim Castings is a Product Marketer for Twilio SendGrid Email, focused on turning customer insights into product strategy and launches that make email easier for developers and marketers.

Related Posts

Related Resources

A newspaper article

Twilio Docs

From APIs to SDKs to sample apps

API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.
An Open book

Resource Center

The latest ebooks, industry reports, and webinars

Learn from customer engagement experts to improve your own communication.
User group reactions

Ahoy

Twilio's developer community hub

Best practices, code samples, and inspiration to build communications and digital engagement experiences.