Skip to content

Commit

Permalink
Add documentation for email activity api
Browse files Browse the repository at this point in the history
  • Loading branch information
Stuart Reed committed Oct 3, 2018
1 parent f0449de commit 31fd868
Show file tree
Hide file tree
Showing 4 changed files with 229 additions and 0 deletions.
215 changes: 215 additions & 0 deletions packages/client/USAGE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ client.setApiKey(process.env.SENDGRID_API_KEY);
* [MAIL](#mail)
* [MAIL SETTINGS](#mail-settings)
* [MAILBOX PROVIDERS](#mailbox-providers)
* [MESSAGES](#messages)
* [PARTNER SETTINGS](#partner-settings)
* [SCOPES](#scopes)
* [SENDERS](#senders)
Expand Down Expand Up @@ -3089,6 +3090,220 @@ Advanced Stats provide a more in-depth view of your email statistics and the act
console.log(response.body);
})
```
<a name="messages"></a>
# MESSAGES

## Filter all messages
> In order to gain access to the Email Activity Feed API, you must purchase [additional email activity history](https://app.sendgrid.com/settings/billing/addons/email_activity).
Filter all messages to search your Email Activity. All queries need to be [URL encoded](https://meyerweb.com/eric/tools/dencoder/), 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`

You can filter by other operators besides `=`. We also accept `!=`, `<`, and `>`.

For a tutorial on how to get started, check out [Getting Started with the Email Activity API](https://sendgrid.com/docs/API_Reference/Web_API_v3/Tutorials/getting_started_email_activity_api.html).

**Full list of basic query types and examples:**
(replace the data in quotes with the information you want to query)

<table>
<tr>
<th><b>Query</b></th>
<th><b>Unencoded example</b> (put this one into the try it out query - it'll automatically encode it for you)</th>
<th><b>Encoded example</b> (use this one in your code)</th>
</tr>
<tr>
<td><code>msg_id</code></td>
<td><code>msg_id="filter0307p1las1-16816-5A023E36-1.0"</code></td>
<td><code>msg_id%3D%22filter0307p1las1-16816-5A023E36-1.0%22</code></td>
</tr>
<tr>
<td><code>from_email</code></td>
<td><code>from_email="testing@sendgrid.net"</code></td>
<td><code>from_email%3D%22testing%40sendgrid.net%22</code></td>
</tr>
<tr>
<td><code>subject</code></td>
<td><code>subject="This is a subject test"</code></td>
<td><code>subject%22This%20is%20a%20subject%20test%22</code></td>
</tr>
<tr>
<td><code>to_email</code></td>
<td><code>to_email="example@example.com"</code></td>
<td><code>to_email%3D%22example%40example.com%22</code></td>
</tr>
<tr>
<td><code>status</code></td>
<td><code>status="processed"</code></td>
<td><code>status%22processed%22</code></td>
</tr>
<tr>
<td><code>template_id</code></td>
<td><code>template_id="8f0d27bc-cf8f-42d3-b951-3990af7d0619"</code></td>
<td><code>template_id%3D%228f0d27bc-cf8f-42d3-b951-3990af7d0619%22</code></td>
</tr>
<tr>
<td><code>template_name</code></td>
<td><code>template_name="example_template"</code></td>
<td><code>template_name%3D%22example_template%22</code></td>
</tr>
<tr>
<td><code>campaign_name</code></td>
<td><code>campaign_name="example_campaign"</code></td>
<td><code>campaign_name%3D%22example_campaign%22</code></td>
</tr>
<tr>
<td><code>campaign_id</code></td>
<td><code>campaign_id="1453849"</code></td>
<td><code>campaign_id%3D%221453849%22</code></td>
</tr>
<tr>
<td><code>api_key_id</code></td>
<td><code>api_key_id="-hVjtoFgGUNPq3DPPPkJN3mCIDIwrl3qdFZcqYKnlq94"</code> (everything after the middle dot in the API key)</td>
<td><code>api_key_id%3D%22-hVjtoFgGUNPq3DPPPkJN3mCIDIwrl3qdFZcqYKnlq94%22</code></td>
</tr>
<tr>
<td><code>api_key_name</code></td>
<td><code>api_key_name="test_name"</code></td>
<td><code>api_key_name%3D%22test_name%22</code></td>
</tr>
<tr>
<td><code>events</code></td>
<td><code>status="processed"</code></td>
<td><code>status%3D%22processed%22</code></td>
</tr>
<tr>
<td><code>originating_ip</code> - this is the IP address of the person sending the message</td>
<td><code>originating_ip="4.77.777.77"</code></td>
<td><code>originating_ip%3D%224.77.777.77%22</code></td>
</tr>
<tr>
<td><code>categories</code> - custom tags that you create</td>
<td><code>categories="category_example"</code></td>
<td><code>categories="category_example"</code></td>
</tr>
<tr>
<td><code>unique_args</code> - custom tracking arguments that you can attach to SMTP API calls</td>
<td><code>unique_args="example argument"</code></td>
<td><code>unique_args%3D%22example%20argument%22</code></td>
</tr>
<tr>
<td><code>outbound_ip</code> - this is the SendGrid dedicated IP address used to send the email</td>
<td><code>outbound_ip="4.77.777.77"</code></td>
<td><code>outbound_ip%3D%224.77.777.77%22</code></td>
</tr>
<tr>
<td><code>last_event_time</code></td>
<td><code>last_event_time="2017-11-07T23:13:58Z"</code></td>
<td><code>last_event_time%3D%E2%80%9C2017-11-07T23%3A13%3A58Z%E2%80%9D</code></td>
</tr>
<tr>
<td><code>clicks</code></td>
<td><code>clicks="0"</code></td>
<td><code>clicks%3D%220%22</code></td>
</tr>
<tr>
<td><code>unsubscribe_group_name</code></td>
<td><code>unsubscribe_group_name="Global Unsubscribes"</code></td>
<td><code>unsubscribe_group_name%3D%22Global%20Unsubscribes%22</code></td>
</tr>
<tr>
<td><code>unsubscribe_group_id</code></td>
<td><code>unsubscribe_group_id="1041"</code></td>
<td><code>unsubscribe_group_id%3D%221041%22</code></td>
</tr>
<tr>
<td><code>teammate</code> - teamates username</td>
<td><code>teammate="my_username"</code></td>
<td><code>teammate%3D%22my_username%22</code></td>
</tr>
</table>

For information about building combined queries, see [Building compound Email Activity queries](https://sendgrid.com/docs/API_Reference/Web_API_v3/Tutorials/getting_started_email_activity_api.html#-Creating-compound-queries).

### GET /messages


```javascript
request.method = 'GET';
request.url = '/v3/messages';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Filter messages by message ID

> In order to gain access to the Email Activity Feed API, you must purchase [additional email activity history](https://app.sendgrid.com/settings/billing/addons/email_activity).
Get all of the details about the specified message.

### GET /messages/{msg_id}


```javascript
request.method = 'GET';
request.url = '/v3/messages/{msg_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Request a CSV

> In order to gain access to the Email Activity Feed API, you must purchase [additional email activity history](https://app.sendgrid.com/settings/billing/addons/email_activity).
This request kicks of a process to generate a CSV file. When the file is generated, the email that is listed as the account owner gets an email that links out to the file that is ready for download. The link expires in 3 days.

The CSV fill contain the last 1 million messages. This endpoint will be rate limited to 1 request every 12 hours.

### POST /messages/download


```javascript
request.method = 'POST';
request.url = '/v3/messages/download';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Download CSV

> In order to gain access to the Email Activity Feed API, you must purchase [additional email activity history](https://app.sendgrid.com/settings/billing/addons/email_activity).
Download the CSV that you requested with the POST Request a CSV.

When the file is generated, the email that is listed as the account owner gets an email that links out to the file that is ready for download. The link expires in 3 days.

The CSV fill contain the last 1 million messages. This endpoint will be rate limited to 1 request every 12 hours.

### GET /messages/download/{download_uuid}


```javascript
request.method = 'POST';
request.url = '/v3/messages/download';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
<a name="partner-settings"></a>
# PARTNER SETTINGS

Expand Down
8 changes: 8 additions & 0 deletions packages/client/USE_CASES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ This documentation provides examples for specific SendGrid v3 API non mail/send

* [How to Setup a Domain Whitelabel](#domain-white-label)
* [How to View Email Statistics](#email-stats)
* [How to use the Email Activity Feed](#email-activity-feed)


<a name="domain-white-label"></a>
Expand All @@ -19,3 +20,10 @@ Find more information about all of SendGrid's whitelabeling related documentatio
You can find documentation for how to view your email statistics via the UI [here](https://app.sendgrid.com/statistics) and via API [here](https://github.com/sendgrid/sendgrid-nodejs/blob/master/packages/client/USAGE.md#stats).

Alternatively, we can post events to a URL of your choice via our [Event Webhook](https://sendgrid.com/docs/API_Reference/Webhooks/event.html) about events that occur as SendGrid processes your email.

<a name="email-activity-feed">
# How to use the Email Activity Feed

You can find documentation for how to use the Email Activity Feed via the UI [here](https://sendgrid.com/docs/ui/analytics-and-reporting/email-activity-feed/) and via API [here](https://github.com/sendgrid/sendgrid-nodejs/blob/master/packages/client/USAGE.md#messages).

Find more information about getting started with the Email Activity Feed API [here](https://sendgrid.com/docs/API_Reference/Web_API_v3/Tutorials/getting_started_email_activity_api.html).
1 change: 1 addition & 0 deletions use-cases/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ This documentation provides examples for specific SendGrid v3 API use cases. Ple
* [CC, BCC and Reply To](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/cc-bcc-reply-to.md)
* [Flexible Email Address Fields](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/flexible-address-fields.md)
* [Handling Success/Failure/Errors](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/success-failure-errors.md)
* [Show Email Activity](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/email-activity.md)
* [Advanced Usage](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/advanced.md)
* [Transactional Templates](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/transactional-templates.md)
* [Legacy Transactional Templates](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/transactional-legacy-templates.md)
Expand Down
5 changes: 5 additions & 0 deletions use-cases/email-activity.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# How to View Email Activity

You can find documentation for how to use the Email Activity Feed via the UI [here](https://sendgrid.com/docs/ui/analytics-and-reporting/email-activity-feed/) and via API [here](https://github.com/sendgrid/sendgrid-nodejs/blob/master/packages/client/USAGE.md#messages).

Find more information about getting started with the Email Activity Feed API [here](https://sendgrid.com/docs/API_Reference/Web_API_v3/Tutorials/getting_started_email_activity_api.html).

0 comments on commit 31fd868

Please sign in to comment.