openapi.city
Sign in

Email Activity (beta)

Email delivery and marketing service

sendgrid.com/docs ↗
Version
1.0.0
OpenAPI
3.0.0
Endpoints
334
Schemas
545
86
Quality
Updated
3 days ago
Email email marketing communications
Use this API in your AI agent

Query structured spec data via REST or MCP. Get exactly what your agent needs.

Get API Key

Server URLs

http://api.sendgrid.com/v3

Endpoints

GET POST PUT PATCH DELETE

Apikeypermissions 1 endpoints

GET /scopes

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.

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.

operationId: GET_scopes

Parameters

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

Responses

200 —
401 —
403 —
404 —
500 —
GET /scopes

Apikeys 6 endpoints

GET /api_keys

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.

operationId: ApiKeys_getAll

Parameters

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

Responses

200 —
401 —
403 —
404 —
500 —
GET /api_keys
POST /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. 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 for all available scopes. An API key’s scopes can be updated after creation using the “Update API keys” endpoint.

operationId: ApiKeys_createKey

Parameters

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

Request Body

application/json
schema ApiKeysCreateKeyRequest
Property Type Required
name string required
scopes array optional

Responses

201 —
400 —
401 —
403 —
404 —
500 —
POST /api_keys
DELETE /api_keys/{api_key_id}

This endpoint allows you to revoke an existing API Key using an api_key_id

Authentications using a revoked API Key will fail after after some small propogation delay. If the API Key ID does not exist, a 404 status will be returned.

operationId: ApiKeys_revokeKey

Parameters

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

Responses

204 —
400 —
401 —
403 —
404 —
500 —
DELETE /api_keys/{api_key_id}
GET /api_keys/{api_key_id}

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 for all available scopes. An API key’s scopes can be updated after creation using the “Update API keys” endpoint.

operationId: ApiKeys_getByKeyId

Parameters

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

Responses

200 —
400 —
401 —
403 —
404 —
500 —
GET /api_keys/{api_key_id}
PATCH /api_keys/{api_key_id}

This endpoint allows you to update the name of an existing API Key.

You must pass this endpoint a JSON request body with a name property, which will be used to rename the key associated with the api_key_id passed in the URL.

operationId: ApiKeys_updateKeyName

Parameters

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

Request Body

application/json
schema ApiKeysUpdateKeyNameRequest
Property Type Required
name string required

Responses

200 —
400 —
401 —
403 —
404 —
500 —
PATCH /api_keys/{api_key_id}
PUT /api_keys/{api_key_id}

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 for all available scopes.

operationId: ApiKeys_updateNameAndScopes

Parameters

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

Request Body

application/json
schema ApiKeysUpdateNameAndScopesRequest
Property Type Required
name string required
scopes array optional

Responses

200 —
400 —
401 —
403 —
404 —
500 —
PUT /api_keys/{api_key_id}

Alerts 5 endpoints

GET /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.

operationId: GET_alerts

Parameters

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

Responses

200 —
GET /alerts
POST /alerts

This endpoint allows you to create a new alert.

Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. There are two types of alerts that can be created with this endpoint:

  • usage_limit allows you to set the threshold at which an alert will be sent.
  • stats_notification allows 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.

operationId: POST_alerts

Parameters

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

Request Body

application/json
schema PostAlertsRequest
Property Type Required
type string required
email_to string required
frequency string optional
percentage integer optional

Responses

201 —
400 —
POST /alerts
DELETE /alerts/{alert_id}

This endpoint allows you to delete an 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.

operationId: Alerts_deleteAlertById

Parameters

Name In Required Type Description
alert_id path required integer

The ID of the alert you would like to retrieve.
on-behalf-of header optional string —

Responses

204 —
DELETE /alerts/{alert_id}
GET /alerts/{alert_id}

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.

operationId: Alerts_getSpecificAlert

Parameters

Name In Required Type Description
alert_id path required integer

The ID of the alert you would like to retrieve.
on-behalf-of header optional string —

Responses

200 —
GET /alerts/{alert_id}
PATCH /alerts/{alert_id}

This endpoint allows you to update an 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.

operationId: Alerts_updateAlert

Parameters

Name In Required Type Description
alert_id path required integer

The ID of the alert you would like to retrieve.
on-behalf-of header optional string —

Request Body

application/json
schema AlertsUpdateAlertRequest
Property Type Required
email_to string optional
frequency string optional
percentage integer optional

Responses

200 —
PATCH /alerts/{alert_id}

Blocksapi 4 endpoints

DELETE /suppression/blocks

This endpoint allows you to delete all email addresses on your blocks list.

There are two options for deleting blocked emails:

  1. You can delete all blocked emails by setting delete_all to true in the request body.
  2. You can delete a selection of blocked emails by specifying the email addresses in the emails array of the request body.
operationId: BlocksApi_deleteAllBlockedEmails

Parameters

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

Request Body

application/json
schema BlocksApiDeleteAllBlockedEmailsRequest
Property Type Required
emails array optional
delete_all boolean optional

Responses

204 —
DELETE /suppression/blocks
GET /suppression/blocks

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

operationId: BlocksApi_getAllEmailAddresses

Parameters

Name In Required Type Description
start_time query optional integer

The start of the time range when a blocked email was created (inclusive). This is a unix timestamp.
end_time query optional integer

The end of the time range when a blocked email was created (inclusive). This is a unix timestamp.
limit query optional integer

Limit the number of results to be displayed per page.
offset query optional integer

The point in the list to begin displaying results.
on-behalf-of header optional string —

Responses

200 —
GET /suppression/blocks
DELETE /suppression/blocks/{email}

This endpoint allows you to delete a specific email address from your blocks list.

operationId: BlocksApi_deleteSpecificBlock

Parameters

Name In Required Type Description
email path required string

The email address of the specific block.
on-behalf-of header optional string —

Responses

204 —
DELETE /suppression/blocks/{email}
GET /suppression/blocks/{email}

This endpoint allows you to retrieve a specific email address from your blocks list.

operationId: BlocksApi_getSpecificBlock

Parameters

Name In Required Type Description
email path required string

The email address of the specific block.
on-behalf-of header optional string —

Responses

200 —
GET /suppression/blocks/{email}

Bouncesapi 4 endpoints

DELETE /suppression/bounces

This endpoint allows you to delete all emails on your bounces list.

There are two options for deleting bounced emails:

  1. You can delete all bounced emails by setting delete_all to true in the request body.
  2. You can delete a selection of bounced emails by specifying the email addresses in the emails array of the request body.
operationId: BouncesApi_deleteBounces

Parameters

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

Request Body

application/json
schema BouncesApiDeleteBouncesRequest
Property Type Required
emails array optional
delete_all boolean optional

Responses

204 —
401 —
DELETE /suppression/bounces
GET /suppression/bounces

This endpoint allows you to retrieve all of your bounces.

operationId: BouncesApi_getAllBounces

Parameters

Name In Required Type Description
start_time query optional integer

Refers start of the time range in unix timestamp when a bounce was created (inclusive).
end_time query optional integer

Refers end of the time range in unix timestamp when a bounce was created (inclusive).
on-behalf-of header optional string —

Responses

200 —
401 —
GET /suppression/bounces
DELETE /suppression/bounces/{email}

This endpoint allows you to remove an email address from your bounce list.

operationId: BouncesApi_removeBounce

Parameters

Name In Required Type Description
email path required string —
email_address query required string

The email address you would like to remove from the bounce list.
on-behalf-of header optional string —

Request Body

application/json
schema ContactsApiListsDeleteListByIdRequest

Responses

204 —
401 —
DELETE /suppression/bounces/{email}
GET /suppression/bounces/{email}

This endpoint allows you to retrieve a specific bounce by email address.

operationId: BouncesApi_getByEmailAddress

Parameters

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

Responses

200 —
GET /suppression/bounces/{email}

Csv(uionly) 2 endpoints

POST /messages/download

This is BETA functionality. You may not have access, and we reserve the right to change functionality without notice.

This request will kick off a backend process to generate a CSV file. Once generated, the worker will then send an email for the user download the file. The link will expire in 3 days.

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

This endpoint is similar to the GET Single Message endpoint - the only difference is that /download is added to indicate that this is a CSV download requests but the same query is used to determine what the CSV should contain.

operationId: CsvUiOnly_requestCsvDownload

Parameters

Name In Required Type Description
query query optional string

Uses a SQL like syntax to indicate which messages to include in the CSV

Responses

202 —
400 —
429 —
500 —
POST /messages/download
GET /messages/download/{download_uuid}

This endpoint will return a presigned URL that can be used to download the CSV that was requested from the “Request a CSV” endpoint.

operationId: CsvUiOnly_generateCsvDownloadUrl

Parameters

Name In Required Type Description
download_uuid path required string

UUID used to locate the download csv request entry in the DB.

This is the UUID provided in the email sent to the user when their csv file is ready to download

Responses

200 —
404 —
500 —
GET /messages/download/{download_uuid}

Campaignsapi 11 endpoints

GET /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.

operationId: GET_campaigns

Parameters

Name In Required Type Description
limit query optional integer

The number of results you would like to receive at a time.
offset query optional integer

The index of the first campaign to return, where 0 is the first campaign.
on-behalf-of header optional string —

Responses

200 —
GET /campaigns
POST /campaigns

This endpoint allows you to create a campaign.

In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign.

operationId: POST_campaigns

Parameters

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

Request Body

application/json
schema campaign_request
Property Type Required
title string required
editor string optional
ip_pool string optional
subject string optional
list_ids array optional
sender_id integer optional
categories array optional
segment_ids array optional
html_content string optional
plain_content string optional
suppression_group_id integer optional
custom_unsubscribe_url string optional

Responses

201 —
400

“title”: “title can’t be blank”
“title”: “title is too long (maximum is 100 characters)”
“categories”: “categories exceeds 10 category limit”
“html_content”: “html_content exceeds the 1MB limit”
“plain_content”: “plain_content exceeds the 1MB limit”
“sender_id”: “sender_id does not exist”
“sender_id”: “sender_id is not a verified sender identity”
“list_ids”: “list_ids do not all exist”
“segment_ids”: “segment_ids do not all exist”
“ip_pool”: “The ip pool you provided is invalid”
“suppression_group_id”: “suppression_group_id does not exist”
“unsubscribes”: “Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.”
“”: “The JSON you have submitted cannot be parsed.”
“”: “You’ve reached your limit of 250 campaigns. Please delete one or more and try again.”
401 —
POST /campaigns
DELETE /campaigns/{campaign_id}

This endpoint allows you to delete a specific campaign.

operationId: CampaignsApi_deleteCampaignById

Parameters

Name In Required Type Description
campaign_id path required integer

The id of the campaign you would like to retrieve.
on-behalf-of header optional string —

Responses

204 —
401 —
404

””: “not found”
DELETE /campaigns/{campaign_id}
GET /campaigns/{campaign_id}

This endpoint allows you to retrieve a specific campaign.

operationId: CampaignsApi_getSingleCampaign

Parameters

Name In Required Type Description
campaign_id path required integer

The id of the campaign you would like to retrieve.
on-behalf-of header optional string —

Responses

200 —
401 —
404

””: “not found”
GET /campaigns/{campaign_id}
PATCH /campaigns/{campaign_id}

This endpoint allows you to update a specific campaign.

This is especially useful if you only set up the campaign using POST /campaigns, but didn’t set many of the parameters.

operationId: CampaignsApi_updateSpecificCampaign

Parameters

Name In Required Type Description
campaign_id path required integer

The id of the campaign you would like to retrieve.
on-behalf-of header optional string —

Request Body

application/json
schema CampaignsApiUpdateSpecificCampaignRequest
Property Type Required
title string required
subject string required
categories array required
html_content string required
plain_content string required

Responses

200 —
400

“title”: “title can’t be blank”
“title”: “title is too long (maximum is 100 characters)”
“categories”: “categories exceeds 10 category limit”
“html_content”: “html_content exceeds the 1MB limit”
“plain_content”: “plain_content exceeds the 1MB limit”
“sender_id”: “sender_id does not exist”
“sender_id”: “sender_id is not a verified sender identity”
“list_ids”: “list_ids do not all exist”
“segment_ids”: “segment_ids do not all exist”
“ip_pool”: “The ip pool you provided is invalid”
“suppression_group_id”: “suppression_group_id does not exist”
“unsubscribes”: “Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.”
“”: “The JSON you have submitted cannot be parsed.”
401 —
403

””: “You may only update a campaign when it is in draft mode.”
404

””: “not found”
PATCH /campaigns/{campaign_id}
DELETE /campaigns/{campaign_id}/schedules

This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.

A successful unschedule will return a 204.
If the specified campaign is in the process of being sent, the only option is to cancel (a different method).

operationId: CampaignsApi_unscheduleCampaign

Parameters

Name In Required Type Description
campaign_id path required integer —
on-behalf-of header optional string —

Responses

204 —
403

””: “This campaign is already In Progress.”
“”: “This campaign is already Sent.”
“”: “This campaign is already Paused.”
“”: “This campaign is already Canceled.”
404

””: “not found”
DELETE /campaigns/{campaign_id}/schedules
GET /campaigns/{campaign_id}/schedules

This endpoint allows you to retrieve the date and time that a campaign has been scheduled to be sent.

operationId: CampaignsApi_getScheduledTime

Parameters

Name In Required Type Description
campaign_id path required integer —
on-behalf-of header optional string —

Responses

200 —
404

””: “not found”
GET /campaigns/{campaign_id}/schedules
PATCH /campaigns/{campaign_id}/schedules

This endpoint allows to you change the scheduled time and date for a campaign to be sent.

operationId: CampaignsApi_updateScheduledTime

Parameters

Name In Required Type Description
campaign_id path required integer —
on-behalf-of header optional string —

Request Body

application/json
schema CampaignsApiUpdateScheduledTimeRequest
Property Type Required
send_at integer required

Responses

200 —
400

””: “The JSON you have submitted cannot be parsed.”
“send_at”: “Please choose a future time for sending your campaign.”
“”:”You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing”
403

“send_at”: “You cannot update the send_at value of non-scheduled campaign.”
404

””: “not found”
PATCH /campaigns/{campaign_id}/schedules
POST /campaigns/{campaign_id}/schedules

This endpoint allows you to schedule a specific date and time for your campaign to be sent.

If you have the flexibility, it’s better to schedule mail for off-peak times. Most emails are scheduled and sent at the top of the hour or half hour. Scheduling email to avoid those times (for example, scheduling at 10:53) can result in lower deferral rates because it won’t be going through our servers at the same times as everyone else’s mail.

operationId: CampaignsApi_scheduleCampaign

Parameters

Name In Required Type Description
campaign_id path required integer —
on-behalf-of header optional string —

Request Body

application/json
schema CampaignsApiScheduleCampaignRequest
Property Type Required
send_at integer required

Responses

201 —
400

“subject”: “subject can’t be blank”
“sender_id”: “sender_id can’t be blank”
“plain_content”: “plain_content can’t be blank, please provide plain text or html content”
“list_ids”: “You must select at least 1 segment or 1 list to send to.”
“send_at”: “Please choose a future time for sending your campaign.”
“unsubscribe_tag”: “An [unsubscribe] tag in both your html and plain content is required to send a campaign.”
“suppression_group_id”: “Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign.”
“”: “The JSON you have submitted cannot be parsed.”
“”:”You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing”
401 —
403

””: “You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH.”
404

””: “not found”
POST /campaigns/{campaign_id}/schedules
POST /campaigns/{campaign_id}/schedules/now

This endpoint allows you to immediately send an existing campaign.

Normally a POST request would have a body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed.

operationId: CampaignsApi_sendCampaignNow

Parameters

Name In Required Type Description
campaign_id path required integer —
on-behalf-of header optional string —

Responses

201 —
400

“subject”: “subject can’t be blank”
“sender_id”: “sender_id can’t be blank”
“plain_content”: “plain_content can’t be blank, please provide plain text or html content”
“list_ids”: “You must select at least 1 segment or 1 list to send to.”
“unsubscribe_tag”: “An [unsubscribe] tag in both your html and plain content is required to send a campaign.”
“suppression_group_id”: “Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign.”
“”: “You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing”
401 —
403

””: “You may only send a campaign when it is in draft mode.”
404

””: “not found”
POST /campaigns/{campaign_id}/schedules/now
POST /campaigns/{campaign_id}/schedules/test

This endpoint allows you to send a test campaign.

To send to multiple addresses, use an array for the JSON “to” value [“one@address”,”two@address”]

operationId: CampaignsApi_sendTestCampaign

Parameters

Name In Required Type Description
campaign_id path required integer —
on-behalf-of header optional string —

Request Body

application/json
schema CampaignsApiSendTestCampaignRequest
Property Type Required
to string required

Responses

204 —
400

””: “The JSON you have submitted cannot be parsed.”
“to”: “Please provide an email address to which the test should be sent.”
“to”: “You can only send tests to 10 addresses at a time.”
“subject”: “Please add a subject to your campaign before sending a test.”
“plain_content”: “Plain content and html content can’t both be blank. Please set one of these values before sending a test.”
“sender_id”: “Please assign a sender identity to your campaign before sending a test.”
404

””: “not found”
POST /campaigns/{campaign_id}/schedules/test

Cancelscheduledsends 7 endpoints

POST /mail/batch

This endpoint allows you to generate a new batch ID.

Once a batch_id is created, you can associate it with a scheduled send using the /mail/send endpoint. Passing the batch_id as a field in the /mail/send request body will assign the ID to the send you are creating.

Once an ID is associated with a scheduled send, the send can be accessed and its send status can be modified using the batch_id.

operationId: CancelScheduledSends_request

Parameters

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

Responses

201 —
400 —
401 —
403 —
404 —
500 —
POST /mail/batch
GET /mail/batch/{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.

operationId: CancelScheduledSends_validateBatchId

Parameters

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

Responses

200 —
400 —
401 —
403 —
404 —
500 —
GET /mail/batch/{batch_id}
GET /user/scheduled_sends

This endpoint allows you to retrieve all cancelled and paused scheduled send information.

This endpoint will return only the scheduled sends that are associated with a batch_id. If you have scheduled a send using the /mail/send endpoint and the send_at field but no batch_id, the send will be scheduled for delivery; however, it will not be returned by this endpoint. For this reason, you should assign a batch_id to any scheduled send you may need to pause or cancel in the future.

operationId: CancelScheduledSends_allScheduledSends

Parameters

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

Responses

200 —
400 —
401 —
403 —
404 —
500 —
GET /user/scheduled_sends
POST /user/scheduled_sends

This endpoint allows you to cancel or pause a scheduled send associated with a batch_id.

Passing this endpoint a batch_id and status will cancel or pause the scheduled send.

Once a scheduled send is set to pause or cancel you must use the “Update a scheduled send” endpoint to change its status or the “Delete a cancellation or pause from a scheduled send” endpoint to remove the status. Passing a status change to a scheduled send that has already been paused or cancelled will result in a 400 level status code.

If the maximum number of cancellations/pauses are added to a send, a 400 level status code will be returned.

operationId: CancelScheduledSends_byBatchIdStatus

Parameters

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

Request Body

application/json
schema CancelScheduledSendsByBatchIdStatusRequest
Property Type Required
status string required
batch_id string required

Responses

201 —
400 —
401 —
403 —
404 —
500 —
POST /user/scheduled_sends
DELETE /user/scheduled_sends/{batch_id}

This endpoint allows you to delete the cancellation/pause of a scheduled send.

Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.

operationId: CancelScheduledSends_cancellationPause

Parameters

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

Responses

204 —
400 —
401 —
403 —
404 —
500 —
DELETE /user/scheduled_sends/{batch_id}
GET /user/scheduled_sends/{batch_id}

This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific batch_id.

operationId: CancelScheduledSends_byBatchId

Parameters

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

Responses

200 —
400 —
401 —
403 —
404 —
500 —
GET /user/scheduled_sends/{batch_id}
PATCH /user/scheduled_sends/{batch_id}

This endpoint allows you to update the status of a scheduled send for the given batch_id.

If you have already set a cancel or pause status on a scheduled send using the “Cancel or pause a scheduled send” endpoint, you can update it’s status using this endpoint. Attempting to update a status once it has been set with the “Cancel or pause a scheduled send” endpoint will result in a 400 error.

operationId: CancelScheduledSends_updateStatus

Parameters

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

Request Body

application/json
schema CancelScheduledSendsUpdateStatusRequest
Property Type Required
status string required

Responses

204 —
400 —
401 —
403 —
404 —
500 —
PATCH /user/scheduled_sends/{batch_id}

Categories 3 endpoints

GET /categories

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

operationId: GET_categories

Parameters

Name In Required Type Description
limit query optional integer

The number of categories to display per page.
category query optional string

Allows you to perform a prefix search on this particular category.
offset query optional integer

The point in the list that you would like to begin displaying results.
on-behalf-of header optional string —

Responses

200 —
400 —
GET /categories
GET /categories/stats

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.

operationId: Categories_getEmailStatisticsFor

Parameters

Name In Required Type Description
start_date query required string

The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD
end_date query optional string

The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.
categories query required string

The individual categories that you want to retrieve statistics for. You may include up to 10 different categories.
limit query optional integer

The number of results to include.
offset query optional integer

The number of results to skip.
aggregated_by query optional string

How to group the statistics. Must be either “day”, “week”, or “month”.
on-behalf-of header optional string —

Responses

200 —
GET /categories/stats
GET /categories/stats/sums

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.

operationId: Categories_getSums

Parameters

Name In Required Type Description
sort_by_metric query optional string

The metric that you want to sort by. Must be a single metric.
sort_by_direction query optional string

The direction you want to sort.
start_date query required string

The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.
end_date query optional string

The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.
limit query optional integer

Limits the number of results returned.
offset query optional integer

The point in the list to begin retrieving results.
aggregated_by query optional string

How to group the statistics. Must be either “day”, “week”, or “month”.
on-behalf-of header optional string —

Responses

200 —
GET /categories/stats/sums

Certificates 5 endpoints

POST /sso/certificates

This endpoint allows you to create an SSO certificate.

operationId: Certificates_createSSOCertificate

Request Body

application/json
schema CertificatesCreateSsoCertificateRequest
Property Type Required
enabled boolean optional
integration_id string required
public_certificate string required

Responses

200 —
400 —
401 —
403 —
429 —
500 —
POST /sso/certificates
DELETE /sso/certificates/{cert_id}

This endpoint allows you to delete an SSO certificate.

You can retrieve a certificate’s ID from the response provided by the “Get All SSO Integrations” endpoint.

operationId: Certificates_deleteSsoCertificate

Parameters

Name In Required Type Description
cert_id path required string —

Responses

200 —
400 —
401 —
403 —
429 —
500 —
DELETE /sso/certificates/{cert_id}
GET /sso/certificates/{cert_id}

This endpoint allows you to retrieve an individual SSO certificate.

operationId: Certificates_getIndividual

Parameters

Name In Required Type Description
cert_id path required string —

Responses

200 —
400 —
401 —
403 —
429 —
500 —
GET /sso/certificates/{cert_id}
PATCH /sso/certificates/{cert_id}

This endpoint allows you to update an existing certificate by ID.

You can retrieve a certificate’s ID from the response provided by the “Get All SSO Integrations” endpoint.

operationId: Certificates_updateById

Parameters

Name In Required Type Description
cert_id path required string —

Request Body

application/json
schema CertificatesUpdateByIdRequest
Property Type Required
enabled boolean optional
integration_id string optional
public_certificate string optional

Responses

200

OK
400 —
401 —
403 —
429 —
500 —
PATCH /sso/certificates/{cert_id}
GET /sso/integrations/{integration_id}/certificates

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.

operationId: Certificates_getByIdpConfigurations

Parameters

Name In Required Type Description
integration_id path required string

An ID that matches a certificate to a specific IdP integration.

Responses

200 —
400 —
401 —
403 —
429 —
500 —
GET /sso/integrations/{integration_id}/certificates

Contacts 2 endpoints

DELETE /marketing/contacts

This endpoint can be used to delete one or more contacts.

The query parameter ids must set to a comma-separated list of contact IDs for bulk contact deletion.

The query parameter delete_all_contacts must be set to "true" to delete all contacts.

You must set either ids or delete_all_contacts.

Deletion jobs are processed asynchronously.

Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

operationId: Contacts_deleteBulkContacts

Parameters

Name In Required Type Description
delete_all_contacts query optional string

Must be set to "true" to delete all contacts.
ids query optional string

A comma-separated list of contact IDs.

Responses

202 —
400 —
401 —
403 —
404 —
500 —
DELETE /marketing/contacts
GET /marketing/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.

operationId: Contacts_getRecentContacts

Responses

200 —
400 —
401 —
403 —
404 —
500 —
GET /marketing/contacts
Load more endpoints

Schemas

object AlertsDeleteAlertByIdResponse 
{
  "type": "object",
  "properties": {}
}
object AlertsGetSpecificAlertResponse 
{
  "type": "object",
  "required": [
    "created_at",
    "email_to",
    "id",
    "type",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "The ID of the alert."
    },
    "type": {
      "enum": [
        "usage_alert",
        "stats_notification"
      ],
      "type": "string",
      "description": "The type of alert."
    },
    "email_to": {
      "type": "string",
      "description": "The email address that the alert will be sent to."
    },
    "frequency": {
      "type": "string",
      "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: \"daily\", \"weekly\", or \"monthly\"."
    },
    "created_at": {
      "type": "integer",
      "description": "A Unix timestamp indicating when the alert was created."
    },
    "percentage": {
      "type": "integer",
      "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent."
    },
    "updated_at": {
      "type": "integer",
      "description": "A Unix timestamp indicating when the alert was last modified."
    }
  }
}
object AlertsUpdateAlertRequest 
{
  "type": "object",
  "example": {
    "email_to": "example@example.com"
  },
  "properties": {
    "email_to": {
      "type": "string",
      "description": "The new email address you want your alert to be sent to.\nExample: test@example.com"
    },
    "frequency": {
      "type": "string",
      "description": "The new frequency at which to send the stats_notification alert.\nExample: monthly"
    },
    "percentage": {
      "type": "integer",
      "description": "The new percentage threshold at which the usage_limit alert will be sent.\nExample: 90"
    }
  }
}
object AlertsUpdateAlertResponse 
{
  "type": "object",
  "required": [
    "created_at",
    "email_to",
    "id",
    "type",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "The ID of the alert."
    },
    "type": {
      "enum": [
        "usage_alert",
        "stats_notification"
      ],
      "type": "string",
      "description": "The type of alert."
    },
    "email_to": {
      "type": "string",
      "description": "The email address that the alert will be sent to."
    },
    "frequency": {
      "type": "string",
      "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: \"daily\", \"weekly\", or \"monthly\"."
    },
    "created_at": {
      "type": "integer",
      "description": "A Unix timestamp indicating when the alert was created."
    },
    "percentage": {
      "type": "integer",
      "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent."
    },
    "updated_at": {
      "type": "integer",
      "description": "A Unix timestamp indicating when the alert was last modified."
    }
  }
}
object ApiKeysCreateKeyRequest 
{
  "type": "object",
  "example": {
    "name": "My API Key",
    "scopes": [
      "mail.send",
      "alerts.create",
      "alerts.read"
    ]
  },
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "The name you will use to describe this API Key."
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The individual permissions that you are giving to this API Key."
    }
  }
}
object ApiKeysCreateKeyResponse 
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "api_key": {
      "type": "string"
    },
    "api_key_id": {
      "type": "string"
    }
  }
}
object ApiKeysGetAllResponse 
{
  "type": "object",
  "properties": {
    "result": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/api_key_name_id"
      }
    }
  }
}
object ApiKeysGetByKeyIdResponse 
{
  "type": "object",
  "properties": {
    "result": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/api_key_name_id_scopes"
      }
    }
  }
}
object ApiKeysUpdateKeyNameRequest 
{
  "type": "object",
  "example": {
    "name": "A New Hope"
  },
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "The new name of the API Key."
    }
  }
}
object ApiKeysUpdateNameAndScopesRequest 
{
  "type": "object",
  "example": {
    "name": "Profiles key",
    "scopes": [
      "user.profile.read",
      "user.profile.update"
    ]
  },
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}
object BlocksApiDeleteAllBlockedEmailsRequest 
{
  "type": "object",
  "example": {
    "emails": [
      "example1@example.com",
      "example2@example.com"
    ],
    "delete_all": false
  },
  "properties": {
    "emails": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The specific blocked email addresses that you want to delete."
    },
    "delete_all": {
      "type": "boolean",
      "description": "Indicates if you want to delete all blocked email addresses."
    }
  }
}
object BlocksApiDeleteAllBlockedEmailsResponse 
{
  "type": "object",
  "properties": {}
}
object BlocksApiDeleteSpecificBlockResponse 
{
  "type": "object",
  "properties": {}
}
object BouncesApiDeleteBouncesRequest 
{
  "type": "object",
  "example": {
    "emails": [
      "example@example.com",
      "example2@example.com"
    ],
    "delete_all": false
  },
  "properties": {
    "emails": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Delete multiple emails from your bounce list at the same time. This should not be used with the delete_all parameter."
    },
    "delete_all": {
      "type": "boolean",
      "description": "This parameter allows you to delete **every** email in your bounce list. This should not be used with the emails parameter."
    }
  }
}
object BouncesApiDeleteBouncesResponse 
{
  "type": "object",
  "example": {},
  "properties": {}
}
array BouncesApiGetAllBouncesResponse 
{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/bounce_response"
  }
}
array BouncesApiGetByEmailAddressResponse 
{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/bounce_response"
  }
}
object BouncesApiRemoveBounceResponse 
{
  "type": "object",
  "example": {},
  "properties": {}
}
object CampaignsApiDeleteCampaignById401Response 
{
  "type": "object",
  "example": {
    "errors": [
      {
        "field": null,
        "message": "authorization required"
      }
    ]
  },
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "nullable": true,
            "x-konfig-null-placeholder": true
          },
          "message": {
            "type": "string",
            "example": "authorization required"
          }
        }
      }
    }
  }
}
object CampaignsApiDeleteCampaignById404Response 
{
  "type": "object",
  "example": {},
  "properties": {}
}
object CampaignsApiDeleteCampaignByIdResponse 
{
  "type": "object",
  "example": {},
  "properties": {}
}
object CampaignsApiGetScheduledTimeResponse 
{
  "type": "object",
  "title": "View Scheduled Time of a Campaign response",
  "required": [
    "send_at"
  ],
  "properties": {
    "send_at": {
      "type": "integer",
      "format": "int64"
    }
  }
}
object CampaignsApiGetSingleCampaign401Response 
{
  "type": "object",
  "example": {
    "errors": [
      {
        "field": null,
        "message": "authorization required"
      }
    ]
  },
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "nullable": true,
            "x-konfig-null-placeholder": true
          },
          "message": {
            "type": "string",
            "example": "authorization required"
          }
        }
      }
    }
  }
}
object CampaignsApiGetSingleCampaign404Response 
{
  "type": "object",
  "example": {
    "errors": [
      {
        "field": null,
        "message": "not found"
      }
    ]
  },
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "nullable": true,
            "x-konfig-null-placeholder": true
          },
          "message": {
            "type": "string",
            "example": "not found"
          }
        }
      }
    }
  }
}
object CampaignsApiGetSingleCampaignResponse 
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "ip_pool": {
      "type": "string"
    },
    "subject": {
      "type": "string"
    },
    "list_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      }
    },
    "sender_id": {
      "type": "integer"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "segment_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      }
    },
    "html_content": {
      "type": "string"
    },
    "plain_content": {
      "type": "string"
    },
    "suppression_group_id": {
      "type": "integer"
    },
    "custom_unsubscribe_url": {
      "type": "string"
    }
  }
}
object CampaignsApiScheduleCampaignRequest 
{
  "type": "object",
  "title": "Schedule a Campaign request",
  "example": {
    "send_at": 1489771528
  },
  "required": [
    "send_at"
  ],
  "properties": {
    "send_at": {
      "type": "integer",
      "description": "The unix timestamp for the date and time you would like your campaign to be sent out."
    }
  }
}
object CampaignsApiScheduleCampaignResponse 
{
  "type": "object",
  "title": "Schedule a Campaign response",
  "required": [
    "id",
    "send_at",
    "status"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "The campaign ID."
    },
    "status": {
      "enum": [
        "Scheduled"
      ],
      "type": "string",
      "description": "The status of your campaign."
    },
    "send_at": {
      "type": "integer",
      "description": "The date time you scheduled your campaign to be sent."
    }
  }
}
object CampaignsApiSendCampaignNowResponse 
{
  "type": "object",
  "title": "Send a Campaign response",
  "required": [
    "id",
    "status"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "status": {
      "type": "string"
    }
  }
}
object CampaignsApiSendTestCampaignRequest 
{
  "type": "object",
  "example": {
    "to": "your.email@example.com"
  },
  "required": [
    "to"
  ],
  "properties": {
    "to": {
      "type": "string",
      "format": "email",
      "description": "The email address that should receive the test campaign."
    }
  }
}
object CampaignsApiSendTestCampaignResponse 
{
  "type": "object",
  "title": "Send a Test Campaign request",
  "required": [
    "to"
  ],
  "properties": {
    "to": {
      "type": "string"
    }
  }
}
object CampaignsApiUnscheduleCampaignResponse 
{
  "type": "object",
  "example": {},
  "properties": {}
}
object CampaignsApiUpdateScheduledTimeRequest 
{
  "type": "object",
  "title": "Update a Scheduled Campaign request",
  "example": {
    "send_at": 1489451436
  },
  "required": [
    "send_at"
  ],
  "properties": {
    "send_at": {
      "type": "integer",
      "format": "int64"
    }
  }
}
object CampaignsApiUpdateScheduledTimeResponse 
{
  "type": "object",
  "title": "Update a Scheduled Campaign response",
  "required": [
    "id",
    "send_at",
    "status"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "The campaign ID"
    },
    "status": {
      "type": "string",
      "description": "The status of the schedule."
    },
    "send_at": {
      "type": "integer",
      "description": "The unix timestamp to send the campaign."
    }
  }
}
object CampaignsApiUpdateSpecificCampaign403Response 
{
  "type": "object",
  "example": {
    "errors": [
      {
        "field": null,
        "message": "You may only update a campaign when it is in draft mode."
      }
    ]
  },
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "nullable": true,
            "x-konfig-null-placeholder": true
          },
          "message": {
            "type": "string",
            "example": "You may only update a campaign when it is in draft mode."
          }
        }
      }
    }
  }
}
object CampaignsApiUpdateSpecificCampaignRequest 
{
  "type": "object",
  "title": "Update a Campaign request",
  "example": {
    "title": "May Newsletter",
    "subject": "New Products for Summer!",
    "categories": [
      "summer line"
    ],
    "html_content": "<html><head><title></title></head><body><p>Check out our summer line!</p></body></html>",
    "plain_content": "Check out our summer line!"
  },
  "required": [
    "title",
    "subject",
    "categories",
    "html_content",
    "plain_content"
  ],
  "properties": {
    "title": {
      "type": "string",
      "description": "The title of the campaign."
    },
    "subject": {
      "type": "string",
      "description": "The subject line for your campaign."
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The categories you want to tag on this campaign."
    },
    "html_content": {
      "type": "string",
      "description": "The HTML content of this campaign."
    },
    "plain_content": {
      "type": "string",
      "description": "The plain content of this campaign."
    }
  }
}
object CampaignsApiUpdateSpecificCampaignResponse 
{
  "type": "object",
  "example": {
    "errors": [
      {
        "field": "title",
        "message": "title can't be blank"
      },
      {
        "field": "title",
        "message": "title is too long (maximum is 100 characters)"
      },
      {
        "field": "categories",
        "message": "categories exceeds 10 category limit"
      },
      {
        "field": "html_content",
        "message": "html_content exceeds the 1MB limit"
      },
      {
        "field": "plain_content",
        "message": "plain_content exceeds the 1MB limit"
      },
      {
        "field": "sender_id",
        "message": "sender_id does not exist"
      },
      {
        "field": "sender_id",
        "message": "sender_id is not a verified sender identity"
      },
      {
        "field": "list_ids",
        "message": "list_ids do not all exist"
      },
      {
        "field": "segment_ids",
        "message": "segment_ids do not all exist"
      },
      {
        "field": "ip_pool",
        "message": "The ip pool you provided is invalid"
      },
      {
        "field": "suppression_group_id",
        "message": "suppression_group_id does not exist"
      },
      {
        "field": "unsubscribes",
        "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other."
      },
      {
        "field": null,
        "message": "The JSON you have submitted cannot be parsed."
      }
    ]
  },
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "example": "title",
            "nullable": true
          },
          "message": {
            "type": "string",
            "example": "title can't be blank"
          }
        }
      }
    }
  }
}
array CancelScheduledSendsAllScheduledSendsResponse 
{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/user_scheduled_send_status"
  }
}
array CancelScheduledSendsByBatchIdResponse 
{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/user_scheduled_send_status"
  },
  "title": "Retrieve scheduled send response"
}
object CancelScheduledSendsByBatchIdStatusRequest 
{
  "type": "object",
  "title": "Cancel or pause a scheduled send request",
  "example": {
    "status": "pause",
    "batch_id": "YOUR_BATCH_ID"
  },
  "required": [
    "batch_id",
    "status"
  ],
  "properties": {
    "status": {
      "enum": [
        "pause",
        "cancel"
      ],
      "type": "string",
      "default": "pause",
      "description": "The status of the send you would like to implement. This can be pause or cancel. To delete a pause or cancel status see DELETE /v3/user/scheduled_sends/{batch_id}"
    },
    "batch_id": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9]",
      "description": "The batch ID is the identifier that your scheduled mail sends share."
    }
  }
}
object CancelScheduledSendsRequestResponse 
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "help": {
            "type": "object"
          },
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
object CancelScheduledSendsUpdateStatusRequest 
{
  "type": "object",
  "example": {
    "status": "pause"
  },
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "enum": [
        "cancel",
        "pause"
      ],
      "type": "string",
      "description": "The status you would like the scheduled send to have."
    }
  }
}
object CancelScheduledSendsUpdateStatusResponse 
{
  "type": "object",
  "example": {},
  "properties": {}
}
array CategoriesGetEmailStatisticsForResponse 
{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/category_stats"
  }
}
object CertificatesCreateSsoCertificateRequest 
{
  "type": "object",
  "example": {
    "enabled": false,
    "integration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312",
    "public_certificate": "<your x509 certificate>"
  },
  "required": [
    "public_certificate",
    "integration_id"
  ],
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "Indicates if the certificate is enabled."
    },
    "integration_id": {
      "type": "string",
      "description": "An ID that matches a certificate to a specific IdP integration. This is the `id` returned by the \"Get All SSO Integrations\" endpoint."
    },
    "public_certificate": {
      "type": "string",
      "description": "This public certificate allows SendGrid to verify that SAML requests it receives are signed by an IdP that it recognizes."
    }
  },
  "description": ""
}
array CertificatesGetByIdpConfigurationsResponse 
{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/sso-certificate-body"
  }
}
object CertificatesUpdateByIdRequest 
{
  "type": "object",
  "example": {
    "enabled": false,
    "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312",
    "public_certificate": "<your x509 certificate>"
  },
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "Indicates whether or not the certificate is enabled."
    },
    "integration_id": {
      "type": "string",
      "description": "An ID that matches a certificate to a specific IdP integration."
    },
    "public_certificate": {
      "type": "string",
      "description": "This public certificate allows SendGrid to verify that SAML requests it receives are signed by an IdP that it recognizes."
    }
  }
}
object ContactsApiCustomFieldsCreateNewFieldRequest 
{
  "type": "object",
  "example": {
    "name": "pet",
    "type": "text"
  },
  "properties": {
    "name": {
      "type": "string"
    },
    "type": {
      "type": "string"
    }
  }
}
object ContactsApiCustomFieldsGetAllResponse 
{
  "type": "object",
  "title": "List All Custom Fields response",
  "required": [
    "custom_fields"
  ],
  "properties": {
    "custom_fields": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/contactdb_custom_field_with_id"
      }
    }
  }
}
object ContactsApiCustomFieldsGetReservedFieldsResponse 
{
  "type": "object",
  "properties": {
    "reserved_fields": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        }
      }
    }
  }
}
array ContactsApiListsAddMultipleRecipientsToListRequest 
{
  "type": "array",
  "items": {
    "type": "integer"
  },
  "example": [
    "recipient_id1",
    "recipient_id2"
  ]
}
Load more schemas

Versions

Version Endpoints Schemas Ingested Status
1.0.0 334 545 2026-05-11 current
1.0.0 334 545 2026-04-16