Retrieve detailed information about a specific email message by its unique message ID. This endpoint returns comprehensive details including sender, recipient, subject, delivery status, template ID, and a list of events associated with the message. Requirements: - The "30 Days Additional Email Activity History" paid add-on must be purchased - API key must have "Email Activity" permission enabled - Available on Pro plans and higher Note: For Regional (EU) subusers, no data will be generated. If these requirements are not met, the API will return a 403 Forbidden error.

Retrieves the offerings (email packages and add-ons) assigned to a specific customer account. IMPORTANT: This endpoint is part of the Account Provisioning API and is only available to Twilio SendGrid reseller partners with a formal partnership agreement. Standard SendGrid accounts will receive a 403 Forbidden error. Offerings include base email packages (e.g., Free, Essentials, Pro) and add-ons (e.g., Marketing Campaigns, Dedicated IPs, Expert Services). The available offerings depend on your reseller agreement with Twilio SendGrid. Use this endpoint to check what features are currently assigned to a customer account before making updates via the Update Account Offerings endpoint.

Retrieves the full details of a single contact by their unique ID from SendGrid Marketing Campaigns. Returns all standard fields (email, name, address, etc.) and any custom fields defined for the contact. Use 'Get Contacts by Emails' or 'Search Contacts' endpoints to find a contact's ID first. Requires Marketing Campaigns permissions on your API key.

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

Retrieves a list of all Sender identities associated with your SendGrid account. Sender identities are used in Marketing Campaigns to define the 'from' information for your emails. This endpoint supports pagination through query parameters. Pagination: Use the limit parameter to control page size (default 500 if not specified). Use lastSeenID for cursor-based pagination by passing the ID of the last sender from the previous page to get the next page of results. Filtering: Use the id parameter to retrieve information about a specific sender identity. Verification: Only verified senders can be used to send emails. Check the verified.status field in the response to determine if a sender is ready for use. Note: Senders may be locked if they are associated with a campaign in Draft, Scheduled, or In Progress status.

Retrieves a list of Subuser IDs assigned to a specific IP address in your SendGrid account. Returns up to 100 subuser IDs per request. Use pagination parameters ('after_key' and 'limit') to iterate through large result sets. The response includes subuser IDs only; use the Subusers API to get detailed information about each subuser.

Retrieves all accounts under the organization.

Retrieve email statistics for SendGrid Marketing Automations (automated email workflows). Returns performance metrics including delivery rates, opens, unique_opens, clicks, unique_clicks, bounces, unsubscribes, and spam_reports for each Automation. Supports filtering by specific Automation IDs and pagination for large result sets. Requirements: - API key must have the 'marketing.read' or 'marketing.automation.read' scope - Account must have Advanced Marketing Campaigns subscription - If IP whitelisting is enabled, the requestor's IP must be whitelisted Note: This endpoint may return empty results if no Marketing Automations exist in the account.

Retrieves all available SendGrid offerings for account provisioning. This is a Partner/Reseller API endpoint that lists all the SendGrid product offerings that can be assigned to customer accounts. These include email packages, dedicated IPs, Marketing Campaigns, and other add-on features. Note: This endpoint is only available to SendGrid reseller partners with a formal partnership agreement. Access requires: - Valid partner API credentials - IP address whitelisting on SendGrid's partner API The returned offerings can be used when creating or updating customer accounts via the Account Provisioning API.

Retrieve all categories associated with your Marketing Campaigns Single Sends. This endpoint returns up to your latest 1,000 categories that have been used to organize and tag your Single Sends in SendGrid's Marketing Campaigns. Categories help you filter and track your Single Sends by topic, campaign type, or any custom grouping you define. Use cases: - List all existing categories before creating a new Single Send - Verify category names for filtering Single Sends searches - Audit category usage across your marketing campaigns Limitations: - Returns up to 1,000 most recent categories - Paid plans: 1,000 categories daily limit - Free plans: 100 categories daily limit Note: This endpoint requires Marketing Campaigns API access. The API key must have the appropriate marketing scopes (marketing.read) and the requestor's IP address may need to be whitelisted for Marketing API access. Response: Returns a list of category name strings.

Retrieves all existing contact export jobs from SendGrid Marketing Campaigns. Returns an array of export jobs with their status, type, creation/completion timestamps, and download URLs for ready exports. Use this endpoint when you need to check the status of exports but don't have the export IDs. Export files are available for download for 72 hours after creation. Possible status values: 'pending', 'ready', or 'failure'.

Retrieve all field definitions including custom and reserved fields from Marketing Campaigns. This action returns complete information about all field definitions in your SendGrid account: - Custom Fields: User-created fields (up to 500) with Text, Number, or Date types. Can be edited/deleted. - Reserved Fields: System-defined fields (email, first_name, last_name, etc.). Read-only, cannot be modified. Each field includes its unique ID (used in API calls), name, type, and metadata with management URLs. Useful for discovering field IDs needed for contact management operations. No parameters required - simply call to get all field definitions.

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.

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

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.

Retrieve email statistics for SendGrid Single Sends (one-time marketing email campaigns). Returns performance metrics including delivery rates, opens, clicks, bounces, and unsubscribes for each Single Send. Supports filtering by specific Single Send IDs and pagination for large result sets. Use this action to analyze the performance of your marketing email campaigns and track engagement metrics over time. Requires the 'marketing.read' API scope.

Retrieves all SSO (Single Sign-On) certificates associated with a specific IdP integration. The integration_id parameter should be obtained from the 'Get All SSO Integrations' endpoint. Each certificate contains the X509 public certificate used to verify SAML authentication requests. Note: This endpoint requires an account with SSO features enabled.

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.

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.

Retrieve the current state of a customer account 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 account state indicates whether the customer can send email: - 'activated': Account is active and can send email - 'deactivated': Account is deactivated and cannot send email - 'suspended': Account is temporarily suspended - 'banned': Account is permanently banned - 'indeterminate': Unknown state - contact SendGrid support if encountered

Retrieve an individual SSO certificate by its ID. SSO (Single Sign-On) certificates are X509 certificates used by SendGrid to verify that SAML requests are coming from your Identity Provider (IdP) such as Okta, Azure AD, or other SAML-compatible providers. Note: This endpoint requires SSO to be enabled on your SendGrid account (typically available on Pro or higher plans) and appropriate API key permissions.

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.

Retrieves the details of a specific Marketing Sender by its unique ID. Returns comprehensive sender information including: - Sender identification (ID, nickname) - Email configuration (from email/name, reply-to email/name) - Physical address details (address, city, state, zip, country) - Status flags (verified, locked) - Timestamps (created_at, updated_at) Note: Only verified Senders can be used to send emails. A Sender becomes locked when associated with a campaign in Draft, Scheduled, or In Progress status.

Retrieves the authenticated user's SendGrid account details including account type (e.g., 'free', 'paid') and sender reputation score (0-100). This is a read-only endpoint that requires no parameters. The response includes the account type which indicates the user's subscription level, and the reputation score which reflects the sender's email deliverability standing. Required scope: user.account.read

Retrieve the authenticated user's profile details. This endpoint returns the current user's profile information including their name, contact details, company, and address. No parameters are required - the profile is retrieved for the authenticated user based on the API key used. Required API Scope: user.profile.read

Retrieve click-tracking statistics for a specific SendGrid Marketing Automation. Returns detailed link click statistics including the URL of each link, its position in the email, and the total number of clicks received. Results can be grouped by automation step for multi-step automations. Use this endpoint to analyze which links in your automation emails are performing best and optimize your email content accordingly. Requires the 'marketing.read' API scope.

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.

Retrieves multiple SendGrid Marketing Contacts by their IDs in a single batch request. This is more efficient than making individual GET requests when you need to fetch multiple contacts at once. You can supply up to 100 contact IDs per request. Use cases: - Fetch contact details for a list of known contact IDs - Verify contact existence before performing operations - Bulk retrieve contact data for reporting or sync purposes Note: Contact IDs can be obtained from 'Search Contacts', 'Get Contacts by Emails', or 'Add or Update a Contact' actions. For backup purposes, consider using the Export Contacts feature to regularly backup your contacts.

Retrieve daily bounce statistics filtered by a specific classification type. Returns the number of bounces for the specified classification (e.g., 'Invalid Address', 'Reputation', 'Technical Failure') in descending order for each day within the given date range. Use this to analyze bounce patterns by classification over time. Classifications help categorize SMTP bounce responses into meaningful groups like: - Content: Issues with email content - Invalid Address: Hard bounces from non-existent addresses - Mailbox Unavailable: Temporary mailbox issues - Reputation: Sender reputation problems - Technical Failure: Server/connection issues - Frequency or Volume Too High: Rate limiting - Unclassified: Ambiguous responses

Retrieves the details of a specific Bulk Email Address Validation Job by its ID. Use this endpoint to check the status and progress of a bulk email validation job. You can track whether a job is pending, processing, or completed, and when results are available for download. Prerequisites: - This feature requires a Pro or Premier SendGrid account with Email Address Validation enabled. - The API key must have the 'Email Address Validation' scope. Job Statuses: - Pending: Job created but file not yet uploaded - Ready: File uploaded, waiting to process - Processing: Validation in progress - Done: Validation complete, results available - Error or Failed: Job encountered an error

Search for Marketing Campaigns contacts by their email addresses. This endpoint retrieves up to 100 contacts matching the provided emails, with case-insensitive matching that ignores whitespace. Returns 200 on success with matching contacts, 404 if no contacts match, or 400 for invalid email formats. This is simpler than using SGQL queries when you have specific email addresses to look up.

Retrieves up to 100 Marketing Campaigns contacts by searching for specific identifier values. Choose one identifier_type (email, phone_number_id, external_id, or anonymous_id) and provide a list of values to search. Returns a mapping of each searched identifier to its corresponding contact data. Found contacts include full details; not-found identifiers return empty objects. Returns 200 on success, 404 if no contacts match, 400 for invalid requests.

Retrieves a specific design's details from your Design Library by its ID. Returns the full design object including HTML content, plain text content, editor type, timestamps, and thumbnail URL. Useful for inspecting design details before making updates via the update design endpoint.

Retrieves detailed information about a specific IP address on your SendGrid account. Returns information including: - Parent assignment status (whether the parent can send mail from this IP) - Automatic warmup settings - Associated IP Pools (with IDs and names) - Creation and modification timestamps - Billing and enablement status - Lease status (whether it's a SendGrid IP or customer-owned) - Region information (if include_region=True) Note: This endpoint is part of the IP Address Management API (beta) and requires appropriate IP management permissions. For Subuser information, use a different endpoint.

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

Retrieve all suppression groups for a specific email address. This endpoint returns a list of all suppression groups in your SendGrid account, along with the suppression status of the specified email address in each group. Suppressed emails will not receive content sent under their respective suppression groups. Use cases: - Check which groups an email address is suppressed in - Verify email subscription status across all groups - Debug delivery issues for a specific recipient Note: The API requires the asm.groups.suppressions.read scope.

Retrieve SendGrid Engagement Quality (SEQ) scores for a specified date range. SEQ is a composite deliverability score (1-5) based on engagement metrics from mailbox providers. Higher scores indicate better engagement and inbox placement. Returns 200 with scores if available, or 202 if scores are still being calculated. Requirements for scores: - Open tracking must be enabled - Account must have sent at least 1,000 messages in the past 30 days Note: SEQ scores are stored for a maximum of 90 days.

Retrieves email engagement statistics (opens, clicks) segmented by geographic location (country and state/province). Currently supports US and Canada statistics only. Use this endpoint to analyze how your emails perform in different geographic regions. Note: SendGrid stores up to 7 days of email activity, and returns max 500 items by default. Requires 'geo.stats.read' API permission scope.

Retrieves details for a single suppression group (also known as an unsubscribe group). A suppression group allows recipients to unsubscribe from specific types of emails (e.g., newsletters, alerts) rather than all emails. Use this endpoint to get the group's name, description, default status, and the count of unsubscribed addresses. Note: You can create up to 200 suppression groups per SendGrid account.

Retrieve a specific Marketing Integration by its unique ID. An Integration is a connection from SendGrid Marketing Campaigns to a supported third-party application (currently only Segment is supported). This allows you to customize and automate email event forwarding to your Segment account. Returns the full Integration object including its configuration settings, email event filters, and destination properties.

Retrieves IP addresses assigned to a specific IP Pool. This endpoint is part of the IP Address Management API (beta) and requires dedicated IP addresses and appropriate API permissions. The response includes IP address details and optionally region information. Use pagination parameters (limit, after_key) for large result sets. Note: This feature requires a SendGrid Pro plan or higher with dedicated IP addresses.

Retrieve the warmup status for a specific dedicated IP address. IP warmup is the process of gradually increasing email sending volume through a new IP to build sender reputation. This endpoint returns the IP address and when it entered warmup mode. Use 'Retrieve all IPs currently in warmup' endpoint first to get a list of IPs that are currently warming up. Requires a SendGrid account with dedicated IP addresses and appropriate API permissions.

Retrieve the contact count and billable contact count for a specific marketing list. Returns both the total number of contacts currently stored in the list and the number of billable contacts (those that count toward your billing quota). This is useful for monitoring list growth, validating contact additions, and tracking billing-relevant metrics without retrieving full contact details. The list ID must be a valid UUID from the new Marketing Campaigns API. Legacy contactdb list IDs (numeric format) are not compatible with this endpoint. Required API scope: 'marketing.read' (provides access to Marketing Campaigns API). Note: If IP Access Management is enabled on your SendGrid account, ensure the requesting server's IP address is whitelisted to avoid 403 Forbidden errors.

Retrieves a filtered list of contact segments from SendGrid Marketing Campaigns V2. Segments group contacts based on SQL queries for targeted email campaigns. Use filters to retrieve specific segments by ID, segments associated with particular lists, or segments without parent list restrictions. Filter options (applied in order of precedence): 1. 'ids' - Get specific segments by UUID (ignores other filters) 2. 'parent_list_ids' - Get segments filtered by specific contact lists 3. 'no_parent_list_id' - Get segments without list filters (global segments) Returns empty list if no segments match criteria. Contact counts refresh hourly. Newly created segments may show 0 contacts initially, populating within 15-30 minutes.

Retrieves the current open tracking settings for your SendGrid account. Open tracking works by inserting an invisible image (tracking pixel) at the end of HTML emails. When a recipient opens the email and their email client loads images, SendGrid logs an 'open' event. The response indicates whether open tracking is enabled. Open event data is available in SendGrid's Statistics portal and can be received via Event Webhook. Note: Open tracking only works with HTML emails where images are enabled. Plain text emails cannot be tracked for opens. Required scope: tracking_settings.open.read

Retrieves the upload status for recipients in the Legacy Marketing Campaigns contacts database (contactdb). Use this endpoint to monitor the progress of recipient data being processed after bulk uploads via the Add Recipients endpoint. IMPORTANT - Legacy API: This is a Legacy Marketing Campaigns API endpoint. It may not be accessible for newer SendGrid accounts created after the migration to Marketing Campaigns. For newer accounts, use the Import Contacts Status endpoint (import_contacts_status) instead. No parameters required - simply call this endpoint to get the current upload status for all pending recipient upload operations. Common use case: After calling add_recipients to bulk upload contacts, use this endpoint to check if the upload has completed processing.

This endpoint gets amount of IP Addresses that can still be created during a given period and the price of those IPs.

Retrieves a sample of up to 50 contacts from your Marketing Contacts database, sorted by email address. Includes the total contact count. This endpoint is useful for quickly previewing contacts without pagination. For full contact exports, use the Export Contacts endpoint instead. Requires Marketing Campaigns read access.

Retrieves details of a specific SendGrid pre-built design template by ID. Pre-built designs are professional email templates provided by SendGrid that you can duplicate and customize. Use this to inspect a design's HTML content, subject line, and metadata before duplicating it via the 'Duplicate SendGrid Pre-built Design' endpoint. Requires Marketing Campaigns access.

Retrieves the public key for a specific Event Webhook by ID. The public key is used to verify the signature of incoming webhook requests (found in the X-Twilio-Email-Event-Webhook-Signature header). Use this endpoint after enabling signature verification to get the key needed for validation. Webhook IDs can be found using the 'Retrieve all of your event webhooks' action.

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.

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.

Search for Single Sends (marketing email campaigns) by name, status, and/or categories. Use this endpoint to find specific Single Sends when you have many campaigns. - Search by name using partial/wildcard matching - Filter by status: 'draft', 'scheduled', or 'triggered' - Filter by categories (returns campaigns matching ANY specified category) Results are paginated. Use page_token from the response to retrieve additional pages. Requires Marketing Campaigns API access (marketing.singlesends.read scope).

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.

Retrieves monthly email statistics for a specific subuser. Returns metrics such as blocks, bounces, clicks, delivered emails, opens, requests, unique clicks/opens, and unsubscribes. Note: This endpoint requires the subusers.stats.monthly.read API scope and is only available for SendGrid Pro plans and above that have subusers configured. Important: Sort operations are not available for: bounce_drops, deferred, invalid_emails, processed, spam_report_drops, spam_reports, or unsubscribe_drops metrics.

Retrieve SendGrid Engagement Quality (SEQ) scores for all subusers on a specific date. Returns engagement scores (1-5 scale, higher is better) that measure email deliverability based on recipient engagement metrics like open rates, bounce rates, and spam complaints. Requirements: Subusers must have open tracking enabled and sent 1,000+ messages in the past 30 days to receive a score. Response codes: 200 (scores available), 202 (scores being calculated - retry later). Note: This endpoint requires parent account access with subuser management permissions.

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.

Retrieve Subusers accessible to a specified Teammate, including their permission levels and scopes. Admin Teammates have access to all Subusers. For restricted Teammates, only returns Subusers they have explicit access to. Supports pagination via after_subuser_id and filtering by username.

Retrieves credit information for a specific Subuser account, including the credit type (unlimited, recurring, or nonrecurring), reset frequency, remaining credits, total allowable credits, and used credits. Note: This endpoint requires parent account credentials with subuser management permissions. Subuser accounts cannot access this endpoint.

Retrieves the default domain authentication configuration for your SendGrid account. The default domain is used to send all mail unless overridden by a matching authenticated domain for the 'From' address. Returns domain details (id, subdomain, domain, username, IPs, DNS records, validation status) if a default is set. Required scope: whitelabel.read

Retrieves the configuration and settings for a single Event Webhook by its ID. Returns the webhook URL, enabled status, subscribed event types (bounce, click, delivered, open, etc.), and OAuth/signature settings if configured. Use 'Get All Event Webhooks' endpoint first to obtain webhook IDs.

Retrieve the total number of contacts stored in your SendGrid Marketing Campaigns account. This endpoint returns: - The total contact count across all lists and segments - The billable contact count for the current billing period - A breakdown of billable contacts by subuser (if applicable) Use this to monitor your contact database size and track billing-relevant metrics. No parameters are required - simply call this endpoint to get your current counts. Requires the 'marketing.read' API scope.

Retrieve a list of scopes for which this user has access

Initiates a bulk contact import by requesting an upload URL for a CSV file. This is step 1 of a two-step process: 1. Call this action with field mappings to get an upload_uri and upload_headers 2. PUT your CSV file to the upload_uri with the required headers Supports up to 1 million contacts or 5GB per import (whichever is smaller). CSV files may be gzip-compressed. The import runs asynchronously - use the returned job_id with the 'Import Contacts Status' action to track progress. Requires at least one contact identifier in field_mappings: email, phone_number_id, external_id, or anonymous_id. Contacts are upserted - existing contacts (matched by identifier) are updated, new ones are created.

Check the status of a contact import, update, or delete job in SendGrid Marketing Campaigns. Use this endpoint to monitor asynchronous contact operations by providing the job_id returned from contact modification endpoints. Returns the job status ('pending', 'completed', 'errored', or 'failed'), processing counts (created, updated, deleted, errored), and timestamps. If errors occurred, an errors_url is provided to download detailed error information.

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.

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.

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.

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.

Retrieves a list of all Bulk Email Address Validation Jobs for the account. Bulk Email Validation allows you to upload a CSV file with up to 1 million email addresses to be validated asynchronously. Each job has a status indicating whether it is pending, processing, done, or has errors. Note: This feature requires a Pro or Premier SendGrid account with Email Address Validation enabled. The API key must have the 'Email Address Validation' scope.

List designs from the Design Library. Fetches user-created designs stored in the SendGrid Design Library (part of Marketing Campaigns). Returns up to 100 designs per request by default, with pagination support via page_token. Use summary=True for basic info or summary=False to include full HTML/plain content. Note: This endpoint requires the new Marketing Campaigns platform. Pre-built SendGrid designs are available at a different endpoint (/v3/designs/pre-builts). Required scope: design_library.read

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

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.

Retrieves all authenticated domains that have been assigned to a specific subuser. Authenticated domains allow subusers to send email using their parent account's domain authentication. Requires the 'whitelabel.read' scope and is only available on Pro plan or higher.

Manually refresh a Marketing Campaigns V2 segment to update its contact membership. This endpoint triggers an immediate refresh of the segment's contact list based on its query criteria. Normally, SendGrid refreshes segments hourly, but this allows you to force an update when needed. IMPORTANT LIMITATIONS: - Requires a Marketing Campaigns Basic or Advanced plan (returns 403 for free accounts) - Maximum 2 refreshes per segment per day (resets at midnight in user's timezone) - Minimum 1 hour between refreshes for the same segment - Maximum 10 refresh requests across all segments per day (resets at 0:00 UTC) After a successful refresh request, contacts matching the segment criteria will be updated within 15-30 minutes depending on segment complexity.

Request a presigned URL and headers to upload a file containing email addresses for bulk validation. This endpoint returns an upload URL (upload_uri), request headers (upload_headers), and a job ID (job_id) which can be used to track the validation progress. The file can contain up to 1 million email addresses or 50 MB of data. After uploading, SendGrid asynchronously validates the emails and sends results to the account's email address. Note: This feature requires a Pro or Premier level SendGrid account with Email Address Validation permissions enabled on the API key. Workflow: 1. Call this endpoint to get the presigned URL and headers 2. Use the returned upload_uri and upload_headers to PUT your CSV file 3. Use the job_id with the 'Get Bulk Email Validation Job' endpoint to track progress

Remove an IP address from an IP pool in your SendGrid account. This endpoint allows you to disassociate a dedicated IP address from an IP pool. After removal, the IP address will no longer be used when sending emails through that pool. The IP address remains in your account and can be added to another pool or used independently. Prerequisites: - The IP pool must exist in your SendGrid account - The IP address must be currently assigned to the specified pool - Your API key must have the 'ips.pools.ips.delete' scope Note: Each SendGrid account can have up to 100 IP pools.

Remove an IP address from an authenticated domain's custom SPF configuration. This endpoint dissociates a dedicated IP address from an authenticated domain, which is useful when you no longer want that IP to be included in your custom SPF record for the domain. Prerequisites: - The domain must already be authenticated (created via Authenticate a Domain endpoint) - The IP must currently be associated with the domain - Your API key must have 'whitelabel.delete' or 'whitelabel.update' permissions Important Notes: - Domain Authentication was formerly called 'Domain Whitelabel' - Returns HTTP 204 No Content on success (empty response body) - Returns HTTP 403 Forbidden if API key lacks required permissions - Returns HTTP 404 Not Found if the domain ID does not exist or IP is not associated - The IP must be a dedicated IP address currently associated with the domain

Removes a specific IP address from your SendGrid account's allow list. Use this to revoke access for an IP. Get the rule_id from the 'Retrieve a list of currently allowed IPs' endpoint. WARNING: Removing your own IP will block your account access, requiring a support ticket to resolve.

Remove contacts from a marketing list without deleting them from your account. This endpoint allows you to remove one or more contacts from a specified list. The contacts will not be deleted from your SendGrid account - only their membership in the specified list will be removed. They will remain available for use in other lists, segments, or campaigns. The removal operation is asynchronous and returns a job_id to track progress. This is useful when removing large numbers of contacts. Note: This uses the Marketing Campaigns API (/v3/marketing/lists). List IDs and contact IDs are UUIDs. For the legacy Contact Database API, use 'Delete a single recipient from a single list' instead.

Delete a marketing list from your SendGrid account. This endpoint permanently removes a specific list from your Marketing Campaigns. When delete_contacts is false (default), only the list is deleted and contacts remain in your account for use in other lists or segments. When delete_contacts is true, all contacts on the list are also permanently deleted via an asynchronous background job. A job_id is returned to track the deletion progress. Note: This uses the Marketing Campaigns API (/v3/marketing/lists). List IDs are UUIDs (e.g., 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'). For the legacy Contact Database API with integer list IDs, use 'Delete a list' instead.

Removes one or more IP addresses from your SendGrid IP Access Management allow list. This endpoint accepts an array of IP rule IDs (integers) obtained from listing allowed IPs or from the response when adding IPs to the allow list. IDs can be retrieved using the 'retrieve_a_list_of_currently_allowed_ips' action. WARNING: Removing your own IP address will block access to your account. You will need to submit a support ticket to restore access. Double-check the IDs before calling this endpoint. On success, the API returns HTTP 204 with no content body.

Permanently deletes a segment from SendGrid's Marketing Campaigns without affecting contacts. This endpoint removes only the segment definition - all contacts that were members of this segment remain in the database and in any other segments they belong to. This is useful when you want to reorganize your segmentation strategy without losing contact data. Note: This uses the Marketing Campaigns Segmentation v1 API path. For newer implementations, consider using the Segmentation v2 API endpoint at /v3/marketing/segments/2.0/{segment_id}. Important: - This action is destructive and cannot be undone - Returns HTTP 204 No Content on success with an empty response body - Returns HTTP 404 if the segment_id does not exist - Returns HTTP 403 if the API key lacks 'marketing.segments.delete' scope - Contacts in the segment are NOT deleted - only the segment definition is removed

Disassociate ALL authenticated domains from a subuser. This endpoint removes any authenticated domain associations that have been assigned to the specified subuser. After this operation, the subuser will no longer be able to send emails using the parent account's authenticated domains. Requirements: - The subuser must exist and belong to the parent account - The API key must have appropriate subuser management permissions - Use 'list_all_subusers' to find valid subuser usernames Note: This action removes ALL domain associations for the subuser. To remove a specific domain from a subuser with multiple domains, use the 'unlink_subuser_domain' action instead (DELETE /v3/whitelabel/domains/{domain_id}/subuser). On success, returns HTTP 204 No Content with an empty response body.

Renames an existing IP pool in your SendGrid account. IP pools allow you to group your dedicated SendGrid IP addresses together. For example, you might have separate pools for 'transactional' and 'marketing' emails to maintain different sending reputations. Requirements: - SendGrid account with dedicated IP addresses (Pro or Premier plan) - API key with 'ips.pools.update' scope - The IP pool must already exist (use 'Retrieve All IP Pools' to list existing pools) Note: The new name must be unique across all your IP pools and cannot start with a space or period (.).

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.

Resends the verification email for a Marketing Campaigns Sender identity. Use this when the original verification email was lost, expired, or needs to be resent. The sender must have been created via the Marketing Senders API (/v3/marketing/senders) and must not yet be verified. To get valid sender IDs, use the 'Get a list of all senders' endpoint first. Returns an empty response on success. Note: This endpoint requires Marketing Campaigns API permissions. For Verified Senders (created via /v3/verified_senders), use the 'Resend Verified Sender Request' endpoint instead.

Resends the verification email to a sender identity's 'from' email address. Use this when the original verification email was not received, expired, or needs to be resent. The sender identity must have been created via the Sender Identities API (POST /v3/senders) and must not yet be verified. Returns an empty response on success. Note: This endpoint is part of the legacy Sender Identities API. For the newer Verified Senders API, use the 'Resend Verified Sender Request' endpoint (/v3/verified_senders/resend/{id}).

Resend a pending teammate invitation to refresh its expiration date. Teammate invitations expire after 7 days. Use this endpoint to resend an invitation that hasn't been accepted yet, which will reset the expiration date to 7 days from now. The token parameter can be obtained from the 'Retrieve all pending teammates' endpoint. Requires 'teammates.write' scope or full access API key.

Resends the verification email to a Sender Identity's 'from_email' address. Use this when the original verification email was lost, expired, or needs to be resent. The sender must have been created via 'Create Verified Sender Request' and must not yet be verified. Retrieve the sender ID using 'Get All Verified Senders' endpoint. Returns empty response on success.

Retrieves details about a specific bounced email address from the SendGrid suppression list. Use this endpoint to look up bounce information for a particular email address, including: - When the bounce occurred (created timestamp) - Why the email bounced (reason with bounce codes) - The bounce status code (enhanced SMTP status) Bounces occur when an email cannot be delivered to a recipient and the receiving mail server returns a bounce response. SendGrid automatically adds bounced addresses to your suppression list to prevent future delivery attempts. Returns HTTP 200 with bounce details on success, or HTTP 404 if the email address is not found in the bounce suppression list. Requires the 'Suppressions' read scope to be enabled for your API key.

Retrieves a specific branded link by its ID. Branded links (formerly 'Link Whitelabel') allow click-tracked links, opens, and images in your emails to be served from your domain rather than sendgrid.net. Use the 'Retrieve all branded links' endpoint first to get valid IDs. You can make this request on behalf of a subuser by including their ID in the 'on-behalf-of' header.

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

Retrieve the total count of recipients in the Legacy Marketing Campaigns contact database. IMPORTANT: This is a Legacy API endpoint. The contactdb API (/v3/contactdb/*) is part of the Legacy Marketing Campaigns and is not available to newer SendGrid accounts. If you receive a 403 Forbidden error, your account likely does not have access to the legacy API. For accounts using the new Marketing Campaigns, use the 'Get Total Contact Count' action (/v3/marketing/contacts/count) instead to get the count of contacts. This endpoint requires the 'marketing.read' scope (for legacy accounts only).

Retrieves a single custom field definition by its ID from SendGrid Marketing Campaigns. Custom fields store additional information about your contacts beyond the reserved fields (email, first_name, last_name, etc.). This endpoint returns the field's ID, name, and data type. Response includes: - id: Unique string identifier for the custom field (e.g., 'e1_T') - name: The field name (e.g., 'company', 'loyalty_points') - field_type: Data type - 'Text', 'Number', or 'Date' Common errors: - 404: Custom field with the specified ID does not exist - 401: Invalid or missing API key

Retrieves your current address whitelist mail settings from SendGrid. The Address Whitelist setting allows you to specify email addresses or domains for which mail should never be suppressed. For example, if you whitelist 'example.com', all bounces, blocks, and unsubscribes logged for that domain will be ignored and mail will be sent as if under normal sending conditions. This is useful when you want to ensure delivery to specific addresses or domains regardless of previous suppression events. Note: For Regional (EU) subusers, utilizing this feature will cause customer personal information to be stored outside of the EU. Required scope: mail_settings.address_whitelist.read

Checks if an email address is in the global suppression list. Globally suppressed emails will not receive any emails from your SendGrid account. Returns the email address if found in the global suppression list, or an empty response if not suppressed. This is useful for verifying if a recipient has opted out globally before attempting to send emails. Requires the 'asm.suppressions.global.read' scope.

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

Retrieve all SendGrid alerts configured for your account. Returns a list of alert configurations including: - usage_limit alerts: Notify when email usage reaches a specified percentage threshold (0-100%). - stats_notification alerts: Send periodic email statistics at daily, weekly, or monthly intervals. Each alert includes the recipient email address, timestamps, and type-specific settings. Requires 'alerts.read' API scope.

Retrieves all IP addresses that are currently assigned to your account. This endpoint returns a list of IP addresses that have been assigned to your account for sending emails. Each IP address includes information about: - The IP address itself - The IP pools it belongs to - Whether it's currently in warmup mode - The warmup start date (if applicable) A single IP address or a range of IP addresses may be dedicated to an account to send email for multiple domains. The reputation of an IP is based on the aggregate performance of all the senders who use it. Note: This endpoint requires the 'ips.assigned.read' permission scope.

Retrieves a paginated list of all blocked email addresses from your SendGrid account. Blocks occur when a recipient's email server rejects a message for reasons related to the message itself (not the recipient address), such as: - Your sending IP being blocked by an ISP - Message content flagged by spam filters - Server rejection due to policy violations Unlike bounces, SendGrid does NOT automatically suppress future messages to blocked addresses. Use this endpoint to identify problematic deliveries. Returns HTTP 200 with a list of block records, or an empty list if no blocks exist. Supports pagination via limit/offset and filtering by time range or email pattern.

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.

This endpoint allows you to retrieve all branded links. You can submit this request as one of your subusers if you include their ID in the on-behalf-of header in the request.

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.

Retrieve all email categories used for tracking and organizing email statistics. Categories are user-defined labels that can be assigned to emails when sending. They help organize email statistics and enable filtering/grouping of metrics by category. This is useful for tracking different email campaigns, types of communications, or any custom grouping. Note: Category statistics are available for the previous 13 months only. Free plans are limited to 100 categories daily, paid plans allow 1,000 categories. Required scope: categories.read Returns a paginated list of categories. Use limit and offset parameters for pagination through large category lists.

Retrieve all custom field definitions for contacts. Returns a list of all custom fields that have been created for your contacts. Custom fields allow you to store additional information about your contacts beyond the default fields (first_name, last_name, email, etc.). Each custom field includes: - id: Unique integer identifier - name: The field name (alphanumeric and underscores only) - type: The field type (text, number, or date) You can create up to 120 custom fields per account.

Retrieves a paginated list of all email addresses that are globally suppressed from receiving any emails from your SendGrid account. Global suppressions are recipients who have unsubscribed from all your emails, not just specific groups. Each suppression includes the email address and when it was added. Use limit and offset parameters for pagination. Filter by time range with start_time and end_time, or by email pattern with the email parameter. Maximum 500 records per request. This is useful for auditing unsubscribes, compliance reporting, or re-engagement campaigns where you need to identify globally suppressed users.

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

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.

This endpoint allows you to get all of your IP pools.

Retrieves details for a specific IP address including all IP pools it belongs to, subusers that can use it, warmup status, and reverse DNS record. The same IP address can belong to multiple IP pools. Requires the 'ips.read' API scope and a dedicated IP address on your SendGrid account.

Retrieve all IP addresses currently in the warmup process. IP warmup is the process of gradually increasing sending volume through a new IP address to build a positive sending reputation. This endpoint returns all IPs that are actively being warmed up. The response includes: - ip: The IP address being warmed up - start_date: Unix timestamp when the warmup process began Returns an empty array if no IPs are currently in warmup. Note: Requires IP Management permissions on your SendGrid API key.

Retrieve all contact lists from your SendGrid account. Lists are static collections of Marketing Campaigns contacts. Returns an array of all lists with their IDs, names, and contact counts. If no lists exist, returns an empty array.

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.

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.

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

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.

Retrieves a list of all IP addresses that have recently attempted to access your SendGrid account, either through the User Interface or the API. This endpoint is part of SendGrid's IP Access Management feature, which helps monitor and secure account access. Each access attempt record includes the IP address, authentication method used, timestamps, and geographic location. Important Notes: - Requires the 'access_settings.activity.read' scope on your API key. - IP Access Management must be enabled in your SendGrid account settings (Settings > IP Access Management) before this endpoint will return data. - Returns up to the specified limit of most recent access attempts. Use Cases: - Security auditing: Monitor who is accessing your account - Identify suspicious access patterns from unexpected locations - Verify access from known IP addresses

Retrieves all recipients (contacts) belonging to a specific list in SendGrid's Legacy Marketing Campaigns. IMPORTANT: This endpoint is part of SendGrid's legacy Contacts API (/v3/contactdb/). Some SendGrid accounts may not have access to this legacy API. For newer accounts, consider using the newer Marketing Campaigns API endpoints under /v3/marketing/. The response contains an array of recipient objects with details such as email, first name, last name, and timestamps. Results are paginated - use the page and page_size parameters to iterate through large lists. Example use cases: - Export contacts from a specific marketing list - Verify which contacts are subscribed to a list - Audit list membership before sending a campaign

The endpoint provides a paginated list of Reverse DNS records, with optional IP prefix search and adjustable page size using 'limit' and 'offset' parameters.

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.

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

Retrieve a list of all suppressions across all suppression groups. Suppressions are recipient email addresses that have been added to unsubscribe groups. Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. This endpoint returns all suppressed email addresses with their associated group IDs, group names, and the timestamp when the suppression was created. Note: This endpoint requires the asm.groups.suppressions.read scope. If you need to retrieve suppressions for a specific group, use the endpoint /v3/asm/groups/{group_id}/suppressions instead.

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

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.

Retrieves all IP addresses that are assigned to a specific IP pool. IP pools allow you to group your dedicated SendGrid IP addresses together (e.g., separate pools for transactional and marketing emails). This endpoint requires the 'ips.pools.read' scope and a SendGrid account with dedicated IP addresses (typically Pro or Premier plan). Returns the pool name and a list of IP addresses with their warmup status and start dates. Returns 404 if the pool does not exist, or 403 if the API key lacks the required permissions.

Retrieves details of a specific authenticated domain by its unique ID. An authenticated domain (formerly called "Domain Whitelabel") allows you to remove the "via" or "sent on behalf of" message that recipients see when they read your emails. It replaces sendgrid.net with your personal sending domain. The response includes the domain's DNS records (CNAME/TXT/MX), validation status, whether it uses automatic or manual security, and associated user/subdomain information. Use SENDGRID_LIST_ALL_AUTHENTICATED_DOMAINS to get available domain IDs.

Retrieves the details of an existing SendGrid API key by its unique identifier. Returns the API key's name and permission scopes. Note: The actual API key string cannot be retrieved after creation for security reasons - only the name and scopes are returned. Returns 404 if the API key ID does not exist. This endpoint requires 'api_keys.read' scope and may be subject to IP Access Management restrictions.

Retrieves a specific reverse DNS (formerly IP Whitelabel) record by its ID. Reverse DNS allows mailbox providers to verify the sender of an email by performing a reverse DNS lookup. This endpoint returns details about a specific reverse DNS record including its IP address, domain, subdomain, validation status, and A record configuration. Prerequisites: - Account must have dedicated IP addresses (reverse DNS is not available for shared IPs) - API key must have the 'whitelabel.read' scope Related endpoints: - Use 'Retrieve all reverse DNS records' to get the list of record IDs - Use 'Validate a reverse DNS record' to validate the DNS configuration - Use 'Set up reverse DNS' to create a new reverse DNS record

Retrieves a specific campaign from SendGrid's Legacy Marketing Campaigns by its ID. Returns campaign details including title, subject, content, recipients, and status. Note: This is part of the Legacy Marketing Campaigns API. For new implementations, consider using the Marketing Campaigns Single Sends API instead.

Retrieve detailed information about a specific marketing list by its unique ID. This endpoint returns the list's name, contact count, and metadata. When the optional contact_sample parameter is set to true, it also includes up to 50 of the most recent contacts in the list. Lists are static collections of contacts used for organizing and targeting email campaigns in SendGrid Marketing Campaigns. Note: This action uses the new Marketing Campaigns API. The legacy Contact Database API (/v3/contactdb/lists) is deprecated and not accessible for newer SendGrid accounts.

Retrieves a single transactional template by its ID, including all associated template versions. Transactional templates are used for sending personalized emails with dynamic content replacement using Handlebars syntax. This endpoint returns the template's metadata and all versions, allowing you to identify which version is currently active. Use this endpoint to: - View template details before sending emails - Check which template versions exist - Verify which version is currently active - Get version IDs needed for the 'Retrieve a specific transactional template version' endpoint

Retrieve details for a specific SendGrid alert by its ID. Alerts notify you about email usage limits or provide periodic email statistics. Use this endpoint to get full details of a single alert including its type, recipient email, and configuration (percentage threshold or frequency). To get alert IDs, first use the 'Retrieve all alerts' endpoint.

Retrieves details of a specific IP address from your SendGrid account's IP Access Management allow list using its unique rule ID. Returns the IP address, creation timestamp, and last update timestamp. Use 'Retrieve a list of currently allowed IPs' or check the response from 'Add one or more IPs to the allow list' to obtain rule IDs. Note: Removing your own IP from the allow list can lock you out of your account.

Retrieves details for a specific email address from your SendGrid blocks list. Blocks occur when a recipient's email server rejects the message for a reason related to the message itself, not the recipient address. This could be due to your sending IP being blocked by an ISP, or the message content being flagged by a spam filter. Unlike bounces, SendGrid does not automatically suppress future messages to blocked addresses. Use this endpoint to check if a specific email is blocked and understand why. Returns HTTP 200 with block details on success, or HTTP 404 if the email address is not found in the blocks list.

Retrieves details about a specific email address from SendGrid's invalid email suppression list. Invalid emails are addresses that have bounced because of a permanent error such as an invalid mailbox or non-existent domain. This action allows you to check if a specific email exists in your suppression list and get details about why it was added. Returns the email address, the Unix timestamp when it was added, and the reason it was marked as invalid. Returns an empty list if the email is not in the invalid email suppression list. Note: Requires the 'suppression.invalid_emails.read' scope on your API key.

Retrieves a specific inbound parse webhook setting by hostname. This endpoint returns the configuration details for an inbound parse setting, which defines how SendGrid handles incoming emails for a particular hostname. Prerequisites: - The hostname must already be configured as a parse setting in your account. - Use the 'Retrieve all parse settings' endpoint to list available hostnames. Parameters: - hostname: Required. The unique domain or subdomain of the parse setting (e.g., parse.yourdomain.com). Returns: - hostname: The domain/subdomain configured for email parsing. - url: The webhook URL where parsed email data is POSTed. - send_raw: Whether raw MIME content is sent instead of parsed fields. - spam_check: Whether spam filtering is enabled. Error Cases: - 404: Parse setting not found for the specified hostname. - 403: Insufficient permissions to access parse settings.

Retrieves a specific spam report by email address from SendGrid's suppression list. Spam reports are generated when a recipient marks an email as spam. This action allows you to check if a specific email address has been reported as spam. Use cases: - Check if a recipient has marked your emails as spam - Verify spam report details before removing a suppression - Audit spam complaints for a specific email address Returns: An array of spam report objects containing the email address, Unix timestamp when reported, and the IP address that sent the email. Returns an empty array if the email has no spam reports.

Retrieves a specific version of a transactional template by its template ID and version ID. Transactional templates in SendGrid can have multiple versions, allowing for A/B testing, localization, or iterative improvements. Each version contains the email content (HTML and plain text), subject line, and metadata. Use this endpoint to: - Inspect the content and settings of a specific template version - Compare different versions of a template - Retrieve template content for preview or debugging purposes - Verify which version is currently active Required scope: templates.read Note: The template_id for dynamic templates follows the format 'd-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'. The version_id is a UUID returned when creating a version via the API or visible in the SendGrid UI.

Retrieve the branded link associated with a specific subuser. Email link branding (formerly 'Link Whitelabel') allows click-tracked links, opens, and images in emails to be served from your domain rather than sendgrid.net. This endpoint retrieves the branded link that has been associated with a subuser by the parent account. Prerequisites: - The parent account must have created and validated a branded link - The branded link must be associated with the subuser (via API or Subuser Management page) - The API key must have link branding read permissions Note: This operation requires a SendGrid Pro plan or higher with subusers enabled.

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.

Retrieve your current Bounce Purge mail settings. This setting configures the maximum age (in days) of contacts in your hard and soft bounce suppression lists before they are automatically purged. Note: This only affects suppression lists, not Marketing Campaigns contacts.

Retrieves your current click tracking settings from SendGrid. Click tracking monitors user engagement by redirecting links in your emails through SendGrid's servers, allowing you to track when recipients click on links. Returns: - enabled: Whether click tracking is active for HTML emails - enable_text: Whether click tracking is active for plain text emails Note: SendGrid can track up to 1000 links per email. Requires the 'tracking_settings.click.read' scope.

Retrieve the current Enforced TLS settings for your SendGrid account. Enforced TLS settings control whether recipients must support TLS encryption and have valid certificates to receive your emails. By default, SendGrid uses Opportunistic TLS, meaning emails are sent with TLS but fall back to unencrypted delivery if the recipient doesn't support TLS. When Enforced TLS is enabled: - If 'require_tls' is true, recipients must support TLS 1.1 or higher - If 'require_valid_cert' is true, recipients must have a valid certificate - If conditions aren't met, messages are dropped with a block event This endpoint requires the 'user.settings.enforced_tls.read' API scope. Note: This feature may not be available on all SendGrid plans.

Retrieve email statistics segmented by browser type (Chrome, Firefox, Safari, etc.). This endpoint is part of the Advanced Stats API and requires the 'browsers.stats.read' permission. Note: SendGrid only stores up to 7 days of browser-type statistics data. The response provides email click metrics (clicks, unique_clicks) grouped by date and browser type, useful for understanding how recipients interact with email links across different browsers.

Retrieve email statistics segmented by client type (Webmail, Desktop, Phone, Tablet, Other). This endpoint is part of the Advanced Stats API and requires the 'clients.stats.read' permission. Note: SendGrid only stores up to 7 days of client-type statistics data and returns a maximum of 500 items per request. The response provides email engagement metrics (opens, unique_opens) grouped by date and client type, useful for understanding how recipients interact with emails across different email clients.

Retrieve email statistics segmented by device type (Desktop, Webmail, Phone, Tablet, Other). This endpoint is part of the Advanced Stats API and requires the 'stats.read' permission. Note: SendGrid only stores up to 7 days of device-type statistics data. The response provides email engagement metrics (opens, unique_opens) grouped by date and device type, useful for understanding how recipients interact with emails across different devices.

Retrieve email statistics segmented by recipient mailbox provider (e.g., Gmail, Yahoo, Microsoft Outlook). This endpoint is part of the Advanced Stats API and requires the 'stats.read' permission. Note: SendGrid only stores up to 7 days of mailbox provider statistics data. The response provides email delivery and engagement metrics grouped by date and mailbox provider, useful for understanding deliverability performance across different email service providers. Common mailbox providers include: Gmail, Yahoo, Microsoft Outlook (includes hotmail.com, outlook.com, live.com), AOL, and Apple Mail. SendGrid offers groupings for over 200 mailbox providers.

Retrieve email statistics for specific categories within a date range. This endpoint returns detailed email metrics (delivered, opens, clicks, bounces, spam reports, etc.) for the specified categories, grouped by date. Use Cases: - Monitor email performance for specific campaign categories - Compare statistics across different email categories - Track trends over time with day/week/month aggregation Limitations: - Category statistics are available for the previous 13 months only - Free plans: limited to 100 categories daily - Paid plans: limited to 1,000 categories daily - Maximum 10 categories per request Required Scope: categories.stats.read

Retrieves email statistics for specified subusers over a date range. Returns metrics including: blocks, bounces, clicks, delivered, opens, requests, unique_clicks, unique_opens, unsubscribes, and more. Requirements: - SendGrid Pro plan or higher with subusers configured - API key with subusers.stats.read scope Usage Notes: - Statistics are available for the last 3 years - Use aggregated_by to group results by day, week, or month - Results can be paginated using limit and offset parameters

Retrieve your current Footer mail settings from SendGrid. The Footer setting allows you to insert a custom footer at the bottom of all text and HTML email message bodies sent via the SendGrid v3 API or SMTP Relay. This endpoint returns the current enabled status and the configured HTML and plain text footer content.

Retrieves the current forward bounce mail settings for your SendGrid account. Forward bounce mail settings allow you to specify an email address to which bounce reports will be forwarded. When enabled, you will receive notifications at the configured email address whenever a bounce event occurs. Note: This setting only forwards 'Bounce' events (permanent delivery failures). 'Block' events (temporary failures) are not included in the forwarding. Requires the 'mail_settings.read' scope on the API key.

Retrieves the current forward spam mail settings for your SendGrid account. Forward spam mail settings allow you to specify email address(es) to which spam reports will be forwarded. When enabled, you will receive notifications at the configured email address(es) whenever a spam report is filed against your emails. You can set multiple addresses by configuring a comma-separated list of emails in the email field. The Forward Spam setting may also be used to receive emails sent to abuse@ and postmaster@ role addresses if you have authenticated your domain. Requires the 'mail_settings.forward_spam.read' scope on the API key.

Retrieve global email statistics for your SendGrid account within a specific date range. Returns aggregated email metrics including: requests, delivered, bounces, blocks, opens, unique_opens, clicks, unique_clicks, spam_reports, and unsubscribes. Parent accounts can view their own stats or a subuser's aggregated data via the on-behalf-of header. Subusers see only their own stats. Requires 'stats.read' permission.

Retrieves the current Google Analytics tracking settings for your SendGrid account. Google Analytics tracking adds UTM parameters to links in your emails to help you track user behavior and campaign performance in Google Analytics. Returns settings including enabled status and UTM parameters (source, medium, campaign, term, content). Requires 'tracking_settings.google_analytics.read' or 'tracking_settings.read' scope.

Retrieves your current legacy email template mail settings. The legacy template setting wraps an HTML template around your email content, useful for marketing emails and HTML-formatted messages. Note: SendGrid now recommends using the more advanced Dynamic Transactional Templates instead of legacy templates. This endpoint requires the 'mail_settings.template.read' scope. Returns the 'enabled' status and 'html_content' of the configured legacy template.

Retrieves monthly email statistics for all subusers. Returns metrics such as blocks, bounces, clicks, delivered emails, opens, requests, unique clicks/opens, and unsubscribes. Note: This endpoint requires the subusers.stats.monthly.read API scope and is only available for SendGrid Pro plans and above that have subusers configured. Important: Sort operations are not available for: bounce_drops, deferred, invalid_emails, processed, spam_report_drops, spam_reports, or unsubscribe_drops metrics.

This endpoint allows you to retrieve all transactional templates.

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.

Retrieves all recipients (contacts) in a specified segment from SendGrid's Legacy Marketing Campaigns Contact Database. This endpoint returns recipient data including: - Contact info: id, email, first_name, last_name - Timestamps: created_at, updated_at (in Unix time) - Engagement data: last_clicked, last_emailed, last_opened - Any custom fields defined in your contact database Note: This uses the Legacy Contacts API (/v3/contactdb). Segments must be created via the legacy 'create_a_segment' action, not the newer Marketing Campaigns v2 API segments. Supports pagination via 'page' and 'page_size' parameters for segments with many recipients.

Retrieve all reserved fields from the Legacy Marketing Campaigns Contact Database. This endpoint returns a list of fields that are reserved by SendGrid and cannot be used as custom field names. Reserved fields include: - Text fields: first_name, last_name, email - Date fields: created_at, updated_at, last_emailed, last_clicked, last_opened - Set fields: lists, campaigns Note: This is part of the Legacy Marketing Campaigns API. For new implementations, consider using the newer Marketing Campaigns API endpoint /v3/marketing/field_definitions which returns both custom and reserved fields. Required API Scope: Legacy Marketing Campaigns access (contactdb permissions)

Retrieve the cancel/pause status of a scheduled email batch by its batch_id. Use this action to check whether a batch of scheduled emails has been paused or cancelled. The batch_id must have been created via 'create_a_batch_id' and then assigned a status via 'cancel_or_pause_a_scheduled_send'. Returns the batch_id and its status ('pause' or 'cancel'). If the batch has no pause/cancel status (i.e., emails were scheduled normally without being paused or cancelled), this endpoint may return empty data. Note: Only scheduled sends created with a batch_id can be retrieved. Emails scheduled via /mail/send with only send_at (no batch_id) cannot be queried.

Retrieve statistics for emails processed by SendGrid's Inbound Parse Webhook. This endpoint returns metrics about the number of emails received and processed by the Inbound Parse Webhook within a specified date range. The Inbound Parse Webhook allows you to receive incoming emails, parse them, and have their contents (headers, body, attachments) POSTed to a URL you specify. Access Control: - Parent accounts see aggregated stats for their account and all subusers - Subusers see only their own stats - Use the 'on-behalf-of' header to retrieve stats for a specific subuser Required Scope: user.webhooks.parse.stats.read

Retrieves detailed information about a specific Marketing Campaigns segment by its unique ID. Returns segment metadata including the SQL query defining membership criteria (query_dsl), contact count, query validation status, and timestamps. Optionally returns the parsed SQL query as a JSON AST when query_json=true. Note: This uses the Marketing Campaigns V2 Segmentation API. Contact counts are refreshed approximately every hour. Segments using engagement data may take 30 minutes to populate.

Retrieves details of a specific SendGrid teammate by username. Returns teammate information including email, name, user type, admin status, and permission scopes. Use 'Retrieve all teammates' first to get valid usernames. Requires 'teammates.read' API scope for access.

Retrieve email statistics for a specific client type (phone, tablet, webmail, or desktop). This endpoint is part of the Advanced Stats API and provides email engagement metrics (opens, unique_opens) filtered by a specific email client type. Use this to understand how recipients interact with emails on different devices/platforms. Requirements: - Requires 'stats.read' or 'clients.{client_type}.stats.read' permission - SendGrid only stores up to 7 days of client-type statistics data - Maximum 500 items per request

Retrieves the current subscription tracking settings for your SendGrid account. Subscription tracking automatically adds unsubscribe/subscribe links to the bottom of your emails, allowing recipients to manage their email preferences. This endpoint returns the current configuration including whether tracking is enabled and the customizable HTML/text content for the tracking links. No parameters required. Returns the enabled status, custom HTML content, plain text content, and optional custom landing page URL for subscription management.

Retrieves sender reputation scores (0-100) for subusers. Reputation reflects email delivery performance based on recipient engagement, bounces, spam reports, and other negative actions. Higher scores indicate better sender behavior. Requires the 'subusers.reputations.read' API permission scope.

Retrieve aggregated email statistics sums for each category over a date range. This action returns the total sum of each email statistic metric (delivered, opens, clicks, bounces, etc.) for every category used in your SendGrid account. Categories help you organize and track different types of emails you send. Key Features: - Get stats across all categories or paginate through them - Sort by any metric (delivered, opens, clicks, etc.) - Aggregate by day, week, or month for trend analysis - Results are returned sorted by your chosen metric Limitations: - Statistics are only available for the previous 13 months - Paid accounts: 1,000 categories daily limit - Free accounts: 100 categories daily limit Required Scope: categories.stats.sums.read Example Use Cases: - Find your highest-performing email categories by delivery rate - Identify categories with high bounce or spam report rates - Track engagement trends across different email types

Retrieves the count of billable recipients for SendGrid Legacy Marketing Campaigns. This endpoint returns the number of Marketing Campaigns recipients you will be billed for. You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. Important Notes: - This is a Legacy Marketing Campaigns API endpoint (/v3/contactdb/*). - A 403 Forbidden error indicates your account does not have access to the Legacy Marketing Campaigns API. Newer SendGrid accounts may not have access to these endpoints. - For the current Marketing Campaigns API, use the get_total_contact_count action (/v3/marketing/contacts/count) instead. Required Scopes: Marketing Campaigns read permissions (contactdb.read). Response: - recipient_count (integer): The number of billable recipients.

Retrieves the default branded link for message sending. Branded links (formerly 'Link Whitelabel') allow click-tracked links, opens, and images in your emails to be served from your domain rather than sendgrid.net. The priority for default branded link is: 1. User-set default branded link 2. Legacy branded link 3. SendGrid's default link (100.ct.sendgrid.net) You can make this request on behalf of a subuser by including their ID in the 'on-behalf-of' header.

Retrieves all marketing campaign lists that a specific recipient belongs to. NOTE: This is a Legacy Marketing Campaigns API endpoint (/v3/contactdb/). For new implementations, consider using the new Marketing Campaigns API which uses different contact and list management endpoints. Each recipient can be on multiple lists. Use this endpoint to find all lists that a recipient has been added to. The recipient must exist in your Legacy Marketing Campaigns contact database.

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

Retrieve authenticated domains (up to five) assigned to a specific subuser. Parent accounts use this to view domains their subusers can use for sending emails. Requires 'Subuser Management' and 'Domain Authentication' API permissions. Must provide a valid subuser username - use 'list_all_subusers' to find usernames. Returns domain objects with id, subdomain, domain, validation status, and DNS records.

Retrieves the email address currently on file for your SendGrid account. This endpoint returns the primary email address associated with your account, which is used for account-related communications from SendGrid. Required scope: user.email.read Returns: An object containing the email field with your account email address.

Retrieves the current email credit balance for your SendGrid account. This endpoint returns information about your account's email sending credits, including the total number of credits, remaining credits, used credits, and overage (if any). Credits determine how many emails you can send before incurring per-email overage charges. Response includes: - remain: Remaining credits available - total: Total credits assigned to your account - overage: Number of overdrawn credits (if applicable) - used: Number of credits consumed - last_reset: Date of last credit reset - next_reset: Date of next credit reset - reset_frequency: How often credits reset (e.g., 'monthly') Note: This endpoint requires the 'user.credits.read' scope.

Retrieve your current SendGrid account username and user ID. This endpoint returns your account username and user ID. Required Scope: user.username.read Returns: - username (str): Your SendGrid account username - user_id (int): Your SendGrid account user ID

Retrieve a paginated list of all partner settings that can be enabled for your SendGrid account. Partner settings allow integration with third-party services. Note: As of August 30, 2022, Twilio SendGrid removed the New Relic integration. Use Deliverability Insights instead. Requires 'partner_settings.read' API scope.

Schedules a Legacy Marketing Campaigns email for delivery at a specific time. The campaign must have subject, sender_id, content (HTML and plain text with [unsubscribe] tag), and at least one list or segment ID configured before scheduling. For better delivery rates, schedule at off-peak times (e.g., 10:53) rather than on the hour. Note: You cannot schedule a campaign that has already been sent or scheduled - use the update endpoint to modify a scheduled campaign.

Schedule a Single Send for immediate or future delivery. Use send_at: 'now' to send immediately, or provide an ISO 8601 date-time for scheduled delivery. The Single Send must be fully configured with sender_id, recipients (list_ids, segment_ids, or send_to_all), and an unsubscribe option (suppression_group_id or custom_unsubscribe_url) before scheduling.

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.

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.

Search for recipients in the Legacy Marketing Campaigns contact database by field value. This endpoint allows searching recipients by any field (email, first_name, last_name, or custom fields). It performs an exact match search equivalent to using 'eq' operator. For date fields (created_at, updated_at), searches are performed at day granularity. A Unix timestamp like 1422835600 searches the entire day containing that timestamp. IMPORTANT: This is a Legacy Marketing Campaigns API endpoint (/v3/contactdb/). It requires Legacy Marketing Campaigns access. Newer accounts may not have access and should use the new Marketing Campaigns Search Contacts API instead. Returns a list of matching recipients with their details including email, names, custom fields, and metadata like created_at/updated_at timestamps.

Immediately sends an existing marketing campaign to its configured recipients. IMPORTANT: This is a Legacy Marketing Campaigns API endpoint. You may only send a campaign when it is in 'draft' status. The campaign must have: - A subject line - A sender_id (verified sender identity) - At least one list_id or segment_id for recipients Once sent, the campaign cannot be unsent. This action triggers immediate delivery to all recipients in the configured lists/segments. Note: This endpoint requires the 'marketing_campaigns.create' or 'marketing_campaigns.update' API scope. The Legacy Marketing Campaigns feature may require specific account access.

Send a test marketing email before launching a campaign. This endpoint allows you to test your marketing email by sending it to up to 10 email addresses. The test email uses a Dynamic Transactional Template that you specify. Requirements: - A valid template_id for a Dynamic Transactional Template (Legacy templates not supported) - Either a from_address (verified email) OR a sender_id (verified sender identity) - At least one recipient email in the emails array (max 10) Use Case: Test your email template content, formatting, and delivery before sending to your full contact list.

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.

Set up reverse DNS (rDNS) for a dedicated IP address. Reverse DNS allows mailbox providers to verify the sender by performing a reverse DNS lookup when receiving emails. This improves email deliverability by establishing trust between your sending IP and your domain. Prerequisites: - Your SendGrid account must have a dedicated IP address (not a shared IP) - You must own and control the domain being configured - After setup, you'll need to add the provided A record to your DNS provider How it works: 1. Call this endpoint with your domain and dedicated IP 2. SendGrid returns an A record configuration 3. Add the A record to your DNS provider 4. Use the validate endpoint to verify the configuration Note: Reverse DNS is only available for dedicated IP addresses which require a Pro plan or higher, or can be purchased as an add-on ($30/month per IP).

Put a dedicated IP address into warmup mode. IP warmup gradually increases the sending volume from an IP address to build a positive sending reputation. SendGrid automatically limits the hourly email volume during warmup to prevent deliverability issues. The IP must be a dedicated IP assigned to your account and must have at least one other warm IP to handle overflow traffic. Warmup typically completes in 30-60 days depending on email volume.

Stop warming up a dedicated IP address and remove automatic sending limits. When an IP is in warmup mode, SendGrid automatically limits the hourly email volume to gradually build sender reputation. This action removes those limits and takes the IP out of warmup mode. Important Notes: - Returns 204 No Content on success (empty response body) - The IP must be a dedicated IP assigned to your SendGrid account - The IP must currently be in warmup mode - Requires IP Management permissions on the API key - Only stop warmup when the IP has completed its warmup schedule (typically 30+ days) Related Actions: - Use 'Retrieve all IPs currently in warmup' to see which IPs are warming up - Use 'Start warming up an IP address' to begin warmup for a new IP - Use 'Retrieve the warmup status for a specific IP address' to check warmup progress

Retrieves summed email statistics for all subusers over a date range. Returns aggregated metrics including: blocks, bounces, clicks, delivered, opens, requests, unique_clicks, unique_opens, unsubscribes, and more for each subuser. Requirements: - SendGrid Pro plan or higher with subusers configured - API key with subusers.stats.sums.read scope Usage Notes: - Statistics are available for the last 3 years - Use aggregated_by to group results by day, week, or month - Results can be sorted by metric using sort_by_metric and sort_by_direction - Results can be paginated using limit and offset parameters

Sends a test event notification to a specified URL to verify your webhook endpoint is properly configured to receive SendGrid events. The test sends a POST request with a JSON array containing sample event data. Optionally test OAuth authentication by providing OAuth credentials or referencing an existing webhook's saved credentials via its ID. Returns HTTP 204 on success.

Enable or disable signature verification for a single Event Webhook by its ID. When signature verification is enabled, SendGrid generates an ECDSA key pair and signs all webhook payloads using the private key. The signature is included in the X-Twilio-Email-Event-Webhook-Signature header of each webhook request. You can verify authenticity of incoming webhook requests using the public key returned by this endpoint. This helps ensure webhook requests genuinely originate from SendGrid and haven't been tampered with. Requires a valid webhook ID from the 'Get All Event Webhooks' endpoint.

Disassociate an authenticated domain from a subuser. This removes the link between a domain authentication and a specific subuser, preventing the subuser from sending emails using that domain. Prerequisites: - The domain must be authenticated and associated with the subuser - You must have the subuser's username - You must have the domain_id of the authenticated domain Use 'list_the_authenticated_domain_associated_with_the_given_user' to find domains linked to a specific subuser before calling this endpoint. Note: Each subuser can have up to 5 authenticated domains associated with them. This endpoint is for users with multiple domain associations.

Unschedule a campaign that has already been scheduled to be sent. Note: This endpoint is part of the Legacy Marketing Campaigns API. SendGrid recommends migrating to the new Marketing Campaigns for new implementations. A successful unschedule operation returns HTTP 204 No Content. The campaign must be in a 'Scheduled' state to be unscheduled. If the campaign is already being sent, you must use the cancel campaign endpoint instead. Common error scenarios: - 404: Campaign not found or not scheduled - 403: Insufficient permissions or IP not whitelisted - 400: Campaign cannot be unscheduled (e.g., already sent or in progress)

Update a specific branded link's default status. Link branding (formerly 'Link Whitelabel') allows all click-tracked links in your emails to be served from your domain rather than sendgrid.net. Use this endpoint to change which branded link is the default for your account. You can submit this request as one of your subusers by including their ID in the on-behalf-of header.

Updates an existing marketing campaign. You can modify the campaign's title, subject line, HTML content, plain text content, and categories. Note: You can only update campaigns that are in draft status - campaigns that have been scheduled or sent cannot be modified. This is part of the Legacy Marketing Campaigns API.

Updates the offerings (email packages and add-ons) assigned to a customer account. IMPORTANT: This endpoint is part of the Account Provisioning API and is only available to Twilio SendGrid reseller partners with a formal partnership agreement. Standard SendGrid accounts will receive a 403 Forbidden error. This is a PUT operation that completely replaces all offerings on the account. You must include ALL offerings you want the account to retain in each request. Offerings not included will be removed from the account. Available offerings include: - Base email packages (e.g., Free, Essentials, Pro) - Each account requires exactly one - Marketing Campaigns add-ons - Dedicated IP addresses - Expert Services Use the List Offerings endpoint to see all available offerings, and the Get Account Offerings endpoint to see what's currently assigned before making updates. When removing IP addresses, the API removes the most recently added IP. Contact SendGrid support if you need to remove a specific IP address.

Updates the address whitelist mail settings for your SendGrid account. The Address Whitelist setting allows you to specify email addresses or domains for which mail should never be suppressed due to bounces, blocks, or unsubscribes. For example, if you whitelist 'example.com', all bounces, blocks, and unsubscribes logged for that domain will be ignored and mail will be sent as normal. Key behaviors: - Use 'enabled' to turn the whitelist on/off - The 'list' parameter REPLACES the entire whitelist (not appends) - Include all addresses/domains you want whitelisted in a single request - For CAN-SPAM compliance, avoid whitelisting generic domains Note: For Regional (EU) subusers, utilizing this feature will cause customer personal information to be stored outside of the EU. Required scope: mail_settings.address_whitelist.update

Updates the name of an existing recipient list in the Marketing Campaigns. This action allows you to rename a contact list. Lists are static collections of contacts in SendGrid Marketing Campaigns that can be used for email campaigns and segmentation. Prerequisites: - The list_id must be obtained from an existing list - Use 'Retrieve All Lists' action to get available list IDs - Requires SendGrid Marketing Campaigns API access Note: This uses the Marketing Campaigns Contact Database API (/v3/contactdb/lists/). This is a legacy endpoint that SendGrid maintains for backwards compatibility. For new implementations using UUID-based list IDs, use the 'Update List' action instead.

Update the state of a customer account using the Account Provisioning API. IMPORTANT: This endpoint is ONLY available to Twilio SendGrid reseller partners with a formal partnership agreement and proper IP whitelisting. Standard SendGrid accounts will receive a 403 Forbidden error. Use this endpoint to: - Activate a customer account to enable email sending (state='activated') - Deactivate a customer account to disable email sending (state='deactivated') Account states: - 'activated': Account is active and can send email - 'deactivated': Account is deactivated and cannot send email Prerequisites: - Valid SendGrid Partner/Reseller credentials - IP address must be whitelisted with SendGrid - Customer account must exist (created via SENDGRID_CREATE_AN_ACCOUNT)

Update an existing SendGrid alert's settings. Supports updating two types of alerts: - usage_limit: Update the percentage threshold (0-100) or email recipient. - stats_notification: Update the frequency (daily/weekly/monthly) or email recipient. Note: You can only update fields relevant to the alert's type. Use 'Retrieve all alerts' to get the alert ID and current settings before updating.

Updates the settings for an authenticated domain in SendGrid. Use this endpoint to modify the custom_spf and default settings for an existing authenticated domain. To get the domain_id, first use the 'List all authenticated domains' endpoint. Parameters: - domain_id (required): The numeric ID of the authenticated domain to update. - custom_spf (optional): Set to true for manual SPF configuration, false for automatic. - default (optional): Set to true to make this the default sending domain. Note: If you enable custom_spf, automatic security will be disabled and you'll need to configure your own SPF, DKIM, and MX records manually.

Updates the name of an existing IP Pool in your SendGrid account. IP Pools allow you to group your dedicated SendGrid IP addresses together for better management of email sending reputation. For example, you might have separate pools named 'transactional' and 'marketing' to maintain separate reputations for different email types. Requirements: - SendGrid account with dedicated IP addresses (Pro or Premier plan) - API key with 'IP Address Management' scope or 'ips.pools.update' permission - The IP Pool must already exist (use 'Get All IP Pools' to find pool IDs) Note: This API endpoint is part of the IP Address Management API (public beta). The pool name must be unique and cannot start with a period (.) or space.

Update an existing Single Sign-On (SSO) integration for your SendGrid account. This endpoint allows you to modify SAML 2.0 SSO configuration settings for an integration with your Identity Provider (IdP) such as Okta, Azure AD, or Duo. You can update the integration name, enable/disable status, and IdP URLs. Note: SSO is available only for SendGrid Email API Pro, Premier, and Marketing Campaigns Advanced plans. The integration ID can be retrieved from the 'Get All SSO Integrations' endpoint.

Updates an existing Inbound Parse Webhook setting by hostname. Prerequisites: 1. The hostname must already exist as a configured parse setting. 2. Use 'Retrieve all parse settings' to list available hostnames. Parameters: - hostname: Required. The hostname of the parse setting to update. - url: Optional. New webhook URL to receive parsed emails via HTTP POST. - send_raw: Optional. Set to true to receive raw MIME content instead of parsed fields. - spam_check: Optional. Set to true to enable spam filtering (emails ≤2.5MB). - on_behalf_of: Optional. Subuser username to make the call on their behalf. Returns: The updated parse setting with hostname, url, send_raw, and spam_check values. Note: Only include the fields you want to update. Omitted fields remain unchanged.

Updates the name of an existing SendGrid API key. This endpoint only modifies the key's display name and does not change its permissions/scopes. Use this to rename API keys for better organization. To update both name and scopes, use the 'Update API Key Name and Scopes' endpoint instead.

Updates both the name and permission scopes of an existing SendGrid API key. IMPORTANT: The scopes array completely replaces the key's existing permissions. To preserve existing permissions while adding new ones, first retrieve the key's current scopes using 'Retrieve an existing API Key', then include all desired scopes in this request. To update only the name without changing scopes, use 'Update API key name' (PATCH) endpoint instead. Requires 'api_keys.update' scope on the authenticating API key.

Updates the scheduled send time for a Legacy Marketing Campaigns email. The campaign must already be scheduled before using this endpoint. Use the Schedule a Campaign endpoint first to initially schedule a draft campaign. This endpoint changes only the send_at timestamp. Note: Legacy Marketing Campaigns require the 'marketing_campaigns.update' scope on your API key.

Update the status of a scheduled send batch that already has a pause or cancel status. Use to change between 'pause' and 'cancel' on batches that have an existing status (set via 'cancel_or_pause_a_scheduled_send'). To set initial status, use that action instead. To remove status entirely (resume), use 'delete_a_cancellation_or_pause_from_a_scheduled_send'. Notes: - Paused sends expire 72 hours after their send_at time - Cancelled sends are discarded at send_at time - Max 10 paused/cancelled batches allowed at once

Updates an existing segment in SendGrid's Marketing Campaigns using the Segmentation V2 API. You can update the segment's name and/or the SQL query that defines membership criteria. At least one of 'name' or 'query_dsl' should be provided for the update. Important notes: - Segment names must be unique within your account - The query_dsl must select 'contact_id' and 'updated_at' from the 'contact_data' table - Segment counts are refreshed approximately once per hour, not immediately - For engagement-based segments (opens, clicks), population takes about 30 minutes Use the create_segment or get_list_of_segments endpoints to obtain valid segment IDs.

Updates an existing Sender identity for use in SendGrid Marketing Campaigns. Important Notes: - Partial updates are supported - only include fields you want to change. - Changes to from_email require re-verification of the Sender. - If your domain is authenticated, new from_email addresses will auto-verify. - The required fields (nickname, from_email, address, city, country) must not be empty if included in the update. Use Cases: - Update physical address information for CAN-SPAM compliance. - Change the reply-to email address for a campaign. - Update the display name for branding purposes. - Modify the nickname for better organization in the dashboard.

Updates an existing sender identity in SendGrid. This action allows partial updates - only the fields you provide will be modified, while all other fields remain unchanged. Important Notes: - Changing the from_email address requires re-verification of the sender identity. - Fields marked as "required" in the create endpoint must not be set to empty strings if included in the update request. - First retrieve sender IDs using the 'Get all sender identities' action. Use this to update sender display names, addresses, or reply-to information.

Updates the configuration of a specific Event Webhook by its ID. You can modify the webhook URL, enable/disable it, subscribe to specific event types (bounce, click, delivered, open, etc.), set a friendly name, and configure OAuth settings. Only include fields you want to update - unspecified fields remain unchanged. For signature verification settings, use the separate 'Toggle Signature Verification' endpoint. The webhook ID is required and can be obtained from the 'Retrieve all event webhooks' or 'Create a new event webhook' endpoints.

Updates an existing suppression group (also known as an unsubscribe group). A suppression group allows recipients to unsubscribe from specific types of emails (e.g., newsletters, promotions, alerts) rather than all emails from your account. You can update the group's name, description, or set it as the default suppression group. The name and description are visible to recipients when they manage their email subscriptions. Note: Only one suppression group can be the default at a time. Setting is_default=true will remove the default status from any other group. Requires the 'Unsubscribe Groups' permission scope on your API key.

Updates the authenticated user's profile information in SendGrid. Important: At least one parameter must be provided. You can update any combination of profile fields including name, company, address, phone, and website. Use Cases: - Update contact information when user details change - Add or modify company affiliation - Update address for account management purposes - Set or change website URL Required API Scope: user.profile.update Note: This endpoint may require IP whitelisting to be configured in your SendGrid account settings if access restrictions are enabled.

Update your Bounce Purge mail settings in SendGrid. This setting configures automatic purging of contacts from your hard and soft bounce suppression lists based on a specified number of days (1-3650). Note: This only affects suppression lists, not Marketing Campaigns contacts. Only provide values for the bounce types you want to configure; empty values will be ignored.

Updates click tracking settings for your SendGrid account. Click tracking monitors email engagement by redirecting links through SendGrid's servers (or your branded domain), allowing you to track when recipients click links. Parameters: - enabled: Enable/disable click tracking for HTML emails - enable_text: Enable/disable click tracking for plain text emails Note: SendGrid can track up to 1000 links per email. Consider privacy implications as tracking may require recipient consent depending on their location. Requires the 'tracking_settings.click.update' scope.

Updates the name of an existing custom field in SendGrid Marketing Contacts. Only custom fields can be modified; Reserved Fields (like email, first_name, last_name) cannot be updated. The field_type cannot be changed after creation. Requires a valid custom_field_id obtained from 'Create Custom Field Definition' or 'Get All Field Definitions'.

Updates an existing email design in the SendGrid Design Library using PATCH. Only fields provided in the request will be updated; other fields remain unchanged. Use this to modify design name, HTML content, subject, categories, or plain text content. Requires the design ID which can be obtained from list_designs or create_design actions.

Updates settings for a dedicated IP address in your SendGrid account. This endpoint allows you to modify: - Auto warmup status: Enable/disable automatic IP warmup to build sender reputation - Parent assignment: Allow/revoke parent account access to send from this IP - Enabled status: Enable/disable the IP for sending email (non-Twilio IPs only) At least one of is_auto_warmup, is_parent_assigned, or is_enabled must be provided. Note: This API is part of the IP Address Management API which is in public beta. Requires a Pro Email API or Advanced Marketing Campaigns plan with dedicated IPs.

Update the Enforced TLS settings for your SendGrid account. Enforced TLS controls whether recipients must support TLS encryption and have valid certificates to receive your emails. By default, SendGrid uses Opportunistic TLS, meaning emails are sent with TLS but fall back to unencrypted delivery if the recipient doesn't support TLS. When Enforced TLS is enabled: - If 'require_tls' is true, recipients must support TLS 1.1 or higher - If 'require_valid_cert' is true, recipients must have a valid certificate - If conditions aren't met, messages are dropped with a block event This is an account-wide setting that applies to all emails sent through the account. Requires the 'user.settings.enforced_tls.update' API scope. Note: This feature may not be available on all SendGrid plans.

Update your Footer mail settings in SendGrid. This endpoint allows you to configure a custom footer that will be appended to the bottom of all outgoing text and HTML email bodies sent via the SendGrid v3 API or SMTP Relay. You can set the HTML and plain text versions of the footer content, and enable or disable the setting. Only provide the fields you want to update; omitted fields will retain their current values.

Updates the forward bounce mail settings for your SendGrid account. Forward bounce mail settings allow you to specify an email address to which bounce reports (permanent delivery failures) will be forwarded. This is useful for monitoring email delivery issues and maintaining list hygiene. Note: This setting only forwards 'Bounce' events. 'Block' events (temporary failures like rate limits) are not included in the forwarding. Requires the 'mail_settings.forward_bounce.update' scope on the API key.

Updates the Forward Spam mail settings for your SendGrid account. When enabled, spam reports will be forwarded to the specified email address(es). You can configure multiple forwarding addresses by providing a comma-separated list of email addresses. This setting can also be used to receive emails sent to abuse@ and postmaster@ role addresses if you have authenticated your domain. Requires the 'mail_settings.forward_spam.update' scope on the API key.

Updates Google Analytics tracking settings for your SendGrid account. When enabled, UTM parameters are automatically appended to all links in your emails, allowing you to track email campaign performance in Google Analytics. You can configure the utm_source, utm_medium, utm_campaign, utm_term, and utm_content parameters that will be added to links. Requires 'tracking_settings.google_analytics.update' scope.

Update an existing Marketing Integration by its unique ID. An Integration is a connection from SendGrid Marketing Campaigns to a supported third-party application (currently only Segment is supported). This allows you to customize and automate email event forwarding to your Segment account. You can update the label, email event filters, and destination properties. Only the fields you provide will be updated; other fields remain unchanged.

Update the name of an existing contact list in SendGrid Marketing Campaigns. This endpoint allows you to rename a contact list. The list must already exist and you need its UUID to perform the update. Note: This action uses the Marketing Campaigns API (/v3/marketing/lists/). List IDs must be in UUID format (e.g., 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'). For legacy Contact Database lists (numeric IDs), use the 'Update a List' action instead. Prerequisites: Obtain the list ID from 'Get All Lists' or 'Create List' actions. Requires the Marketing Campaigns API scope (marketing.lists.update).

Updates open tracking settings for your SendGrid account. Open tracking monitors email engagement by inserting an invisible 1x1 pixel image (tracking pixel) at the end of HTML emails. When a recipient opens the email and their email client loads images, SendGrid logs an 'open' event. Open tracking data is available in SendGrid's Statistics portal, Email Activity interface, and can be received via Event Webhook. Note: Open tracking only works with HTML emails where images are enabled by the recipient's email client. Plain text emails cannot be tracked for opens. Requires the 'tracking_settings.open.update' scope.

Update a Single Send draft by its ID. This endpoint allows you to modify specific properties of a Single Send without affecting other fields. Note: Setting 'send_at' prepopulates the send date in the UI but does not schedule the Single Send. To schedule it, use the Schedule Single Send endpoint or the SendGrid UI.

Update an existing SSO (Single Sign-On) certificate by its ID. This endpoint allows you to modify the properties of an SSO certificate used for SAML 2.0 authentication. You can update the public certificate, enable/disable the certificate, or change its integration association. The certificate ID can be obtained from the 'Get All SSO Certificates by Integration' endpoint or from the response when creating a new certificate. Note: This endpoint requires SSO to be enabled on your SendGrid account (typically available on Pro, Premier, or Marketing Campaigns Advanced plans) and appropriate API key permissions.

Updates subscription tracking settings for your SendGrid account. Subscription tracking automatically adds unsubscribe links to the bottom of your emails, allowing recipients to opt out of future communications. You can customize the HTML content, plain text content, landing page, replacement tags, and custom URL for unsubscribe handling. Requires 'tracking_settings.subscription.update' scope.

Updates a teammate's permissions in your SendGrid account. To grant full admin access: set is_admin to True and scopes to an empty array []. To assign specific permissions: set is_admin to False and provide the desired scopes. Only the parent account owner or teammates with admin privileges can update permissions. Requires the 'teammates.update' API scope. Note: SSO teammates should be updated using the 'Edit SSO Teammate' action instead.

Updates the legacy email template mail settings for your SendGrid account. When enabled, this template wraps around all emails sent via the SendGrid API. Note: SendGrid now recommends using Dynamic Transactional Templates instead of legacy templates for more advanced templating features. The html_content must include the '<% body %>' tag to indicate where the email body content will be inserted. Required scope: mail_settings.template.update

Update the credit allocation settings for a SendGrid Subuser. This action allows you to configure how many email credits a Subuser can use and how those credits are managed. Credits control the number of emails a Subuser can send. Credit Types: - unlimited: Subuser has no credit limit (no restrictions on sending). - recurring: Credits reset periodically (daily/weekly/monthly) to a fixed amount. - nonrecurring: One-time credit allocation that does not automatically reset. Usage Examples: - Set unlimited credits: type='unlimited' (omit total and reset_frequency) - Set 1000 monthly recurring credits: type='recurring', total=1000, reset_frequency='monthly' - Set 500 one-time credits: type='nonrecurring', total=500 (omit reset_frequency) Note: Requires a SendGrid parent account with Subuser management capabilities.

Updates the remaining credits for a specific Subuser account by adding or subtracting from the current credit balance. Use a positive allocation_update value to increase credits or a negative value to decrease credits. Returns the updated credit information including the new remaining balance, total credits, and credit type. Note: This endpoint requires parent account credentials with subuser management permissions. Only available on Pro or Premier SendGrid plans.

Updates the email address currently on file for your SendGrid account. This endpoint modifies the primary email address associated with your account, which is used for account-related communications from SendGrid. Required scope: user.email.update Request body: Requires an email field with the new email address. Returns: An object containing the email field with the updated account email address.

Update the password for your SendGrid account. Important: This endpoint requires username/password authentication and cannot be accessed using API key authentication. API keys do not have the user.password.update scope. This is a security measure to protect account credentials. This is a destructive operation that changes account access credentials.

Update the username for your SendGrid account. This endpoint allows you to change the username associated with your account. The username must be unique across all SendGrid accounts. Required scope: user.username.update Note: Updating your username may affect how you log into the SendGrid dashboard.

Validate whether a mail batch ID exists in SendGrid's system. This endpoint checks if a batch ID has been created and is valid. A successful response (HTTP 200) indicates the batch ID exists. An invalid batch ID returns HTTP 400. Important: A valid batch ID simply means it has been created via the 'Create a batch ID' endpoint. It does NOT indicate whether any emails have been sent using this batch ID or whether it's assigned to a scheduled send. Use this endpoint to verify batch IDs before using them with the Cancel Scheduled Sends API (pause, cancel, or resume scheduled sends). Required scope: mail.batch.read

This endpoint allows you to validate a branded link. It checks that the required DNS CNAME records are correctly configured for your branded link domain. The validation verifies: - domain_cname: The CNAME record for your branded link subdomain (e.g., links.yourdomain.com) - owner_cname: The CNAME record that verifies ownership of the branded link You can submit this request as one of your subusers if you include their ID in the on-behalf-of header in the request. Note: You should configure your DNS records before calling this endpoint. The validation will fail if the CNAME records are not properly set up with your DNS provider.

This endpoint allows you to validate an authenticated domain. It checks that the required DNS records are correctly configured for your sending domain. The validation verifies different records based on your domain's security setting: When automatic_security is enabled (default): - mail_cname: The CNAME record for your mail subdomain - dkim1: The first DKIM CNAME record - dkim2: The second DKIM CNAME record When automatic_security is disabled: - mail_server: The MX record pointing to SendGrid - subdomain_spf: The SPF TXT record for your subdomain - dkim: The DKIM TXT record containing your public key If validation fails, the response includes detailed reasons for each failed record, helping you identify which DNS entries need to be corrected. Note: Configure your DNS records with your domain provider before calling this endpoint. Validation will fail if records are not properly set up. DNS changes may take up to 48 hours to propagate.

Validates an email address and returns a verdict on its validity. This endpoint checks if an email address is valid, risky, or invalid by analyzing: - Email syntax and format - Domain DNS records (MX/A records) - Disposable email detection - Role-based email detection (e.g., admin@, hr@) - Known and suspected bounce history Returns a score from 0-1 indicating validity likelihood and a verdict of 'Valid', 'Risky', or 'Invalid'. Also detects potential typos and provides domain suggestions. Note: This is a premium feature available only to Email API Pro and Premier level accounts. Rate limited to 600 requests per minute.

Validate a reverse DNS (rDNS) record to check if DNS is properly configured. This endpoint verifies that the A record for reverse DNS has been correctly added to your DNS provider. After setting up reverse DNS, you must add the provided A record to your DNS, then use this endpoint to validate the configuration. Response Interpretation: - valid: true in validation_results.a_record means the A record is properly configured - valid: false means validation could not confirm the record - check the reason field - A false result indicates undetermined status, not necessarily invalid configuration Prerequisites: - A reverse DNS record must already exist (created via 'Set up reverse DNS') - The A record must be added to your DNS provider before validation - Requires a dedicated IP address (not available for shared IPs) - Requires 'whitelabel.update' API scope Note: DNS propagation can take up to 48 hours. If validation fails immediately after adding DNS records, wait and try again later.

Verifies a sender identity using a token from the verification email. When you create a sender identity via 'Create Verified Sender Request', SendGrid sends a verification email to that address. The email contains a verification link with a unique token. Use this endpoint with that token to complete verification. After verification, the sender can be used to send emails. Note: The token is only available in the verification email and cannot be retrieved via API.

Retrieves the details of a specific Legacy Sender Identity by its unique ID. Returns comprehensive sender information including: - Sender identification (ID, nickname) - Email configuration (from email/name, reply-to email/name) - Physical address details (address, city, state, zip, country) - Status flags (verified, locked) - Timestamps (created_at, updated_at) Note: This endpoint is for Legacy Sender Identities (used with Legacy Marketing Campaigns). For Marketing Senders (used with new Marketing Campaigns), use the 'Get a specific sender' action instead. Only verified Senders can be used to send emails. A Sender becomes locked when associated with an active campaign.

Retrieves the scheduled send date and time for a Legacy Marketing Campaign. Use this endpoint to check when a campaign is scheduled to be sent. Note: This endpoint is part of the Legacy Marketing Campaigns API. For newer implementations, consider using the Single Sends API. The campaign must be scheduled (not in draft or already sent status) for this endpoint to return schedule data. Returns a 404 error if the campaign is not found or not scheduled.