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

Clear filters

GET POST PUT PATCH DELETE

Apikeys 1 endpoints

PUT /api_keys/{api_key_id} Update API key name and scopes

This endpoint allows you to update the name and scopes of a given API key.

You must pass this endpoint a JSON request body with a name field and a scopes array containing at least one scope. The name and scopes fields will be used to update the key associated with the api_key_id in the request URL.

If you need to update a key’s scopes only, pass the name field with the key’s existing name; the name will not be modified. If you need to update a key’s name only, use the “Update API key name” endpoint.

See the API Key Permissions List 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}

Contacts 2 endpoints

PUT /marketing/contacts Add or Update a Contact

This endpoint allows the upsert (insert or update) of up to 30,000 contacts, or 6MB of data, whichever is lower.

Because the creation and update of contacts is an asynchronous process, the response will not contain immediate feedback on the processing of your upserted contacts. Rather, it will contain an HTTP 202 response indicating the contacts are queued for processing or an HTTP 4XX error containing validation errors. Should you wish to get the resulting contact’s ID or confirm your contacts have been updated or added, you can use the “Get Contacts by Emails” endpoint.

Please note that custom fields need to have been already created if you wish to set their values for the contacts being upserted. To do this, please use the “Create Custom Field Definition” endpoint.

You will see a job_id in the response to your request. This can be used to check the status of your upsert job. To do so, please use the “Import Contacts Status” endpoint.

If the contact already exists in the system, any entries submitted via this endpoint will update the existing contact. The contact to update will be determined only by the email field and any fields omitted from the request will remain as they were. A contact’s ID cannot be used to update the contact.

The email field will be changed to all lower-case. If a contact is added with an email that exists but contains capital letters, the existing contact with the all lower-case email will be updated.

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

operationId: Contacts_upsertBatchContacts

Request Body

application/json

schema ContactsUpsertBatchContactsRequest

Property	Type	Required
contacts	array	required
└ city	string	optional
└ email	string	required
└ country	string	optional
└ last_name	string	optional
└ first_name	string	optional
└ postal_code	string	optional
└ custom_fields	object	optional
└ address_line_1	string	optional
└ address_line_2	string	optional
└ alternate_emails	array	optional
└ state_province_region	string	optional
list_ids	array	optional

Responses

202 —

400 —

401 —

403 —

404 —

500 —

PUT /marketing/contacts

PUT /marketing/contacts/imports Import Contacts

This endpoint allows a CSV upload containing up to one million contacts or 5GB of data, whichever is smaller.

Imports take place asynchronously: the endpoint returns a URL (upload_uri) and HTTP headers (upload_headers) which can subsequently be used to PUT a file of contacts to be imported into our system.

Uploaded CSV files may also be gzip-compressed.

In either case, you must include the field file_type with the value csv in your request body.

The field_mappings paramter is a respective list of field definition IDs to map the uploaded CSV columns to. It allows you to use CSVs where one or more columns are skipped (null) or remapped to the contact field.

For example, if field_mappings is set to [null, "w1", "_rf1"], this means skip column 0, map column 1 to the custom field with the ID w1, and map column 2 to the reserved field with the ID _rf1. See the “Get All Field Definitions” endpoint to fetch your custom and reserved field IDs to use with field_mappings.

Once you recieve the response body you can then initiate a second API call where you use the supplied URL and HTTP header to upload your file. For example:

curl --upload-file "file/path.csv" "URL_GIVEN" -H 'HEADER_GIVEN'

If you’d like to monitor the status of your import job, use the job_id and the “Import Contacts Status” endpoint.
Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

operationId: Contacts_importCsv

Request Body

application/json

schema ContactsImportCsvRequest

Property	Type	Required
list_ids	array	optional
file_type	string	required
field_mappings	array	required

Responses

200 —

400 —

401 —

403 —

404 —

500 —

PUT /marketing/contacts/imports

Ippools 1 endpoints

PUT /ips/pools/{pool_name} Rename an IP pool

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

operationId: IpPools_updateName

Parameters

Name	In	Required	Type	Description
pool_name	path	required	string	The name of the IP pool that you want to retrieve the IP addresses for.

Request Body

application/json

schema IpPoolsUpdateNameRequest

Property	Type	Required
name	string	optional

Responses

200 —

404 —

PUT /ips/pools/{pool_name}

Singlesends 1 endpoints

PUT /marketing/singlesends/{id}/schedule Schedule Single Send

This endpoint allows you to schedule a Single Send for future delivery using a Single Send ID.

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

operationId: SingleSends_schedulePut

Parameters

Name	In	Required	Type	Description
id	path	required	string	—

Request Body

application/json

schema SingleSendsSchedulePutRequest

Property	Type	Required
send_at	string	required

Responses

201 —

404 —

500 —

PUT /marketing/singlesends/{id}/schedule

Subusermonitorsettings 1 endpoints

PUT /subusers/{subuser_name}/monitor Update Monitor Settings for a subuser

operationId: SubuserMonitorSettings_updateForSubuserNameMonitor

Parameters

Name	In	Required	Type	Description
subuser_name	path	required	string	The name of the subuser for which to retrieve monitor settings.

Request Body

application/json

schema monitor

Property	Type	Required
email	string	required
frequency	number	required

Responses

200 —

400 —

401 —

PUT /subusers/{subuser_name}/monitor

Subusersapi 1 endpoints

PUT /subusers/{subuser_name}/ips Update IPs assigned to a subuser

This endpoint allows you update your subusers’ assigned IP.

Each subuser should be assigned to an IP address from which all of this subuser’s mail will be sent. Often, this is the same IP as the parent account, but each subuser can have one or more of their own IP addresses as well.

More information:

operationId: SubusersApi_updateSubuserIps

Parameters

Name	In	Required	Type	Description
subuser_name	path	required	string	—

Request Body

application/json

schema SubusersApiUpdateSubuserIpsRequest

array of string

Responses

200 —

401 —

PUT /subusers/{subuser_name}/ips

Usersapi 3 endpoints

PUT /user/email Update your account email address

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

operationId: UsersApi_updateEmail

Parameters

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

Request Body

application/json

schema UsersApiUpdateEmailRequest

Property	Type	Required
email	string	optional

Responses

200 —

PUT /user/email

PUT /user/password Update your password

This endpoint allows you to update your password.

operationId: UsersApi_updatePassword

Parameters

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

Request Body

application/json

schema UsersApiUpdatePasswordRequest

Property	Type	Required
new_password	string	required
old_password	string	required

Responses

200 —

PUT /user/password

PUT /user/username Update your username

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

operationId: UsersApi_updateUsername

Parameters

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

Request Body

application/json

schema UsersApiUpdateUsernameRequest

Property	Type	Required
username	string	optional

Responses

200 —

PUT /user/username

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