Email Activity (beta)
The Beta endpoints for the new Email Activity APIs - functionality is subject to change without notice. You may not have access to this Beta endpoint. Email…
Communication#openapi#email#marketing
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
The Beta endpoints for the new Email Activity APIs - functionality is subject to change without notice. You may not have access to this Beta endpoint.
Email Activity offers filtering and search by event type for two days worth of data. There is an optional add-on to store 60 days worth of data. This add-on also gives you access to the ability to download a CSV of the 60 days worth of email event data. The Beta endpoints for the new Email Activity APIs - functionality is subject to change without notice. You may not have access to this Beta endpoint.
Email Activity offers filtering and search by event type for two days worth of data. There is an optional add-on to store 60 days worth of data. This add-on also gives you access to the ability to download a CSV of the 60 days worth of email event data.
Endpoints 334
IP Access Management
- GETRetrieve all recent access attempts
/access_settings/activity?limit=20This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the… - GETRetrieve a list of currently allowed IPs
/access_settings/whitelistThis endpoint allows you to retrieve a list of IP addresses that are currently allowed to access your account. Each IP address returned to you will have… - POSTAdd one or more IPs to the allow list
/access_settings/whitelistThis endpoint allows you to add one or more allowed IP addresses. To allow one or more IP addresses, pass them to this endpoint in an array. Once an IP… - DELETERemove one or more IPs from the allow list
/access_settings/whitelistThis endpoint allows you to remove one or more IP addresses from your list of allowed addresses. To remove one or more IP addresses, pass this endpoint an… - GETRetrieve a specific allowed IP
/access_settings/whitelist/:rule_idThis endpoint allows you to retreive a specific IP address that has been allowed to access your account. You must include the ID for the specific IP address… - DELETERemove a specific IP from the allowed list
/access_settings/whitelist/:rule_idThis endpoint allows you to remove a specific IP address from your list of allowed addresses. When removing a specific IP address from your list, you must…
Alerts
- GETRetrieve all alerts
/alertsThis 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… - POSTCreate a new Alert
/alertsThis endpoint allows you to create a new alert. Alerts allow you to specify an email address to receive notifications regarding your email usage or… - GETRetrieve a specific alert
/alerts/:alert_idThis endpoint allows you to retrieve a specific alert. Alerts allow you to specify an email address to receive notifications regarding your email usage or… - DELETEDelete an alert
/alerts/:alert_idThis endpoint allows you to delete an alert. Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. *… - PATCHUpdate an alert
/alerts/:alert_idThis endpoint allows you to update an alert. Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. *…
API Keys
- GETRetrieve all API Keys belonging to the authenticated user
/api_keys?limit=0This 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… - POSTCreate API keys
/api_keysThis 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… - GETRetrieve an existing API Key
/api_keys/:api_key_idThis 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,… - PUTUpdate API key name and scopes
/api_keys/:api_key_idThis 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… - DELETEDelete API keys
/api_keys/:api_key_idThis 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… - PATCHUpdate API key name
/api_keys/:api_key_idThis 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…
Suppressions - Unsubscribe Groups
- GETRetrieve all suppression groups associated with the user.
/asm/groups?id=0This endpoint allows you to retrieve a list of all suppression groups created by this user. This endpoint can also return information for multiple group IDs… - POSTCreate a new suppression group
/asm/groupsThis endpoint allows you to create a new suppression group. To add an email address to the suppression group, create a Suppression. - GETGet information on a single suppression group.
/asm/groups/:group_idThis endpoint allows you to retrieve a single suppression group. - DELETEDelete a Suppression Group
/asm/groups/:group_idThis endpoint allows you to delete a suppression group. If a recipient uses the "one-click unsubscribe" option on an email associated with a deleted group,… - PATCHUpdate a suppression group.
/asm/groups/:group_idThis endpoint allows you to update or change a suppression group.
Suppressions - Suppressions
- GETRetrieve all suppressions for a suppression group
/asm/groups/:group_id/suppressionsThis endpoint allows you to retrieve all suppressed email addresses belonging to the given group. - POSTAdd suppressions to a suppression group
/asm/groups/:group_id/suppressionsThis endpoint allows you to add email addresses to an unsubscribe group. If you attempt to add suppressions to a group that has been deleted or does not… - POSTSearch for suppressions within a group
/asm/groups/:group_id/suppressions/searchThis endpoint allows you to search a suppression group for multiple suppressions. When given a list of email addresses and a group ID, this endpoint will only… - DELETEDelete a suppression from a suppression group
/asm/groups/:group_id/suppressions/:emailThis endpoint allows you to remove a suppressed email address from the given suppression group. Removing an address will remove the suppression, meaning email… - GETRetrieve all suppressions
/asm/suppressionsThis endpoint allows you to retrieve a list of all suppressions. - GETRetrieve all suppression groups for an email address
/asm/suppressions/:emailThis endpoint returns a list of all groups from which the given email address has been unsubscribed.
Suppressions - Global Suppressions
- POSTAdd recipient addresses to the global suppression group.
/asm/suppressions/globalThis endpoint allows you to add one or more email addresses to the global suppressions group. - GETRetrieve a Global Suppression
/asm/suppressions/global/:emailThis endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed. If the… - DELETEDelete a Global Suppression
/asm/suppressions/global/:emailThis endpoint allows you to remove an email address from the global suppressions group. Deleting a suppression group will remove the suppression, meaning… - GETRetrieve all global suppressions
/suppression/unsubscribes?start_time=0&end_time=0&limit=0&offset=0This endpoint allows you to retrieve a list of all email address that are globally suppressed.
Stats
- GETRetrieve email statistics by browser.
/browsers/stats?browsers=string&limit=0&offset=0&aggregated_by=day&start_date=string&end_date=stringThis endpoint allows you to retrieve your email statistics segmented by browser type. We only store up to 7 days of email activity in our database. By… - GETRetrieve email statistics by client type.
/clients/stats?start_date=string&end_date=string&aggregated_by=dayThis endpoint allows you to retrieve your email statistics segmented by client type. We only store up to 7 days of email activity in our database. By default,… - GETRetrieve stats by a specific client type.
/clients/:client_type/stats?start_date=string&end_date=string&aggregated_by=dayThis endpoint allows you to retrieve your email statistics segmented by a specific client type. We only store up to 7 days of email activity in our database.… - GETRetrieve email statistics by device type.
/devices/stats?limit=0&offset=0&aggregated_by=day&start_date=string&end_date=stringThis endpoint allows you to retrieve your email statistics segmented by the device type. We only store up to 7 days of email activity in our database. By… - GETRetrieve email statistics by country and state/province.
/geo/stats?country=US&limit=0&offset=0&aggregated_by=day&start_date=string&end_date=stringThis endpoint allows you to retrieve your email statistics segmented by country and state/province. We only store up to 7 days of email activity in our… - GETRetrieve email statistics by mailbox provider.
/mailbox_providers/stats?mailbox_providers=string&limit=0&offset=0&aggregated_by=day&start_date=string&end_date=stringThis endpoint allows you to retrieve your email statistics segmented by recipient mailbox provider. We only store up to 7 days of email activity in our… - GETRetrieve global email statistics
/stats?limit=0&offset=0&aggregated_by=day&start_date=string&end_date=stringThis endpoint allows you to retrieve all of your global email statistics between a given date range. Parent accounts will see aggregated stats for their…
Campaigns API
- GETRetrieve all Campaigns
/campaigns?limit=10&offset=0This 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… - POSTCreate a Campaign
/campaignsThis 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… - GETRetrieve a single campaign
/campaigns/:campaign_idThis endpoint allows you to retrieve a specific campaign. - DELETEDelete a Campaign
/campaigns/:campaign_idThis endpoint allows you to delete a specific campaign. - PATCHUpdate a Campaign
/campaigns/:campaign_idThis 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… - GETView Scheduled Time of a Campaign
/campaigns/:campaign_id/schedulesThis endpoint allows you to retrieve the date and time that a campaign has been scheduled to be sent. - POSTSchedule a Campaign
/campaigns/:campaign_id/schedulesThis 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… - DELETEUnschedule a Scheduled Campaign
/campaigns/:campaign_id/schedulesThis 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… - PATCHUpdate a Scheduled Campaign
/campaigns/:campaign_id/schedulesThis endpoint allows to you change the scheduled time and date for a campaign to be sent. - POSTSend a Campaign
/campaigns/:campaign_id/schedules/nowThis 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… - POSTSend a Test Campaign
/campaigns/:campaign_id/schedules/testThis 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"]
Categories
- GETRetrieve all categories
/categories?limit=50&category=string&offset=0This endpoint allows you to retrieve a list of all of your categories. - GETRetrieve Email Statistics for Categories
/categories/stats?start_date=string&end_date=string&categories=string&limit=500&offset=0&aggregated_by=dayThis 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… - GETRetrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]
/categories/stats/sums?sort_by_metric=delivered&sort_by_direction=desc&start_date=string&end_date=string&limit=5&offset=0&aggregated_by=dayThis 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…
Contacts API - Custom Fields
- GETRetrieve all custom fields
/contactdb/custom_fieldsThis endpoint allows you to retrieve all custom fields. - POSTCreate a Custom Field
/contactdb/custom_fieldsThis endpoint allows you to create a custom field. You can create up to 120 custom fields. - GETRetrieve a Custom Field
/contactdb/custom_fields/:custom_field_idThis endpoint allows you to retrieve a custom field by ID. - DELETEDelete a Custom Field
/contactdb/custom_fields/:custom_field_idThis endpoint allows you to delete a custom field by ID. - GETRetrieve reserved fields
/contactdb/reserved_fieldsThis endpoint allows you to list all fields that are reserved and can't be used for custom field names.
Contacts API - Lists
- GETRetrieve all lists
/contactdb/listsThis endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned. - POSTCreate a List
/contactdb/listsThis endpoint allows you to create a list for your recipients. - DELETEDelete Multiple lists
/contactdb/listsThis endpoint allows you to delete multiple recipient lists. - GETRetrieve a single list
/contactdb/lists/:list_id?list_id=0This endpoint allows you to retrieve a single recipient list. - DELETEDelete a List
/contactdb/lists/:list_id?delete_contacts=trueThis endpoint allows you to delete a specific recipient list with the given ID. - PATCHUpdate a List
/contactdb/lists/:list_id?list_id=0This endpoint allows you to update the name of one of your recipient lists. - GETRetrieve all recipients on a List
/contactdb/lists/:list_id/recipients?page=0&page_size=0&list_id=0This endpoint allows you to retrieve all recipients on the list with the given ID. - POSTAdd Multiple Recipients to a List
/contactdb/lists/:list_id/recipientsThis endpoint allows you to add multiple recipients to a list. Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should… - POSTAdd a Single Recipient to a List
/contactdb/lists/:list_id/recipients/:recipient_idThis endpoint allows you to add a single recipient to a list. - DELETEDelete a Single Recipient from a Single List
/contactdb/lists/:list_id/recipients/:recipient_id?list_id=0&recipient_id=0This endpoint allows you to delete a single recipient from a list.
Contacts API - Recipients
- GETRetrieve recipients
/contactdb/recipients?page=0&page_size=0This endpoint allows you to retrieve all of your Marketing Campaigns recipients. Batch deletion of a page makes it possible to receive an empty page of… - POSTAdd recipients
/contactdb/recipientsThis endpoint allows you to add a Marketing Campaigns recipient. You can add custom field data as a parameter on this endpoint. We have provided an example… - DELETEDelete Recipients
/contactdb/recipientsThis endpoint allows you to deletes one or more recipients. The body of an API call to this endpoint must include an array of recipient IDs of the recipients… - PATCHUpdate Recipient
/contactdb/recipientsThis endpoint allows you to update one or more recipients. The body of an API call to this endpoint must include an array of one or more recipient objects. It… - GETRetrieve the count of billable recipients
/contactdb/recipients/billable_countThis endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for. You are billed for marketing campaigns based on… - GETRetrieve a Count of Recipients
/contactdb/recipients/countThis endpoint allows you to retrieve the total number of Marketing Campaigns recipients. - GETSearch recipients
/contactdb/recipients/search?{field_name}=stringThis endpoint allows you to perform a search on all of your Marketing Campaigns recipients. field_name: * is a variable that is substituted for your actual… - POSTSearch recipients
/contactdb/recipients/search<p> Search using segment conditions without actually creating a segment. Body contains a JSON object with <code>conditions</code>, a list of conditions as… - GETRetrieve a single recipient
/contactdb/recipients/:recipient_idThis endpoint allows you to retrieve a single recipient by ID from your contact database. - DELETEDelete a Recipient
/contactdb/recipients/:recipient_idThis endpoint allows you to delete a single recipient with the given ID from your contact database. > Use this to permanently delete your recipients from all… - GETRetrieve the lists that a recipient is on
/contactdb/recipients/:recipient_id/listsThis endpoint allows you to retrieve the lists that a given recipient belongs to. Each recipient can be on many lists. This endpoint gives you all of the… - GETGet Recipient Upload Status
/contactdb/statusThis endpoint allows you to check the upload status of a Marketing Campaigns recipient.
Contacts API - Segments
- GETRetrieve all segments
/contactdb/segmentsThis endpoint allows you to retrieve all of your segments. - POSTCreate a Segment
/contactdb/segmentsThis endpoint allows you to create a new segment. Valid operators for create and update depend on the type of the field for which you are searching. Dates… - GETRetrieve a segment
/contactdb/segments/:segment_id?segment_id=0This endpoint allows you to retrieve a single segment with the given ID. - DELETEDelete a segment
/contactdb/segments/:segment_id?delete_contacts=trueThis endpoint allows you to delete a segment from your recipients database. You also have the option to delete all the contacts from your Marketing Campaigns… - PATCHUpdate a segment
/contactdb/segments/:segment_id?segment_id=stringThis endpoint allows you to update a segment. - GETRetrieve recipients on a segment
/contactdb/segments/:segment_id/recipients?page=0&page_size=0This endpoint allows you to retrieve all of the recipients in a segment with the given ID.
Designs API
- GETList Designs
/designs?page_size=100&page_token=string&summary=trueThis endpoint allows you to retrieve a list of designs already stored in your Design Library. A GET request to /designs will return a list of your existing… - POSTCreate Design
/designsThis endpoint allows you to create a new design. You can add a new design by passing data, including a string of HTML email content, to /designs. When… - GETList SendGrid Pre-built Designs
/designs/pre-builts?page_size=100&page_token=string&summary=trueThis endpoint allows you to retrieve a list of pre-built designs provided by Twilio SendGrid. Unlike the /designs endpoint where *your* designs are stored, a… - GETGet SendGrid Pre-built Design
/designs/pre-builts/:idThis endpoint allows you to retrieve a single pre-built design. A GET request to /designs/pre-builts/{id} will retrieve details about a specific pre-built… - POSTDuplicate SendGrid Pre-built Design
/designs/pre-builts/:idThis endpoint allows you to duplicate one of the pre-built Twilio SendGrid designs. Like duplicating one of your existing designs, you are not required to… - GETGet Design
/designs/:idThis endpoint allows you to retrieve a single design. A GET request to /designs/{id} will retrieve details about a specific design in your Design Library.… - POSTDuplicate Design
/designs/:idThis endpoint allows you to duplicate one of your existing designs. Modifying an existing design is often the easiest way to create something new. You are not… - DELETEDelete Design
/designs/:idThis endpoint allows you to delete a single design. Be sure to check the ID of the design you intend to delete before making this request; deleting a design… - PATCHUpdate Design
/designs/:idThis endpoint allows you to edit a design. The Design API supports PATCH requests, which allow you to make partial updates to a single design. Passing data to…
IP Addresses
- GETRetrieve all IP addresses
/ips?ip=string&exclude_whitelabels=true&limit=10&offset=0&subuser=string&sort_by_direction=descThis endpoint allows you to retrieve a list of all assigned and unassigned IPs. Response includes warm up status, pools, assigned subusers, and reverse DNS… - POSTAdd IPs
/ipsThis endpoint is for adding a(n) IP Address(es) to your account. - GETRetrieve all assigned IPs
/ips/assignedThis endpoint allows you to retrieve only assigned IP addresses. A single IP address or a range of IP addresses may be dedicated to an account in order to… - GETGet remaining IPs count
/ips/remainingThis endpoint gets amount of IP Addresses that can still be created during a given period and the price of those IPs. - GETRetrieve all IP pools an IP address belongs to
/ips/:ip_addressThis endpoint allows you to see which IP pools a particular IP address has been added to. The same IP address can be added to multiple IP pools. A single IP…
IP Pools
- GETRetrieve all IP pools
/ips/poolsThis endpoint allows you to get all of your IP pools. - POSTCreate an IP pool
/ips/poolsThis endpoint allows you to create an IP pool. Before you can create an IP pool, you need to activate the IP in your SendGrid account: 1. Log into your… - GETRetrieve all the IPs in a specified pool
/ips/pools/:pool_nameThis endpoint allows you to get all of the IP addresses that are in a specific IP pool. - PUTRename an IP pool
/ips/pools/:pool_nameThis endpoint allows you to update the name of an IP pool. - DELETEDelete an IP pool
/ips/pools/:pool_nameThis endpoint allows you to delete an IP pool. - POSTAdd an IP address to a pool
/ips/pools/:pool_name/ipsThis endpoint allows you to add an IP address to an IP pool. You can add the same IP address to multiple pools. It may take up to 60 seconds for your IP… - DELETERemove an IP address from a pool
/ips/pools/:pool_name/ips/:ipThis endpoint allows you to remove an IP address from an IP pool.
IP Warmup
- GETRetrieve all IPs currently in warmup
/ips/warmupThis endpoint allows you to retrieve all of your IP addresses that are currently warming up. - POSTStart warming up an IP address
/ips/warmupThis endpoint allows you to put an IP address into warmup mode. - GETRetrieve the warmup status for a specific IP address
/ips/warmup/:ip_addressThis endpoint allows you to retrieve the warmup status for a specific IP address. You can retrieve all of your warming IPs using the "Retrieve all IPs… - DELETEStop warming up an IP address
/ips/warmup/:ip_addressThis endpoint allows you to remove an IP address from warmup mode. Your request will return a 204 status code if the specified IP was successfully removed…
Cancel Scheduled Sends
- POSTCreate a batch ID
/mail/batchThis 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.… - GETValidate batch ID
/mail/batch/:batch_idThis 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… - GETRetrieve all scheduled sends
/user/scheduled_sendsThis endpoint allows you to retrieve all cancelled and paused scheduled send information. This endpoint will return only the scheduled sends that are… - POSTCancel or pause a scheduled send
/user/scheduled_sendsThis 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… - GETRetrieve scheduled send
/user/scheduled_sends/:batch_idThis endpoint allows you to retrieve the cancel/paused scheduled send information for a specific batch_id. - DELETEDelete a cancellation or pause from a scheduled send
/user/scheduled_sends/:batch_idThis endpoint allows you to delete the cancellation/pause of a scheduled send. Scheduled sends cancelled less than 10 minutes before the scheduled time are… - PATCHUpdate a scheduled send
/user/scheduled_sends/:batch_idThis 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…
Mail Send
- POSTv3 Mail Send
/mail/sendThe 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…
Settings - Mail
- GETRetrieve all mail settings
/mail_settings?limit=0&offset=0This endpoint allows you to retrieve a list of all mail settings. Each setting will be returned with an enabled status set to true or false and a short… - GETRetrieve address whitelist mail settings
/mail_settings/address_whitelistThis endpoint allows you to retrieve your current email address whitelist settings. The Address Whitelist setting allows you to specify email addresses or… - PATCHUpdate address whitelist mail settings
/mail_settings/address_whitelistThis endpoint allows you to update your current email address whitelist settings. You can select whether or not this setting should be enabled by assigning… - GETRetrieve bounce purge mail settings
/mail_settings/bounce_purgeThis endpoint allows you to retrieve your current bounce and purge settings. The Bounce Perge setting allows you to set a schedule that Twilio SendGrid will… - PATCHUpdate bounce purge mail settings
/mail_settings/bounce_purgeThis endpoint allows you to update your current bounce and purge settings. The Bounce Perge setting allows you to set a schedule that Twilio SendGrid will use… - GETRetrieve footer mail settings
/mail_settings/footerThis endpoint allows you to retrieve your current Footer mail settings. The Footer setting will insert a custom footer at the bottom of your text and HTML… - PATCHUpdate footer mail settings
/mail_settings/footerThis endpoint allows you to update your current Footer mail settings. The Footer setting will insert a custom footer at the bottom of your text and HTML email… - GETRetrieve forward bounce mail settings
/mail_settings/forward_bounceThis endpoint allows you to retrieve your current bounce forwarding mail settings. Enabling the Forward Bounce setting allows you to specify email addresses… - PATCHUpdate forward bounce mail settings
/mail_settings/forward_bounceThis endpoint allows you to update your current bounce forwarding mail settings. Enabling the Forward Bounce setting allows you to specify an email address to… - GETRetrieve forward spam mail settings
/mail_settings/forward_spamThis endpoint allows you to retrieve your current Forward Spam mail settings. Enabling the Forward Spam setting allows you to specify email addresses to which… - PATCHUpdate forward spam mail settings
/mail_settings/forward_spamThis endpoint allows you to update your current Forward Spam mail settings. Enabling the Forward Spam setting allows you to specify email addresses to which… - GETRetrieve legacy template mail settings
/mail_settings/templateThis endpoint allows you to retrieve your current legacy email template settings. This setting refers to our original email templates. We currently support… - PATCHUpdate template mail settings
/mail_settings/templateThis endpoint allows you to update your current legacy email template settings. This setting refers to our original email templates. We currently support more…
Contacts
- GETGet Sample Contacts
/marketing/contactsThis 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… - PUTAdd or Update a Contact
/marketing/contactsThis 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… - DELETEDelete Contacts
/marketing/contacts?delete_all_contacts=string&ids=stringThis 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.… - POSTGet Batched Contacts by IDs
/marketing/contacts/batchThis endpoint is used to retrieve a set of contacts identified by their IDs. This can be more efficient endpoint to get contacts than making a series of… - GETGet Total Contact Count
/marketing/contacts/countThis endpoint returns the total number of contacts you have stored. Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues… - GETGet All Existing Exports
/marketing/contacts/exportsUse this endpoint to retrieve details of all current exported jobs. It will return an array of objects, each of which records an export job in flight or… - POSTExport Contacts
/marketing/contacts/exportsUse this endpoint to export lists or segments of contacts. If you would just like to have a link to the exported list sent to your email set the… - GETExport Contacts Status
/marketing/contacts/exports/:idThis endpoint can be used to check the status of a contact export job. To use this call, you will need the id from the "Export Contacts" call. If you would… - PUTImport Contacts
/marketing/contacts/importsThis endpoint allows a CSV upload containing up to one million contacts or 5GB of data, whichever is smaller. Imports take place asynchronously: the endpoint… - GETImport Contacts Status
/marketing/contacts/imports/:idThis endpoint can be used to check the status of a contact import job. Use the job_id from the "Import Contacts," "Add or Update a Contact," or "Delete… - POSTSearch Contacts
/marketing/contacts/searchUse this endpoint to locate contacts. The request body's query field accepts valid SGQL for searching for a contact. Because contact emails are stored in… - POSTGet Contacts by Emails
/marketing/contacts/search/emailsThis endpoint allows you to retrieve up to 100 contacts matching the searched email address(es), including any alternate_emails. Email addresses are unique to… - GETGet a Contact by ID
/marketing/contacts/:idThis endpoint returns the full details and all fields for the specified contact. The "Get Contacts by Emails" endpoint can be used to get the ID of a contact.…
Custom Fields
- GETGet All Field Definitions
/marketing/field_definitionsThis endpoint retrieves all defined Custom Fields and Reserved Fields. - POSTCreate Custom Field Definition
/marketing/field_definitionsThis endpoint creates a new custom field definition. Custom field definitions are created with the given name and field_type. Although field names are stored… - DELETEDelete Custom Field Definition
/marketing/field_definitions/:custom_field_idThis endpoint deletes a defined Custom Field. You cand delete only Custom Fields; Reserved Fields cannot be deleted. - PATCHUpdate Custom Field Definition
/marketing/field_definitions/:custom_field_idThis endopoint allows you to update a defined Custom Field. Only your Custom fields can be modified; Reserved Fields cannot be updated.
Lists
- GETGet All Lists
/marketing/lists?page_size=100&page_token=stringThis endpoint returns an array of all of your contact lists. - POSTCreate List
/marketing/listsThis 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… - GETGet a List by ID
/marketing/lists/:id?contact_sample=falseThis endpoint returns data about a specific list. Setting the optional parameter contact_sample=true returns the contact_sample in the response body. Up to… - DELETEDelete a list
/marketing/lists/:id?delete_contacts=falseThis endpoint allows you to deletes a specific list. Optionally, you can also delete contacts associated to the list. The query parameter,… - PATCHUpdate List
/marketing/lists/:idThis endpoint updates the name of a list. - DELETERemove Contacts from a List
/marketing/lists/:id/contacts?contact_ids=stringThis endpoint allows you to remove contacts from a given list. The contacts will not be deleted. Only their list membership will be changed. - GETGet List Contact Count
/marketing/lists/:id/contacts/countThis endpoint returns the number of contacts on a specific list.
segmenting contacts
- GETGet List of Segments
/marketing/segments?parent_list_ids=string&no_parent_list_id=falseThis 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… - POSTCreate Segment
/marketing/segmentsThis endpoint allows you to create a segment. - GETGet Segment by ID
/marketing/segments/:segment_id?query_json=trueThis endpoint allows you to retrieve a single segment by ID. - DELETEDelete Segment
/marketing/segments/:segment_idThis 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.… - PATCHUpdate Segment
/marketing/segments/:segment_idThis 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.
Segmenting Contacts V2 - Beta
- GETGet List of Segments
/marketing/segments/2.0?parent_list_ids=string&no_parent_list_id=falseThe 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… - POSTCreate Segment
/marketing/segments/2.0The 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… - GETGet Segment by ID
/marketing/segments/2.0/:segment_id?contacts_sample=trueThe Segmentation V2 API is currently in private beta. If you'd like to be added to the beta, please fill out this form - DELETEDelete segment
/marketing/segments/2.0/:segment_idThe Segmentation V2 API is currently in private beta. If you'd like to be added to the beta, please fill out this form - PATCHUpdate Segment
/marketing/segments/2.0/:segment_idThe 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…
Segmenting Contacts
- POSTBulk Delete Segments
/marketing/segments/deleteThis 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…
Senders
- POSTCreate a Sender Identity
/marketing/sendersThis endpoint allows you to create a new sender identity. *You may create up to 100 unique sender identities.* Sender identities are required to be verified…
Single Sends
- GETGet All Single Sends
/marketing/singlesends?page_size=0&page_token=stringThis endpoint allows you to retrieve all your Single Sends. Returns all of your Single Sends with condensed details about each, including the Single Sends'… - POSTCreate Single Send
/marketing/singlesendsThis endpoint allows you to create a new Single Send. Please note that if you are migrating from the previous version of Single Sends, you no longer need to… - DELETEBulk Delete Single Sends
/marketing/singlesends?ids=stringThis endpoint allows you to delete multiple Single Sends using an array of Single Sends IDs. To first retrieve all your Single Sends' IDs, you can make a GET… - GETGet All Categories
/marketing/singlesends/categoriesThis endpoint allows you to retrieve all the categories associated with your Single Sends. This endpoint will return your latest 1,000 categories. - POSTGet Single Sends Search
/marketing/singlesends/search?page_size=0&page_token=stringThis endpoint allows you to search for Single Sends based on specified criteria. You can search for Single Sends by passing a combination of values using the… - GETGet Single Send by ID
/marketing/singlesends/:idThis endpoint allows you to retrieve details about one Single Send using a Single Send ID. You can retrieve all of your Single Sends by making a GET request… - POSTDuplicate Single Send
/marketing/singlesends/:idThis endpoint allows you to duplicate an existing Single Send using its Single Send ID. Duplicating a Single Send is useful when you want to create a Single… - DELETEDelete Single Send by ID
/marketing/singlesends/:idThis endpoint allows you to delete one Single Send using a Single Send ID. To first retrieve all your Single Sends' IDs, you can make a GET request to the… - PATCHUpdate Single Send
/marketing/singlesends/:idThis endpoint allows you to update a Single Send using a Single Send ID. You only need to pass the fields you want to update. Any blank/missing fields will… - PUTSchedule Single Send
/marketing/singlesends/:id/scheduleThis 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… - DELETEDelete Single Send Schedule
/marketing/singlesends/:id/scheduleThis endpoint allows you to cancel a scheduled Single Send using a Single Send ID. Making a DELETE request to this endpoint will cancel the scheduled sending…
Marketing Campaigns Stats
- GETGet All Automation Stats
/marketing/stats/automations?automation_ids=string&page_size=50&page_token=stringThis 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… - GETExport Automation Stats
/marketing/stats/automations/export?ids=string&timezone=UTCThis 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,… - GETGet Automation Stats by ID
/marketing/stats/automations/:id?group_by=step_id&step_ids=3fa85f64-5717-4562-b3fc-2c963f66afa6&aggregated_by=total&start_date=&end_date=&timezone=UTC&page_size=50&page_token=stringThis 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"… - GETGet Automation Click Tracking Stats by ID
/marketing/stats/automations/:id/links?group_by=step_id&step_ids=3fa85f64-5717-4562-b3fc-2c963f66afa6&page_size=50&page_token=stringThis 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… - GETGet All Single Sends Stats
/marketing/stats/singlesends?singlesend_ids=string&page_size=50&page_token=stringThis 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… - GETExport Single Send Stats
/marketing/stats/singlesends/export?ids=string&timezone=UTCThis 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,… - GETGet Single Send Stats by ID
/marketing/stats/singlesends/:id?aggregated_by=total&start_date=&end_date=&timezone=UTC&page_size=50&page_token=string&group_by=ab_variationThis 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… - GETGet Single Send Click Tracking Stats by ID
/marketing/stats/singlesends/:id/links?page_size=50&page_token=string&group_by=ab_variation&ab_variation_id=3fa85f64-5717-4562-b3fc-2c963f66afa6&ab_phase_id=testThis 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…
Send Test Email
- POSTSend a Test Marketing Email
/marketing/test/send_emailThis 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.…
Query
- GETFilter all messages
/messages?query=string&limit=10This 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… - GETFilter messages by message ID
/messages/:msg_idThis 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…
CSV (UI only)
- POSTRequest CSV
/messages/download?query=stringThis 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… - GETDownload CSV
/messages/download/:download_uuidThis endpoint will return a presigned URL that can be used to download the CSV that was requested from the "Request a CSV" endpoint.
Settings - Partner
- GETReturns a list of all partner settings.
/partner_settings?limit=0&offset=0This endpoint allows you to retrieve a list of all partner settings that you can enable. Our partner settings allow you to integrate your SendGrid account… - GETReturns all New Relic partner settings.
/partner_settings/new_relicThis endpoint allows you to retrieve your current New Relic partner settings. Our partner settings allow you to integrate your SendGrid account with our… - PATCHUpdates New Relic partner settings.
/partner_settings/new_relicThis endpoint allows you to update or change your New Relic partner settings. Our partner settings allow you to integrate your SendGrid account with our…
API Key Permissions
- GETRetrieve a list of scopes for which this user has access.
/scopesThis 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…
Teammates
- GETRetrieve access requests
/scopes/requests?limit=50&offset=0This endpoint allows you to retrieve a list of all recent access requests. The Response Header's link parameter will include pagination info. - DELETEDeny access request
/scopes/requests/:request_idThis endpoint allows you to deny an attempt to access your account. Note: Only teammate admins may delete a teammate's access request. - PATCHApprove access request
/scopes/requests/:request_id/approveThis endpoint allows you to approve an access attempt. Note: Only teammate admins may approve another teammate’s access request. - GETRetrieve all teammates
/teammates?limit=500&offset=0This endpoint allows you to retrieve a list of all current Teammates. You can limit the number of results returned using the limit query paramater. To return… - POSTInvite teammate
/teammatesThis endpoint allows you to invite a Teammate to your account via email. You can set a Teammate's initial permissions using the scopes array in the request… - GETRetrieve all pending teammates
/teammates/pendingThis endpoint allows you to retrieve a list of all pending Teammate invitations. Each teammate invitation is valid for 7 days. Users may resend the invitation… - DELETEDelete pending teammate
/teammates/pending/:tokenThis endpoint allows you to delete a pending teammate invite. - POSTResend teammate invite
/teammates/pending/:token/resendThis endpoint allows you to resend a Teammate invitation. Teammate invitations will expire after 7 days. Resending an invitation will reset the expiration date. - GETRetrieve specific teammate
/teammates/:usernameThis endpoint allows you to retrieve a specific Teammate by username. You can retrieve the username's for each of your Teammates using the "Retrieve all… - DELETEDelete teammate
/teammates/:usernameThis endpoint allows you to delete a teammate. Only the parent user or an admin teammate can delete another teammate. - PATCHUpdate teammate's permissions
/teammates/:usernameThis endpoint allows you to update a teammate’s permissions. To turn a teammate into an admin, the request body should contain an is_admin set to true.…
Sender Identities API
- GETGet all Sender Identities
/sendersThis endpoint allows you to retrieve a list of all sender identities that have been created for your account. - POSTCreate a Sender Identity
/sendersThis endpoint allows you to create a new sender identity. You may create up to 100 unique sender identities. - GETView a Sender Identity
/senders/:sender_idThis endpoint allows you to retrieve a specific sender identity. - DELETEDelete a Sender Identity
/senders/:sender_idThis endoint allows you to delete one of your sender identities. - PATCHUpdate a Sender Identity
/senders/:sender_idThis endpoint allows you to update a sender identity. Updates to from.email require re-verification. Partial updates are allowed, but fields that are marked… - POSTResend Sender Identity Verification
/senders/:sender_id/resend_verificationThis enpdoint allows you to resend a sender identity verification email.
Certificates
- POSTCreate an SSO Certificate
/sso/certificatesThis endpoint allows you to create an SSO certificate. - GETGet an SSO Certificate
/sso/certificates/:cert_idThis endpoint allows you to retrieve an individual SSO certificate. - DELETEDelete an SSO Certificate
/sso/certificates/:cert_idThis 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"… - PATCHUpdate SSO Certificate
/sso/certificates/:cert_idThis 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… - GETGet All SSO Certificates by Integration
/sso/integrations/:integration_id/certificatesThis 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…
Single Sign-On Settings
- GETGet All SSO Integrations
/sso/integrations?si=trueThis endpoint allows you to retrieve all SSO integrations tied to your Twilio SendGrid account. The IDs returned by this endpoint can be used by the APIs… - POSTCreate an SSO Integration
/sso/integrationsThis endpoint allows you to create an SSO integration. - GETGet an SSO Integration
/sso/integrations/:id?si=trueThis endpoint allows you to retrieve an SSO integration by ID. You can retrieve the IDs for your configurations from the response provided by the "Get All SSO… - DELETEDelete an SSO Integration
/sso/integrations/:idThis endpoint allows you to delete an IdP configuration by ID. You can retrieve the IDs for your configurations from the response provided by the "Get All SSO… - PATCHUpdate an SSO Integration
/sso/integrations/:id?si=trueThis endpoint allows you to modify an exisiting SSO integration. You can retrieve the IDs for your configurations from the response provided by the "Get All…
Single Sign-On Teammates
- POSTCreate SSO Teammate
/sso/teammatesThis endpoint allows you to create an SSO Teammate. The email provided for this user will also function as the Teammate’s username. - PATCHEdit an SSO Teammate
/sso/teammates/:usernameThis endpoint allows you to modify an existing SSO Teammate. To turn a teammate into an admin, the request body should contain the is_admin field set to true.…
Subusers API
- GETList all Subusers
/subusers?username=string&limit=0&offset=0This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back… - POSTCreate Subuser
/subusersThis endpoint allows you to create a new subuser. - GETRetrieve Subuser Reputations
/subusers/reputations?usernames=stringThis endpoint allows you to request the reputations for your subusers. Subuser sender reputations give a good idea how well a sender is doing with regards to… - DELETEDelete a subuser
/subusers/:subuser_nameThis endpoint allows you to delete a subuser. This is a permanent action. Once deleted, a subuser cannot be retrieved. - PATCHEnable/disable a subuser
/subusers/:subuser_nameThis endpoint allows you to enable or disable a subuser. - PUTUpdate IPs assigned to a subuser
/subusers/:subuser_name/ipsThis 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…
Subuser Statistics
- GETRetrieve email statistics for your subusers.
/subusers/stats?limit=0&offset=0&aggregated_by=day&subusers=string&start_date=string&end_date=stringThis endpoint allows you to retrieve the email statistics for the given subusers. You may retrieve statistics for up to 10 different subusers by including an… - GETRetrieve monthly stats for all subusers
/subusers/stats/monthly?date=string&subuser=string&sort_by_metric=delivered&sort_by_direction=desc&limit=5&offset=0This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range. When using the sort_by_metric to sort your stats… - GETRetrieve the totals for each email statistic metric for all subusers.
/subusers/stats/sums?sort_by_direction=desc&start_date=string&end_date=string&limit=5&offset=0&aggregated_by=string&sort_by_metric=deliveredThis endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range. - GETRetrieve the monthly email statistics for a single subuser
/subusers/:subuser_name/stats/monthly?date=string&sort_by_metric=delivered&sort_by_direction=desc&limit=5&offset=0This endpoint allows you to retrive the monthly email statistics for a specific subuser. When using the sort_by_metric to sort your stats by a specific…
Subuser Monitor Settings
- GETRetrieve monitor settings for a subuser
/subusers/:subuser_name/monitor - PUTUpdate Monitor Settings for a subuser
/subusers/:subuser_name/monitor - POSTCreate monitor settings
/subusers/:subuser_name/monitor - DELETEDelete monitor settings
/subusers/:subuser_name/monitor
Blocks API
- GETRetrieve all blocks
/suppression/blocks?start_time=0&end_time=0&limit=0&offset=0This endpoint allows you to retrieve all email addresses that are currently on your blocks list. - DELETEDelete blocks
/suppression/blocksThis 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… - GETRetrieve a specific block
/suppression/blocks/:emailThis endpoint allows you to retrieve a specific email address from your blocks list. - DELETEDelete a specific block
/suppression/blocks/:emailThis endpoint allows you to delete a specific email address from your blocks list.
Bounces API
- GETRetrieve all bounces
/suppression/bounces?start_time=0&end_time=0This endpoint allows you to retrieve all of your bounces. - DELETEDelete bounces
/suppression/bouncesThis 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… - GETRetrieve a Bounce
/suppression/bounces/:emailThis endpoint allows you to retrieve a specific bounce by email address. - DELETEDelete a bounce
/suppression/bounces/:email?email_address=user@example.comThis endpoint allows you to remove an email address from your bounce list.
Invalid Emails API
- GETRetrieve all invalid emails
/suppression/invalid_emails?start_time=0&end_time=0&limit=0&offset=0This endpoint allows you to retrieve a list of all invalid email addresses. - DELETEDelete invalid emails
/suppression/invalid_emailsThis endpoint allows you to remove email addresses from your invalid email address list. There are two options for deleting invalid email addresses: 1) You… - GETRetrieve a specific invalid email
/suppression/invalid_emails/:emailThis endpoint allows you to retrieve a specific invalid email addresses. - DELETEDelete a specific invalid email
/suppression/invalid_emails/:emailThis endpoint allows you to remove a specific email address from the invalid email address list.
Spam Reports API
- GETRetrieve all spam reports
/suppression/spam_reports?start_time=0&end_time=0&limit=0&offset=0This endpoint allows you to retrieve all spam reports. - DELETEDelete spam reports
/suppression/spam_reportsThis endpoint allows you to delete your spam reports. Deleting a spam report will remove the suppression, meaning email will once again be sent to the… - GETRetrieve a specific spam report
/suppression/spam_reports/:emailThis endpoint allows you to retrieve a specific spam report by email address. - DELETEDelete a specific spam report
/suppression/spam_reports/:emailThis endpoint allows you to delete a specific spam report by email address. Deleting a spam report will remove the suppression, meaning email will once again…
Transactional Templates
- GETRetrieve paged transactional templates.
/templates?generations=legacy&page_size=1.0&page_token=stringThis endpoint allows you to retrieve all transactional templates. - POSTCreate a transactional template.
/templatesThis endpoint allows you to create a transactional template. - GETRetrieve a single transactional template.
/templates/:template_idThis endpoint allows you to retrieve a single transactional template. - POSTDuplicate a transactional template.
/templates/:template_idThis endpoint allows you to duplicate a transactional template. - DELETEDelete a template.
/templates/:template_idThis endpoint allows you to delete a transactional template. - PATCHEdit a transactional template.
/templates/:template_idThis endpoint allows you to edit the name of a transactional template. To edit the template itself, create a new transactional template version.
Transactional Templates Versions
- POSTCreate a new transactional template version.
/templates/:template_id/versionsThis endpoint allows you to create a new version of a template. - GETRetrieve a specific transactional template version.
/templates/:template_id/versions/:version_idThis endpoint allows you to retrieve a specific version of a template. - DELETEDelete a transactional template version.
/templates/:template_id/versions/:version_idThis endpoint allows you to delete a transactional template version. - PATCHEdit a transactional template version.
/templates/:template_id/versions/:version_idThis endpoint allows you to edit the content of your template version. - POSTActivate a transactional template version.
/templates/:template_id/versions/:version_id/activateThis endpoint allows you to activate a version of one of your templates.
Settings - Tracking
- GETRetrieve Tracking Settings
/tracking_settingsThis endpoint allows you to retrieve a list of all tracking settings on your account. - GETRetrieve Click Track Settings
/tracking_settings/clickThis endpoint allows you to retrieve your current click tracking setting. Click Tracking overrides all the links and URLs in your emails and points them to… - PATCHUpdate Click Tracking Settings
/tracking_settings/clickThis endpoint allows you to enable or disable your current click tracking setting. Click Tracking overrides all the links and URLs in your emails and points… - GETRetrieve Google Analytics Settings
/tracking_settings/google_analyticsThis endpoint allows you to retrieve your current setting for Google Analytics. Google Analytics helps you understand how users got to your site and what… - PATCHUpdate Google Analytics Settings
/tracking_settings/google_analyticsThis endpoint allows you to update your current setting for Google Analytics. Google Analytics helps you understand how users got to your site and what… - GETGet Open Tracking Settings
/tracking_settings/openThis endpoint allows you to retrieve your current settings for open tracking. Open Tracking adds an invisible image at the end of the email which can track… - PATCHUpdate Open Tracking Settings
/tracking_settings/openThis endpoint allows you to update your current settings for open tracking. Open Tracking adds an invisible image at the end of the email which can track… - GETRetrieve Subscription Tracking Settings
/tracking_settings/subscriptionThis endpoint allows you to retrieve your current settings for subscription tracking. Subscription tracking adds links to the bottom of your emails that… - PATCHUpdate Subscription Tracking Settings
/tracking_settings/subscriptionThis endpoint allows you to update your current settings for subscription tracking. Subscription tracking adds links to the bottom of your emails that allows…
Users API
- GETGet a user's account information.
/user/accountThis endpoint allows you to retrieve your user account details. Your user's account information includes the user's account type and reputation. - GETRetrieve your credit balance
/user/creditsThis endpoint allows you to retrieve the current credit balance for your account. Each account has a credit balance, which is a base number of emails it can… - GETRetrieve your account email address
/user/emailThis endpoint allows you to retrieve the email address currently on file for your account. - PUTUpdate your account email address
/user/emailThis endpoint allows you to update the email address currently on file for your account. - PUTUpdate your password
/user/passwordThis endpoint allows you to update your password. - GETGet a user's profile
/user/profile - PATCHUpdate a user's profile
/user/profileThis endpoint allows you to update your current profile details. Any one or more of the parameters can be updated via the PATCH /user/profile endpoint. You… - GETRetrieve your username
/user/usernameThis endpoint allows you to retrieve your current account username. - PUTUpdate your username
/user/usernameThis endpoint allows you to update the username for your account.
Settings - Enforced TLS
- GETRetrieve current Enforced TLS settings.
/user/settings/enforced_tlsThis endpoint allows you to retrieve your current Enforced TLS settings. The Enforced TLS settings specify whether or not the recipient is required to support… - PATCHUpdate Enforced TLS settings
/user/settings/enforced_tlsThis endpoint allows you to update your Enforced TLS settings. To require TLS from recipients, set require_tls to true. If either require_tls or…
Webhooks
- GETRetrieve Event Webhook settings
/user/webhooks/event/settingsThis endpoint allows you to retrieve your current event webhook settings. If an event type is marked as true, then the event webhook will include information… - PATCHUpdate Event Notification Settings
/user/webhooks/event/settingsThis endpoint allows you to update your current event webhook settings. If an event type is marked as true, then the event webhook will include information… - GETRetrieve Signed Webhook Public Key
/user/webhooks/event/settings/signedThis endpoint allows you to retrieve your signed webhook's public key. Once you have enabled signing of the Event Webhook, you will need the public key… - PATCHEnable/Disable Signed Webhook
/user/webhooks/event/settings/signedThis endpoint allows you to enable or disable signing of the Event Webhook. This endpoint takes a single boolean request parameter, enabled. You may either… - POSTTest Event Notification Settings
/user/webhooks/event/testThis endpoint allows you to test your event webhook by sending a fake event notification post to the provided URL. SendGrid’s Event Webhook will notify a URL… - GETRetrieve all parse settings
/user/webhooks/parse/settingsThis endpoint allows you to retrieve all of your current inbound parse settings. - GETRetrieves Inbound Parse Webhook statistics.
/user/webhooks/parse/stats?limit=string&offset=string&aggregated_by=day&start_date=string&end_date=The day the request is made.This endpoint allows you to retrieve the statistics for your Parse Webhook useage. SendGrid's Inbound Parse Webhook allows you to parse the contents and…
Settings - Inbound Parse
- POSTCreate a parse setting
/user/webhooks/parse/settingsThis endpoint allows you to create a new inbound parse setting. Creating an Inbound Parse setting requires two pieces of information: a url and a hostname.… - GETRetrieve a specific parse setting
/user/webhooks/parse/settings/:hostnameThis endpoint allows you to retrieve a specific inbound parse setting by hostname. You can retrieve all your Inbound Parse settings and their associated host… - DELETEDelete a parse setting
/user/webhooks/parse/settings/:hostnameThis endpoint allows you to delete a specific inbound parse setting by hostname. You can retrieve all your Inbound Parse settings and their associated host… - PATCHUpdate a parse setting
/user/webhooks/parse/settings/:hostnameThis endpoint allows you to update a specific inbound parse setting by hostname. You can retrieve all your Inbound Parse settings and their associated host…
Email Address Validation
- POSTValidate an email
/validations/emailThis endpoint allows you to validate an email address.
Sender Verification
- GETGet All Verified Senders
/verified_senders?limit=0.0&lastSeenID=0.0&id=0This endpoint allows you to retrieve all the Sender Identities associated with an account. This endpoint will return both verified and unverified senders. You… - POSTCreate Verified Sender Request
/verified_sendersThis 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…
Showing 300 of 334 endpoints. Fork the collection to see all of them.
API details
- Base URL
http://api.sendgrid.com/v3- Authentication
- An API key in the Authorization header
- Operations
- 334 operations on 201 pathsGET 154POST 71DELETE 56PATCH 43PUT 10
- Main resources
- Contacts 13Settings - Mail 13Contacts API - Recipients 12Domain Authentication 12Campaigns API 11Single Sends 11Teammates 11Contacts API - Lists 10Link branding 10Designs API 9
- Response formats
application/json- Description format
- OpenAPI 3.0.0, API version
1.0.0 - Links
- Documentation · OpenAPI document
- Listed from
- APIs.guru OpenAPI Directory (CC0-1.0)
Source updated
How to test the Email Activity (beta) in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Email Activity (beta) collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Retrieve all recent access attempts” (GET /access_settings/activity?limit=20), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Email Activity (beta)?
The Beta endpoints for the new Email Activity APIs - functionality is subject to change without notice. You may not have access to this Beta endpoint. Email… It is listed under Communication and has 334 endpoints.
Who publishes the Email Activity (beta)?
It is listed from SendGrid's public API description (an OpenAPI document), not published by SendGrid on Swastik Codes. Anyone who controls sendgrid.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Email Activity (beta)?
Requests go to http://api.sendgrid.com/v3. Endpoint paths are added to this base URL.
How do I authenticate with the Email Activity (beta)?
With an API key in the Authorization header.
How many endpoints does the Email Activity (beta) have?
334 operations on 201 paths (154 GET, 71 POST, 56 DELETE, 43 PATCH, 10 PUT). The largest groups are Contacts, Settings - Mail, Contacts API - Recipients, Domain Authentication.
Is forking the Email Activity (beta) free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.