Filter messages by ID

API Overview

Use this endpoint to retrieve detailed events for a specific message. You can obtain an sg_message_id from the Filter All Messages endpoint. This endpoint provides comprehensive details and the full event timeline for a single email.

Operation overview

GET/v3/logs/{sg_message_id}

Base url: https://api.sendgrid.com (for global users and subusers)

Base url: https://api.eu.sendgrid.com (for EU regional subusers)

Get all of the details about the specified message.

Operation details

Authentication

API Key

Headers

Property nameTypeRequiredDescription

Authorizationstring

required

Default: Bearer <<YOUR_API_KEY_HERE>>

Path parameters

Property nameTypeRequiredDescription

sg_message_idstring

required

The ID of the message you are requesting details for.

Query string

Property nameTypeRequiredDescription

subuserstring<^\d+$>

Optional

For requests authenticated as the parent account, this argument must be passed if the desired message belongs to a subuser.

Responses

200400403404429default

Detailed information for the specified message, including all events related to the message

Schema

Property nameTypeRequiredDescriptionChild properties

from_emailstring

Optional

The 'From' email address used to deliver the message. This may not be a valid email address.

sg_message_idstring

Optional

A unique ID assigned to the message.

subjectstring

Optional

The email's subject line.

to_emailstring

Optional

The intended recipient's email address.

statusenum<string>

Optional

A summary of the message status based on which events have occurred.

Possible values:

processeddelivereddeferreddroppedbouncedblocked

template_idstring

Optional

The ID associated with a Twilio SendGrid email template used to format the message.

asm_group_idinteger

Optional

The unsubscribe group associated with this email.

teammatestring

Optional

Teammate's username.

Pattern: ^$|^[A-Za-z0-9]+Max length: 64

api_key_idstring

Optional

The ID of the API Key used to authenticate the sending request for the message.

Pattern: ^$|^[A-Za-z0-9_-]+Max length: 50

events

array(oneOf):

Optional

All events recorded for this message. Most recent events will be returned upto the maximum of 100 events.

Max items: 100

Show events properties

Property nameTypeRequiredDescriptionChild properties

eventenum<string>

Optional

Possible values:

bounce

emailstring

Optional

Recipient email address.

sg_message_idstring

Optional

SendGrid Message ID, a string that uniquely identifies the message

Example: Xj5LmNkWSOqRbdvOpR34BA.recvd-85abf8d92c-3qfgp-2-7890E356-43C.1

sg_event_idstring

Optional

SendGrid Event ID, a string that uniquely identifies the event

Example: 2M1MaNdWRNipzTpyUCWQ2g

timestampinteger

Optional

Unix timestamp

Example: 1755187955

smtp-idstring

Optional

SMTP ID associated with the message

Example: <14c5d75ce93.dfd.64b469@ismtpd-555>

ipstring

Optional

IPv4 or IPv6 address

Example: 192.168.1.1

tlsenum<integer>

Optional

Indicates whether TLS was used (1). This field will only be present if TLS was used.

Possible values:

1

categoryarray[string]

Optional

Message categories

asm_group_idinteger

Optional

The ID of the ASM (Advanced Suppression Manager) group associated with the message

Example: 12345

bounce_classificationenum<string>

Optional

Possible values:

ContentFrequency or Volume Too HighInvalid AddressMailbox UnavailableReputationTechnicalUnclassified

reasonstring

Optional

SMTP response code and message indicating the reason the delivery succeeded or failed

Example:

250 2.0.0 OK  1755119505 e9e14a558f8cb-3e543d3ec1csi148151125cb.10 - gsmtp

statusstring

Optional

SMTP status code associated with the bounce

Example: 5.1.1Pattern: ^([245]\.[01234567]\.[01234567]|[1-5][0-9][0-9])$

typeenum<string>

Optional

The type of bounce that occurred.

bounce typically means that the message is permanently undeliverable (hard bounce).
blocked indicates that the message was temporarily undeliverable (soft bounce).

Possible values:

bounceblocked

cert_errenum<string>

Optional

Indicates that there was a certificate error during the TLS handshake.

Possible values:

1

custom_argsobject

Optional

Custom arguments provided with the mail send request. We deviate here from the Event Webhook schema by NOT merging custom args into the top level of the object, in order to avoid collisions with system-defined fields. These are known as Custom Args in /v3/mail/send but Unique Args in SMTP and HTTP v2 mail send (/api/mail.send.json).

Example: {"key1":"value1"}

Show custom_args properties

client_ipstring

Optional

The IP address of the user who sent the message.

categoryarray[string]

Optional

The categories associated with the message.

custom_argsobject

Optional

Custom key-value pairs associated with the message.

Show custom_args properties

outbound_ipstring

Optional

The IP address used to send to the remote Mail Transfer Agent.

outbound_ip_typestring

Optional

The type of outbound IP address used to send the message.

Example: dedicated

marketing_campaign_idinteger

Optional

The ID of the marketing campaign associated with the message.

marketing_campaign_namestring

Optional

The name of the marketing campaign associated with the message.

marketing_campaign_split_idinteger

Optional

The ID of the split associated with the marketing campaign.

marketing_campaign_versionstring

Optional

The version of the marketing campaign associated with the message.

Filter messages by ID

1const client = require("@sendgrid/client");
2client.setApiKey(process.env.SENDGRID_API_KEY);
3
4const sg_message_id =
5  "zYMjsUZORvevDeb4hlcVjg.recvd-6f5cbff5dc-k58s2-1-68CB0DC2-12.0";
6
7const request = {
8  url: `/v3/logs/${sg_message_id}`,
9  method: "GET",
10};
11
12client
13  .request(request)
14  .then(([response, body]) => {
15    console.log(response.statusCode);
16    console.log(response.body);
17  })
18  .catch((error) => {
19    console.error(error);
20  });