Filter all messages
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.
Bearer <<YOUR_API_KEY_HERE>>application/jsonOptional
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
- accepted values:
- 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
INoperator accepts a list of string values:field IN ('value1', 'value2')statusandeventaccept onlyIN, even for a single value:status IN ('delivered')sg_message_idaccepts=for a single ID orINfor multipleLIKEoperator performs case-insensitive prefix search:field LIKE 'prefix%'- the pattern must end with
%and must have a non-empty prefix before% LIKE ANYoperator 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) containsAllis a function:containsAll(field, "keyword1 keyword2", "keyword3 keyword4", ..)containsAllperforms case-insensitive full-text keyword search and is only supported onsubjectandreasoncontainsAllmatches 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")andcontainsAll(subject, "invoice", "overdue")are acceptable subjectandreasonsplit 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 keywords5,2,2and"order_id"becomesorderandid - 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.
- on
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')Optional
Number of messages to return (1–1000).
10Minimum: 1Maximum: 1000Optional
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.
["20223230"]Max items: 1A page of messages matching the filter.
Optional
List of messages matching the filter query.
1const client = require("@sendgrid/client");2client.setApiKey(process.env.SENDGRID_API_KEY);34const data = {5query: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};89const request = {10url: `/v3/logs`,11method: "POST",12body: data,13};1415client16.request(request)17.then(([response, body]) => {18console.log(response.statusCode);19console.log(response.body);20})21.catch((error) => {22console.error(error);23});