In order to gain access to the Email Activity Feed API, you must purchase additional email activity history.

The 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.

Getting started

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

1
2
3
curl --request GET \
 --url 'http://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 <> with the subject you want to search):

1
2
3
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 <> with the URL encoded recipients email):

1
2
3
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 bounced emails

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

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

Subject queries have this format:

status="bounced"

Encoded, this query would look like this:

status%3D%22bouced%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 recipients email is bounced. Here are some common use cases:

Filter by a recipient email that was bounced

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

1
2
3
curl --request GET \
 --url 'https://api.sendgrid.com/v3/messages?limit=10&query=status%3D%22bounced%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)

1
2
3
curl --request GET \
 --url 'https://api.sendgrid.com/v3/messages?limit=10&query=last_event_time%20BETWEEN%20TIMESTAMP%20%{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 <> and <> with a URL encoded UTC date string in this format: YYYY-MM-DD HH:mm:SS, and and replace <> with the URL encoded recipient’s email)

1
2
3
curl --request GET \
 --url 'https://api.sendgrid.com/v3/messages?limit=10&query=last_event_time%20BETWEEN%20TIMESTAMP%20%{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 if it 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
  • 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)

Query Unencoded example
msg_id msg_id="filter0307p1las1-16816-5A023E36-1.0"
from_email from_email="testing@sendgrid.net"
subject subject="This is a subject test"
to_email to_email="example@example.com"
status status="processed"
template_id template_id="8f0d27bc-cf8f-42d3-b951-3990af7d0619"
template_name template_name="example_template"
campaign_name campaign_name="example_campaign"
campaign_id campaign_id="1453849"
api_key_id api_key_id="SG.xxxxxxxxxxxxxxxx" (everything before the middle dot in the API key)
api_key_name api_key_name="test_name"
events status="processed"
originating_ip - this is the IP address of the person sending the message originating_ip="4.77.777.77"
categories - custom tags that you create categories="category_example"
unique_args - custom tracking arguments that you can attach to SMTP API calls unique_args="example argument"
outbound_ip - this is the SendGrid dedicated IP address used to send the email outbound_ip="4.77.777.77"
last_event_time last_event_time="2017-11-07T23:13:58Z"
clicks clicks="0"
unsubscribe_group_name unsubscribe_group_name="Global Unsubscribes"
unsubscribe_group_id unsubscribe_group_id="1041"
teammate - teamates username teammate="my_username"

Additional Resources