Email Activity (beta)

Delete an authenticated domain. **This endpoint allows you to delete an authenticated domain.**

Remove an IP from an authenticated domain. **This endpoint allows you to remove an IP address from that domain's authentication.**

Disassociate an authenticated domain from a given user. **This endpoint allows you to disassociate a specific authenticated domain from a subuser.** Authenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain authentication. To associate an authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The parent may then associate the authenticated domain via the subuser management tools.

Delete a reverse DNS record **This endpoint allows you to delete a reverse DNS record.** A call to this endpoint will respond with a 204 status code if the deletion was successful. You can retrieve the IDs associated with all your reverse DNS records using the "Retrieve all reverse DNS records" endpoint.

Delete a branded link **This endpoint allows you to delete a branded link.** Your request will receive a response with a 204 status code if the deletion was successful. The call does not return the link's details, so if you wish to record these make sure you call the "Retrieve a branded link" endpoint *before* you request its deletion. You can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.

Disassociate a branded link from a subuser **This endpoint allows you to take a branded link away from a subuser.** Link branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers). Your request will receive a response with a 204 status code if the disassociation was successful.

Get Design **This endpoint allows you to retrieve a single design**. A GET request to `/designs/{id}` will retrieve details about a specific design in your Design Library. This endpoint is valuable when retrieving information stored in a field that you wish to update using a PATCH request.

Filter all 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](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` **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=“[email protected]” | 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="[email protected]" | 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](https://docs.google.com/a/sendgrid.com/document/d/1fWoKTFNfg5UUsB6t9KuIcSo9CetKF_T0bGfWJ_gdPCs/edit?usp=sharing). Coming soon, example compound queries: limit + to email + date

Get SendGrid Pre-built Design **This endpoint allows you to retrieve a single pre-built design**. A GET request to `/designs/pre-builts/{id}` will retrieve details about a specific pre-built design. This endpoint is valuable when retrieving details about a pre-built design that you wish to duplicate and modify.

Filter messages by message 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.

Retrieve all recent access attempts **This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API.**

Retrieve a list of currently allowed IPs **This endpoint allows you to retrieve a list of IP addresses that are currently allowed to access your account.** Each IP address returned to you will have `created_at` and `updated_at` dates. Each IP will also be associated with an `id` that can be used to remove the address from your allow list.

Retrieve a specific allowed IP **This endpoint allows you to retreive a specific IP address that has been allowed to access your account.** You must include the ID for the specific IP address you want to retrieve in your call. You can retrieve the IDs associated with your allowed IP addresses using the "Retrieve a list of currently allowed IPs" endpoint.

Retrieve all alerts **This endpoint allows you to retrieve all of your alerts.** Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. * Usage alerts allow you to set the threshold at which an alert will be sent. * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". For more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).

Retrieve a specific alert **This endpoint allows you to retrieve a specific alert.** Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. * Usage alerts allow you to set the threshold at which an alert will be sent. * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". For more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).

Retrieve all API Keys belonging to the authenticated user **This endpoint allows you to retrieve all API Keys that belong to the authenticated user.** A successful response from this API will include all available API keys' names and IDs. For security reasons, there is not a way to retrieve the key itself after it's created. If you lose your API key, you must create a new one. Only the "Create API keys" endpoint will return a key to you and only at the time of creation. An `api_key_id` can be used to update or delete the key, as well as retrieve the key's details, such as its scopes.

Retrieve an existing API Key **This endpoint allows you to retrieve a single API key using an `api_key_id`.** The endpoint will return a key's name, ID, and scopes. If the API Key ID does not, exist a `404` status will be returned. See the [API Key Permissions List](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization) for all available scopes. An API key's scopes can be updated after creation using the "Update API keys" endpoint.

Retrieve all suppression groups associated with the user. **This endpoint allows you to retrieve a list of all suppression groups created by this user.** This endpoint can also return information for multiple group IDs that you include in your request. To add a group ID to your request, simply append `?id=123456&id=123456`, with the appropriate group IDs.

Get information on a single suppression group. **This endpoint allows you to retrieve a single suppression group.**

Retrieve all suppressions for a suppression group **This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.**

Retrieve all suppressions **This endpoint allows you to retrieve a list of all suppressions.**

Retrieve all suppression groups for an email address **This endpoint returns a list of all groups from which the given email address has been unsubscribed.**

Retrieve a Global Suppression **This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.** If the email address you include in the URL path parameter `{email}` is already globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned.

Retrieve email statistics by browser. **This endpoint allows you to retrieve your email statistics segmented by browser type.** **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).

Retrieve all Campaigns **This endpoint allows you to retrieve a list of all of your campaigns.** Returns campaigns in reverse order they were created (newest first). Returns an empty array if no campaigns exist.

Retrieve a single campaign **This endpoint allows you to retrieve a specific campaign.**

View Scheduled Time of a Campaign **This endpoint allows you to retrieve the date and time that a campaign has been scheduled to be sent.**

Retrieve all categories **This endpoint allows you to retrieve a list of all of your categories.**

Retrieve Email Statistics for Categories **This endpoint allows you to retrieve all of your email statistics for each of your categories.** If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.

Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?] **This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.** If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.

Retrieve stats by a specific client type. **This endpoint allows you to retrieve your email statistics segmented by a specific client type.** **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. ## Available Client Types - phone - tablet - webmail - desktop Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).

Retrieve email statistics by client type. **This endpoint allows you to retrieve your email statistics segmented by client type.** **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).

Retrieve all custom fields **This endpoint allows you to retrieve all custom fields.**

Retrieve a Custom Field **This endpoint allows you to retrieve a custom field by ID.**

Retrieve all lists **This endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned.**

Retrieve a single list **This endpoint allows you to retrieve a single recipient list.**

Retrieve all recipients on a List **This endpoint allows you to retrieve all recipients on the list with the given ID.**

Retrieve recipients **This endpoint allows you to retrieve all of your Marketing Campaigns recipients.** Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved.

Retrieve the count of billable recipients **This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.** You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value.

Retrieve a Count of Recipients **This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.**

Retrieve a single recipient **This endpoint allows you to retrieve a single recipient by ID from your contact database.**

Retrieve the lists that a recipient is on **This endpoint allows you to retrieve the lists that a given recipient belongs to.** Each recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to.

Search recipients **This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.** field_name: * is a variable that is substituted for your actual custom field name from your recipient. * Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200) * If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through Mon, 02 Feb 2015 23:59:59 GMT.

Retrieve reserved fields **This endpoint allows you to list all fields that are reserved and can't be used for custom field names.**

Retrieve all segments **This endpoint allows you to retrieve all of your segments.**

Retrieve a segment **This endpoint allows you to retrieve a single segment with the given ID.**

Retrieve recipients on a segment **This endpoint allows you to retrieve all of the recipients in a segment with the given ID.**

Get Recipient Upload Status **This endpoint allows you to check the upload status of a Marketing Campaigns recipient.**

Retrieve email statistics by device type. **This endpoint allows you to retrieve your email statistics segmented by the device type.** **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. ## Available Device Types | **Device** | **Description** | **Example** | |---|---|---| | Desktop | Email software on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. | | Webmail | A web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com. | | Phone | A smart phone. | iPhone, Android, Blackberry, etc. | Tablet | A tablet computer. | iPad, android based tablet, etc. | | Other | An unrecognized device. | Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).

Retrieve email statistics by country and state/province. **This endpoint allows you to retrieve your email statistics segmented by country and state/province.** **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).