Email Activity (beta)

Validate an email **This endpoint allows you to validate an email address.**

Create Verified Sender Request **This endpoint allows you to create a new Sender Identify**. Upon successful submission of a `POST` request to this endpoint, an identity will be created, and a verification email will be sent to the address assigned to the `from_email` field. You must complete the verification process using the sent email to fully verify the sender. If you need to resend the verification email, you can do so with the Resend Verified Sender Request, `/resend/{id}`, endpoint. If you need to authenticate a domain rather than a Single Sender, see the [Domain Authentication API](https://sendgrid.api-docs.io/v3.0/domain-authentication/authenticate-a-domain).

Resend Verified Sender Request **This endpoint allows you to resend a verification email to a specified Sender Identity**. Passing the `id` assigned to a Sender Identity to this endpoint will resend a verification email to the `from_address` associated with the Sender Identity. This can be useful if someone loses their verification email or needs to have it resent for any other reason. You can retrieve the IDs associated with Sender Identities by passing a "Get All Verified Senders" endpoint.

Email DNS records to a co-worker **This endpoint is used to share DNS records with a colleagues** Use this endpoint to send SendGrid-generated DNS record information to a co-worker so they can enter it into your DNS provider to validate your domain and link branding. What type of records are sent will depend on whether you have chosen Automated Security or not. When using Automated Security, SendGrid provides you with three CNAME records. If you turn Automated Security off, you are instead given TXT and MX records. If you pass a `link_id` to this endpoint, the generated email will supply the DNS records necessary to complete [Link Branding](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/) setup. If you pass a `domain_id` to this endpoint, the generated email will supply the DNS records needed to complete [Domain Authentication](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/). Passing both IDs will generate an email with the records needed to complete both setup steps. You can retrieve all your domain IDs from the returned `id` fields for each domain using the "List all authenticated domains" endpoint. You can retrieve all of your link IDs using the "Retrieve all branded links" endpoint.

Authenticate a domain **This endpoint allows you to authenticate a domain.** If you are authenticating a domain for a subuser, you have two options: 1. Use the "username" parameter. This allows you to authenticate a domain on behalf of your subuser. This means the subuser is able to see and modify the authenticated domain. 2. Use the Association workflow (see Associate Domain section). This allows you to authenticate a domain created by the parent to a subuser. This means the subuser will default to the assigned domain, but will not be able to see or modify that authenticated domain. However, if the subuser authenticates their own domain it will overwrite the assigned domain.

Associate an authenticated domain with a given user. **This endpoint allows you to associate a specific authenticated domain with 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.

Add an IP to an authenticated domain **This endpoint allows you to add an IP address to an authenticated domain.**

Validate a domain authentication. **This endpoint allows you to validate an authenticated domain. If it fails, it will return an error message describing why the domain could not be validated.**

Set up reverse DNS **This endpoint allows you to set up reverse DNS.**

Validate a reverse DNS record **This endpoint allows you to validate a reverse DNS record.** Always check the `valid` property of the response’s `validation_results.a_record` object. This field will indicate whether it was possible to validate the reverse DNS record. If the `validation_results.a_record.valid` is `false`, this indicates only that Twilio SendGrid could not determine the validity your reverse DNS record — it may still be valid. If validity couldn’t be determined, you can check the value of `validation_results.a_record.reason` to find out why. You can retrieve the IDs associated with all your reverse DNS records using the "Retrieve all reverse DNS records" endpoint.

Create a branded link **This endpoint allows you to create a new branded link.** To create the link branding, supply the root domain and, optionally, the subdomain — these go into separate fields in your request body. The root domain should match your FROM email address. If you provide a subdomain, it must be different from the subdomain you used for authenticating your domain. You can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.

Validate a branded link **This endpoint allows you to validate a branded link.** You can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.

Associate a branded link with a subuser **This endpoint allows you to associate a branded link with a subuser account.** 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).

Update Design **This endpoint allows you to edit a design**. The Design API supports PATCH requests, which allow you to make partial updates to a single design. Passing data to a specific field will update only the data stored in that field; all other fields will be unaltered. For example, updating a design's name requires that you make a PATCH request to this endpoint with data specified for the `name` field only. ``` { "name": "" } ```

Update API key name and scopes **This endpoint allows you to update the name and scopes of a given API key.** You must pass this endpoint a JSON request body with a `name` field and a `scopes` array containing at least one scope. The `name` and `scopes` fields will be used to update the key associated with the `api_key_id` in the request URL. If you need to update a key's scopes only, pass the `name` field with the key's existing name; the `name` will not be modified. If you need to update a key's name only, use the "Update API key name" endpoint. 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.

Rename an IP pool **This endpoint allows you to update the name of an IP pool.**

Schedule Single Send **This endpoint allows you to schedule a Single Send for future delivery using a Single Send ID.** To schedule a Single Send, you must pass a date string in ISO 8601 time format (yyyy-MM-ddTHH:mm:ssZ) using the required `send_at` field. For example, the ISO 8601 format for 9:00 AM UTC on May 6, 2020 would be `2020-05-06T09:00:00Z`. You may also pass the string `"now"` to send the Single Send immediately.

Add or Update a Contact **This endpoint allows the [upsert](https://en.wiktionary.org/wiki/upsert) (insert or update) of up to 30,000 contacts, or 6MB of data, whichever is lower**. Because the creation and update of contacts is an asynchronous process, the response will not contain immediate feedback on the processing of your upserted contacts. Rather, it will contain an HTTP 202 response indicating the contacts are queued for processing or an HTTP 4XX error containing validation errors. Should you wish to get the resulting contact's ID or confirm your contacts have been updated or added, you can use the "Get Contacts by Emails" endpoint. Please note that custom fields need to have been already created if you wish to set their values for the contacts being upserted. To do this, please use the "Create Custom Field Definition" endpoint. You will see a `job_id` in the response to your request. This can be used to check the status of your upsert job. To do so, please use the "Import Contacts Status" endpoint. If the contact already exists in the system, any entries submitted via this endpoint will update the existing contact. The contact to update will be determined only by the `email` field and any fields omitted from the request will remain as they were. A contact's ID cannot be used to update the contact. The email field will be changed to all lower-case. If a contact is added with an email that exists but contains capital letters, the existing contact with the all lower-case email will be updated. Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Import Contacts **This endpoint allows a CSV upload containing up to one million contacts or 5GB of data, whichever is smaller.** Imports take place asynchronously: the endpoint returns a URL (`upload_uri`) and HTTP headers (`upload_headers`) which can subsequently be used to `PUT` a file of contacts to be imported into our system. Uploaded CSV files may also be [gzip-compressed](https://en.wikipedia.org/wiki/Gzip). In either case, you must include the field `file_type` with the value `csv` in your request body. The `field_mappings` paramter is a respective list of field definition IDs to map the uploaded CSV columns to. It allows you to use CSVs where one or more columns are skipped (`null`) or remapped to the contact field. For example, if `field_mappings` is set to `[null, "w1", "_rf1"]`, this means skip column 0, map column 1 to the custom field with the ID `w1`, and map column 2 to the reserved field with the ID `_rf1`. See the "Get All Field Definitions" endpoint to fetch your custom and reserved field IDs to use with `field_mappings`. Once you recieve the response body you can then initiate a **second** API call where you use the supplied URL and HTTP header to upload your file. For example: `curl --upload-file "file/path.csv" "URL_GIVEN" -H 'HEADER_GIVEN'` If you'd like to monitor the status of your import job, use the `job_id` and the "Import Contacts Status" endpoint. Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Update IPs assigned to a subuser **This endpoint allows you update your subusers' assigned IP.** Each subuser should be assigned to an IP address from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have one or more of their own IP addresses as well. More information: * [How to request more IPs](https://sendgrid.com/docs/ui/account-and-settings/dedicated-ip-addresses/) * [Setup Reverse DNS](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/)

Update Monitor Settings for a subuser

Update your account email address **This endpoint allows you to update the email address currently on file for your account.**

Update your password **This endpoint allows you to update your password.**

Update your username **This endpoint allows you to update the username for your account.**

Create API keys **This endpoint allows you to create a new API Key for the user.** To create your initial SendGrid API Key, you should [use the SendGrid App](https://app.sendgrid.com/settings/api_keys). Once you have created a first key with scopes to manage additional API keys, you can use this API for all other key management. > There is a limit of 100 API Keys on your account. A JSON request body containing a `name` property is required when making requests to this endpoint. If the number of maximum keys, 100, is reached, a `403` status will be returned. Though the `name` field is required, it does not need to be unique. A unique API key ID will be generated for each key you create and returned in the response body. It is not necessary to pass a `scopes` field to the API when creating a key, but you should be aware that omitting the `scopes` field from your request will create a key with "Full Access" permissions by default. 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.

Get Automation Click Tracking Stats by ID **This endpoint lets you retrieve click-tracking stats for a single Automation**. The stats returned list the URLs embedded in your Automation and the number of clicks each one received. Responses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100. You can retrieve a specific page of responses with the `page_token` query string parameter.

Get Automation Stats by ID **This endpoint allows you to retrieve stats for a single Automation using its ID.** Multiple Automation IDs can be retrieved using the "Get All Automation Stats" endpoint. Once you have an ID, this endpoint will return detailed stats for the single automation specified. You may constrain the stats returned using the `start_date` and `end_date` query string parameters. You can also use the `group_by` and `aggregated_by` query string parameters to further refine the stats returned.

Export Automation Stats **This endpoint allows you to export Automation stats as CSV data**. You can specify one Automation or many: include as many Automation IDs as you need, separating them with commas, as the value of the `ids` query string paramter. The data is returned as plain text response but in CSV format, so your application making the call can present the information in whatever way is most appropriate, or just save the data as a `.csv` file.

Get Single Send Click Tracking Stats by ID **This endpoint lets you retrieve click-tracking stats for one Single Send**. The stats returned list the URLs embedded in the specified Single Send and the number of clicks each one received. Responses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100. You can retrieve a specific page of responses with the `page_token` query string parameter.

Get Single Send Stats by ID **This endpoint allows you to retrieve stats for an individual Single Send using a Single Send ID.** Multiple Single Send IDs can be retrieved using the "Get All Single Sends Stats" endpoint. Once you have an ID, this endpoint will return detailed stats for the Single Send specified. You may constrain the stats returned using the `start_date` and `end_date` query string parameters. You can also use the `group_by` and `aggregated_by` query string parameters to further refine the stats returned.

Export Single Send Stats **This endpoint allows you to export Single Send stats as .CSV data**. You can specify one Single Send or many: include as many Single Send IDs as you need, separating them with commas, as the value of the `ids` query string paramter. The data is returned as plain text response but in .CSV format, so your application making the call can present the information in whatever way is most appropriate, or just save the data as a .csv file.

Get All Automation Stats **This endpoint allows you to retrieve stats for all your Automations.** By default, all of your Automations will be returned, but you can specify a selection by passing in a comma-separated list of Automation IDs as the value of the query string parameter `automation_ids`. Responses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100. You can retrieve a specific page of responses with the `page_token` query string parameter.

Get All Single Sends Stats **This endpoint allows you to retrieve stats for all your Single Sends.** By default, all of your Single Sends will be returned, but you can specify a selection by passing in a comma-separated list of Single Send IDs as the value of the query string parameter `singlesend_ids`. Responses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100. You can retrieve a specific page of responses with the `page_token` query string parameter.

Create Design **This endpoint allows you to create a new design**. You can add a new design by passing data, including a string of HTML email content, to `/designs`. When creating designs from scratch, be aware of the styling constraints inherent to many email clients. For a list of best practices, see our guide to [Cross-Platform Email Design](https://sendgrid.com/docs/ui/sending-email/cross-platform-html-design/). The Design Library can also convert your design’s HTML elements into drag and drop modules that are editable in the Designs Library user interface. For more, visit the [Design and Code Editor documentation](https://sendgrid.com/docs/ui/sending-email/editor/#drag--drop-markup). Because the `/designs` endpoint makes it easy to add designs, you can create a design with your preferred tooling or migrate designs you already own without relying on the Design Library UI.