Linkbranding 7 endpoints

DELETE /whitelabel/links/subuser 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.

Your request will receive a response with a 204 status code if the disassociation was successful.

operationId: LinkBranding_disassociateBrandedLinkFromSubuser

Parameters

Name	In	Required	Type	Description
username	query	required	string	The username of the subuser account that you want to disassociate a branded link from.

Responses

204 —

DELETE /whitelabel/links/subuser

GET /whitelabel/links/subuser Retrieve a subuser's branded link

This endpoint allows you to retrieve the branded link associated with 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 then 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.

operationId: LinkBranding_getSubuserBrandedLink

Parameters

Name	In	Required	Type	Description
username	query	required	string	The username of the subuser to retrieve associated branded links for.

Responses

200 —

GET /whitelabel/links/subuser

DELETE /whitelabel/links/{id} 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.

operationId: LinkBranding_deleteBrandedLink

Parameters

Name	In	Required	Type	Description
id	path	required	integer	The ID of the branded link you want to retrieve.
on-behalf-of	header	optional	string	—

Responses

204 —

DELETE /whitelabel/links/{id}

GET /whitelabel/links/{id} Retrieve a branded link

This endpoint allows you to retrieve a specific branded link by providing its ID.

You can submit this request as one of your subusers if you include their ID in the on-behalf-of header in the request.

operationId: LinkBranding_getBrandedLinkById

Parameters

Name	In	Required	Type	Description
id	path	required	integer	The ID of the branded link you want to retrieve.
on-behalf-of	header	optional	string	—

Responses

200 —

GET /whitelabel/links/{id}

PATCH /whitelabel/links/{id} Update a branded link

This endpoint allows you to update a specific branded link. You can use this endpoint to change a branded link’s default status.

You can submit this request as one of your subusers if you include their ID in the on-behalf-of header in the request.

operationId: LinkBranding_updateBrandedLink

Parameters

Name	In	Required	Type	Description
id	path	required	integer	The ID of the branded link you want to retrieve.
on-behalf-of	header	optional	string	—

Request Body

application/json

schema LinkBrandingUpdateBrandedLinkRequest

Property	Type	Required
default	boolean	optional

Responses

200 —

PATCH /whitelabel/links/{id}

POST /whitelabel/links/{id}/validate 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.

operationId: LinkBranding_validateBrandedLink

Parameters

Name	In	Required	Type	Description
id	path	required	integer	The ID of the branded link that you want to validate.
on-behalf-of	header	optional	string	—

Responses

200 —

500 —

POST /whitelabel/links/{id}/validate

POST /whitelabel/links/{link_id}/subuser Associate a branded link with a subuser

This endpoint allows you to associate a branded link with a subuser account.

operationId: LinkBranding_associateBrandedLinkWithSubuser

Parameters

Name	In	Required	Type	Description
link_id	path	required	integer	The ID of the branded link you want to associate.

Request Body

application/json

schema LinkBrandingAssociateBrandedLinkWithSubuserRequest

Property	Type	Required
username	string	optional

Responses

200 —

POST /whitelabel/links/{link_id}/subuser

Lists 7 endpoints

GET /marketing/lists Get All Lists

This endpoint returns an array of all of your contact lists.

operationId: Lists_getAll

Parameters

Name	In	Required	Type	Description
page_size	query	optional	number	Maximum number of elements to return. Defaults to 100, returns 1000 max
page_token	query	optional	string	—

Responses

200 —

GET /marketing/lists

POST /marketing/lists Create List

This endpoint creates a new contacts list.

Once you create a list, you can use the UI to trigger an automation every time you add a new contact to the list.

A link to the newly created object is in _metadata.

operationId: Lists_createNewList

Request Body

application/json

schema ListsCreateNewListRequest

Property	Type	Required
name	string	required

Responses

200 —

400 —

POST /marketing/lists

DELETE /marketing/lists/{id} Delete a list

This endpoint allows you to deletes a specific list.

Optionally, you can also delete contacts associated to the list. The query parameter, delete_contacts=true, will delete the list and start an asynchronous job to delete associated contacts.

operationId: Lists_deleteList

Parameters

Name	In	Required	Type	Description
id	path	required	string	—
delete_contacts	query	optional	boolean	Flag indicates that all contacts on the list are also to be deleted.

Responses

200 —

204 —

404 —

DELETE /marketing/lists/{id}

GET /marketing/lists/{id} 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.

operationId: Lists_getListById

Parameters

Name	In	Required	Type	Description
id	path	required	string	—
contact_sample	query	optional	boolean	Setting this parameter to the true will cause the contact_sample to be returned

Responses

200 —

404 —

GET /marketing/lists/{id}

PATCH /marketing/lists/{id} Update List

This endpoint updates the name of a list.

operationId: Lists_updateName

Parameters

Name	In	Required	Type	Description
id	path	required	string	—

Request Body

application/json

schema ListsUpdateNameRequest

Property	Type	Required
name	string	optional

Responses

200 —

400 —

404 —

PATCH /marketing/lists/{id}

DELETE /marketing/lists/{id}/contacts Remove Contacts from a List

This endpoint allows you to remove contacts from a given list.

The contacts will not be deleted. Only their list membership will be changed.

operationId: Lists_removeContactsFromList

Parameters

Name	In	Required	Type	Description
id	path	required	string	—
contact_ids	query	required	string	comma separated list of contact ids

Responses

202 —

400 —

404 —

DELETE /marketing/lists/{id}/contacts

GET /marketing/lists/{id}/contacts/count Get List Contact Count

This endpoint returns the number of contacts on a specific list.

operationId: Lists_contactCountGet

Parameters

Name	In	Required	Type	Description
id	path	required	string	—

Responses

200 —

404 —

GET /marketing/lists/{id}/contacts/count

Mailsend 1 endpoints

POST /mail/send v3 Mail Send

The Mail Send endpoint allows you to send email over SendGrid’s v3 Web API, the most recent version of our API. If you are looking for documentation about the v2 Mail Send endpoint, see our v2 API Reference.

Helper Libraries

Twilio SendGrid provides libraries to help you quickly and easily integrate with the v3 Web API in 7 different languages:

Dynamic Transactional Templates and Handlebars

In order to send a dynamic template, specify the template ID with the template_id parameter.

To specify handlebar substitutions, define your substitutions in the request JSON with this syntax:

"dynamic_template_data": {
      "guest": "Jane Doe",
      "partysize": "4",
      "english": true,
      "date": "April 1st, 2021"
    }

For more information about Dynamic Transactional Templates and Handlebars, see our documentation and reference pages.

Mail Body Compression

Mail body compression is available to some high volume accounts. Talk to your CSM if you are interested in this functionality. Mail body compression works by setting up a JSON payload as defined on this page, then compressing it with gzip (the gzip file can be no more than 30mb).

To use mail body compression:

Add a Content-Encoding header, with a value of gzip.
a. Content-Encoding: gzip
Send the gzip as a data-binary.
a. --data-binary '@data.json.gz'

Multiple Reply-To Emails

Using reply_to_list allows senders to include more than one recipient email address to receive reply and/or bounce messages from the recipient of the email.

Usage Considerations

reply_to is mutually exclusive with reply_to_list. If both are used, then the API call will be rejected.
The reply_to_list object, when used, must at least have an email parameter and may also contain a name parameter.
Each email address in the reply_to_list should be unique.
There is a limit of 1000 reply_to_list emails per mail/send request.
In SMTP calls, we will omit any invalid emails.

Possible 400 Error Messages

reply_to is mutually exclusive with reply_to_list.
The reply_to_list object, when used, must at least have an email parameter and may also contain a name parameter.
Each email address in the reply_to_list should be unique.
There is a limit of X reply_to emails per mail/send request.
The reply_to_list email does not contain a valid address.
The reply_to_list email exceeds the maximum total length of X characters.
The reply_to_list email parameter is required.

operationId: MailSend_v3EmailSend

Request Body

application/json

schema MailSendV3EmailSendRequest

Property	Type	Required
asm	object	optional
└ group_id	integer	required
└ groups_to_display	array	optional
from	object	required
└ name	string	optional
└ email	string	required
content	array	required
└ type	string	required
└ value	string	required
headers	object	optional
send_at	integer	optional
subject	string	required
batch_id	string	optional
reply_to	object	optional
└ name	string	optional
└ email	string	required
categories	array	optional
attachments	array	optional
└ type	string	optional
└ content	string	required
└ filename	string	required
└ content_id	string	optional
└ disposition	string	optional
custom_args	string	optional
template_id	string	optional
ip_pool_name	string	optional
mail_settings	object	optional
└ footer	object	optional
└ html	string	optional
└ text	string	optional
└ enable	boolean	optional
└ sandbox_mode	object	optional
└ enable	boolean	optional
└ bypass_list_management	object	optional
└ enable	boolean	optional
└ bypass_spam_management	object	optional
└ enable	boolean	optional
└ bypass_bounce_management	object	optional
└ enable	boolean	optional
└ bypass_unsubscribe_management	object	optional
└ enable	boolean	optional
reply_to_list	array	optional
└ name	string	optional
└ email	string	required
personalizations	array	required
└ cc	array	optional
└ name	string	optional
└ email	string	required
└ to	array	required
└ name	string	optional
└ email	string	required
└ bcc	array	optional
└ name	string	optional
└ email	string	required
└ from	object	optional
└ name	string	optional
└ email	string	required
└ headers	object	optional
└ send_at	integer	optional
└ subject	string	optional
└ custom_args	object	optional
└ substitutions	object	optional
└ dynamic_template_data	object	optional
tracking_settings	object	optional
└ ganalytics	object	optional
└ enable	boolean	optional
└ utm_term	string	optional
└ utm_medium	string	optional
└ utm_source	string	optional
└ utm_content	string	optional
└ utm_campaign	string	optional
└ open_tracking	object	optional
└ enable	boolean	optional
└ substitution_tag	string	optional
└ click_tracking	object	optional
└ enable	boolean	optional
└ enable_text	boolean	optional
└ subscription_tracking	object	optional
└ html	string	optional
└ text	string	optional
└ enable	boolean	optional
└ substitution_tag	string	optional

Responses

202 —

400 —

401 —

403 —

404 —

413 —

500 —

POST /mail/send

Marketingcampaignsstats 8 endpoints

GET /marketing/stats/automations 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.

operationId: MarketingCampaignsStats_getAllAutomationStats

Parameters

Name	In	Required	Type	Description
automation_ids	query	optional	array	This endpoint returns all automation IDs if no `automation_ids` are specified.
page_size	query	optional	integer	The number of elements you want returned on each page.
page_token	query	optional	string	The stats endpoints are paginated. To get the next page, call the passed `_metadata.next` URL. If `_metadata.prev` doesn’t exist, you’re at the first page. Similarly, if `_metadata.next` is not present, you’re at the last page.

Responses

200 —

400 —

GET /marketing/stats/automations

GET /marketing/stats/automations/export 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.

operationId: MarketingCampaignsStats_exportAutomationStats

Parameters

Name	In	Required	Type	Description
ids	query	optional	array	The IDs of Automations for which to export stats.
timezone	query	optional	string	The IANA Area/Region string representing the timezone in which the stats are to be presented; i.e. `"America/Chicago"`. This parameter changes the timezone format only; it does not alter which stats are returned.

Responses

200 —

400 —

GET /marketing/stats/automations/export

GET /marketing/stats/automations/{id} 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.

operationId: MarketingCampaignsStats_getStatsById

Parameters

Name	In	Required	Type	Description
id	path	required	string	—
group_by	query	optional	array	Automations can have multiple steps. Including `step_id` as a `group_by` metric allows further granularity of stats.
step_ids	query	optional	array	Comma-separated list of `step_ids` that you want the link stats for.
aggregated_by	query	optional	string	Dictates how the stats are time-sliced. Currently, `"total"` and `"day"` are supported.
start_date	query	optional	string	Format: `YYYY-MM-DD`. If this parameter is included, the stats’ start date is included in the search.
end_date	query	optional	string	Format: `YYYY-MM-DD`.If this parameter is included, the stats’ end date is included in the search.
timezone	query	optional	string	IANA Area/Region string representing the timezone in which the stats are to be presented, e.g., “America/Chicago”.
page_size	query	optional	integer	The number of elements you want returned on each page.
page_token	query	optional	string	The stats endpoints are paginated. To get the next page, call the passed `_metadata.next` URL. If `_metadata.prev` doesn’t exist, you’re at the first page. Similarly, if `_metadata.next` is not present, you’re at the last page.

Responses

200 —

400 —

404 —

GET /marketing/stats/automations/{id}

GET /marketing/stats/automations/{id}/links 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.

operationId: MarketingCampaignsStats_getAutomationLinkStat

Parameters

Name	In	Required	Type	Description
id	path	required	string	The ID of the Automation you want to get click tracking stats for.
group_by	query	optional	array	Automations can have multiple steps. Including `step_id` as a `group_by` metric allows further granularity of stats.
step_ids	query	optional	array	Comma-separated list of `step_ids` that you want the link stats for.
page_size	query	optional	integer	The number of elements you want returned on each page.
page_token	query	optional	string	The stats endpoints are paginated. To get the next page, call the passed `_metadata.next` URL. If `_metadata.prev` doesn’t exist, you’re at the first page. Similarly, if `_metadata.next` is not present, you’re at the last page.

Responses

200 —

400 —

404 —

GET /marketing/stats/automations/{id}/links

GET /marketing/stats/singlesends 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.

operationId: MarketingCampaignsStats_getAllSingleSendsStats

Parameters

Name	In	Required	Type	Description
singlesend_ids	query	optional	array	This endpoint returns all Single Send IDs if no IDs are included in `singlesend_ids`.
page_size	query	optional	integer	The number of elements you want returned on each page.
page_token	query	optional	string	The stats endpoints are paginated. To get the next page, call the passed `_metadata.next` URL. If `_metadata.prev` doesn’t exist, you’re at the first page. Similarly, if `_metadata.next` is not present, you’re at the last page.

Responses

200 —

400 —

GET /marketing/stats/singlesends

GET /marketing/stats/singlesends/export 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.

operationId: MarketingCampaignsStats_exportSingleSendStats

Parameters

Name	In	Required	Type	Description
ids	query	optional	array	The IDs of Single Sends for which to export stats.
timezone	query	optional	string	The IANA Area/Region string representing the timezone in which the stats are to be presented; i.e. `"America/Chicago"`. This parameter changes the timezone format only; it does not alter which stats are returned.

Responses

200 —

400 —

GET /marketing/stats/singlesends/export

GET /marketing/stats/singlesends/{id} 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.

operationId: MarketingCampaignsStats_getSingleSendStatsById

Parameters

Name	In	Required	Type	Description
id	path	required	string	—
aggregated_by	query	optional	string	Dictates how the stats are time-sliced. Currently, `"total"` and `"day"` are supported.
start_date	query	optional	string	Format: `YYYY-MM-DD`. If this parameter is included, the stats’ start date is included in the search.
end_date	query	optional	string	Format: `YYYY-MM-DD`.If this parameter is included, the stats’ end date is included in the search.
timezone	query	optional	string	IANA Area/Region string representing the timezone in which the stats are to be presented, e.g., “America/Chicago”.
page_size	query	optional	integer	The number of elements you want returned on each page.
page_token	query	optional	string	The stats endpoints are paginated. To get the next page, call the passed `_metadata.next` URL. If `_metadata.prev` doesn’t exist, you’re at the first page. Similarly, if `_metadata.next` is not present, you’re at the last page.
group_by	query	optional	array	A/B Single Sends have multiple variation IDs and phase IDs. Including these additional fields allows further granularity of stats by these fields.

Responses

200 —

400 —

404 —

GET /marketing/stats/singlesends/{id}

GET /marketing/stats/singlesends/{id}/links 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.

operationId: MarketingCampaignsStats_getSingleSendLinkStatById

Parameters

Name	In	Required	Type	Description
id	path	required	string	—
page_size	query	optional	integer	The number of elements you want returned on each page.
page_token	query	optional	string	The stats endpoints are paginated. To get the next page, call the passed `_metadata.next` URL. If `_metadata.prev` doesn’t exist, you’re at the first page. Similarly, if `_metadata.next` is not present, you’re at the last page.
group_by	query	optional	array	A/B Single Sends have multiple variation IDs and phase IDs. Including these additional fields allows further granularity of stats by these fields.
ab_variation_id	query	optional	string	—
ab_phase_id	query	optional	string	—

Responses

200 —

400 —

404 —

GET /marketing/stats/singlesends/{id}/links

Query 2 endpoints

GET /messages 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, 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=“testing@sendgrid.net”	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=”example@example.com”	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.

Coming soon, example compound queries: limit + to email + date

operationId: Query_filterMessages

Parameters

Name	In	Required	Type	Description
query	query	required	string	Use the query syntax to filter your email activity.
limit	query	optional	number	The number of messages returned. This parameter must be greater than 0 and less than or equal to 1000
X-Query-Id	header	optional	string	—
X-Cursor	header	optional	string	—

Responses

200 —

400 —

429 —

GET /messages

GET /messages/{msg_id} 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.

operationId: Query_messageDetails

Parameters

Name	In	Required	Type	Description
msg_id	path	required	string	The ID of the message you are requesting details for.

Responses

200 —

400 —

404 —

429 —

GET /messages/{msg_id}

Reversedns 5 endpoints

GET /whitelabel/ips Retrieve all reverse DNS records

This endpoint allows you to retrieve all of the Reverse DNS records created by this account.

You may include a search key by using the ip query string parameter. This enables you to perform a prefix search for a given IP segment (e.g., ?ip="192.").

Use the limit query string parameter to reduce the number of records returned. All records will be returned if you have fewer records than the specified limit.

The offset query string parameter allows you to specify a non-zero index from which records will be returned. For example, if you have ten records, ?offset=5 will return the last five records (at indexes 5 through 9). The list starts at index zero.

operationId: ReverseDns_getAllReverseDnsRecords

Parameters

Name	In	Required	Type	Description
limit	query	optional	integer	The maximum number of results to retrieve.
offset	query	optional	integer	The point in the list of results to begin retrieving IP addresses from.
ip	query	optional	string	The IP address segment that you’d like to use in a prefix search.
on-behalf-of	header	optional	string	—

Responses

200 —

GET /whitelabel/ips

POST /whitelabel/ips Set up reverse DNS

This endpoint allows you to set up reverse DNS.

operationId: ReverseDns_setUpReverseDns

Parameters

Name	In	Required	Type	Description
on-behalf-of	header	optional	string	—

Request Body

application/json

schema ReverseDnsSetUpReverseDnsRequest

Property	Type	Required
ip	string	required
domain	string	required
subdomain	string	optional

Responses

201 —

POST /whitelabel/ips

DELETE /whitelabel/ips/{id} 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.

operationId: ReverseDns_deleteReverseDnsRecord

Parameters

Name	In	Required	Type	Description
id	path	required	string	The ID of the reverse DNS record that you would like to retrieve.
on-behalf-of	header	optional	string	—

Responses

204 —

DELETE /whitelabel/ips/{id}

GET /whitelabel/ips/{id} Retrieve a reverse DNS record

This endpoint allows you to retrieve a reverse DNS record.

You can retrieve the IDs associated with all your reverse DNS records using the “Retrieve all reverse DNS records” endpoint.

operationId: ReverseDns_getRecord

Parameters

Name	In	Required	Type	Description
id	path	required	string	The ID of the reverse DNS record that you would like to retrieve.
on-behalf-of	header	optional	string	—

Responses

200 —

GET /whitelabel/ips/{id}

POST /whitelabel/ips/{id}/validate 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.

operationId: ReverseDns_validateRecord

Parameters

Name	In	Required	Type	Description
id	path	required	string	The ID of the reverse DNS record that you would like to validate.
on-behalf-of	header	optional	string	—

Responses

200 —

404

Unexpected error in API call. See HTTP response body for details.

500 —

POST /whitelabel/ips/{id}/validate

Segmentingcontacts 6 endpoints

GET /marketing/segments 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

operationId: SegmentingContacts_listSegments

Parameters

Name	In	Required	Type	Description
parent_list_ids	query	optional	string	A comma separated list of list ids to be used when searching for segments with the specified parent_list_id, no more than 50 is allowed
no_parent_list_id	query	optional	boolean	If set to `true` segments with an empty value of `parent_list_id` will be returned in the filter. If the value is not present it defaults to ‘false’.

Responses

200 —

401 —

403 —

404 —

500 —

GET /marketing/segments

POST /marketing/segments Create Segment

This endpoint allows you to create a segment.

operationId: SegmentingContacts_createNewSegment

Request Body

application/json

schema SegmentingContactsCreateNewSegmentRequest

Property	Type	Required
name	string	required
query_dsl	string	required
parent_list_ids	array	optional
parent_list_id	string	optional

Responses

201 —

401 —

403 —

404 —

500 —

POST /marketing/segments

POST /marketing/segments/delete Bulk Delete Segments

This endpoint allows you to delete segments in bulk.

If the segments are used by automations or the segments do not exist in the database, the segment IDs that could not be deleted along with automation IDs that are associated to those segments will be returned.

operationId: SegmentingContacts_bulkDeleteSegments

Request Body

application/json

schema SegmentingContactsBulkDeleteSegmentsRequest

Property	Type	Required
ids	array	optional

Responses

200 —

202 —

400 —

401 —

403 —

404 —

500 —

POST /marketing/segments/delete

DELETE /marketing/segments/{segment_id} Delete Segment

This endpoint allows you to delete a segment by segment_id.

Note that deleting a segment does not delete the contacts associated with the segment by default. Contacts associated with a deleted segment will remain in your list of all contacts and any other segments they belong to.

operationId: SegmentingContacts_deleteById

Parameters

Name	In	Required	Type	Description
segment_id	path	required	string	—

Responses

202 —

400 —

401 —

403 —

404 —

500 —

DELETE /marketing/segments/{segment_id}

GET /marketing/segments/{segment_id} Get Segment by ID

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

operationId: SegmentingContacts_getById

Parameters

Name	In	Required	Type	Description
segment_id	path	required	string	—
query_json	query	optional	boolean	Defaults to `false`. Set to `true` to return the parsed SQL AST as a JSON object in the field `query_json`

Responses

200 —

401 —

403 —

404 —

500 —

GET /marketing/segments/{segment_id}

PATCH /marketing/segments/{segment_id} Update Segment

This endpoint allows you to update a segment.

Segment name needs to be unique. A user can not update a segment name to an existing one.

operationId: SegmentingContacts_updateSegmentById

Parameters

Name	In	Required	Type	Description
segment_id	path	required	string	—

Request Body

application/json

schema segment_write_v2

Property	Type	Required
name	string	required
query_dsl	string	required
parent_list_ids	array	optional

Responses

200 —

401 —

403 —

404 —

500 —

PATCH /marketing/segments/{segment_id}

Segmentingcontactsv2beta 5 endpoints

GET /marketing/segments/2.0 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

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

operationId: GET_segments

Parameters

Name	In	Required	Type	Description
parent_list_ids	query	optional	string	A comma separated list up to 50 in size, to filter segments on. Only segments that have any of these list ids as the parent list will be retrieved. This is different from the parameter of the same name used when creating a segment.
no_parent_list_id	query	optional	boolean	If set to `true` segments with an empty value of `parent_list_id` will be returned in the filter. If the value is not present it defaults to ‘false’.

Responses

200 —

400 —

404 —

500 —

GET /marketing/segments/2.0

POST /marketing/segments/2.0 Create Segment

The Segmentation V2 API is currently in private beta. If you’d like to be added to the beta, please fill out this form

Segment name has to be unique. A user can not create a new segment with an existing segment name.

operationId: POST_segments

Request Body

application/json

schema segment_write_v2

Property	Type	Required
name	string	required
query_dsl	string	required
parent_list_ids	array	optional

Responses

201 —

400 —

404 —

429 —

500 —

POST /marketing/segments/2.0

DELETE /marketing/segments/2.0/{segment_id} Delete segment

The Segmentation V2 API is currently in private beta. If you’d like to be added to the beta, please fill out this form

operationId: SegmentingContactsV2Beta_deleteSegmentById

Parameters

Name	In	Required	Type	Description
segment_id	path	required	string	—

Responses

202 —

400 —

404 —

500 —

DELETE /marketing/segments/2.0/{segment_id}

GET /marketing/segments/2.0/{segment_id} 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

operationId: SegmentingContactsV2Beta_getById

Parameters

Name	In	Required	Type	Description
segment_id	path	required	string	—
contacts_sample	query	optional	boolean	Defaults to `true`. Set to `false` to exclude the contacts_sample in the response.

Responses

200 —

400 —

500 —

GET /marketing/segments/2.0/{segment_id}

PATCH /marketing/segments/2.0/{segment_id} Update Segment

The Segmentation V2 API is currently in private beta. If you’d like to be added to the beta, please fill out this form

Segment name has to be unique. A user can not create a new segment with an existing segment name.

operationId: SegmentingContactsV2Beta_updateSegmentById

Parameters

Name	In	Required	Type	Description
segment_id	path	required	string	—

Request Body

application/json

schema segment_update

Property	Type	Required
name	string	optional
query_dsl	string	optional

Responses

200 —

400 —

429 —

500 —

PATCH /marketing/segments/2.0/{segment_id}

Sendtestemail 1 endpoints

POST /marketing/test/send_email Send a Test Marketing Email

This endpoint allows you to send a test marketing email to a list of email addresses.

Before sending a marketing message, you can test it using this endpoint. You may specify up to 10 contacts in the emails request body field. You must also specify a template_id and include either a from_address or sender_id. You can manage your templates with the Twilio SendGrid App or the Transactional Templates API.

Please note that this endpoint works with Dynamic Transactional Templates only. Legacy Transactional Templates will not be delivered.

For more information about managing Dynamic Transactional Templates, see How to Send Email with Dynamic Transactional Templates.

You can also test your Single Sends in the Twilio SendGrid Marketing Campaigns UI.

operationId: SendTestEmail_toContacts

Request Body

application/json

schema SendTestEmailToContactsRequest

Property	Type	Required
emails	array	required
sender_id	integer	optional
template_id	string	required
from_address	string	optional
version_id_override	string	optional
suppression_group_id	integer	optional
custom_unsubscribe_url	string	optional

Responses

202 —

400 —

POST /marketing/test/send_email

Senderidentitiesapi 6 endpoints

GET /senders Get all Sender Identities

This endpoint allows you to retrieve a list of all sender identities that have been created for your account.

operationId: SenderIdentitiesApi_getAll

Parameters

Name	In	Required	Type	Description
on-behalf-of	header	optional	string	—

Responses

200 —

GET /senders

POST /senders Create a Sender Identity

This endpoint allows you to create a new sender identity.

You may create up to 100 unique sender identities.

operationId: POST_senders

Parameters

Name	In	Required	Type	Description
on-behalf-of	header	optional	string	—

Request Body

application/json

schema PostSendersRequest

Property	Type	Required
zip	string	optional
city	string	required
from	object	optional
state	string	optional
address	string	required
country	string	required
nickname	string	required
reply_to	object	optional
address_2	string	optional

Responses

201 —

400 —

POST /senders

DELETE /senders/{sender_id} Delete a Sender Identity

This endoint allows you to delete one of your sender identities.

operationId: SenderIdentitiesApi_deleteSenderIdentity

Parameters

Name	In	Required	Type	Description
sender_id	path	required	integer	The ID of the sender identity that you want to retrieve.
on-behalf-of	header	optional	string	—

Responses

204 —

403 —

404 —

DELETE /senders/{sender_id}

GET /senders/{sender_id} View a Sender Identity

This endpoint allows you to retrieve a specific sender identity.

operationId: SenderIdentitiesApi_viewSenderIdentity

Parameters

Name	In	Required	Type	Description
sender_id	path	required	integer	The ID of the sender identity that you want to retrieve.
on-behalf-of	header	optional	string	—

Responses

200 —

404 —

GET /senders/{sender_id}

PATCH /senders/{sender_id} Update a Sender Identity

This endpoint allows you to update a sender identity.

Updates to from.email require re-verification.

Partial updates are allowed, but fields that are marked as “required” in the POST (create) endpoint must not be nil if that field is included in the PATCH request.

operationId: SenderIdentitiesApi_updateSenderIdentity

Parameters

Name	In	Required	Type	Description
sender_id	path	required	integer	The ID of the sender identity that you want to retrieve.
on-behalf-of	header	optional	string	—

Request Body

application/json

schema sender-id-request

Property	Type	Required
zip	string	optional
city	string	optional
from	object	optional
└ name	string	optional
└ email	string	optional
state	string	optional
address	string	optional
country	string	optional
nickname	string	optional
reply_to	object	optional
└ name	string	optional
└ email	string	optional
address_2	string	optional

Responses

200 —

400 —

403 —

404 —

PATCH /senders/{sender_id}

POST /senders/{sender_id}/resend_verification Resend Sender Identity Verification

This enpdoint allows you to resend a sender identity verification email.

operationId: SenderIdentitiesApi_resendVerificationEmail

Parameters

Name	In	Required	Type	Description
sender_id	path	required	integer	The ID of the sender identity for which you would like to resend a verification email.
on-behalf-of	header	optional	string	—

Responses

204 —

400 —

404 —

POST /senders/{sender_id}/resend_verification

Senderverification 2 endpoints

GET /verified_senders Get All Verified Senders

This endpoint allows you to retrieve all the Sender Identities associated with an account.

This endpoint will return both verified and unverified senders.

You can limit the number of results returned using the limit, lastSeenID, and id query string parameters.

limit allows you to specify an exact number of Sender Identities to return.
lastSeenID will return senders with an ID number occuring after the passed in ID. In other words, the lastSeenID provides a starting point from which SendGrid will iterate to find Sender Identities associated with your account.
id will return information about only the Sender Identity passed in the request.

operationId: SenderVerification_getAllSenderIdentities

Parameters

Name	In	Required	Type	Description
limit	query	optional	number	—
lastSeenID	query	optional	number	—
id	query	optional	integer	—

Responses

200 —

401 —

403 —

404 —

500 —

GET /verified_senders

POST /verified_senders 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.

operationId: SenderVerification_createVerifiedSenderRequest

Request Body

application/json

schema verified-sender-request-schema

Property	Type	Required
zip	string	optional
city	string	optional
state	string	optional
address	string	optional
country	string	optional
address2	string	optional
nickname	string	required
reply_to	string	required
from_name	string	optional
from_email	string	required
reply_to_name	string	optional

Responses

201 —

400 —

401 —

403 —

404 —

500 —

POST /verified_senders