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 messages by message ID

Filter messages by message ID

GET /messages/{msg_id}

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

Get all of the details about the specified message.

Authentication

  • API Key

Headers

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required
Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required

Path Parameters

msg_id
string

The ID of the message you are requesting details for.

required

Responses

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
required
msg_id
string

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

required
subject
string

The email's subject line.

required
to_email
string

The intended recipient's email address.

format: email
required
status
string

The message's status.

Allowed Values: processed, delivered, not delivered
required
template_id
string

The ID associated with a Twilio SendGrid email template used to format the message.

required
asm_group_id
integer

The unsubscribe group associated with this email.

minimum: 1
required
teammate
string

Teammate's username

maxLength: 64minLength: 0pattern: ^$|^[A-Za-z0-9]+
required
api_key_id
string

The ID of the API Key used to authenticate the sending request for the message.

maxLength: 50minLength: 3pattern: ^[A-Za-z0-9]+
required
events
array[object]

List of events related to email message

required
event_name
string

Name of event

Allowed Values: bounced, opened, clicked, processed, dropped, delivered, deferred, spam_report, unsubscribe, group_unsubscribe, group_resubscribe
processed
string

The date when the event was processed

reason
string

Explanation of what caused the message to be "bounced", "deferred", or "blocked". Usually contains error message from the server - e.g. message from gmail why mail was deferred.

maxLength: 1024
attempt_num
integer

Used with "deferred" events to indicate the attempt number out of 10. One "deferred" entry will exists under events array for each time a message was deferred with error message from the server.

maximum: 10minimum: 1
url
string

Used with "clicked" event to indicate which url the user clicked.

pattern: ^((http[s]?|ftp):\/)?\/?([^:\/\s]+)((\/\w+)*\/)([\w\-\.]+[^#?\s]+)(.*)?(#[\w\-]+)?$
bounce_type
string

Use to distinguish between types of bounces

Allowed Values: soft, hard
http_user_agent
string

Client recipient used to click or open message

mx_server
string

The MX server that received the email. For example, mx.gmail.com

originating_ip
string

This is the IP of the user who sent the message.

format: ipv4
required
categories
array[string]

Categories users associated to the message

required
unique_args
string

JSON hash of key-value pairs associated with the message.

default: Null
required
outbound_ip
string

IP used to send to the remote Mail Transfer Agent.

format: ipv4
required
outbound_ip_type
string

Whether or not the outbound IP is dedicated vs shared

Allowed Values: dedicated, shared
required
{
  "from_email": "jane_doe@example.com",
  "msg_id": "in aliquip id aliqua",
  "subject": "est incididunt adipisicing pariatur",
  "to_email": "send@test.com",
  "status": "not delivered",
  "template_id": "123e4567-e89b-12d3-a456-426655440000",
  "asm_group_id": 11376349,
  "teammate": "",
  "api_key_id": "sdfsdfsdf123",
  "originating_ip": "2.3.4.5",
  "events": [
    {
      "event_name": "bounced",
      "processed": 1492453589,
      "server_response": "some error message"
    }
  ],
  "categories": [
    "hi",
    "bye"
  ],
  "unique_args": "{'key': 'value'}",
  "outbound_ip": "1.2.3.4",
  "outbound_ip_type": "dedicated"
}
object
errors
array[object]
message
string
field
string
object
errors
array[object]
message
string

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.