Getting Started with the Email Activity Feed API

The Email Activity API gives you access to query all of your stored messages, to query individual messages, and to download a CSV with data about the stored messages.

In order to gain access to the Email Activity Feed API, you must purchase additional email activity history. Once purchased, you must also update your existing API key(s) to have Email Activity access or create a new API key with Email Activity access.

Getting started

Start with this basic query to the Email Activity Feed API (replace <<your API key>> with an API key from your account):

curl --request GET \
 --url 'https://api.sendgrid.com/v3/messages?limit=10' \
 --header 'authorization: Bearer <<your API key>>'

This returns a list of the 10 most recent emails you've sent. Next, check out some of the common use cases to narrow down your search.

Encoding queries

All queries need to be URL encoded and have this format:

query={query_type}="{query_content}"

Encoded, this query would look like this:

query=query_type%3D%22query_content%22

Queries for common use cases

Here are some queries for common use cases. For a full list of possible query types, see the query reference.

Filter by subject

Use this query to filter by email subject (replace <<your API key>> with an API key from your account, and replace <<subject>> with the subject you want to search):

curl --request GET \
 --url 'https://api.sendgrid.com/v3/messages?limit=10&query=subject%3D<<subject>>' \
 --header 'authorization: Bearer <<your API key>>'

Subject queries have this format:

subject="This is a subject test"

Encoded, this query would look like this:

subject%3D%22This%20is%20a%20subject%20test%22

Filter by recipient email

Use this query to filter by a recipient's email: (replace <<your API key>> with an API key from your account, and replace <<email>> with the URL encoded recipients email):

curl --request GET \
 --url 'https://api.sendgrid.com/v3/messages?limit=10&query=to_email%3D%22<<email>>%22' \
 --header 'authorization: Bearer <<your API key>>'

Recipient email queries have this format:

to_email="example@example.com"

Encoded, this query would look like this:

to_email%3D%22example%40example.com%22

Filter by undelivered emails

Use this query to filter by all undelivered emails: (replace <<your API key>> with an API key from your account):

curl --request GET \
 --url 'https://api.sendgrid.com/v3/messages?limit=10&query=status%3D%22not_delivered%22' \
 --header 'authorization: Bearer <<your API key>>'

Subject queries have this format:

status="not_delivered"

Encoded, this query would look like this:

status%3D%22not_delivered%22

Creating compound queries

Use operators and keywords to combine queries for a compound query. For example, you could filter for emails between a date range or you could filter for when a specific recipient's email is not delivered. Here are some common use cases:

Filter by a recipient email that was undelivered

Use this query to filter by a recipient's email and by emails that are not delivered: (replace <<your API key>> with an API key from your account, and replace <<email>> with the URL encoded recipients email):

curl --request GET \
 --url 'https://api.sendgrid.com/v3/messages?limit=10&query=status%3D%22not_delivered%22%20AND%20to_email%3D%22<<email>>%22' \
 --header 'authorization: Bearer <<your API key>>'

Filter by date range

Use this query to filter to emails between specific dates: (replace <<your API key>> with an API key from your account, and replace {start_date} and {end_date} with a URL encoded UTC date string in this format: YYYY-MM-DD HH:mm:SS. Encoded, this looks like this: 2018-02-01T00%3A00%3A00.000Z)

curl --request GET \
 --url 'https://api.sendgrid.com/v3/messages?limit=10&query=last_event_time%20BETWEEN%20TIMESTAMP%20%22{start_date}%22%20AND%20TIMESTAMP%20%22{end_date}%22' \
 --header 'authorization: Bearer <<your API key>>'

Filter by a recipient and a date range

Use this query to filter to emails by recipient and between specific dates: (replace <<your API key>> with an API key from your account, replace <<start_date>> and <<end_date>> with a URL encoded UTC date string in this format: YYYY-MM-DD HH:mm:SS, and replace <<email>> with the URL encoded recipient's email)

curl --request GET \
 --url 'https://api.sendgrid.com/v3/messages?limit=10&query=last_event_time%20BETWEEN%20TIMESTAMP%20%22{start_date}%22%20AND%20TIMESTAMP%20%22{end_date}%22AND%20to_email%3D%22<<email>>%22' \
 --header 'authorization: Bearer <<your API key>>'

Keywords and Operator reference

There are several operators and keywords that you can use to build Compound queries. Use these operators between query statements. If the character used as the delimiter is found within the string. The escape character is \, which must be escaped with a preceding \. All queries need to be URL encoded.

This is a full list of accepted operators and keywords:

• =
• !=
• <
• >
• <=
• >=
• - - to
• +
• /
• *
• - - subtraction
• AND
• BETWEEN
• NOT BETWEEN
• CONTAINS
• DAY
• FALSE
• HOUR
• IN
• NOT IN
• INTERVAL
• IS
• IS NOT
• LIKE
• NOT LIKE
• MINUTE
• MONTH
• NOT
• NULL
• OR
• SECOND
• TIMESTAMP
• TRUE
• YEAR

Query reference

This is a full list of basic query types and examples: (replace the data in quotes with the information you want to query, and then URL encode it)

Additional Resources

• Email Activity Feed API Reference
• Email Activity Feed UI