Skip to contentSkip to navigationSkip to topbar
Page tools
Useful for sharing or LLM
Accelerate development with AI

On this page
Looking for more inspiration?Visit the

Filter all messages


API Overview

api-overview page anchor

Use this endpoint to search processed email messages and identify specific messages of interest sent from your account. The response returns a list of messages that match your filter criteria, including each message's sg_message_id and key delivery attributes such as sender, recipient, subject, and status. Pass the sg_message_id to the Filter Messages by ID endpoint to retrieve full event-level details for that message.


POST/v3/logs

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

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

List recent messages within Email Logs, or search for messages using a filter.


Authentication

authentication page anchor
Property nameTypeRequiredDescription
Authorizationstring
required
Default: Bearer <<YOUR_API_KEY_HERE>>
Encoding type:application/json
Schema
Property nameTypeRequiredDescriptionChild properties
querystring

Optional

Allowed event fields, operators, and functions

  • sg_message_id: =, IN
  • subject: =, LIKE, containsAll()
  • to_email: =, LIKE
  • from_email: =, LIKE
  • status: IN
  • event: IN
    • accepted values: bounce, click, deferred, delivered, dropped, open, processed, spamreport, group_unsubscribe, group_resubscribe, unsubscribe
  • reason: =, LIKE, containsAll()
  • api_key_id: =
    • the ID of the API key used to send the message, not the key itself
  • outbound_ip: =, LIKE
  • categories: IN, LIKE, LIKE ANY
  • sg_message_id_created_at: >, <, >=, <=

Notes:

  • multiple conditions (up to 160) can be combined with AND
  • nesting is not allowed
  • IN operator accepts a list of string values: field IN ('value1', 'value2')
  • status and event accept only IN, even for a single value: status IN ('delivered')
  • sg_message_id accepts = for a single ID or IN for multiple
  • LIKE operator performs case-insensitive prefix search: field LIKE 'prefix%'
  • the pattern must end with % and must have a non-empty prefix before %
  • LIKE ANY operator performs case-insensitive prefix search against multiple patterns (max 5): categories LIKE ANY ('prefix1%', 'prefix2%')
  • interior %, _, and \ characters in patterns are treated as literals (escaped automatically)
  • containsAll is a function: containsAll(field, "keyword1 keyword2", "keyword3 keyword4", ..)
  • containsAll performs case-insensitive full-text keyword search and is only supported on subject and reason
  • containsAll matches rows containing every given keyword, in any position, regardless of order
  • each argument may hold one or more space-separated keywords; so containsAll(subject, "invoice overdue") and containsAll(subject, "invoice", "overdue") are acceptable
  • subject and reason split keywords differently, so the same string can behave differently on each field:
    • on subject, every character that is not a letter or digit splits keywords, so "5.2.2" becomes the three keywords 5, 2, 2 and "order_id" becomes order and id
    • on reason, . and _ do not split keywords, so "5.2.2" or "order_id" stays a single keyword. All other punctuation (spaces, ,, -, :, /, @, and similar) still splits keywords.
Example: sg_message_id_created_at > TIMESTAMP "2025-01-01T00:00:00Z" AND sg_message_id_created_at < TIMESTAMP "2025-02-01T00:00:00Z" AND status IN ('delivered', 'processed') AND categories IN ('newsletter', 'marketing')

limitinteger

Optional

Number of messages to return (1–1000).

Default: 10Minimum: 1Maximum: 1000

subusersarray[string<^\d+$>]

Optional

For requests authenticated as the parent account, this argument must be passed if the desired messages belong to a subuser. You can only call this endpoint for 1 subuser at a time.

Example: ["20223230"]Max items: 1
200400403429default

A page of messages matching the filter.

Schema
Property nameTypeRequiredDescriptionChild properties
messagesarray[object]

Optional

List of messages matching the filter query.

Filter all messagesLink to code sample: Filter all messages
1
const client = require("@sendgrid/client");
2
client.setApiKey(process.env.SENDGRID_API_KEY);
3
4
const data = {
5
query:
6
"sg_message_id_created_at > TIMESTAMP \"2025-01-01T00:00:00Z\" AND sg_message_id_created_at < TIMESTAMP \"2025-02-01T00:00:00Z\" AND status IN ('delivered', 'processed') AND categories IN ('newsletter', 'marketing')",
7
};
8
9
const request = {
10
url: `/v3/logs`,
11
method: "POST",
12
body: data,
13
};
14
15
client
16
.request(request)
17
.then(([response, body]) => {
18
console.log(response.statusCode);
19
console.log(response.body);
20
})
21
.catch((error) => {
22
console.error(error);
23
});