SendGrid

Activates a specific version of a transactional template, making it the default version used when sending emails. Only one version can be active at a time per template. When you activate a version, any previously active version becomes inactive. The activated version's content (HTML, plain text, subject) will be used for all emails sent using this template until a different version is activated. Use this endpoint to switch between template versions for A/B testing, rollbacks, or deploying new email designs.

Adds a batch of IP addresses to a specified IP Pool in SendGrid. This operation appends multiple IPs to an existing IP Pool. All IP assignments must succeed for the operation to complete - if any single IP assignment fails, the entire operation will return an error. Requirements: - A SendGrid account with dedicated IP addresses (Pro or Premier plan) - API key with 'IP Address Management' permissions - Valid pool ID and IP addresses that exist in your SendGrid account - Each IP Pool can have a maximum of 100 IPs Note: This endpoint is part of the IP Address Management API which is currently in public beta.

Adds a dedicated IP address to an IP pool in your SendGrid account. **Prerequisites:** - You must have a SendGrid Pro or Premier plan with dedicated IP addresses - The IP address must be activated in your SendGrid account (Settings > IP Addresses > Edit > "Allow my account to send mail using this IP address") - A reverse DNS record must be set up for the IP address - The IP pool must already exist (create one first if needed) **Key Features:** - An IP address can be added to multiple pools simultaneously - Changes may take up to 60 seconds to propagate - Returns the IP's warmup status and all pools it's assigned to **Common Use Cases:** - Segregate transactional and marketing email to different IP pools - Organize IPs by brand, customer, or email type for reputation management - Set up dedicated sending infrastructure for high-volume senders

Add an IP address to an authenticated domain for custom SPF configuration. This endpoint associates a dedicated IP address with an authenticated domain, which is useful for manually specifying IPs in your custom SPF record. The authenticated domain (formerly called 'domain whitelabel') allows you to remove the 'via' or 'sent on behalf of' message from your emails. **Prerequisites:** - The domain must already be authenticated (created via Authenticate a Domain endpoint) - The IP must be a dedicated IP address belonging to your SendGrid account - Your API key must have 'whitelabel.update' and appropriate IP permissions **Returns:** The updated authenticated domain object with the IP added to the 'ips' array.

Adds a single recipient to a contact list in SendGrid's Legacy Contact Database. IMPORTANT: This uses the deprecated Legacy API (/v3/contactdb/). Many accounts no longer have access and will receive 403 errors. Use PUT /v3/marketing/contacts instead. Prerequisites: The recipient and list must already exist in your database. Parameters: - list_id: Numeric list ID from 'create_a_list' or 'retrieve_all_lists' - recipient_id: Base64-encoded lowercase email (e.g., 'test@example.com' → 'dGVzdEBleGFtcGxlLmNvbQ==') Returns: Empty dict {} on success (HTTP 201), or error details with status_code, message, and hint for troubleshooting.

Provisions a new Twilio SendGrid IP address to your account. This endpoint adds (purchases) a dedicated IP address to your SendGrid account. You can optionally: - Enable automatic warmup to gradually increase sending volume - Assign the IP to the parent account for sending email - Assign up to 100 Subusers to the IP address at creation - Specify the region (global/US or EU) for the IP address Important Requirements: - Requires a Pro or Premier SendGrid account (not available for Free/Essential plans) - Requires API key with Billing permissions (mutually exclusive from other permissions) - Additional IPs cost $30/month per IP - Parent must be assigned before the IP can be added to IP pools or used for sending Note: This is a billing operation that will incur charges on your SendGrid account.

Add dedicated IP addresses to your SendGrid account. This endpoint provisions new dedicated IP addresses for sending emails. Dedicated IPs give you full control over your sender reputation and are recommended for high-volume senders. Note: This endpoint requires the 'ips.create' API key scope and may require an appropriate SendGrid plan that supports dedicated IPs.

Adds one or more IPv4 addresses to your SendGrid account's IP access management allow list. Once enabled, only requests from these IPs can access SendGrid UI, API, and SMTP relay. Each IP is assigned a unique ID for future removal. Supports single IPs, CIDR notation (e.g., '192.168.1.0/24'), and wildcards (e.g., '192.*.*.*'). SendGrid limits the total allowed IPs to 1000. Note: IPv6 addresses are not supported. Warning: Be careful not to add IPs that exclude your own, as this could block your access.

Adds or updates contacts in SendGrid Marketing Campaigns. This is an asynchronous operation that queues contacts for processing. Returns a job_id to track the import status. Contacts are matched by identifier (email, phone_number_id, external_id, or anonymous_id) - existing contacts are updated, new ones are created. Email addresses are automatically lowercased. Max 30,000 contacts or 6MB per request.

**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.

Adds one or more email addresses to the global suppression group. Email addresses added to this group will no longer receive any emails from your SendGrid account. This is useful for managing recipients who have opted out of all communications or for ensuring certain addresses never receive emails. The action is idempotent - adding an email that is already suppressed will succeed without error. Returns the list of email addresses that were processed.

**This endpoint allows you to approve an access attempt.** **Note:** Only teammate admins may approve another teammate’s access request.

Assigns multiple subusers to a specified IP address in a single operation. All subuser assignments must succeed; if any assignment fails, the entire operation returns an error. Requires IP Address Management permissions. Note: This API is part of the IP Address Management API which is in public beta.

Associate a branded link with a subuser account for email link tracking. This allows a subuser to use the parent account's branded link (link branding/ whitelabel) for link tracking in their emails, ensuring tracked links appear to come from your domain rather than SendGrid's domain. Prerequisites: - A validated branded link must exist in the parent account - The subuser account must already exist - API key must have link branding and subuser management permissions - Requires SendGrid Pro plan or higher with subuser feature enabled Notes: - A subuser can only have one branded link associated at a time - If the subuser already has a branded link, it will be replaced - The association does not transfer ownership; parent maintains control

Associate an authenticated domain with a subuser, allowing the subuser to send emails using the parent account's domain authentication. The parent account must first authenticate and validate the domain before associating it. Prerequisites: - The domain must be authenticated by the parent account - The subuser must exist and belong to the parent account - Use 'list_all_authenticated_domains' to find available domain IDs - Use 'list_all_subusers' to find valid subuser usernames Note: The subuser will default to using the assigned domain but cannot see or modify it. If the subuser authenticates their own domain, it will overwrite the assigned domain. To associate multiple domains with a subuser, use the 'bind_authenticated_domains_to_user' action instead.

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.

Generates a one-time SSO authentication URL for logging into a customer's Twilio SendGrid account. IMPORTANT: This endpoint is only available to Twilio SendGrid reseller partners with a formal partnership agreement. Standard SendGrid accounts will receive a 403 Forbidden error. The returned redirect_url contains a one-time authorization code that: - Is valid for 60 seconds after generation - Can only be used once for security (prevents replay attacks) - Authenticates the user as an Admin Teammate with full account management permissions - Only works for the base Admin Teammate (not for additional teammates or subusers) Use Case: This is typically used by partner platforms to provide seamless SSO access for their customers into their respective SendGrid accounts. Prerequisites: - Partner-level API credentials with appropriate scopes - IP whitelisting configured for your partner account - Valid accountID from a customer account under your partner organization

Associates an additional authenticated domain with a subuser. A subuser can have up to 5 authenticated domains linked to it. This endpoint is used to add domains beyond the first one (use 'Associate an authenticated domain with a given user' for the initial association). The parent account must first authenticate and validate the domain before associating it with a subuser. Requires Subuser Management permissions.

Permanently deletes multiple Single Sends in a single operation by providing their IDs. You can delete up to 1000 Single Sends per request. Single Send IDs can be retrieved using the 'Get all single sends' action or from the SendGrid Marketing Campaigns UI. WARNING: This operation is irreversible - deleted Single Sends cannot be recovered. All associated data including statistics, configurations, and scheduled sends will be permanently removed. Returns 204 No Content on successful deletion with an empty response body.

Cancel or pause a group of scheduled email sends by their batch_id. Use 'pause' to temporarily hold sends (resumable via 'update_a_scheduled_send' or deletable via 'delete_a_cancellation_or_pause_from_a_scheduled_send') or 'cancel' to permanently discard them. Limits: max 10 paused/cancelled batches at a time; must be set at least 10 minutes before the scheduled send_at time. Returns a 400 error if the batch already has a status set or limits are exceeded.

Retrieves the verification status of a SendGrid account, checking if Domain Authentication and Single Sender Verification have been completed. Returns two boolean values: - `domain_verified`: True if Domain Authentication is complete - `sender_verified`: True if Single Sender Verification is complete This is a read-only endpoint that requires no parameters.

Generate a new mail batch ID to group multiple email sends together. The batch ID allows you to: - Group related email sends for bulk operations - Pause all scheduled sends associated with the batch ID - Cancel all scheduled sends associated with the batch ID Use the returned batch_id when sending emails via the Mail Send API by including it in your send request. Later, you can manage these grouped sends using the Scheduled Sends API endpoints (pause, cancel, or resume). This endpoint requires no input parameters and generates a unique batch ID on each call.

Create a new branded link by specifying the root domain, which must align with your FROM email, and an optional unique subdomain. Subusers can request using the `on-behalf-of` header.

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.

Creates a custom field for storing additional contact information in SendGrid. Custom fields allow you to store additional data about your contacts beyond the default fields. You can create up to 120 custom fields per account. **Valid field types:** - `text`: For string/text values - `number`: For numeric values - `date`: For date values (use MM/DD/YYYY format or epoch timestamp) **Naming constraints:** - Field names must be unique - Cannot use reserved field names: first_name, last_name, email, created_at, updated_at, last_emailed, last_clicked, last_opened - Names should contain only alphanumeric characters, underscores, and hyphens **Note:** Once a custom field is created with a specific type, the type cannot be changed. To use a different type, you must delete the field and create a new one.

Create a new contact list in SendGrid's Marketing Campaigns. This endpoint creates a list that can be used to organize and segment your contacts for targeted email campaigns. Once created, you can add recipients to the list using the 'Add a Single Recipient to a List' action. Note: List names must be unique within your account. Attempting to create a list with a duplicate name will result in a 400 error.

Creates a new customer account under your organization using the Account Provisioning API. IMPORTANT: This endpoint is only available to Twilio SendGrid reseller partners with a formal partnership agreement. Standard SendGrid accounts will receive a 403 Forbidden error. The response includes the account_id which must be stored for all subsequent Account Provisioning API operations on this customer account.

Create a new SendGrid alert. Supports two alert types: - **usage_limit**: Notifies when email usage reaches a percentage threshold (requires `percentage` param). - **stats_notification**: Sends periodic email statistics (requires `frequency` param: daily/weekly/monthly).

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.

Create a new suppression group (unsubscribe group) to allow recipients to opt out of specific types of emails. Suppression groups are specific categories of email (like newsletters, promotions, or alerts) that recipients can individually unsubscribe from. You can create up to 200 suppression groups per account. **Important Notes:** - The name and description will be visible to recipients when they manage their email preferences - Wait at least one minute after creating a group before using it in email sends - To add email addresses to the suppression group, use the "Add suppressions to a suppression group" action **Example use cases:** - Daily newsletters - Weekly digests - Marketing promotions - System alerts - Event invitations

**This endpoint allows you to create a new version of a template.**

Creates a new IP pool in your SendGrid account. IP pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for transactional and marketing emails to maintain separate reputations. Requires a SendGrid account with dedicated IP addresses (Pro or Premier plan). You can create up to 100 IP pools per account.

Creates a new IP Pool in your SendGrid account using the IP Address Management API. IP Pools allow you to group your dedicated SendGrid IP addresses together (e.g., separate pools for transactional vs marketing emails to maintain separate reputations). This endpoint creates the pool AND optionally assigns IPs in a single atomic operation. If any IP assignment fails, the entire operation fails and no pool is created. Requirements: - SendGrid Pro or Premier plan with dedicated IP addresses - IP Address Management API access (beta feature) - Maximum 100 IP pools per account - Maximum 100 IPs per pool

Create an SSO certificate for SAML 2.0 Single Sign-On authentication. This endpoint creates an SSO certificate that allows SendGrid to verify SAML requests from your Identity Provider (IdP). The certificate is used in the SAML authentication flow to establish trust between SendGrid and your IdP. Note: SSO functionality requires a SendGrid Email API Pro, Premier, or Marketing Campaigns Advanced plan.

Create a new Single Sign-On (SSO) integration for your SendGrid account. This endpoint allows you to configure SAML 2.0 SSO with your Identity Provider (IdP) such as Okta, Azure AD, or Duo. SSO enables your team members to authenticate using your organization's identity management system. **Note**: SSO is available only for SendGrid Email API Pro, Premier, and Marketing Campaigns Advanced plans. Requires appropriate SSO permissions.

Creates a Single Sign-On (SSO) Teammate in SendGrid. SSO Teammates authenticate via your Identity Provider (IdP) instead of username/password. Requires: Enterprise SendGrid account with SSO integration enabled. Permission assignment (choose ONE approach): - Set `is_admin=true` for full admin access - Set `persona` for predefined permission sets (accountant/developer/marketer/observer) - Set `scopes` array for custom granular permissions For Subuser-restricted access, set `has_restricted_subuser_access=true` and provide `subuser_access` array.

Creates a new Inbound Parse Webhook setting to receive and parse incoming emails. **Prerequisites:** 1. The hostname must be part of a domain that is authenticated via SendGrid Domain Authentication. 2. Your domain's MX records must point to `mx.sendgrid.net` (priority 10). 3. The receiving URL must be publicly accessible and return HTTP 200 on success. **Parameters:** - `hostname`: Required. A subdomain of your authenticated domain (e.g., `parse.yourdomain.com`). - `url`: Required. Public webhook URL to receive parsed emails via HTTP POST. - `send_raw`: Optional. Set to `true` to receive raw MIME content. - `spam_check`: Optional. Set to `true` to enable spam filtering (emails ≤2.5MB). **Returns:** The created parse setting with hostname, url, send_raw, and spam_check values.

Creates a new SendGrid API key with specified permissions. The first API key must be created in the SendGrid App UI; subsequent keys can be created via this endpoint. Limit: 100 keys per account. If no scopes are specified, the key receives Full Access permissions. The API key string is only returned once in the response - store it securely. Requires 'api_keys.create' scope on the authenticating API key.

Creates a new segment in SendGrid's Contact Database (Legacy Marketing Campaigns). Segments group contacts based on specified conditions for targeted email campaigns. Conditions support various operators: 'eq' (equals), 'ne' (not equals), 'contains', 'not_contains', 'gt', 'lt', 'ge', 'le' for text/date/number fields. Multiple conditions can be combined using 'and'/'or' logical operators.

Creates a new Sender identity for use in SendGrid Marketing Campaigns. You may create up to 100 unique Senders. Senders must be verified before use - if your domain is authenticated the Sender will auto-verify, otherwise a verification email will be sent to the from_email address. Required fields: nickname, from_email, from_name, address, city, and country.

**Create a new sender identity in SendGrid.** A sender identity is required to send email through SendGrid. It represents the "from" information that recipients will see. You may create up to 100 unique sender identities. **Verification**: Newly created senders must be verified before use: - If your domain is authenticated with SendGrid, the sender will auto-verify - Otherwise, a verification email will be sent to the from_email address - Only verified senders can be used to send emails **Required fields**: address, city, country, from_email, from_name, nickname, reply_to_email **Optional fields**: address_2, state, zip, reply_to_name **Use cases**: - Set up sender identities for different teams or campaigns - Configure transactional email senders - Manage multiple brand identities

Create a new transactional email template in SendGrid. Transactional templates allow you to create reusable email templates for sending transactional emails. Each account and subuser can create up to 300 templates. Templates are not shared between parent accounts and subusers. You can create either: - Legacy templates: Use substitution tags like -name- for variable replacement - Dynamic templates: Use Handlebars syntax like {{name}} for more powerful templating After creating a template, you'll need to add a version with content before it can be used to send emails.

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.

Creates a new email design in the SendGrid Design Library. The design can be used for Single Sends, Automations, and Dynamic Templates. Requires at minimum an html_content parameter with valid HTML. Returns the created design with its unique ID, thumbnail URL, and timestamps.

Create a SendGrid Marketing Integration for email event forwarding to Segment. This action creates an integration that automatically forwards specified email events (like opens, clicks, bounces, etc.) from SendGrid Marketing Campaigns to your Segment account for analytics and customer data management. **Prerequisites:** - A Segment account with a configured Source - The write key from your Segment Source - API key with Marketing permissions (Full Access or Custom Access with Marketing scope) **Limits:** - Maximum of 10 Segment integrations per user **Common Use Cases:** - Track email engagement in your customer data platform - Trigger automated workflows based on email events - Build unified customer profiles with email interaction data

Create a new contact list in SendGrid Marketing Campaigns. Lists are static collections of contacts used for organizing and targeting email campaigns. Once created, you can add contacts to the list using the Contacts API or configure automations to trigger when new contacts are added. Note: You can create a maximum of 1000 lists per account. List names must be unique within your account. Requires the Marketing Campaigns API scope (marketing.lists.create).

Creates a new contact segment using SendGrid's Marketing Campaigns Segmentation V2 API. Segments allow you to group contacts based on SQL queries against contact data and engagement events. Segment names must be unique. Contacts matching the query criteria are automatically added within 15-30 minutes. Use engagement data (opens, clicks) for behavioral targeting or contact fields (email, name, custom fields) for demographic segments.

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.

**This endpoint allows you to create a new subuser.** Subusers allow you to segment your email sending and API activity. They are typically available on Pro plans or above. Your API key must have proper 'subuser' permissions to use this endpoint. The requester's IP address must be whitelisted in your SendGrid account settings if IP access management is enabled.

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.

Removes a batch of IP addresses from a specified IP Pool in SendGrid. This operation unassigns the specified IPs from the pool but does NOT delete the IPs from your SendGrid account - they remain available for assignment to other pools. Requirements: - A SendGrid account with dedicated IP addresses (Pro or Premier plan) - API key with 'IP Address Management' permissions - Valid pool ID and IP addresses that are currently assigned to that pool Note: This endpoint is part of the IP Address Management API which is currently in public beta.

Removes multiple subusers from a specified IP address in a single batch operation. This action unassigns subusers from an IP address, preventing them from sending email through that IP. This is useful for managing IP reputation or reallocating IP resources. All removals must succeed; if any subuser removal fails, the entire operation returns an error. Requires IP Address Management permissions. Use GET_A_LIST_OF_SUBUSERS_ASSIGNED_TO_AN_IP first to verify which subusers are currently assigned to the IP address. Note: This API is part of the IP Address Management API which is in public beta.

Removes an email address from your SendGrid bounce suppression list. Use this to manually clear a bounced email, allowing future delivery attempts. Bounces occur when an email cannot be delivered due to permanent failures (e.g., invalid address, mailbox full). SendGrid automatically adds these to your bounce list. **When to use:** After verifying the email is now valid, fixing issues that caused the bounce, or when the recipient confirms they want to receive emails again. **Response codes:** 204 (success), 404 (email not in bounce list), 403 (insufficient permissions). **Caution:** Repeatedly sending to addresses that bounce negatively impacts sender reputation. Only remove bounces when you have valid reason to believe the address is now deliverable.

Permanently delete a branded link from your SendGrid account. A successful deletion returns HTTP 204 No Content. The operation is irreversible - once deleted, the branded link cannot be recovered. If you need to record the link's details, use the 'Retrieve a branded link' endpoint before deletion. Note: Links will only break if you remove the associated DNS CNAME records from your DNS host after deletion. Subusers can delete branded links using the `on-behalf-of` header with their ID.

Permanently deletes a specific marketing campaign from your SendGrid account. **Note**: This endpoint is part of the Legacy Marketing Campaigns API. The campaign cannot be recovered once deleted. Ensure you have the correct campaign ID before calling this endpoint. Returns HTTP 204 No Content on successful deletion.

Removes a specific identifier (EMAIL, PHONENUMBERID, EXTERNALID, or ANONYMOUSID) from a contact without deleting the entire contact. The operation runs asynchronously and returns a job_id to track progress. Note: This will fail if you try to remove the contact's only identifier - contacts must have at least one identifier.

Permanently deletes a custom field from your SendGrid contact database. **Important:** - This uses the Legacy Marketing Campaigns Contacts API - Only custom fields can be deleted; reserved fields cannot be deleted - Deleting a custom field will remove all data stored in that field for all contacts - This action cannot be undone **How to get the custom_field_id:** - Use 'Retrieve all custom fields' action to list all custom fields and their IDs - The ID is returned when creating a custom field via 'Create a custom field' - Custom field IDs are integers (e.g., 182757801, 182757802) Returns HTTP 204 (No Content) on successful deletion.

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.

Permanently deletes a customer account under your organization using the Account Provisioning API. **WARNING:** This action is IRREVERSIBLE and will: - Revoke all API keys and SSO access (user can no longer log in) - Remove all SendGrid resources including dedicated IPs - Cancel billing effective immediately **ACCESS REQUIREMENTS:** This endpoint is only available to Twilio SendGrid reseller partners with a formal partnership agreement. Standard SendGrid accounts will receive a 403 Forbidden error. **PARAMETERS:** - accountID: The unique account identifier (UUID format) from Create Account or List Accounts **RESPONSES:** - HTTP 200: Account successfully deleted - HTTP 403: Forbidden - requires partner/reseller API credentials - HTTP 404: Account ID not found

Delete a SendGrid alert by its ID. Permanently removes an alert from your account. Alerts allow you to receive notifications regarding email usage or statistics: - **Usage alerts**: Notify when email usage reaches a percentage threshold - **Stats notifications**: Periodic email statistics reports (daily/weekly/monthly) Returns HTTP 204 No Content on successful deletion.