Menu

E-Mail Activity

You must purchase additional email activity history to gain access to the Email Activity Feed API.

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

Once retrieved, you can inspect the data associated with your messages to better understand your mail send. For example, you may retrieve all bounced messages or all messages with the same subject line and search for commonalities among them.

See "Getting Started with the Email Activity Feed API" for help building queries and working with the API.

You can also work with email activity in the Activity section of the Twilio SendGrid App.

Filter all messages

Filter all messages

GET /messages

This is BETA functionality. You may not have access, and we reserve the right to change functionality without notice.

Filter all messages to search your Email Activity. All queries need to be URL encoded, and have this format:

query={query_type}="{query_content}"

encoded, this would look like this:

query=type%3D%22query_content%22

for example:

Filter by a specific email - query=to_email%3D%22example%40example.com%22

Filter by subject line - query=subject%3d%22A%20Great%20Subject%22

Full list of basic query types and examples:

Filter query Unencoded Example (put this one into the try it out query - it'll automatically encode it for you) Encoded Example (use this one in your code)
msg_id msg_id=“filter0307p1las1-16816-5A023E36-1.0” msg_id%3D%22filter0307p1las1-16816-5A023E36-1.0%22
from_email from_email=“testing@sendgrid.net” from_email%3D%22testing%40sendgrid.net%22
subject subject="This is a subject test" subject%22This%20is%20a%20subject%20test%22
to_email to_email="example@example.com" to_email%3D%22example%40example.com%22
status status%22processed%22
template_id
asm_group_id
api_key_id
events status="processed" status%3D%22processed%22
originating_ip
categories
unique_args
outbound_ip
last_event_time last_event_time=“2017-11-07T23:13:58Z” last_event_time%3D%E2%80%9C2017-11-07T23%3A13%3A58Z%E2%80%9D
clicks clicks="0" clicks%3D%220%22

For information about building compound queries, and for the full query language functionality, see the query language reference.

Coming soon, example compound queries: limit + to email + date

Authentication

  • API Key

Headers

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required
X-Query-Id
string
default: None
X-Cursor
string
default: None
Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required

Query String

query
string

Use the query syntax to filter your email activity.

default: None
required
limit
integer

The number of results to return.

default: None

Responses

object
messages
array[object]
from_email
string

The 'From' email address used to deliver the message. This address should be a verified sender in your Twilio SendGrid account.

default: format: email
msg_id
string

A unique ID assigned to the message. This ID can be used to retrieve activity data for the specific message.

subject
string

The email's subject line.

to_email
string

The intended recipient's email address.

format: email
status
string

The message's status.

Allowed Values: processed, delivered, not delivered
opens_count
integer

The number of times the message was opened.

clicks_count
integer

The number of times links in the message were clicked.

last_event_time
integer

A timestamp of the last event received for the specific message.

object
errors
array[object]
required
message
string
object
errors
array[object]
message
string
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more