Email Activity (beta)

Retrieve all IP addresses **This endpoint allows you to retrieve a list of all assigned and unassigned IPs.** Response includes warm up status, pools, assigned subusers, and reverse DNS info. The start_date field corresponds to when warmup started for that IP. A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.

Retrieve all assigned IPs **This endpoint allows you to retrieve only assigned IP addresses.** A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.

Retrieve all IP pools an IP address belongs to **This endpoint allows you to see which IP pools a particular IP address has been added to.** The same IP address can be added to multiple IP pools. A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.

Retrieve all IP pools **This endpoint allows you to get all of your IP pools.**

Retrieve all the IPs in a specified pool **This endpoint allows you to get all of the IP addresses that are in a specific IP pool.**

Get remaining IPs count **This endpoint gets amount of IP Addresses that can still be created during a given period and the price of those IPs.**

Retrieve all IPs currently in warmup **This endpoint allows you to retrieve all of your IP addresses that are currently warming up.**

Retrieve the warmup status for a specific IP address **This endpoint allows you to retrieve the warmup status for a specific IP address.** You can retrieve all of your warming IPs using the "Retrieve all IPs currently in warmup" endpoint.

Validate batch ID **This endpoint allows you to validate a batch ID.** When you pass a valid `batch_id` to this endpoint, it will return a `200` status code and the batch ID itself. If you pass an invalid `batch_id` to the endpoint, you will receive a `400` level status code and an error message. A `batch_id` does not need to be assigned to a scheduled send to be considered valid. A successful response means only that the `batch_id` has been created, but it does not indicate that it has been associated with a send.

Retrieve all mail settings **This endpoint allows you to retrieve a list of all mail settings.** Each setting will be returned with an `enabled` status set to `true` or `false` and a short description that explains what the setting does.

Retrieve address whitelist mail settings **This endpoint allows you to retrieve your current email address whitelist settings.** The Address Whitelist setting allows you to specify email addresses or domains for which mail should never be suppressed. For example, if you own the domain `example.com`, and one or more of your recipients use `[email protected]` addresses, placing `example.com` in the address whitelist setting instructs Twilio SendGrid to ignore all bounces, blocks, and unsubscribes logged for that domain. In other words, all bounces, blocks, and unsubscribes will still be sent to `example.com` as if they were sent under normal sending conditions.

Retrieve bounce purge mail settings **This endpoint allows you to retrieve your current bounce and purge settings.** The Bounce Perge setting allows you to set a schedule that Twilio SendGrid will use to automatically delete contacts from your soft and hard bounce suppression lists. A hard bounce occurs when an email message has been returned to the sender because the recipient's address is invalid. A hard bounce might occur because the domain name doesn't exist or because the recipient is unknown. A soft bounce occurs when an email message reaches the recipient's mail server but is bounced back undelivered before it actually reaches the recipient. A soft bounce might occur because the recipient's inbox is full. You can also manage this setting in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings). You can manage your bounces manually using the [Bounces API](https://sendgrid.api-docs.io/v3.0/bounces-api) or the [Bounces menu in the Twilio SendGrid App](https://app.sendgrid.com/suppressions/bounces).

Retrieve footer mail settings **This endpoint allows you to retrieve your current Footer mail settings.** The Footer setting will insert a custom footer at the bottom of your text and HTML email message bodies. You can insert your HTML or plain text directly using the "Update footer mail settings" endpoint, or you can create the footer using the [Mail Settings menu in the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings).

Retrieve forward bounce mail settings **This endpoint allows you to retrieve your current bounce forwarding mail settings.** Enabling the Forward Bounce setting allows you to specify `email` addresses to which bounce reports will be forwarded. This endpoint returns the email address you have set to receive forwarded bounces and an `enabled` status indicating if the setting is active.

Retrieve forward spam mail settings **This endpoint allows you to retrieve your current Forward Spam mail settings.** Enabling the Forward Spam setting allows you to specify `email` addresses to which spam reports will be forwarded. This endpoint returns any email address(es) you have set to receive forwarded spam and an `enabled` status indicating if the setting is active.

Retrieve legacy template mail settings **This endpoint allows you to retrieve your current legacy email template settings.** This setting refers to our original email templates. We currently support more fully featured [Dynamic Transactional Templates](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/). The legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages. For instructions on using legacy templates, see how to ["Create and Edit Legacy Transactional Templates](https://sendgrid.com/docs/ui/sending-email/create-and-edit-legacy-transactional-templates/). For help migrating to our current template system, see ["Migrating from Legacy Templates"](https://sendgrid.com/docs/ui/sending-email/migrating-from-legacy-templates/).

Retrieve email statistics by mailbox provider. **This endpoint allows you to retrieve your email statistics segmented by recipient mailbox provider.** **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/).

Get All Existing Exports **Use this endpoint to retrieve details of all current exported jobs**. It will return an array of objects, each of which records an export job in flight or recently completed. Each object's `export_type` field will tell you which kind of export it is and its `status` field will indicate what stage of processing it has reached. Exports which are `ready` will be accompanied by a `urls` field which lists the URLs of the export's downloadable files — there will be more than one if you specified a maximum file size in your initial export request. Use this endpoint if you have exports in flight but do not know their IDs, which are required for the "Export Contacts Status" endpoint. Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Import Contacts Status **This endpoint can be used to check the status of a contact import job**. Use the `job_id` from the "Import Contacts," "Add or Update a Contact," or "Delete Contacts" endpoints as the `id` in the path parameter. If there is an error with your `PUT` request, download the `errors_url` file and open it to view more details. The job `status` field indicates whether the job is `pending`, `completed`, `errored`, or `failed`. Pending means not started. Completed means finished without any errors. Errored means finished with some errors. Failed means finshed with all errors, or the job was entirely unprocessable: for example, if you attempt to import file format we do not support. The `results` object will have fields depending on the job type. Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Get List of Segments **This endpoint allows you to retrieve a list of segments.** The query param `parent_list_ids` is treated as a filter. Any match will be returned. 0 matches will return a response code of 200 with an empty `results` array. `parent_list_ids` | `no_parent_list_id` | `result` -----------------:|:--------------------:|:------------- empty | false | all segments values | false | segments filtered by list_ids values | true | segments filtered by list_ids and segments with no parent list_ids empty | true | segments with no parent list_ids

Get Segment by ID **This endpoint allows you to retrieve a single segment by ID.**

Get All Single Sends **This endpoint allows you to retrieve all your Single Sends.** Returns all of your Single Sends with condensed details about each, including the Single Sends' IDs. For more details about an individual Single Send, pass the Single Send's ID to the `/marketing/singlesends/{id}` endpoint.

Get All Categories **This endpoint allows you to retrieve all the categories associated with your Single Sends.** This endpoint will return your latest 1,000 categories.

Get Single Send by ID **This endpoint allows you to retrieve details about one Single Send using a Single Send ID.** You can retrieve all of your Single Sends by making a GET request to the `/marketing/singlesends` endpoint.

Get Total Contact Count **This endpoint returns the total number of contacts you have stored.** Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Export Contacts Status **This endpoint can be used to check the status of a contact export job**. To use this call, you will need the `id` from the "Export Contacts" call. If you would like to download a list, take the `id` that is returned from the "Export Contacts" endpoint and make an API request here to get the `urls`. Once you have the list of URLs, make a `GET` request on each URL to download your CSV file(s). Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Get a Contact by ID **This endpoint returns the full details and all fields for the specified contact**. The "Get Contacts by Emails" endpoint can be used to get the ID of a contact. Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Get Sample Contacts **This endpoint will return up to 50 of the most recent contacts uploaded or attached to a list**. This list will then be sorted by email address. The full contact count is also returned. Please note that pagination of the contacts has been deprecated. Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Get All Field Definitions **This endpoint retrieves all defined Custom Fields and Reserved Fields.**

Get All Lists **This endpoint returns an array of all of your contact lists.**

Get a List by ID **This endpoint returns data about a specific list.** Setting the optional parameter `contact_sample=true` returns the `contact_sample` in the response body. Up to fifty of the most recent contacts uploaded or attached to a list will be returned, sorted alphabetically, by email address. The full contact count is also returned.

Get List Contact Count **This endpoint returns the number of contacts on a specific list.**

Returns a list of all partner settings. **This endpoint allows you to retrieve a list of all partner settings that you can enable.** Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [Partners documentation](https://sendgrid.com/docs/ui/account-and-settings/partners/).

Returns all New Relic partner settings. **This endpoint allows you to retrieve your current New Relic partner settings.** Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [Partners documentation](https://sendgrid.com/docs/ui/account-and-settings/partners/). By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [SendGrid for New Relic documentation](https://sendgrid.com/docs/ui/analytics-and-reporting/tracking-stats-using-new-relic/).

Retrieve a list of scopes for which this user has access. **This endpoint returns a list of all scopes that this user has access to.** API Keys are used to authenticate with [SendGrid's v3 API](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. This endpoint returns all the scopes assigned to the key you use to authenticate with it. To retrieve the scopes assigned to another key, you can pass an API key ID to the "Retrieve an existing API key" endpoint. For a more detailed explanation of how you can use API Key permissions, please visit our [API Keys documentation](https://sendgrid.com/docs/ui/account-and-settings/api-keys/).

Get List of Segments **The Segmentation V2 API is currently in private beta. If you'd like to be added to the beta, please fill out this [form]({https://docs.google.com/forms/d/e/1FAIpQLSd5zwC9dRk8lAp1oTWjdGc-aSY69flW_7wnutvKBhpUluSnfQ/viewform)** The query param `parent_list_ids` is treated as a filter. Any match will be returned. 0 matches will return a response code of 200 with an empty `results` array. `parent_list_ids` | `no_parent_list_id` | `result` -----------------:|:--------------------:|:------------- empty | false | all segments values | false | segments filtered by list_ids values | true | segments filtered by list_ids and segments with no parent list_ids empty | true | segments with no parent list_ids

Get Segment by ID **The Segmentation V2 API is currently in private beta. If you'd like to be added to the beta, please fill out this [form]({https://docs.google.com/forms/d/e/1FAIpQLSd5zwC9dRk8lAp1oTWjdGc-aSY69flW_7wnutvKBhpUluSnfQ/viewform)**

Get an SSO Certificate **This endpoint allows you to retrieve an individual SSO certificate.**

Get All SSO Integrations **This endpoint allows you to retrieve all SSO integrations tied to your Twilio SendGrid account.** The IDs returned by this endpoint can be used by the APIs additional endpoints to modify your SSO integrations.

Get an SSO Integration **This endpoint allows you to retrieve an SSO integration by ID.** You can retrieve the IDs for your configurations from the response provided by the "Get All SSO Integrations" endpoint.

Get All SSO Certificates by Integration **This endpoint allows you to retrieve all your IdP configurations by configuration ID.** The `integration_id` expected by this endpoint is the `id` returned in the response by the "Get All SSO Integrations" endpoint.

Retrieve global email statistics **This endpoint allows you to retrieve all of your global email statistics between a given date range.** Parent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their own stats.

List all Subusers **This endpoint allows you to retrieve a list of all of your subusers.** You can choose to retrieve specific subusers as well as limit the results that come back from the API.

Retrieve Subuser Reputations **This endpoint allows you to request the reputations for your subusers.** Subuser sender reputations give a good idea how well a sender is doing with regards to how recipients and recipient servers react to the mail that is being received. When a bounce, spam report, or other negative action happens on a sent email, it will affect your sender rating.

Retrieve email statistics for your subusers. **This endpoint allows you to retrieve the email statistics for the given subusers.** You may retrieve statistics for up to 10 different subusers by including an additional _subusers_ parameter for each additional subuser.

Retrieve monthly stats for all subusers **This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.** When using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics: `bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`.

Retrieve the totals for each email statistic metric for all subusers. **This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.**

Retrieve monitor settings for a subuser

Retrieve the monthly email statistics for a single subuser **This endpoint allows you to retrive the monthly email statistics for a specific subuser.** When using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics: `bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`.

Retrieve all blocks **This endpoint allows you to retrieve all email addresses that are currently on your blocks list.**