Sendgrid

Learn how to use Sendgrid with Composio

Overview

Enum

SENDGRID

Description

SendGrid is a cloud-based email delivery platform providing transactional and marketing email services, with APIs for integration, analytics, and scalability

Authentication Details

apiKey
stringRequired

Actions

Update a sender identity by sending a patch request with the id and json-formatted changes. unchanged fields will stay the same. retrieve ids via get to /verified senders.

Action Parameters

id
stringRequired
address
string
address2
string
city
string
country
string
from_email
stringRequired
from_name
string
nickname
stringRequired
reply_to
stringRequired
reply_to_name
string
state
string
zip
string

Action Response

data
object
successful
boolean
error

This api endpoint lists all accessible scopes for the user’s api key, with permissions determining endpoint access. visit sendgrid documentation for more on api key permissions.

Action Parameters

Action Response

data
object
successful
boolean
error

This operation removes a batch of ips from an ip pool. all ips associated with the pool will be unassigned from the deleted pool. however, this operation does not remove the ips from your account.

Action Parameters

poolid
stringRequired
ips
arrayRequired

Action Response

data
object
successful
boolean
error

The design api enables partial design updates using patch requests, changing only specified fields, like the ‘name’ field, with no impact on other data.

Action Parameters

id
stringRequired
categories
array
generate_plain_content
booleanDefaults to True
html_content
string
name
stringDefaults to My Design
plain_content
stringDefaults to <generated from html_content if left empty>
subject
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to get all of your ip pools.

Action Parameters

Action Response

data
object
successful
boolean
error

Delete a specific event webhook by id with this endpoint. unlike other endpoints which default to the oldest webhook, this requires an id, else it errors to prevent accidental deletions. to disable, not delete, use enabled property to false.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

This api endpoint enables the deletion of multiple single sends by providing their ids. retrieve ids with a get request to /marketing/singlensends. deletions are irreversible.

Action Parameters

ids
array

Action Response

data
object
successful
boolean
error

This endpoint returns all the integrations for the user making this call.

Action Parameters

Action Response

data
object
successful
boolean
error

This api endpoint allows users to cancel or pause a scheduled email by providing its batch id. to change or remove this status, specific endpoints must be used; exceeding limits or duplicating actions will trigger a 400 error.

Action Parameters

batch_id
stringRequired
status
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve your current settings for subscription tracking. subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails.

Action Parameters

Action Response

data
object
successful
boolean
error

Retrieve monthly email stats for subusers with sort by metric, excluding sorts by bounce drops, deferred, invalid emails, processed, spam report drops, spam reports, unsubscribe drops.

Action Parameters

subuser_name
stringRequired
date
stringRequired
sort_by_metric
stringDefaults to delivered
sort_by_direction
string
limit
integerDefaults to 5
offset
integer

Action Response

data
object
successful
boolean
error

This endpoint will return the total number of bounces by classification in descending order for each day. you can retrieve the bounce classification totals in csv format by specifying "text/csv" in the accept header.

Action Parameters

start_date
string
end_date
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete a specific recipient list with the given id.

Action Parameters

list_id
integerRequired
delete_contacts
boolean

Action Response

data
object
successful
boolean
error

Set up an event webhook by providing a url, choosing events for post requests, and receive a unique id. after creation, you can add names, oauth, and signature verification.

Action Parameters

bounce
boolean
click
boolean
deferred
boolean
delivered
boolean
dropped
boolean
enabled
boolean
friendly_name
string
group_resubscribe
boolean
group_unsubscribe
boolean
oauth_client_id
string
oauth_client_secret
string
oauth_token_url
string
open
boolean
processed
boolean
spam_report
boolean
unsubscribe
boolean
url
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve all suppressed email addresses belonging to the given group.

Action Parameters

group_id
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint lets users delete spam reports, lifting email suppression for specified addresses. it’s advised only when recipients want to resume emails. two deletion methods: ‘delete all’ or listing emails. use ‘bypass filters’ for exceptions.

Action Parameters

delete_all
boolean
emails
array

Action Response

data
object
successful
boolean
error

Retrieve your google analytics settings, which are set to google’s recommended defaults, to understand user site activity. for details, use google’s guides and best practices links.

Action Parameters

Action Response

data
object
successful
boolean
error

This endpoint retrieves a paginated list of all your bounces, allowing customization of page size with limit and starting position with offset for multiple requests.

Action Parameters

start_time
integer
end_time
integer
limit
integer
offset
integer
email
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to update the remaining credits for a subuser.

Action Parameters

subuser_name
stringRequired
allocation_update
integerRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete a specific inbound parse setting by hostname. you can retrieve all your inbound parse settings and their associated host names with the “retrieve all parse settings” endpoint.

Action Parameters

hostname
stringRequired

Action Response

data
object
successful
boolean
error

Retrieve an event webhook by id to get settings, event types, and url details. without id, the oldest is returned. signatures and oauth webhooks have extra properties. use another endpoint for multiple webhook ids.

Action Parameters

id
stringRequired
include
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete an existing sender.

Action Parameters

id
integerRequired

Action Response

data
object
successful
boolean
error

This operation adds a twilio sendgrid ip address to your account. you can also assign up to 100 subusers to the ip address at creation.

Action Parameters

include_region
boolean
is_auto_warmup
booleanRequired
is_parent_assigned
booleanRequired
region
string
subusers
array

Action Response

data
object
successful
boolean
error

This endpoint schedules campaign emails for a specific time, recommending off-peak times like 10:53 instead of on the hour to minimize server deferrals and enhance delivery rates.

Action Parameters

campaign_id
integerRequired
send_at
integerRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a single transactional template.

Action Parameters

template_id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a specific invalid email addresses.

Action Parameters

email
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve all of your segments.

Action Parameters

Action Response

data
object
successful
boolean
error

Summarize email activity filtering: use url-encoded queries in the format query={type}="{content}" to search email activity. example: filter by email with query=to email\%3d"example@example.com". reference more at sendgrid query reference.

Action Parameters

query
stringRequired
limit
integerDefaults to 10

Action Response

data
object
successful
boolean
error

This endpoint removes an ip from warmup mode, returning a 204 code if successful. for warmup status details prior to removal, use the “retrieve warmup status” endpoint.

Action Parameters

ip_address
stringRequired

Action Response

data
object
successful
boolean
error

Get marketing campaigns segment by id

Action Parameters

segment_id
stringRequired
contacts_sample
boolean

Action Response

data
object
successful
boolean
error

this 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 teammates” endpoint.

Action Parameters

username
stringRequired

Action Response

data
object
successful
boolean
error

Initiating a backend process creates a csv file of up to 1 million events from the last 30 days, emailed to the user with a 3-day expiry link. limited to one request per 12 hours, it’s similar to the get single message but for csv downloads.

Action Parameters

query
string

Action Response

data
object
successful
boolean
error

Update your google analytics settings to track user activity on your site more effectively; defaults follow google’s recommendations. for guidance, visit google’s url builder and campaign building best practices.

Action Parameters

enabled
boolean
utm_campaign
string
utm_content
string
utm_medium
string
utm_source
string
utm_term
string

Action Response

data
object
successful
boolean
error

Add an ip address to a pool with this endpoint. activation in sendgrid needed first. it takes up to 60 seconds. possible to add to multiple pools. retrieve ips via a specific endpoint.

Action Parameters

pool_name
stringRequired
ip
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to immediately send an existing campaign. normally a post request would have a body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed.

Action Parameters

campaign_id
integerRequired

Action Response

data
object
successful
boolean
error

This api endpoint retrieves assigned ip addresses used to send emails for various domains, where the ip’s reputation is influenced by the collective performance of all sending users.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve your current profile details.

Action Parameters

Action Response

data
object
successful
boolean
error

The function lists your ip pools and samples up to 10 ips from each. for more ips per pool, use “get ips assigned to an ip pool.” max of 100 ip pools per user.

Action Parameters

limit
integer
after_key
integer
ip
string
region
string
include_region
boolean

Action Response

data
object
successful
boolean
error

This endpoint lets you access settings for whitelisting specific emails or domains to prevent email suppression due to bounces, blocks, or unsubscribes.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve all of your alerts.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint allows you to update an existing certificate by id. you can retrieve a certificate’s id from the response provided by the “get all sso integrations” endpoint.

Action Parameters

cert_id
stringRequired
enabled
boolean
integration_id
string
public_certificate
string

Action Response

data
object
successful
boolean
error

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

Action Parameters

campaign_id
integerRequired

Action Response

data
object
successful
boolean
error

Create an sso teammate with email as username. assign roles using is admin, scopes, or persona. admins have full rights, personas have predefined permissions, and scopes are specific rights. teammates can manage subusers with potential limitations.

Action Parameters

email
stringRequired
first_name
stringRequired
has_restricted_subuser_access
boolean
is_admin
boolean
last_name
stringRequired
persona
string
scopes
array
subuser_access
array

Action Response

data
object
successful
boolean
error

The endpoint retrieves settings for tracking email opens using an invisible image. it logs open events when images load, with data available in sendgrid’s statistics portal and event webhook.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint allows you to create a new suppression group. to add an email address to the suppression group, create a suppression.

Action Parameters

description
string
is_default
boolean
name
string

Action Response

data
object
successful
boolean
error

Retrieve email stats by browser with advanced stats api, storing 7 days of data, and defaulting to 500 items per request. segment by location, device, and more. visit provided link for details.

Action Parameters

browsers
string
limit
integer
offset
integer
aggregated_by
string
start_date
stringRequired
end_date
string

Action Response

data
object
successful
boolean
error

The designs/pre-builts endpoint fetches a list of twilio sendgrid’s ready-made designs, not user-specific ones, with 100 results per request by default, adjustable with page size. useful for duplicating and editing design ids.

Action Parameters

page_size
integerDefaults to 100
page_token
string
summary
booleanDefaults to True

Action Response

data
object
successful
boolean
error

Endpoint checks reverse dns record validity via valid in validation results.a record. if false, it’s undetermined, not necessarily invalid. check reason for explanation. retrieve ids with “retrieve all reverse dns records” endpoint.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to update the settings for an authenticated domain.

Action Parameters

domain_id
stringRequired
custom_spf
boolean
default
boolean

Action Response

data
object
successful
boolean
error

This endpoint asynchronously deletes an identifier (not the entire contact) from a contact, failing if it’s their only one. allowed identifier types are email, phonenumberid, externalid, or anonymousid.

Action Parameters

contact_id
stringRequired
identifier_type
stringRequired
identifier_value
stringRequired

Action Response

data
object
successful
boolean
error

Retrieve authenticated domain lists in pages using the limit parameter for page size and offset to start from specific list positions. multiple requests handle large lists.

Action Parameters

limit
integer
offset
integer
exclude_subusers
boolean
username
string
domain
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to send a test campaign. to send to multiple addresses, use an array for the json “to” value [“one@address”,“two@address”]

Action Parameters

campaign_id
integerRequired
to
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to remove an ip address from that domain’s authentication.

Action Parameters

id
integerRequired
ip
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint lets you remove ips from your allowed list by sending an array of their ids, obtained from another endpoint. carefully select ips to avoid blocking your account access. if blocked, submit a support ticket.

Action Parameters

ids
array

Action Response

data
object
successful
boolean
error

The endpoint can handle 30k contacts or 6mb, reports queuing/errors, needs extra steps to confirm changes and retrieve ids. custom fields must pre-exist and exact identifiers are required for updates; email addresses are auto-lowered in case.

Action Parameters

contacts
arrayRequired
list_ids
array

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a single segment with the given id.

Action Parameters

segment_id
integerRequired

Action Response

data
object
successful
boolean
error

This endpoint provides an array with details on active or completed export jobs. each object includes export type, status, and downloadable urls for ready exports. useful when export ids are unknown.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve all the categories associated with your single sends. this endpoint will return your latest 1,000 categories.

Action Parameters

Action Response

data
object
successful
boolean
error

The endpoint provides details of cancelled or paused scheduled sends but only if they have a batch id. sends scheduled without a batch id via /mail/send won’t be listed and can’t be paused or cancelled later through this endpoint.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint allows you to create an sso integration.

Action Parameters

completed_integration
boolean
enabled
booleanRequired
entity_id
stringRequired
name
stringRequired
signin_url
stringRequired
signout_url
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete an alert.

Action Parameters

alert_id
integerRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to get a list of all your senders.

Action Parameters

Action Response

data
object
successful
boolean
error

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

Action Parameters

email
stringRequired

Action Response

data
object
successful
boolean
error

Manually refresh a segment by segment id.

Action Parameters

segment_id
stringRequired
user_time_zone
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to update the name of an ip pool.

Action Parameters

pool_name
stringRequired
name
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to verify a sender requests. the token is generated by sendgrid and included in a verification email delivered to the address that’s pending verification.

Action Parameters

token
stringRequired

Action Response

data
object
successful
boolean
error

Retrieve user’s api key names and ids with this endpoint; keys themself cannot be retrieved for security. lost keys require recreation. use ‘api key id’ to manage keys.

Action Parameters

limit
integer

Action Response

data
object
successful
boolean
error

this endpoint allows you to update an alert.

Action Parameters

alert_id
integerRequired
email_to
string
frequency
string
percentage
integer

Action Response

data
object
successful
boolean
error

this endpoint allows you to enable or disable a subuser.

Action Parameters

subuser_name
stringRequired
disabled
boolean

Action Response

data
object
successful
boolean
error

This endpoint lets you delete a single send with its id, which you can obtain by a get request to /marketing/singlensends. note: deletion is irreversible.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

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

Action Parameters

username
string

Action Response

data
object
successful
boolean
error

Retrieve spam reports in pages using limit for page size and offset to continue from a specific list position. multiple requests handle larger lists.

Action Parameters

start_time
integer
end_time
integer
limit
integer
offset
integer
email
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve all of your email statistics for each of your categories. if you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.

Action Parameters

start_date
stringRequired
end_date
string
categories
stringRequired
aggregated_by
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to update your current settings for subscription tracking. subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails.

Action Parameters

enabled
boolean
html_content
string
landing
string
plain_content
string
replace
string
url
string

Action Response

data
object
successful
boolean
error

Fetches your account’s ip addresses with details such as pool association and warm-up status. ‘is parent assigned’ and ‘pool’ must be exclusive. pagination needs ‘limit’ and ‘before key’ or ‘after key’.

Action Parameters

ip
string
limit
integer
after_key
integer
before_key
string
is_leased
boolean
is_enabled
boolean
is_parent_assigned
boolean
pool
string
start_added_at
integer
end_added_at
integer
region
string
include_region
boolean

Action Response

data
object
successful
boolean
error

Retrieves offerings available under the organization.

Action Parameters

Action Response

data
object
successful
boolean
error

Search json data for segments by specifying criteria for dates, text, and campaign ids using operators and boolean logic. optional list ids can refine results. used for email metrics.

Action Parameters

conditions
arrayRequired
list_id
integerRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to create an sso certificate.

Action Parameters

enabled
boolean
integration_id
stringRequired
public_certificate
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint retrieves enforced tls settings that mandate recipients to support tls 1.1+ or have a valid certificate. if not met, messages are dropped with a “tls required but not supported” block event.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint allows you to create a new version of a template.

Action Parameters

template_id
stringRequired
active
integer
editor
string
generate_plain_content
booleanDefaults to True
html_content
string
name
stringRequired
plain_content
stringDefaults to <generated from html_content if left empty>
subject
stringRequired
test_data
string

Action Response

data
object
successful
boolean
error

The api endpoint allows subusers to fetch up to five domains verified by the main account for sending emails, with a defined order of domain selection.

Action Parameters

username
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to activate a version of one of your templates.

Action Parameters

template_id
stringRequired
version_id
stringRequired

Action Response

data
object
successful
boolean
error

this 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 is a permanent action.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve all custom fields.

Action Parameters

Action Response

data
object
successful
boolean
error

This operation retrieves details of an ip pool, such as name, id, some sample ips (up to 10), and the total ip count. for more ips, use “get ips assigned to an ip pool.”

Action Parameters

poolid
stringRequired
include_region
boolean

Action Response

data
object
successful
boolean
error

This endpoint removes an email from suppressions, allowing future emails to be sent to it. use with consent or bypass filters for one-off emails.

Action Parameters

email
stringRequired

Action Response

data
object
successful
boolean
error

This operation deletes an ip pool and unassigns all ip addresses associated with the pool. ip addresses associated with the deleted pool will remain in your account.

Action Parameters

poolid
stringRequired

Action Response

data
object
successful
boolean
error

Create a new inbound parse setting with a twilio sendgrid authenticated hostname and a public url to receive parsed messages via http post. complete domain authentication and mx record setup as instructed in sendgrid documentation.

Action Parameters

hostname
string
send_raw
boolean
spam_check
boolean
url
string

Action Response

data
object
successful
boolean
error

Use the endpoint to test marketing emails with a template id and up to 10 contacts. requires a from address or sender id. supports only dynamic transactional templates. manage with sendgrid app or api.

Action Parameters

custom_unsubscribe_url
string
emails
arrayRequired
from_address
string
sender_id
integer
suppression_group_id
integer
template_id
stringRequired
version_id_override
string

Action Response

data
object
successful
boolean
error

This endpoint enables campaign creation, requiring a subject, sender id, content (html and text suggested), and a list or segment id for sending or scheduling, but not for initial creation.

Action Parameters

categories
array
custom_unsubscribe_url
string
editor
string
html_content
string
ip_pool
string
list_ids
array
plain_content
string
segment_ids
array
sender_id
integer
subject
string
suppression_group_id
integer
title
stringRequired

Action Response

data
object
successful
boolean
error

Sendgrid’s inbound parse webhook parses incoming emails, up to 30mb, and posts to a specified url, with available integrations listed in their library index.

Action Parameters

limit
string
offset
string
aggregated_by
string
start_date
stringRequired
end_date
stringDefaults to The day the request is made.

Action Response

data
object
successful
boolean
error

this endpoint allows you to put an ip address into warmup mode.

Action Parameters

ip
string

Action Response

data
object
successful
boolean
error

Retrieve email stats by provider with advanced stats api, displaying details like location and device. only 7 days of data stored, 500 items per request. more info at sendgrid’s statistics overview.

Action Parameters

mailbox_providers
string
limit
integer
offset
integer
aggregated_by
string
start_date
stringRequired
end_date
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to add one or more email addresses to the global suppressions group.

Action Parameters

recipient_emails
arrayRequired

Action Response

data
object
successful
boolean
error

Use the endpoint to export contact lists or segments by email, with notifications, or download as csvs using an ‘id’. specify the data by id and choose json or csv output with a max file size option.

Action Parameters

file_type
string
list_ids
array
max_file_size
integerDefaults to 5000
notifications__email
boolean
segment_ids
array

Action Response

data
object
successful
boolean
error

Use this endpoint with an id from “export contacts” to check the status and get urls for downloading your csv contact export files. regular exports are recommended for backups.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint retrieves all defined custom fields and reserved fields.

Action Parameters

Action Response

data
object
successful
boolean
error

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

Action Parameters

email
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to update the credits for a subuser.

Action Parameters

subuser_name
stringRequired
reset_frequency
string
total
integer
type
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to check the upload status of a marketing campaigns recipient.

Action Parameters

Action Response

data
object
successful
boolean
error

Retrieve monthly subuser email stats for a date range but can’t sort by metrics like bounce drops, deferred, invalid emails, processed, spam reports, or unsubscribe drops.

Action Parameters

date
stringRequired
subuser
string
sort_by_metric
string
sort_by_direction
string
limit
integerDefaults to 5
offset
integer

Action Response

data
object
successful
boolean
error

Use the endpoint to fetch up to 100 contacts by identifiers (email, phone number, etc.). successful queries return 200, no results return 404, and errors return 400. regular backups are advised.

Action Parameters

identifier_type
stringRequired
identifiers
arrayRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve all of your ip addresses that are currently warming up.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve your user account details. your user’s account information includes the user’s account type and reputation.

Action Parameters

Action Response

data
object
successful
boolean
error

this 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 lists that any one recipient has been added to.

Action Parameters

recipient_id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint deletes a defined custom field. you can delete only custom fields; reserved fields cannot be deleted.

Action Parameters

custom_field_id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete an sso certificate. you can retrieve a certificate’s id from the response provided by the “get all sso integrations” endpoint.

Action Parameters

cert_id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint returns a list of all of a user’s bulk email validation jobs.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint lets you retrieve click-tracking stats for a single automation. the stats returned list the urls embedded in your automation and the number of clicks each one received.

Action Parameters

id
stringRequired
group_by
array
step_ids
array
page_size
integerDefaults to 25
page_token
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to add a single recipient to a list.

Action Parameters

list_id
integerRequired
recipient_id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a single recipient list.

Action Parameters

list_id
integerRequired

Action Response

data
object
successful
boolean
error

Updates an account’s package and attaches optional add-ons like marketing campaigns, dedicated ips, and expert services. note: accounts are limited to one package.

Action Parameters

accountID
stringRequired
offerings
arrayRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a single suppression group.

Action Parameters

group_id
stringRequired

Action Response

data
object
successful
boolean
error

Update single send drafts using its id via this endpoint; only changed properties are affected. the ‘send at’ property sets a date but doesn’t schedule it; use schedule single send endpoint or ui to schedule.

Action Parameters

id
stringRequired
categories
array
email__config__custom__unsubscribe__url
string
email__config__design__id
string
email__config__editor
string
email__config__generate__plain__content
booleanDefaults to True
email__config__html__content
string
email__config__ip__pool
string
email__config__plain__content
string
email__config__sender__id
integer
email__config__subject
string
email__config__suppression__group__id
integer
name
stringRequired
send_at
string
send__to__all
boolean
send__to__list__ids
array
send__to__segment__ids
array

Action Response

data
object
successful
boolean
error

this 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 exist, the suppressions will be added to the global suppressions list.

Action Parameters

group_id
stringRequired
recipient_emails
arrayRequired

Action Response

data
object
successful
boolean
error

This endpoint creates an integration for email event forwarding. each integration has a maximum number of allowed integration instances per user. for example, users can create up to 10 segment integrations.

Action Parameters

destination
stringRequired
filters__email__events
array
label
stringDefaults to Untitled Integration
properties__destination__region
string
properties__write__key
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to validate an email address.

Action Parameters

email
stringRequired
source
string

Action Response

data
object
successful
boolean
error

This endpoint adds allowed ip addresses to a list, which then assigns each ip an id for future removal; ids can be retrieved via a specific retrieval endpoint.

Action Parameters

ips
arrayRequired

Action Response

data
object
successful
boolean
error

Endpoint retrieves up to 100 contacts by email, ignoring case/space; simpler than sgql’s search. success returns 200, 404 for no match, 400 for invalid emails. regular contact backups recommended.

Action Parameters

anonymous_id
string
emails
arrayRequired
external_id
string
phone_number_id
string

Action Response

data
object
successful
boolean
error

This endpoint provides sender reputation scores for subusers, reflecting their email performance based on recipient responses and negative actions like bounces or spam reports.

Action Parameters

usernames
string

Action Response

data
object
successful
boolean
error

The endpoint lets you create a single send draft without needing a template id; it now uses email config. a set send at doesn’t schedule it; it must be done through another endpoint or ui.

Action Parameters

categories
array
email__config__custom__unsubscribe__url
string
email__config__design__id
string
email__config__editor
string
email__config__generate__plain__content
booleanDefaults to True
email__config__html__content
string
email__config__ip__pool
string
email__config__plain__content
string
email__config__sender__id
integer
email__config__subject
string
email__config__suppression__group__id
integer
name
stringRequired
send_at
string
send__to__all
boolean
send__to__list__ids
array
send__to__segment__ids
array

Action Response

data
object
successful
boolean
error

Retrieve a paginated list of partner settings using the limit to set page size and offset to specify the starting point for additional items. multiple requests may be needed for long lists.

Action Parameters

limit
integer
offset
integer

Action Response

data
object
successful
boolean
error

this 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 currently in warmup” endpoint.

Action Parameters

ip_address
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a credits overview for a subuser.

Action Parameters

subuser_name
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint fetches the current email forwarding settings for bounce messages, including the recipient email and whether the feature is active.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint allows you to create a new subuser.

Action Parameters

email
stringRequired
include_region
boolean
ips
arrayRequired
password
stringRequired
region
string
username
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to update a segment.

Action Parameters

segment_id
integerRequired
conditions
array
list_id
integer
name
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to update a defined custom field. only your custom fields can be modified; reserved fields cannot be updated.

Action Parameters

custom_field_id
stringRequired
name
stringRequired

Action Response

data
object
successful
boolean
error

The endpoint retrieves settings for original email templates, with a guide for using and migrating from legacy to newer dynamic transactional templates.

Action Parameters

Action Response

data
object
successful
boolean
error

Retrieve your sendgrid engagement quality (seq) scores via api for a chosen date range. get a 200 response for available scores, or a 202 if scores haven’t been calculated yet. scores range from 1 to 5, higher indicating better engagement.

Action Parameters

from
stringRequired
to
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to remove a specific email address from the invalid email address list.

Action Parameters

email
stringRequired

Action Response

data
object
successful
boolean
error

Retrieve and manage your bounce/purge settings for soft/hard bounce suppression lists with twilio sendgrid, either automatically or manually via the app/api.

Action Parameters

Action Response

data
object
successful
boolean
error

Sendgrid’s delete recipients’ email data operation removes personal data of up to 5,000 unique email recipients or a 256kb payload per request. invalid emails return an error, and deletions are account-specific, not affecting subusers.

Action Parameters

email_addresses
arrayRequired

Action Response

data
object
successful
boolean
error

The mail send operation uses sendgrid’s v3 api to send emails. visit the provided link for an overview, features, limitations, quickstarts, and helper libraries.

Action Parameters

asm__group__id
integer
asm__groups__to__display
array
attachments
array
batch_id
string
categories
array
content
array
custom_args
string
from__email
string
from__name
string
ip_pool_name
string
mail__settings__bypass__bounce__management__enable
boolean
mail__settings__bypass__list__management__enable
boolean
mail__settings__bypass__spam__management__enable
boolean
mail__settings__bypass__unsubscribe__management__enable
boolean
mail__settings__footer__enable
boolean
mail__settings__footer__html
string
mail__settings__footer__text
string
mail__settings__sandbox__mode__enable
boolean
personalizations
arrayRequired
reply__to__email
string
reply__to__name
string
reply_to_list
array
send_at
integer
subject
string
template_id
string
tracking__settings__click__tracking__enable
boolean
tracking__settings__click__tracking__enable__text
boolean
tracking__settings__ganalytics__enable
boolean
tracking__settings__ganalytics__utm__campaign
string
tracking__settings__ganalytics__utm__content
string
tracking__settings__ganalytics__utm__medium
string
tracking__settings__ganalytics__utm__source
string
tracking__settings__ganalytics__utm__term
string
tracking__settings__open__tracking__enable
boolean
tracking__settings__open__tracking__substitution__tag
string
tracking__settings__subscription__tracking__enable
boolean
tracking__settings__subscription__tracking__html
string
tracking__settings__subscription__tracking__substitution__tag
string
tracking__settings__subscription__tracking__text
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete a segment by id.

Action Parameters

segment_id
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint lets you delete email addresses from your invalid list; delete all by setting delete all to true, or specify individual addresses to remove.

Action Parameters

delete_all
boolean
emails
array

Action Response

data
object
successful
boolean
error

Retrieve the state of the specified account.

Action Parameters

accountID
stringRequired

Action Response

data
object
successful
boolean
error

Use sendgrid for domain validation and branding by sharing dns records—cname for automated security, or txt/mx otherwise. include link id for link branding and domain id for domain auth.

Action Parameters

domain_id
integerRequired
email
stringRequired
link_id
integerRequired
message
stringDefaults to Please set these DNS records in our hosting solution.

Action Response

data
object
successful
boolean
error

This endpoint checks which ip pools contain a specific ip, which may be shared across multiple ip pools and affect the ip’s reputation based on collective usage for email sending.

Action Parameters

ip_address
stringRequired

Action Response

data
object
successful
boolean
error

Use this endpoint to send a message right away by setting send at to now, or schedule it by specifying a future time in iso 8601 format (yyyy-mm-ddthh:mm:ssz).

Action Parameters

id
stringRequired
send_at
stringRequired

Action Response

data
object
successful
boolean
error

this 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 return the email addresses that have been unsubscribed from the given group.

Action Parameters

group_id
stringRequired
recipient_emails
arrayRequired

Action Response

data
object
successful
boolean
error

This endpoint returns the data for a specific integration.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to deletes a specific list. optionally, you can also delete contacts associated to the list. the query parameter, delete contacts=true, will delete the list and start an asynchronous job to delete associated contacts.

Action Parameters

id
stringRequired
delete_contacts
boolean

Action Response

data
object
successful
boolean
error

The endpoint permits async csv uploads for up to 1m contacts or 5gb with specified identifiers and file type, supports gzip, field mappings, uses job id for tracking, and recommends regular backups.

Action Parameters

field_mappings
arrayRequired
file_type
stringRequired
list_ids
array

Action Response

data
object
successful
boolean
error

Retrieve a paginated list of campaigns in reverse creation order with the api endpoint. if none exist, get an empty array. adjust page size with limit, and fetch more with offset.

Action Parameters

limit
integerDefaults to 10
offset
integer

Action Response

data
object
successful
boolean
error

Retrieve subusers accessible to a specified teammate, with available scopes. admin teammates get access to all subusers.

Action Parameters

teammate_name
stringRequired
after_subuser_id
integer
limit
integerDefaults to 100
username
string

Action Response

data
object
successful
boolean
error

Check the status of contact import jobs using job id via this endpoint. it shows if the job is pending, completed, errored, or failed. for errors, download the errors url file. regular contact exports are advised for backup.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint retrieves global email suppressions and confirms if an email is suppressed. if suppressed, the email is returned in the response; if not, an empty json object is returned.

Action Parameters

email
stringRequired

Action Response

data
object
successful
boolean
error

This api endpoint enables updates to sender identities. changing from.email necessitates re-verification. partial updates are valid, but “required” fields must not be empty in patch requests.

Action Parameters

sender_id
integerRequired
address
string
address_2
string
city
string
country
string
from__email
string
from__name
string
nickname
string
reply__to__email
string
reply__to__name
string
state
string
zip
string

Action Response

data
object
successful
boolean
error

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

Action Parameters

Action Response

data
object
successful
boolean
error

The operation modifies an ip address’s settings, such as auto warm-up status, parent account assignment, and active status. the request must have one of is auto warmup, is parent assigned, or is enabled.

Action Parameters

ip
stringRequired
is_auto_warmup
boolean
is_enabled
boolean
is_parent_assigned
boolean

Action Response

data
object
successful
boolean
error

Retrieve paginated lists of globally suppressed emails using limit for page size and offset to start from a specific list position. multiple requests may be needed for large lists.

Action Parameters

start_time
integer
end_time
integer
limit
integer
offset
integer
email
string

Action Response

data
object
successful
boolean
error

Parent accounts can link validated domains to subusers through an endpoint, allowing subusers to email from those domains. the api supports multiple domain associations and listings.

Action Parameters

username
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a specific alert.

Action Parameters

alert_id
integerRequired

Action Response

data
object
successful
boolean
error

The endpoint provides a paginated list of reverse dns records, with optional ip prefix search and adjustable page size using ‘limit’ and ‘offset’ parameters.

Action Parameters

limit
integer
offset
integer
ip
string

Action Response

data
object
successful
boolean
error

This endpoint deletes a reverse dns record, returning a 204 code on success. retrieve record ids using the “retrieve all reverse dns records” endpoint.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

Retrieve a paginated list of subusers with filtering options. use username to filter, limit to set page size, and offset to navigate through the list.

Action Parameters

username
string
limit
integer
region
string
include_region
boolean
offset
integer

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve all transactional templates.

Action Parameters

generations
string
page_size
integerRequired
page_token
string

Action Response

data
object
successful
boolean
error

Retrieves all accounts under the organization.

Action Parameters

offset
string
limit
integerDefaults to 10

Action Response

data
object
successful
boolean
error

Update an api key’s name and/or scopes using json with a name field and scopes array. to change only scopes, reuse the existing name. for just a name update, use another endpoint. see the permissions list for scope options. (https://docs.sendgrid.com)

Action Parameters

api_key_id
stringRequired
name
stringRequired
scopes
array

Action Response

data
object
successful
boolean
error

Retrieve email stats by device type with a 7-day data retention limit. the advanced stats api returns 500 items per request. device types include desktop, webmail, phone, tablet, and other. more analytics available at sendgrid’s statistics overview.

Action Parameters

limit
integer
offset
integer
aggregated_by
string
start_date
stringRequired
end_date
string

Action Response

data
object
successful
boolean
error

Retrieve paginated lists of invalid emails with ‘limit’ for page size and ‘offset’ to start from a specific position for lists exceeding the limit.

Action Parameters

start_time
integer
end_time
integer
limit
integer
offset
integer
email
string

Action Response

data
object
successful
boolean
error

This endpoint checks an account’s base email sending credit balance, which affects per-email charges. more details at sendgrid’s billing documentation.

Action Parameters

Action Response

data
object
successful
boolean
error

This api endpoint is for creating new senders, with a limit of 100. verification is mandatory, either automatic upon domain authentication or via a confirmation email sent to the sender’s address.

Action Parameters

address
stringRequired
address_2
string
city
stringRequired
country
stringRequired
from__email
string
from__name
string
nickname
stringRequired
reply__to__email
string
reply__to__name
string
state
string
zip
string

Action Response

data
object
successful
boolean
error

Creating an ip pool associates specified ips with it. all ips must be successfully assigned, or creation fails with an error. a pool can have up to 100 ips.

Action Parameters

ips
array
name
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to create a new alert.

Action Parameters

email_to
stringRequired
frequency
string
percentage
integer
type
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint retrieves current forward spam settings, listing specified email addresses receiving spam reports and showing if the feature is active.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint allows you to update or change a suppression group.

Action Parameters

group_id
stringRequired
description
string
is_default
boolean
name
string

Action Response

data
object
successful
boolean
error

The endpoint /designs/pre-builts/{id}“ is used to fetch details about a particular pre-built design for duplication and modification.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

Activate forward spam to send spam reports to specified emails; supports multiple addresses and authenticating domains to receive abuse/postmaster mails. configure via twilio sendgrid app.

Action Parameters

email
string
enabled
boolean

Action Response

data
object
successful
boolean
error

Update event webhooks by id with this endpoint or without id to update the oldest one. enable or disable, set url, choose event types, give friendly names, and configure oauth. for signature verification, use a different endpoint.

Action Parameters

id
stringRequired
include
string
bounce
boolean
click
boolean
deferred
boolean
delivered
boolean
dropped
boolean
enabled
boolean
friendly_name
string
group_resubscribe
boolean
group_unsubscribe
boolean
oauth_client_id
string
oauth_client_secret
string
oauth_token_url
string
open
boolean
processed
boolean
spam_report
boolean
unsubscribe
boolean
url
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to set up reverse dns.

Action Parameters

domain
stringRequired
ip
stringRequired
subdomain
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to get the details for a specific sender by id.

Action Parameters

id
integerRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve all of your current inbound parse settings.

Action Parameters

Action Response

data
object
successful
boolean
error

Retrieve a paginated list of assigned/unassigned ips with warmup status, pools, subusers, and dns info. ip reputation is based on email traffic. use limit and offset parameters to control pagination.

Action Parameters

ip
string
exclude_whitelabels
boolean
limit
integerDefaults to 10
offset
integer
subuser
string
sort_by_direction
string

Action Response

data
object
successful
boolean
error

The endpoint updates legacy email templates, replaced by more advanced dynamic transactional templates. legacy templates are html-wrapped email content useful for marketing. guidance is available for using and migrating from legacy templates.

Action Parameters

enabled
boolean
html_content
string

Action Response

data
object
successful
boolean
error

Validate a mail batch id to get a 200 status code for a valid one, or a 400 code for an invalid. a valid id simply means it’s created, not necessarily assigned to a send.

Action Parameters

batch_id
stringRequired

Action Response

data
object
successful
boolean
error

Retrieve individual single send stats using its id. for multiple ids, use “get all single sends stats”. filter results by date or refine with group by and aggregated by parameters.

Action Parameters

id
stringRequired
aggregated_by
string
start_date
stringDefaults to 2021-01-01
end_date
stringDefaults to 2021-12-31
timezone
stringDefaults to UTC
page_size
integerDefaults to 25
page_token
string
group_by
array

Action Response

data
object
successful
boolean
error

Create unique case-insensitive custom fields with alphanumeric/underscore names starting with a letter/underscore. save the id for edits/deletes. limited to 500 fields of type date, text, or number. avoid starting with numbers to prevent campaign issues.

Action Parameters

field_type
stringRequired
name
stringRequired

Action Response

data
object
successful
boolean
error

Use this endpoint to change the status of a scheduled send by batch id. status updates fail with a 400 error if previously set with the cancel/pause endpoint.

Action Parameters

batch_id
stringRequired
status
stringRequired

Action Response

data
object
successful
boolean
error

This operation appends a batch of ips to an ip pool. this operation requires all ip assignments to succeed. if any ip assignments fail, this endpoint will return an error.

Action Parameters

poolid
stringRequired
ips
arrayRequired

Action Response

data
object
successful
boolean
error

Retrieve segments using parent list ids as a filter. an empty or unmatched query returns an empty result with a 200 code. filters combine parent list ids and the absence or presence of no parent list id with segment ids.

Action Parameters

ids
array
parent_list_ids
string
no_parent_list_id
boolean

Action Response

data
object
successful
boolean
error

Retrieve single sends stats with options for filtering by ids, pagination, and custom page sizes from 1-50. default response batch is 25.

Action Parameters

singlesend_ids
array
page_size
integerDefaults to 25
page_token
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range. if you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.

Action Parameters

sort_by_metric
stringDefaults to delivered
sort_by_direction
string
start_date
stringRequired
end_date
string
limit
integerDefaults to 5
offset
integer
aggregated_by
string

Action Response

data
object
successful
boolean
error

The api endpoint retrieves segments, using parent list ids to filter results. if no matches are found, a 200 code with an empty array is returned. filters include list ids, absence of parent ids, or specific segment ids.

Action Parameters

ids
array
parent_list_ids
string
no_parent_list_id
boolean

Action Response

data
object
successful
boolean
error

Update your email settings to enable open tracking with sendgrid, which uses an invisible image to log email opens in various reports if the recipient allows images.

Action Parameters

enabled
boolean

Action Response

data
object
successful
boolean
error

Retrieve email stats by client type with endpoint; stats stored for 7 days, 500 items per request. advanced stats offer detailed insights, segmentable by location, device, and more. visit the provided link for details.

Action Parameters

start_date
stringRequired
end_date
string
aggregated_by
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to unschedule a campaign that has already been scheduled to be sent. a successful unschedule will return a 204. if the specified campaign is in the process of being sent, the only option is to cancel (a different method).

Action Parameters

campaign_id
integerRequired

Action Response

data
object
successful
boolean
error

This endpoint creates a new sender identity via post, sends a verification email to from email, and requires email verification. to resend, use /resend/{id}“. for domain authentication, refer to the domain authentication api.

Action Parameters

address
string
address2
string
city
string
country
string
from_email
stringRequired
from_name
string
nickname
stringRequired
reply_to
stringRequired
reply_to_name
string
state
string
zip
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to duplicate a transactional template.

Action Parameters

template_id
stringRequired
name
string

Action Response

data
object
successful
boolean
error

this endpoint lets you retrieve click-tracking stats for one single send. the stats returned list the urls embedded in the specified single send and the number of clicks each one received.

Action Parameters

id
stringRequired
page_size
integerDefaults to 25
page_token
string
group_by
array
ab_variation_id
string
ab_phase_id
string

Action Response

data
object
successful
boolean
error

Retrieve a paginated list of blocked emails using this endpoint, with adjustable page sizes via the ‘limit’ parameter and starting points with ‘offset’ for multiple requests.

Action Parameters

start_time
integer
end_time
integer
limit
integer
offset
integer
email
string

Action Response

data
object
successful
boolean
error

This endpoint retrieves an allowed ip for your account using its id, with ids obtainable from the endpoint listing currently allowed ips.

Action Parameters

rule_id
stringRequired

Action Response

data
object
successful
boolean
error

Cancel a scheduled single send by making a delete request with its id to the endpoint. this action doesn’t delete the single send content, only stops the send-out.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

Creates a new account, with specified offering, under the organization.

Action Parameters

offerings
arrayRequired
profile__company__name
string
profile__company__website
string
profile__email
string
profile__first__name
string
profile__last__name
string
profile__phone
string
profile__timezone
string

Action Response

data
object
successful
boolean
error

This operation will rename an ip pool. an ip pool name cannot start with a dot/period (.) or space.

Action Parameters

poolid
stringRequired
name
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete the cancellation/pause of a scheduled send. scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.

Action Parameters

batch_id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to create a list for your recipients.

Action Parameters

name
stringRequired

Action Response

data
object
successful
boolean
error

this 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 recipient database who were in this segment.

Action Parameters

segment_id
integerRequired
delete_contacts
boolean

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete a single recipient from a list.

Action Parameters

list_id
integerRequired
recipient_id
stringRequired

Action Response

data
object
successful
boolean
error

The /designs endpoint fetches a list of user’s stored designs, restricted to 100 per request by default but adjustable with page size. pre-built designs are at /designs/pre-builts.

Action Parameters

page_size
integerDefaults to 100
page_token
string
summary
booleanDefaults to True

Action Response

data
object
successful
boolean
error

this endpoint allows you to revoke an existing api key using an api key id authentications using a revoked api key will fail after after some small propogation delay. if the api key id does not exist, a 404 status will be returned.

Action Parameters

api_key_id
stringRequired

Action Response

data
object
successful
boolean
error

this 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 api.

Action Parameters

limit
integerDefaults to 20

Action Response

data
object
successful
boolean
error

This endpoint enables clearing blocked emails either by deleting all with delete all=true or by specifying addresses in the emails array.

Action Parameters

delete_all
boolean
emails
array

Action Response

data
object
successful
boolean
error

this 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 to refresh the expiration date.

Action Parameters

Action Response

data
object
successful
boolean
error

This endpoint lets you change the name of a transactional template. for template modifications, create a new version using the provided link.

Action Parameters

template_id
stringRequired
name
string

Action Response

data
object
successful
boolean
error

this endpoint updates the name of a list.

Action Parameters

id
stringRequired
name
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to list all fields that are reserved and can’t be used for custom field names.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint allows you to update a specific campaign. this is especially useful if you only set up the campaign using post /campaigns, but didn’t set many of the parameters.

Action Parameters

campaign_id
integerRequired
categories
arrayRequired
html_content
stringRequired
plain_content
stringRequired
subject
stringRequired
title
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a list of all tracking settings on your account.

Action Parameters

Action Response

data
object
successful
boolean
error

The endpoint returns the latest 50 contacts, sorted by email, with the total count included. pagination is deprecated; regular export of contacts is advised.

Action Parameters

Action Response

data
object
successful
boolean
error

Use this endpoint with a sender identity’s id to remove it from your account. find sender identity ids through the “get all verified senders” endpoint.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

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

Action Parameters

name
stringRequired
parent_list_ids
array
query_dsl
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete one of your sender identities.

Action Parameters

sender_id
integerRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete a specific campaign.

Action Parameters

campaign_id
integerRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to edit the content of your template version.

Action Parameters

template_id
stringRequired
version_id
stringRequired
active
integer
editor
string
generate_plain_content
booleanDefaults to True
html_content
string
name
stringRequired
plain_content
stringDefaults to <generated from html_content if left empty>
subject
stringRequired
test_data
string

Action Response

data
object
successful
boolean
error

Update your bounce settings with twilio sendgrid to automatically delete contacts from suppression lists based on a set schedule in full days for both soft and hard email bounces. manage settings via their app or api.

Action Parameters

enabled
boolean
hard_bounces
integer
soft_bounces
integer

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a specific authenticated domain.

Action Parameters

domain_id
stringRequired

Action Response

data
object
successful
boolean
error

this 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 additional subusers parameter for each additional subuser.

Action Parameters

limit
integer
offset
integer
aggregated_by
string
subusers
stringRequired
start_date
stringRequired
end_date
string

Action Response

data
object
successful
boolean
error

Retrieve a list of your single sends with brief details, including their ids. for in-depth information on a specific single send, use its id at the /marketing/singlesends/{id}“ endpoint.

Action Parameters

page_size
integer
page_token
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to create a custom field. you can create up to 120 custom fields.

Action Parameters

name
string
type
string

Action Response

data
object
successful
boolean
error

Retrieve a paginated list of mail settings with their enabled status and descriptions. control page size with limit and list position with offset for multiple requests.

Action Parameters

limit
integer
offset
integer

Action Response

data
object
successful
boolean
error

Get a presigned url and headers to upload an email list for verification. ensure the ‘content-type’ matches ‘file type’ in the ‘put’ request. visit the bulk validation overview page for format and sample request.

Action Parameters

file_type
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve the total number of marketing campaigns recipients.

Action Parameters

Action Response

data
object
successful
boolean
error

This endpoint updates bounce forwarding mail settings, allowing users to set an email for bounce report forwards and configure spam mail forwarding in twilio sendgrid app.

Action Parameters

email
string
enabled
boolean

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a list of all suppressions.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a specific sender identity.

Action Parameters

sender_id
integerRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve all of your recipient lists. if you don’t have any lists, an empty array will be returned.

Action Parameters

Action Response

data
object
successful
boolean
error

Enable/disable website access for a subuser, while still preserving email send functionality.

Action Parameters

subuser_name
stringRequired
disabled
boolean

Action Response

data
object
successful
boolean
error

Retrieve a webhook’s public key using its id via this endpoint; if no id is given, the oldest key is returned. useful for signature verification and toggling signature settings. multiple ids can be found using the “get all event webhooks” endpoint.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint enables the creation of a new contacts list, which can automate email sending when new contacts are added. a link to the new list is provided in metadata.

Action Parameters

name
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to approve an access attempt. note: only teammate admins may approve another teammate’s access request.

Action Parameters

request_id
stringRequired

Action Response

data
object
successful
boolean
error

Use sendgrid app to create an initial api key; then manage others via api. json with ‘name’ required; 100 key limit. keys have unique ids, default ‘full access’ unless scopes specified. update scopes with ‘update api keys’ endpoint.

Action Parameters

name
stringRequired
scopes
array

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a single segment by id.

Action Parameters

segment_id
stringRequired
query_json
boolean

Action Response

data
object
successful
boolean
error

This endpoint updates an existing sender. changes to from.email need re-verification. if domain authenticated, new senders auto verify; else, verification email sent. partial updates can be made, but “required” fields in a patch must not be empty.

Action Parameters

id
integerRequired
address
string
address_2
string
city
string
country
string
from__email
string
from__name
string
nickname
string
reply__to__email
string
reply__to__name
string
state
string
zip
string

Action Response

data
object
successful
boolean
error

This endpoint permits the deletion of a segment using segment id, but associated contacts remain in the overall list and any other segments they’re part of.

Action Parameters

segment_id
stringRequired

Action Response

data
object
successful
boolean
error

Export single send stats in .csv format by specifying one or multiple single send ids in the ids query string, separated by commas. data is returned as plain text in .csv for flexible use or saving.

Action Parameters

ids
array
timezone
stringDefaults to UTC

Action Response

data
object
successful
boolean
error

This endpoint searches marketing campaigns recipients. variable ‘field name’ represents custom text fields (url-encoded) or date fields (by unix timestamp) and auto-converts epoch time for ‘reserved’ date fields to a full day range.

Action Parameters

field__name
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a specific inbound parse setting by hostname. you can retrieve all your inbound parse settings and their associated host names with the “retrieve all parse settings” endpoint.

Action Parameters

hostname
stringRequired

Action Response

data
object
successful
boolean
error

Get all of the details about the specified message.

Action Parameters

msg_id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to deny an attempt to access your account. note: only teammate admins may delete a teammate’s access request.

Action Parameters

request_id
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint removes an email from a suppression group, re-enabling email delivery unless specified otherwise, and should only be used when recipients opt back in.

Action Parameters

group_id
stringRequired
email
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to remove contacts from a given list. the contacts will not be deleted. only their list membership will be changed.

Action Parameters

id
stringRequired
contact_ids
stringRequired

Action Response

data
object
successful
boolean
error

this 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 integrations” endpoint.

Action Parameters

id
stringRequired
si
boolean

Action Response

data
object
successful
boolean
error

This endpoint allows admin or parent users to adjust sso teammate permissions using ‘is admin’, ‘scopes’, or ‘persona’, and to control subuser access, including restrictions.

Action Parameters

username
stringRequired
first_name
stringRequired
has_restricted_subuser_access
boolean
is_admin
boolean
last_name
stringRequired
persona
string
scopes
array
subuser_access
array

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve the cancel/paused scheduled send information for a specific batch id.

Action Parameters

batch_id
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint lets you delete an allowed ip address using its id, obtainable via the “retrieve allowed ips” endpoint.

Action Parameters

rule_id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.

Action Parameters

sort_by_direction
string
start_date
stringRequired
end_date
string
limit
integerDefaults to 5
offset
integer
aggregated_by
string
sort_by_metric
stringDefaults to delivered

Action Response

data
object
successful
boolean
error

To delete an organization’s account by id: it revokes api keys/sso, removes sendgrid resources like dedicated ips, and stops billing immediately. this action is irreversible.

Action Parameters

accountID
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve an individual sso certificate.

Action Parameters

cert_id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete a teammate. only the parent user or an admin teammate can delete another teammate.

Action Parameters

username
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint fetches detailed information on a list. using contact sample=true includes up to 50 recent contacts and the total contact count in the response.

Action Parameters

id
stringRequired
contact_sample
boolean

Action Response

data
object
successful
boolean
error

This endpoint removes a spam report for an email, lifting suppression and allowing email to be sent to that address. use with caution and recipient consent, or use bypass filters for exceptions.

Action Parameters

email
stringRequired

Action Response

data
object
successful
boolean
error

Retrieve detailed stats for a specific automation by id, with optional date and aggregation filters, or use another endpoint to get stats for multiple automations.

Action Parameters

id
stringRequired
group_by
array
step_ids
array
aggregated_by
string
start_date
stringDefaults to 2021-01-01
end_date
stringDefaults to 2021-12-31
timezone
stringDefaults to UTC
page_size
integerDefaults to 25
page_token
string

Action Response

data
object
successful
boolean
error

this 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 sso integrations” endpoint.

Action Parameters

id
stringRequired
si
boolean
completed_integration
boolean
enabled
booleanRequired
entity_id
stringRequired
name
stringRequired
signin_url
stringRequired
signout_url
stringRequired

Action Response

data
object
successful
boolean
error

The endpoint lets you duplicate twilio sendgrid pre-built designs without data. if unnamed, “duplicate:” precedes the original name. the copy gets a unique id, modifiable upon creation. use “list sendgrid pre-built designs” for ids.

Action Parameters

id
stringRequired
editor
string
name
stringDefaults to Duplicate: <original design name>

Action Response

data
object
successful
boolean
error

this endpoint returns a specific bulk email validation job. you can use this endpoint to check on the progress of a job.

Action Parameters

job_id
stringRequired

Action Response

data
object
successful
boolean
error

New segment endpoint created: supports various operators for date, text, number, and email fields. values must be strings, can specify campaign for email actions. conditions combinable via “and”/“or”.

Action Parameters

conditions
arrayRequired
list_id
integer
name
stringRequired
recipient_count
integer

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a specific campaign.

Action Parameters

campaign_id
integerRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to resend the verification request for a specific sender.

Action Parameters

id
integerRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to add an ip address to an authenticated domain.

Action Parameters

id
integerRequired
ip
stringRequired

Action Response

data
object
successful
boolean
error

Retrieves offering information about the specified account.

Action Parameters

accountID
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to create a new sender identity. you may create up to 100 unique sender identities.

Action Parameters

address
stringRequired
address_2
string
city
stringRequired
country
stringRequired
nickname
stringRequired
state
string
zip
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete a subuser. this is a permanent action. once deleted, a subuser cannot be retrieved.

Action Parameters

subuser_name
stringRequired

Action Response

data
object
successful
boolean
error

Create an ip pool by activating an ip in sendgrid: log in, go to settings > ip addresses, edit selected ip, check to allow sending, and save.

Action Parameters

name
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint provides a list of authorized ip addresses for your account, each with creation, update dates, and a unique id for potential removal.

Action Parameters

Action Response

data
object
successful
boolean
error

Update tls settings through the endpoint by setting ‘require tls’ to ‘true’ for compulsory tls 1.1+ and valid certificates with recipients. messages without tls are blocked with a specific event notice.

Action Parameters

require_tls
boolean
require_valid_cert
boolean
version
integer

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve all your idp configurations by configuration id. the integration id expected by this endpoint is the id returned in the response by the “get all sso integrations” endpoint.

Action Parameters

integration_id
stringRequired

Action Response

data
object
successful
boolean
error

This api endpoint offers detailed email stats by location, with up to 7 days of data stored and 500 items returned per request. more segmentation options are available. see the user guide for details.

Action Parameters

country
string
limit
integer
offset
integer
aggregated_by
string
start_date
stringRequired
end_date
string

Action Response

data
object
successful
boolean
error

The api lists subuser ids with a specific ip, retrieves up to 100 per request, and iterates with after key for more. use subusers api for details.

Action Parameters

ip
stringRequired
after_key
integer
limit
integer

Action Response

data
object
successful
boolean
error

Use advanced stats api to get email statistics by client type (e.g., phone, desktop), offering location and device details. data storage is limited to 7 days with up to 500 items per request. see statistics overview for further information.

Action Parameters

client_type
stringRequired
start_date
stringRequired
end_date
string
aggregated_by
string

Action Response

data
object
successful
boolean
error

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

Action Parameters

email
stringRequired

Action Response

data
object
successful
boolean
error

Create new designs via /designs by submitting html content. consider email client limitations and see the guide for best practices. convert html to editable modules in the design library, or use preferred tools/migrate existing designs.

Action Parameters

editor
string
html_content
stringRequired
name
stringDefaults to Duplicate: <original design name>
plain_content
stringDefaults to <generated from html_content if left empty>

Action Response

data
object
successful
boolean
error

this endpoint allows you to update the name of an existing api key. you must pass this endpoint a json request body with a name property, which will be used to rename the key associated with the api key id passed in the url.

Action Parameters

api_key_id
stringRequired
name
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete a pending teammate invite.

Action Parameters

token
stringRequired

Action Response

data
object
successful
boolean
error

Retrieve all marketing campaign recipients via this endpoint. use batch deletion carefully, as it may lead to empty pages. continue iterating pages until a 404 error occurs to ensure complete retrieval.

Action Parameters

page
integer
page_size
integer

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a reverse dns record. you can retrieve the ids associated with all your reverse dns records using the “retrieve all reverse dns records” endpoint.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

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

Action Parameters

segment_id
stringRequired
name
string
query_dsl
string

Action Response

data
object
successful
boolean
error

this 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 of your contact lists and all segments if required by applicable law.

Action Parameters

recipient_id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a specific version of a template.

Action Parameters

template_id
stringRequired
version_id
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint enables linking up to five authenticated domains from a parent account to a subuser, giving them permission to send emails with the parent’s domain. domains are prioritized when sending emails.

Action Parameters

domain_id
integerRequired
username
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint provides a paginated list of user categories, with adjustable page size using the limit and pagination control using offset. multiple requests are needed for large lists.

Action Parameters

limit
integerDefaults to 50
category
string
offset
integer

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve the email address currently on file for your account.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a custom field by id.

Action Parameters

custom_field_id
integerRequired

Action Response

data
object
successful
boolean
error

this endpoint will return a presigned url that can be used to download the csv that was requested from the “request a csv” endpoint.

Action Parameters

download_uuid
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint configures click tracking for emails, redirecting links through sendgrid or branded domains for engagement analysis, with a limit of 1000 links per email.

Action Parameters

enabled
boolean

Action Response

data
object
successful
boolean
error

This endpoint resends a verification email to a sender identity’s ‘from address’ by using the ‘id’ of the sender. useful if the original email is lost or needs to be resent. retrieve ids via “get all verified senders” endpoint.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint duplicates existing designs without requiring data in the request body. if you don’t specify a name, it’s labeled “duplicate:” plus the original’s name, but you can set a new name upon creation. each copy gets a unique id.

Action Parameters

id
stringRequired
editor
string
name
stringDefaults to Duplicate: <original design name>

Action Response

data
object
successful
boolean
error

Retrieve your global email stats within a specific date range, with parent accounts viewing their own or a subuser’s aggregated data via the on-behalf-of header, while subusers see only their stats.

Action Parameters

limit
integer
offset
integer
aggregated_by
string
start_date
stringRequired
end_date
string

Action Response

data
object
successful
boolean
error

Retrieve seq scores for sendgrid subusers/accounts on a specific date; expect ‘200’ with scores or ‘202’ if unavailable yet, possibly accessible later. scores range from 1-5, with higher numbers indicating better engagement.

Action Parameters

limit
integerDefaults to 1000
date
stringRequired
after_key
integer

Action Response

data
object
successful
boolean
error

this endpoint allows you to resend a sender identity verification email.

Action Parameters

sender_id
integerRequired

Action Response

data
object
successful
boolean
error

this 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 to the /marketing/singlesends endpoint.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

Authenticates and logs in a user to twilio sendgrid as a specific admin identity configured for sso by partner. any additional teammates or subusers will need to log in directly via app.sendgrid.com

Action Parameters

accountID
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint returns the total number of contacts you have stored. twilio sendgrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Action Parameters

Action Response

data
object
successful
boolean
error

This endpoint provides the billable count of recipients for marketing campaigns, based on the highest number reached in your account.

Action Parameters

Action Response

data
object
successful
boolean
error

This operation returns the ip addresses that are assigned to the specified ip pool.

Action Parameters

poolid
stringRequired
limit
integer
after_key
integer
include_region
boolean

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve your current account username.

Action Parameters

Action Response

data
object
successful
boolean
error

Retrieve a paginated list of teammates with the limit parameter to set page size and offset to specify the starting point for additional items. make multiple requests if needed.

Action Parameters

limit
integerDefaults to 500
offset
integer

Action Response

data
object
successful
boolean
error

this endpoint allows you to get all of the ip addresses that are in a specific ip pool.

Action Parameters

pool_name
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint will return the number of bounces for the classification specified in descending order for each day. you can retrieve the bounce classification totals in csv format by specifying "text/csv" in the accept header.

Action Parameters

classification
stringRequired
start_date
string
end_date
string

Action Response

data
object
successful
boolean
error

This api endpoint checks if a sendgrid account has completed domain authentication (domain verified) and single sender verification (sender verified), returning boolean values for each.

Action Parameters

Action Response

data
object
successful
boolean
error

Update email whitelist settings by toggling enabled. use list to replace entries - include all desired. exclude generic domains for can-spam compliance; whitelist bypasses bounces/unsubscribes for included contacts.

Action Parameters

enabled
boolean
list
array

Action Response

data
object
successful
boolean
error

this endpoint allows you to remove an ip address from an ip pool.

Action Parameters

pool_name
stringRequired
ip
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint returns a list of all groups from which the given email address has been unsubscribed.

Action Parameters

email
stringRequired

Action Response

data
object
successful
boolean
error

this 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 additional endpoints to modify your sso integrations.

Action Parameters

si
boolean

Action Response

data
object
successful
boolean
error

The endpoint tests event webhooks by sending a fake event to your url. it has unique retry logic and requires specific oauth properties to test oauth configurations. saved credentials can be retrieved except for oauth client secret.

Action Parameters

id
string
oauth_client_id
string
oauth_client_secret
string
oauth_token_url
string
url
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve all recipients on the list with the given id.

Action Parameters

list_id
integerRequired
page
integer
page_size
integer

Action Response

data
object
successful
boolean
error

this endpoint allows you to update a specific inbound parse setting by hostname. you can retrieve all your inbound parse settings and their associated host names with the “retrieve all parse settings” endpoint.

Action Parameters

hostname
stringRequired
send_raw
boolean
spam_check
boolean
url
string

Action Response

data
object
successful
boolean
error

This endpoint removes an authenticated domain from a subuser that was previously assigned by a parent account, used for sending emails under the parent’s domain.

Action Parameters

username
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve all of the recipients in a segment with the given id.

Action Parameters

segment_id
integerRequired
page
integer
page_size
integer

Action Response

data
object
successful
boolean
error

this endpoint allows you to resend a teammate invitation. teammate invitations will expire after 7 days. resending an invitation will reset the expiration date.

Action Parameters

token
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint fetches the default domain authentication, used for sending all mail unless overridden by a ‘from’ address match. it provides domain details if a default is set; otherwise, it gives general authentication info.

Action Parameters

domain
string

Action Response

data
object
successful
boolean
error

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

Action Parameters

page_size
integerDefaults to 100
page_token
string

Action Response

data
object
successful
boolean
error

this endpoint gets amount of ip addresses that can still be created during a given period and the price of those ips.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint is for adding a(n) ip address(es) to your account.

Action Parameters

count
integerRequired
subusers
array
warmup
boolean

Action Response

data
object
successful
boolean
error

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

Action Parameters

email
string

Action Response

data
object
successful
boolean
error

This endpoint retrieves your click tracking settings in sendgrid which tracks user engagement by redirecting and monitoring clicks on up to 1000 links per email.

Action Parameters

Action Response

data
object
successful
boolean
error

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

Action Parameters

email
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint provides a list of user-created suppression groups and can return info for multiple groups when their ids are added to the request with ?id=123456.

Action Parameters

id
integer

Action Response

data
object
successful
boolean
error

This endpoint updates an existing integration.

Action Parameters

id
stringRequired
destination
string
filters__email__events
array
label
stringDefaults to Untitled Integration
properties__destination__region
string
properties__write__key
string

Action Response

data
object
successful
boolean
error

This api endpoint deletes email suppression groups. deleted group members get globally suppressed if they unsubscribe. use with caution, only if recipients want to resubscribe. bypass filters available for exceptions.

Action Parameters

group_id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to update the name of one of your recipient lists.

Action Parameters

list_id
integerRequired
name
stringRequired

Action Response

data
object
successful
boolean
error

Use this endpoint to bulk delete contacts with ids as a list of ids or delete all contacts set to "true" for all. deletions are asynchronous. regularly export contacts as a backup.

Action Parameters

delete_all_contacts
string
ids
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to create a transactional template.

Action Parameters

generation
string
name
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint exports single send stats in .csv format, allowing specification of multiple single sends by separating their ids with commas in the ids parameter.

Action Parameters

ids
array
timezone
stringDefaults to UTC

Action Response

data
object
successful
boolean
error

this endpoint allows you to validate an authenticated domain. if it fails, it will return an error message describing why the domain could not be validated.

Action Parameters

id
integerRequired

Action Response

data
object
successful
boolean
error

This api endpoint lets users delete bounced emails: either all by setting delete all to true, or specific ones by listing them in emails. do not use both options together.

Action Parameters

delete_all
boolean
emails
array

Action Response

data
object
successful
boolean
error

This endpoint updates teammate permissions: set is admin to true for admin rights, otherwise to false with relevant scopes. only parent users or admins can modify these settings, and admin users are limited to permission changes.

Action Parameters

username
stringRequired
is_admin
booleanRequired
scopes
arrayRequired

Action Response

data
object
successful
boolean
error

The endpoint provides a list of domains with dmarc, divided by how they fail (hard or soft). hard failures prevent mail delivery using those domains as sender identities. for more on dmarc, visit sendgrid’s guide.

Action Parameters

Action Response

data
object
successful
boolean
error

This endpoint deletes integrations.

Action Parameters

ids
arrayRequired

Action Response

data
object
successful
boolean
error

Retrieve an api key’s details with its id via this endpoint. nonexistent keys yield a 404 error. key scopes can be modified later. refer to the documentation for scope details.

Action Parameters

api_key_id
stringRequired

Action Response

data
object
successful
boolean
error

Access a specific design’s details in your design library with a get request to /designs/{id}“. this endpoint is useful for obtaining info to update via patch request.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

This operation removes a batch of subusers from a specified ip address.

Action Parameters

ip
stringRequired
subusers
arrayRequired

Action Response

data
object
successful
boolean
error

Retrieve all sender identities (verified/unverified) for an account via an endpoint. customize results using limit, lastseenid, and id parameters to define the results scope.

Action Parameters

limit
integer
lastSeenID
integer
id
integer

Action Response

data
object
successful
boolean
error

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

Action Parameters

campaign_id
integerRequired
send_at
integerRequired

Action Response

data
object
successful
boolean
error

Associate authenticated domains with subusers under a parent account to enable email sending using the parent’s domain. authentication by the parent is required. multiple domains can be linked using the specified endpoint.

Action Parameters

domain_id
integerRequired
username
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete a transactional template.

Action Parameters

template_id
stringRequired

Action Response

data
object
successful
boolean
error

Retrieve a list of recent access requests using pagination with limit for page size and offset to control the start position for additional items.

Action Parameters

limit
integerDefaults to 50
offset
integer

Action Response

data
object
successful
boolean
error

Toggle signature verification for event webhooks via an endpoint. defaults to the oldest webhook if no id is provided. use boolean ‘enabled’ to set. returns a public key if enabled. retrieve webhook ids and public keys through specific endpoints.

Action Parameters

id
stringRequired
enabled
booleanRequired

Action Response

data
object
successful
boolean
error

The operation provides details for an ip address, such as its parent account status, warm-up settings, associated pools, add/modify dates, lease status, and enablement, excluding subuser info, which requires a different endpoint.

Action Parameters

ip
stringRequired
include_region
boolean

Action Response

data
object
successful
boolean
error

The endpoint enables domain authentication for users or subusers, offering two methods—‘username’ parameter for visibility and modification, or the association workflow for a fixed, non-editable domain assignment.

Action Parameters

automatic_security
boolean
custom_dkim_selector
string
custom_spf
boolean
default
boolean
domain
stringRequired
ips
array
region
string
subdomain
string
username
string

Action Response

data
object
successful
boolean
error

This endpoint duplicates single sends using an id for easy creation, allowing edits via patch. duplicates are named as “copy of” the original, with a 100-character limit for names.

Action Parameters

id
stringRequired
name
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a single recipient by id from your contact database.

Action Parameters

recipient_id
stringRequired

Action Response

data
object
successful
boolean
error

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

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

Find contacts using this endpoint with a body containing a query in sgql. searches must use lowercase, and only the first 50 matches are returned. queries over 20s will timeout. dates are in iso format, not unix timestamps.

Action Parameters

query
stringRequired

Action Response

data
object
successful
boolean
error

Invite teammates to your account through email with this endpoint, assigning initial permissions via the scopes array. invites expire after 7 days but can be resent.

Action Parameters

email
stringRequired
is_admin
boolean
scopes
arrayRequired

Action Response

data
object
successful
boolean
error

Create a new mail batch id to group email sends, allowing pause or cancel actions via the scheduled sends api.

Action Parameters

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete a custom field by id.

Action Parameters

custom_field_id
integerRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete an authenticated domain.

Action Parameters

domain_id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint returns the full details and all fields for the specified contact. the “get contacts by identifier” endpoint can be used to get the id of a contact.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

Update the state of the specified account.

Action Parameters

accountID
stringRequired
state
stringRequired

Action Response

data
object
successful
boolean
error

this 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 must include at least one when you patch.

Action Parameters

address
string
address2
string
city
string
company
string
country
string
first_name
string
last_name
string
phone
string
state
string
website
string
zip
string

Action Response

data
object
successful
boolean
error

Retrieve all your automation stats by default or specify with ‘automation ids’. results are paginated with customizable ‘page size’ (1-50, default 25) and ‘page token’ for specific pages.

Action Parameters

automation_ids
array
page_size
integerDefaults to 25
page_token
string

Action Response

data
object
successful
boolean
error

The endpoint fetches all event webhooks as objects in an array, showing each webhook’s configuration and id, used to update, delete, or manage signature verification and oauth settings.

Action Parameters

include
string

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete an ip pool.

Action Parameters

pool_name
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to update your password.

Action Parameters

new_password
stringRequired
old_password
stringRequired

Action Response

data
object
successful
boolean
error

this 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 integrations” endpoint.

Action Parameters

id
stringRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to delete a transactional template version.

Action Parameters

template_id
stringRequired
version_id
stringRequired

Action Response

data
object
successful
boolean
error

This endpoint fetches multiple contacts using their ids, allowing up to 100 ids per request for efficiency over single get requests. regular export of contacts is advised for backup.

Action Parameters

ids
arrayRequired

Action Response

data
object
successful
boolean
error

This operation appends a batch of subusers to a specified ip address. this endpoint requires all subuser assignments to succeed. if a subuser assignment fails, this endpoint will return an error.

Action Parameters

ip
stringRequired
subusers
arrayRequired

Action Response

data
object
successful
boolean
error

this endpoint allows you to retrieve a specific spam report by email address.

Action Parameters

email
stringRequired

Action Response

data
object
successful
boolean
error