Connect AI agents to SendGrid

Retrieve a presigned download URL for a CSV export previously requested via the Request CSV tool. Pass the download_uuid included in the notification email SendGrid sends once the CSV is ready (the same UUID appears in that email's download link). The returned presigned_url is a time-limited, directly downloadable link to the CSV file.

Export stats for one or more Automations as CSV data. Provide a comma-separated list of Automation IDs (up to 50) in ids. The response body is raw CSV text (not JSON) that your application can save directly as a .csv file or parse as needed. The timezone parameter only affects how dates are formatted in the CSV; it does not filter which stats are included.

Export stats for one or more Single Sends as CSV data. Provide a comma-separated list of Single Send IDs (up to 50) in ids. The response body is raw CSV text (not JSON) that your application can save directly as a .csv file or parse as needed. The timezone parameter only affects how dates are formatted in the CSV; it does not filter which stats are included.

Retrieve the details of a specific External Integration by its ID, including destination, label, the configured filters.email_events array, and the destination-specific properties object (e.g. write_key and destination_region for Segment). Obtain the id from the List Integrations tool's response (the 'integration_id' field).

Retrieve the current state of a specific sub-account under your Twilio SendGrid partner organization. The returned state is one of: activated, deactivated, suspended, banned, or indeterminate. Suspended, banned, and indeterminate are system-assigned states and cannot be set directly (see Update Account State, which only accepts activated/deactivated).

Retrieve a single SendGrid alert by its numeric alert_id. Returns the alert's type (usage_limit or stats_notification), notification recipient (email_to), created_at/updated_at Unix timestamps, and — depending on type — its frequency (for stats_notification, e.g. daily/weekly/monthly) or percentage usage threshold (for usage_limit).

Retrieve a single entry from this SendGrid account's access allow list by its numeric rule_id. Returns the allowed ip (or CIDR/wildcard range) along with created_at/updated_at Unix timestamps. Obtain rule_id from the List Allowed IPs tool's response (the "id" field).

Retrieve a single API key's name, ID, and scopes using its api_key_id. Returns HTTP 404 if the key does not exist. Use this to inspect a key's granted permission scopes after creation — the secret key value itself is never retrievable after it was first created.

Retrieve a single unsubscribe/suppression (ASM) group by its numeric ID. Returns the group's name, description, is_default flag, id, and unsubscribes count (the number of suppressed addresses currently in the group). Obtain the group_id from the 'List Suppression Groups' tool. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve all unsubscribe/suppression (ASM) groups for a given email address, indicating for each group whether the address is currently suppressed from it. This endpoint returns a list of all groups from which the given email address has been unsubscribed (each entry in the response includes the group's id, name, description, is_default flag, and a suppressed boolean). You can submit this request as one of your subusers by including their value in the on_behalf_of field.

Retrieve the full details of a specific authenticated domain by its domain_id, including its domain/subdomain, username, DNS records (CNAME or TXT/MX and their validity), custom_spf, default, and automatic_security settings. Obtain domain_id from the 'List Authenticated Domains' tool's response (the 'id' field).

Retrieve detailed stats for a single Automation by its ID (obtain IDs from the List Automation Stats tool). Optionally constrain results to a date window with start_date/end_date, control time-slicing with aggregated_by ("total" or "day"), present dates in a specific timezone, and break results down per automation step with group_by=step_id (optionally filtered to specific step_ids). Results are paginated with page_size/page_token.

Retrieve a specific branded link (link branding / click-tracking domain) by its numeric ID. Returns the domain, subdomain, whether it's the account default, whether it has been validated, and its DNS records (domain_cname and owner_cname). Obtain the ID from the 'List Branded Links' tool. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a single Campaign from SendGrid's legacy Marketing Campaigns feature by its numeric campaign_id. Obtain campaign_id from the 'Retrieve all Campaigns' tool. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get a Single Send', for /v3/marketing/singlesends). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve the date and time a Campaign in SendGrid's legacy Marketing Campaigns feature has been scheduled to be sent. Obtain campaign_id from the 'Retrieve all Campaigns' tool. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get Scheduled Time of a Single Send', for /v3/marketing/singlesends). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve email statistics segmented by a single specific client type: phone, tablet, webmail, or desktop. SendGrid only stores up to 7 days of email activity; up to 500 items are returned per request. Use start_date (required) and optionally end_date to bound the range, and aggregated_by to group results by day, week, or month. You can also call this on behalf of a Subuser or parent-account customer using on_behalf_of.

Retrieve the full details and all fields for a single SendGrid Marketing Contact by its contact ID, including name, contact info, custom_fields, list_ids, segment_ids, and timestamps. Use the Get Batched Contacts by IDs tool if you need to look up multiple contacts at once, or the Get Contacts Count tool to find a contact's ID from other identifiers.

Retrieve up to 100 SendGrid Marketing Contacts that match the given values for a single identifier type. identifier_type must be one of email, phone_number_id, external_id, or anonymous_id — you can only search by one identifier type per request. Use this instead of Search Contacts when you have exact identifier values and don't need other SGQL filters. Returns HTTP 200 when at least one value matches (with a per-value error message returned for any that don't), HTTP 404 when none match, and HTTP 400 if any supplied value is invalid.

Retrieve a single custom field by ID from SendGrid's legacy Marketing Campaigns contact database (contactdb). Obtain custom_field_id from the 'Retrieve all custom fields' tool. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get a Field Definition', for /v3/marketing/field_definitions). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Check the status of a specific recipient export job from SendGrid's legacy Marketing Campaigns contact database (contactdb), using the job id returned by the 'Export Recipients' tool. Once status is 'ready', download each file listed in 'urls' with a GET request. SendGrid recommends exporting recipients regularly as a backup. Note: unlike most contactdb endpoints, this one does not support the on-behalf-of header.

Retrieve a single recipient list by ID from SendGrid's legacy Marketing Campaigns contact database (contactdb). Obtain list_id from the 'Retrieve all lists' tool. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get a List', for /v3/marketing/lists). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a single recipient by ID from SendGrid's legacy Marketing Campaigns contact database (contactdb). Obtain recipient_id from the 'Retrieve recipients' tool. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get a Contact by ID', for /v3/marketing/contacts). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a single segment by ID from SendGrid's legacy Marketing Campaigns contact database (contactdb). Obtain segment_id from the 'Retrieve all segments' tool. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get a Segment', for /v3/marketing/segments/2.0). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Check the current recipient-upload processing status of SendGrid's legacy Marketing Campaigns contact database (contactdb), e.g. whether uploads (via the 'Add recipients' tool) are being processed normally or are delayed, and by how many seconds. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead (there is no direct equivalent for /v3/marketing/contacts, which processes uploads asynchronously via job IDs instead). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a single design from your SendGrid Design Library by its ID. Returns the design's name, editor ('code' or 'design'), html_content, plain_content, thumbnail_url, subject, categories, and created_at/updated_at timestamps. Useful before making a PATCH request to update a specific field.

Retrieve a specific Bulk Email Address Validation Job by its job_id, including its status (Initiated, Queued, Ready, Processing, Done, or Error), the total number of segments and how many have been processed so far, whether the results CSV is available for download (is_download_available), started_at/finished_at timestamps, and any errors encountered. Obtain job_id from the Request Bulk Email Validation Upload URL tool's response, or from the List Bulk Email Validation Jobs tool.

Retrieve the full settings for a single Event Webhook by webhook_id, including its enabled state, destination url, which event types it is configured to send (delivered, open, click, bounce, dropped, etc.), friendly_name, OAuth settings if configured, and public_key if signature verification is enabled. Obtain the webhook_id from the List Event Webhooks tool.

Check the status of a SendGrid contact export job by its export id (obtained from the Export Contacts tool's response). Returns status (pending, ready, or failure), created_at/completed_at/expires_at timestamps, and — once status is "ready" — a urls array of downloadable CSV/JSON file links (more than one if a max_file_size was specified in the original export request). If status is "failure", a human-readable message field explains why.

Retrieve a global suppression, or confirm whether an email address is globally suppressed. If the email address is globally suppressed, the response includes that recipient_email. If it is not globally suppressed, an empty JSON object is returned.

Check the status of a SendGrid contact import job by its job_id. Use the job_id returned by the Import Contacts, Add or Update a Contact, or Delete Contacts tools as the id in the path. The response's status field is one of pending (not yet started), completed (finished with no errors), errored (finished with some errors), or failed (finished with all errors, or the job was entirely unprocessable — e.g. an unsupported file format). The results object includes requested_count, created_count, updated_count, deleted_count, and errored_count, plus an errors_url you can download for details on any per-row failures. Also returns started_at and finished_at ISO8601 timestamps. Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Retrieve all External Integrations (email event forwarding destinations, e.g. Segment) configured for the authenticated user. Each entry includes integration_id, user_id, destination, label, the configured filters.email_events array, and the destination-specific properties object (e.g. write_key and destination_region for Segment).

Retrieve details of a specific invalid email address, including the reason it was marked invalid and the Unix timestamp when it was added to the invalid emails list. Returns an array containing zero or one matching entry.

Retrieve details for a specific IP address on this SendGrid account, identified by its literal IP value. Details include whether a parent is assigned, whether it warms up automatically, which IP Pools it belongs to, when it was added/last updated, and whether it's leased/enabled. Set include_region to true to also return the IP's region (us or eu). Note: this does not return Subuser assignment information — use the "Get a List of Subusers Assigned to an IP" tool for that.

Retrieve details for a single IP address on this SendGrid account, identified by its literal IP value, including which IP pools it belongs to (an IP can belong to multiple pools), its subusers, reverse DNS record, warm-up status, and the date it entered warmup.

Retrieve details for a specific IP Pool by its unique ID, including the Pool's name, a sample of up to 10 associated IP addresses, and the total number of IPs in the Pool. Use the Get IPs Assigned to an IP Pool tool to retrieve additional IPs beyond the sample. Set include_region to true to also return IP counts broken down by region.

Retrieve all of the IP addresses that belong to a specific IP pool on this SendGrid account, identified by the pool's name. Returns the pool_name and the array of IP addresses assigned to it.

Validate a mail batch ID. If the batch ID is valid, this returns HTTP 200 and the batch ID itself; if invalid, you'll receive a 400-level status code and an error message. A batch ID does not need to be assigned to a mail send to be considered valid — a successful response only confirms the batch ID has been created, not that it has been used in a send.

Retrieve data about a specific SendGrid Marketing Campaigns contact list by its ID, including its name and contact_count. Set contact_sample to true to also receive a contact_sample array containing up to 50 of the most recent contacts uploaded or attached to the list.

Retrieve full Email Activity details for a single message by its message ID (msg_id), obtained from the Filter Messages tool. Returns sender/recipient addresses, subject, delivery status, template and API key used, originating/outbound IP info, associated categories, and the full events timeline (e.g. processed, delivered, opened, clicked, bounced, dropped, deferred, spam_report, unsubscribe) with per-event details. Note: for Regional (EU) subusers, no Email Activity data is generated for this service.

Get all details for a single message from the Email Logs API by its sg_message_id, obtained from the Search Messages By Filter tool. Returns sender/recipient addresses, subject, a summary status (processed, delivered, deferred, dropped, bounced, or blocked), template and API key used, originating IP, categories, marketing campaign info, and the full timeline of events (up to 100 most recent) for the message. For requests authenticated as the parent account, pass the subuser query parameter if the message belongs to a subuser.

Retrieve a specific Inbound Parse setting by its hostname. Returns the parse setting's url (where parsed data is POSTed), hostname, spam_check flag, and send_raw flag. Use the List Parse Settings tool to see all configured hostnames.

Retrieve details about a single pre-built design provided by Twilio SendGrid, by its ID. Returns the design's name, editor ('code' or 'design'), html_content, plain_content, thumbnail_url, subject, and categories. Useful when you want to inspect a pre-built design before duplicating and modifying it.

Retrieve the full details of a specific Reverse DNS record by its id, including the associated IP address, rDNS hostname, domain/subdomain, users able to send from the IP, validity, and the A record (host/data) that must exist at your DNS host. Obtain the id from the 'List Reverse DNS Records' tool's response (the 'id' field).

Retrieve the cancel/pause scheduled send information for a specific batch_id. Returns an array of {batch_id, status} objects for that batch. Only scheduled sends that were assigned a batch_id and later paused or cancelled via the 'Cancel or Pause a Scheduled Send' tool will be found here.

Retrieve the full configuration of a single webhook security policy by its id, including its name and, depending on configuration, its OAuth client details or the signature public_key used to verify webhook payloads. Obtain the policy id from the List All Security Policies tool.

Retrieve a single SendGrid Marketing Campaigns segment (v1, legacy query-DSL segments) by its segment_id, including its name, query_dsl, contacts_count, a contacts_sample of matching contacts, and timestamps. Set query_json to true to also receive the parsed SQL AST as a JSON object in the query_json field of the response.

Retrieve a SendGrid Marketing Campaigns Segment (v2, SQL-based segmentation) by its segment ID. Returns the segment's name, its SQL query_dsl, contacts_count, refresh status (query_validation, refreshes_used, max_refreshes, last_refreshed_at), and timestamps. Set contacts_sample to false to omit the contacts_sample array (a subset of matching contacts) from the response for a lighter payload. Obtain the segment_id from the 'Create Segment' or a 'List Segments' tool.

Retrieve the details of a specific Sender identity by its numeric id, including its nickname, from/reply_to addresses, physical address, whether it's verified (only verified Senders can send email), and whether it's locked (a Sender is locked while associated with a campaign in Draft, Scheduled, or In Progress status, and cannot be updated or deleted while locked). Obtain the id from the 'Get a List of All Senders' tool. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a single Sender Identity from SendGrid's legacy Marketing Campaigns 'Campaigns' feature by its numeric sender_id. Obtain sender_id from the 'Get a List of All Sender Identities' tool. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('View a Sender', for /v3/marketing/senders). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve the public key used to verify cryptographic signatures for a single Event Webhook by its webhook_id, for webhooks that have signature verification enabled. Obtain the webhook_id from the List Event Webhooks tool. Use this public key in your receiving application to verify that incoming event POST requests genuinely originated from Twilio SendGrid.

Retrieve full details about one Twilio SendGrid Marketing Campaigns Single Send using its ID, including its name, status, categories, send_at, send_to targeting (list_ids/segment_ids/all), email_config (subject/content/sender/unsubscribe settings), and any warnings. Obtain the id from the 'Get All Single Sends' tool's response.

Retrieve detailed stats for a single Single Send by its ID (obtain IDs from the List Single Send Stats tool). Optionally constrain results to a date window with start_date/end_date, control time-slicing with aggregated_by ("total" or "day"), present dates in a specific timezone, and break results down by A/B test variation and/or phase with group_by (comma-separated combination of ab_variation, ab_phase). Results are paginated with page_size/page_token.

Retrieve a specific spam report by recipient email address. Returns an array containing the report's created timestamp (Unix), the recipient's email address, and the IP address the message was sent from. Use this to check whether -- and when -- a specific recipient marked one of your sends as spam. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a single Single Sign-On (SAML) certificate configured on this Twilio SendGrid account by its certificate ID. Returns the certificate's public_certificate (PEM), numeric id, not_before/not_after validity as unix timestamps, and the integration_id of the SSO Integration it's associated with. Obtain the cert_id from the 'Get All SSO Integrations' tool or from the response of the 'Create SSO Certificate' tool.

Retrieve a single Single Sign-On (SAML) integration configured on this Twilio SendGrid account by its integration ID. Returns the integration's name, enabled state, signin_url, signout_url, entity_id, id, single_signon_url, and audience_url. Obtain the id from the 'Get All SSO Integrations' tool. Set include_completed_integration_field to true to also receive the completed_integration field in the response.

Retrieve a Credits overview for a single Subuser: the reset type (unlimited, recurring, or nonrecurring), the reset_frequency (monthly, weekly, or daily), and the current remain/total/used counts. remain is null when type is unlimited; total and used are null when type is unlimited or nonrecurring.

Retrieve a specific email address from this account's blocks suppression list. Returns an array containing the matching block record (created Unix timestamp, email, reason, and SMTP status), or an empty array if the address is not currently blocked. You can submit this request as one of your subusers by including their value in the on_behalf_of field.

Retrieve a specific bounce record by email address from this account's bounces suppression list. Returns an array containing the matching bounce record (created Unix timestamp, email, reason, and enhanced SMTP status), or an empty array if the address has no bounce on record. You can submit this request as one of your subusers by including their value in the on_behalf_of field.

Retrieve the number of bounces for a specific bounce classification, broken down by day and by receiving domain, in descending order. Valid classifications are: Content, Frequency or Volume Too High, Invalid Address, Mailbox Unavailable, Reputation, Technical Failure, and Unclassified. Optionally restrict results to a start_date/end_date range (YYYY-MM-DD, inclusive). By default the response is JSON; set accept_format to 'text/csv' to receive the same data as CSV text instead.

Retrieve a specific Teammate's profile by username, including first/last name, email, scopes, user_type (admin, owner, or teammate), admin flag, and contact details (phone, website, address, city, state, zip, country). Get a Teammate's username from the List Teammates tool. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a single transactional template from SendGrid by its template_id, including its full list of versions (each version has its own id, subject, html_content, plain_content, and active flag). Obtain the template_id from the 'List Templates' or 'Create Template' tool. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a specific version of a transactional template in SendGrid, identified by the parent template_id and the version_id. Returns the version's full details, including subject, html_content, plain_content, active flag, editor, and any warnings. Obtain the template_id from the 'List Templates' tool and the version_id from the 'List Templates', 'Get Template', or 'Create Template Version' tool. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a list of all of the authenticated user's Bulk Email Address Validation Jobs. Each entry in the returned 'result' array includes the job's id, status (Initiated, Queued, Ready, Processing, Done, or Error), started_at, and finished_at timestamps. Use the Get Bulk Email Validation Job tool with a specific job id for full job details, including segment progress and any errors.

Retrieve the warmup status for a specific IP address. Returns the IP address and the Unix timestamp when it entered warmup mode if it is currently warming up. Use List Warm Up IP to retrieve all IPs currently in warmup.

Retrieve a list of the IP addresses that recently attempted to access this SendGrid account, either through the web User Interface or the API. Each entry includes the IP address, whether access was allowed, the authentication method used, the geographic location the attempt originated from, and Unix timestamps for the first and most recent attempt from that IP. Use limit to control how many IPs are returned (default 20).

Retrieve all sub-accounts provisioned under your Twilio SendGrid partner/reseller organization via the Account Provisioning API. Returns each account's Twilio SendGrid account ID and creation timestamp, along with cursor-based pagination info. Supports paging with offset (the last item ID successfully retrieved) and limit (page size, up to 100). This is distinct from the Subusers API — it lists accounts created through partner account provisioning.

Retrieve a paginated list of IP addresses provisioned to a specific Twilio SendGrid sub-account (managed via the Partners/Accounts provisioning API), ordered by most recently added IP. Each result includes the IP address and its region (eu or us). Supports pagination via limit (page size) and offset (the last IP successfully retrieved in a previous call). This is intended for reseller/partner accounts managing IP allocation across sub-accounts.

Retrieve the offerings (the package plus any add-ons) currently assigned to a specific sub-account under your Twilio SendGrid partner organization. Each returned offering includes its name, type (package or addon), quantity, and the start/end dates indicating when it was activated and when it expires (absent if the offering has no expiry).

Retrieve your user account details, including the account type ("free" or "paid") and your current sender reputation score.

Retrieve the account's current Address Whitelist mail setting: whether the whitelist is enabled and the full list of whitelisted email addresses/domains. The Address Whitelist setting specifies addresses or domains for which mail should never be suppressed — bounces, blocks, and unsubscribes logged for whitelisted addresses/domains are still delivered as if under normal sending conditions. Note: for Regional (EU) subusers, using this feature causes customer personal information to be stored outside the EU.

Retrieve all alerts configured on this SendGrid account. Alerts notify you by email either when a usage threshold is reached (type=usage_limit) or on a recurring schedule with stats summaries (type=stats_notification). Returns a JSON array of alert objects, each including id, type, email_to (notification recipient), created_at/updated_at (Unix timestamps), and — depending on type — frequency (e.g. daily/weekly/monthly for stats_notification) or percentage (usage threshold for usage_limit). No parameters are required.

Retrieve all of the authenticated domains that have been assigned to a specific Subuser (a Subuser can have up to five associated domains). This lets Subusers send mail using their parent's domain(s). When selecting a domain to send from, SendGrid checks in this order: (1) a domain assigned to the Subuser matching the From address's domain, (2) the Subuser's default domain, (3) a domain assigned to the parent user matching the From address's domain, (4) the parent's default domain, (5) sendgrid.net.

Retrieve all webhook security policies configured for your SendGrid account, including each policy's id, name, and security configuration (OAuth client details or the signature public key). Use this to find a policy's id before calling Get Security Policy, Update Security Policy, or Delete Security Policy.

Retrieve the list of IP addresses currently allowed to access this SendGrid account (the access allow list). Each entry includes its numeric id (used to remove the address via the Delete Allowed IP tool), the allowed ip (or CIDR/wildcard range), and created_at/updated_at Unix timestamps. No parameters are required.

Retrieve the names and IDs of all API keys belonging to the authenticated user. For security reasons, the key secret itself is never returned by this endpoint — only name and api_key_id. Use the returned api_key_id with the Get/Update/Delete API Key tools. Optionally cap the number of results with limit.

Retrieve all unsubscribe/suppression (ASM) groups created by this user, including each group's id, name, description, is_default flag, and unsubscribes count. Optionally filter to one or more specific group IDs; when multiple IDs are supplied they are appended as repeated 'id' query parameters (e.g. ?id=123&id=456), matching SendGrid's documented behavior. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a list of all suppressions (unsubscribed email addresses) across every unsubscribe/suppression (ASM) group on the account. Each entry includes the suppressed email address, the group_id and group_name it belongs to, and a created_at UNIX timestamp indicating when the suppression was recorded. To scope results to a single group instead, use the 'List Suppressions in Group' tool. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve all IP addresses on this SendGrid account that are currently assigned (in active use for sending). Each result includes the IP address, the IP pools it has been added to, whether it is currently warming up, and the Unix timestamp when warmup started. Unassigned IPs are not returned by this endpoint.

Retrieve a paginated list of all domains you have authenticated in this SendGrid account. Use limit to set the page size and offset to control the starting position within the list (e.g. limit=10, offset=10 requests the second page). Supports filtering by exact username, searching by domain name, and excluding subuser-owned domains. Returns a JSON array of authenticated domain objects (id, domain, subdomain, username, ips, custom_spf, default, dns records, valid, etc.).

Retrieve the authenticated domain that has been assigned to a specific Subuser. Authenticated domains can be associated with Subusers from a parent account so the Subuser can send mail using the parent's domain; to associate a domain, the parent account must first authenticate and validate it, then assign it via the subuser management tools. If the Subuser has multiple domains assigned (via the bulk assignment endpoint), use the List All Authenticated Domains for User tool instead to retrieve all of them.

Retrieve stats for all Automations in this SendGrid Marketing Campaigns account. By default, all Automations are returned; pass a comma-separated list of Automation IDs in automation_ids to scope the results to a specific selection (up to 25 IDs). Each result entry includes the Automation id, the aggregation period ("total" or a YYYY-MM-DD date), the step_id (if grouped by step), and a stats object with counters such as delivered, opens, unique_opens, clicks, unique_clicks, bounces, spam_reports, and unsubscribes. Results are paginated: use page_size (1-50, default 25) to control page length and page_token (from the response's _metadata.next URL) to fetch subsequent pages.

Retrieve a set of SendGrid Marketing Contacts identified by their IDs in a single call, more efficient than making a series of individual Get a Contact by ID requests. Supply up to 100 contact IDs as an array of strings in the ids field. Returns the same full contact detail object (name, contact info, custom_fields, list_ids, segment_ids, timestamps) for each matched contact.

Retrieve the account's current Bounce Purge mail setting: whether it is enabled, and the configured maximum age (in days) of contacts kept in the hard and soft bounce suppression lists before they are automatically purged. A hard bounce means the message was permanently undeliverable (e.g. invalid or unknown recipient address); a soft bounce means the message reached the recipient's mail server but bounced back before delivery (e.g. a full inbox). Returns an object with 'enabled' (boolean), 'soft_bounces' (integer days, nullable), and 'hard_bounces' (integer days, nullable).

Retrieve all branded links (link branding / click-tracking domains) configured on your SendGrid account. Each returned object includes the domain, subdomain, whether it's the account default, whether it has been validated, and its DNS records. Optionally limit the number of results returned per page. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve email statistics (from SendGrid's Advanced Stats API) segmented by browser type (e.g. Chrome, Firefox, Safari), across a date range. SendGrid only stores up to 7 days of this activity. Requires start_date; end_date defaults to today. Optionally filter to specific browsers (up to 10), time-slice with aggregated_by (day/week/month), and paginate with limit/offset. Returns an array of {date, stats: [{type, name, metrics: {clicks, unique_clicks}}]} objects.

Retrieve a paginated list of all Campaigns in SendGrid's legacy Marketing Campaigns feature, newest first. Returns an empty array if no campaigns exist. Use limit to set the page size and offset to page through additional results. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get all Single Sends', for /v3/marketing/singlesends). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve all the categories associated with your Twilio SendGrid Marketing Campaigns Single Sends. Returns your latest 1,000 unique categories in ascending order. Use this to discover valid category values before calling the Search Single Send tool with a categories filter, or before creating/updating a Single Send with categories. No parameters are required.

Retrieve email statistics (blocks, bounces, clicks, delivered, opens, spam reports, unsubscribes, etc.) for one or more of your categories over a date range. Requires start_date and at least one category (up to 10). If you do not narrow down further, this returns a sum for each category grouped by aggregated_by (day/week/month). Returns an array of {date, stats: [{type, name, metrics: {...}}]} objects.

Retrieve the total sum of each email statistic (blocks, bounces, clicks, delivered, opens, spam reports, unsubscribes, etc.) for every category over a given date range. Requires start_date. If you do not narrow down further, this returns a sum for each category in groups of 10 (via limit/offset). Sort the results by a single metric with sort_by_metric and sort_by_direction. Returns a {date, stats: [{type, name, metrics: {...}}]} object.

Retrieve a paginated list of all category names used to group your emails on this SendGrid account (this returns the category names themselves, not statistics — use the 'Retrieve Email Statistics for Categories' tool for stats). Use limit to set the page size and offset to page through additional results. Optionally filter with category to perform a prefix search on category names. Returns an array of {category} objects.

Retrieve the account's current Click Tracking setting. Click Tracking rewrites all links and URLs in your emails to point through SendGrid's servers (or your branded click-tracking domain) so that link clicks can be tracked; SendGrid can track up to 1000 links per email. Returns 'enabled' (whether click tracking is on for HTML emails) and 'enable_text' (whether click tracking also applies to plain-text emails). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve click-tracking stats for a single Automation's embedded links. Each result entry gives the clicked URL (including any {{custom_fields}} substitutions), its url_location (0-indexed position within the message), the step_id it belongs to, and the number of clicks it received. Optionally group/filter by step_id. Results are paginated with page_size/page_token, and the response also includes a total_clicks count.

Retrieve email statistics segmented by client type (phone, tablet, webmail, desktop) for a date range. SendGrid only stores up to 7 days of email activity; up to 500 items are returned per request. Use start_date (required) and optionally end_date to bound the range, and aggregated_by to group results by day, week, or month. You can also call this on behalf of a Subuser or parent-account customer using on_behalf_of.

Retrieve up to 50 of the most recently uploaded or list-attached contacts from SendGrid Marketing Contacts, sorted by email address. The response also includes the full total contact_count for the account. Note that pagination of this endpoint has been deprecated by SendGrid — use the Get Batched Contacts by IDs tool or Export Contacts for retrieving larger or complete sets of contacts. Takes no input parameters.

Retrieve up to 100 SendGrid Marketing Contacts matching the given email address(es), including any alternate_emails. Email addresses are treated as a primary key, so use this endpoint instead of Search Contacts whenever you have exact addresses and don't need other SGQL filters. Addresses do not need to match the case they're stored in, but results are always returned lower-cased; empty strings in the input are ignored. Returns HTTP 200 when at least one address matches (with a per-address error message returned for any that don't), HTTP 404 when none match, and HTTP 400 if any supplied address is invalid. Optionally narrow further by a specific phone_number_id, external_id, or anonymous_id.

Retrieve the total number of contacts stored in SendGrid Marketing Contacts for this account, plus a billable_count for the current billing month, and (for parent accounts with subusers) a billable_breakdown showing each subuser's billable contact usage. Takes no input parameters.

Retrieve the number of contacts currently on a specific SendGrid Marketing Campaigns list, identified by list id. Returns contact_count (total contacts on the list) and billable_count (the portion of those contacts that count toward your account's billing).

Retrieve all custom fields defined on SendGrid's legacy Marketing Campaigns contact database (contactdb). Each entry includes its id, name, and type. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get all Field Definitions', for /v3/marketing/field_definitions). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve details of every recipient export job (in flight or recently completed) for SendGrid's legacy Marketing Campaigns contact database (contactdb). Each entry's export_type shows what kind of export it is (contacts_export, list_export, or segment_export) and status shows its stage (pending, ready, or failure); entries with status 'ready' include download 'urls'. Use this if you have exports in flight but don't know their job IDs. Note: unlike most contactdb endpoints, this one does not support the on-behalf-of header.

Retrieve all recipient lists in SendGrid's legacy Marketing Campaigns contact database (contactdb). Returns an empty array if you have no lists. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get all Lists', for /v3/marketing/lists). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve all recipients on a single list from SendGrid's legacy Marketing Campaigns contact database (contactdb), paginated. Use page and page_size to page through results. Obtain list_id from the 'Retrieve all lists' tool. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get Contacts on a List', for /v3/marketing/lists). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve all recipients in SendGrid's legacy Marketing Campaigns contact database (contactdb), paginated. Because deleting a page of recipients can produce an empty page before the true end of the list, keep paging with increasing 'page' values until you get a 404 rather than stopping at the first empty page. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get all Contacts', for /v3/marketing/contacts). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve the number of recipients in SendGrid's legacy Marketing Campaigns contact database (contactdb) that you are billed for — the highest number of recipients your account has ever held at one time. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get all Contacts Count', for /v3/marketing/contacts, though billing counts may differ in definition). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve the total number of recipients currently in SendGrid's legacy Marketing Campaigns contact database (contactdb). This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get all Contacts Count', for /v3/marketing/contacts). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve every list a given recipient belongs to in SendGrid's legacy Marketing Campaigns contact database (contactdb). Obtain recipient_id from the 'Retrieve recipients' tool. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get Lists a Contact Belongs to', for /v3/marketing/contacts). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

List all field names that are reserved by SendGrid's legacy Marketing Campaigns contact database (contactdb) and therefore cannot be used as a custom field name — e.g. first_name, last_name, email, created_at, updated_at, last_emailed, last_clicked, last_opened, lists, campaigns. Check this before creating a custom field. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get all Field Definitions', which separates reserved fields from custom fields for /v3/marketing/field_definitions). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve all segments in SendGrid's legacy Marketing Campaigns contact database (contactdb), including their conditions and recipient counts. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get List of Segments', for /v3/marketing/segments/2.0). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve all recipients in a segment from SendGrid's legacy Marketing Campaigns contact database (contactdb), paginated. Obtain segment_id from the 'Retrieve all segments' tool. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get Contacts by Segment ID', for /v3/marketing/segments). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve the current credit balance for your account. Each account has a credit balance, which is a base number of emails it can send before receiving per-email charges. Returns the remaining, total, overage, and used credit counts, along with the last/next reset dates and reset frequency.

Retrieve the default domain authentication for your account (or for a specific domain, if provided). When creating or updating a domain authentication, it can be marked as the default; the default domain is used to send all mail unless another authenticated domain matches the From address's domain, in which case that one overrides the default. If no default is set, this returns general information about your domain authentication status instead. Returns an array of authenticated domain objects (each with DNS records, validity, and associated subusers).

Retrieve the default branded link -- the actual link-branding domain used for click-tracked URLs when sending messages. If you have more than one branded link, the default is determined in this order: the validated branded link marked as default (set via 'Create a Branded Link' or 'Update a Branded Link'), then legacy branded links migrated from the whitelabel wizard, then SendGrid's own default branded links (e.g. 100.ct.sendgrid.net). Optionally filter by a specific domain to check its default branded link instead of the account-wide default. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a paginated list of designs stored in your SendGrid Design Library (this does not include SendGrid's pre-built designs, which are retrieved via a separate endpoint). By default up to 100 results are returned per request; use page_size to control the page length and page_token (taken from the previous response's _metadata) to fetch subsequent pages. Set summary to false to receive the full design object (including html_content and plain_content) for each result instead of just the default summary fields.

Retrieve email statistics segmented by device type (desktop, webmail, phone, tablet, other) for a date range. SendGrid only stores up to 7 days of email activity; up to 500 items are returned per request by default (override with limit/offset). Use start_date (required) and optionally end_date to bound the range, and aggregated_by to group results by day, week, or month. You can also call this on behalf of a Subuser or parent-account customer using on_behalf_of.

Retrieve the email address currently on file for your SendGrid account.

Retrieve the account's current Enforced TLS settings: require_tls (whether recipients must support TLS 1.1+) and require_valid_cert (whether recipients must present a valid certificate). If either is true, SendGrid will drop messages to recipients that don't meet the requirement and log a block event with 'TLS required but not supported'.

Retrieve your SendGrid Engagement Quality (SEQ) scores for a specified date range (from/to, inclusive, UTC, YYYY-MM-DD). SEQ scores summarize how well your email program is performing, ranging from 1 (worst) to 5 (best), based on metrics like open rate, spam rate, bounce rate, bounce classification, and engagement recency. A response of HTTP 200 includes a 'result' array with one entry per day in range; the 'score' and 'metrics' fields are omitted for any day the account wasn't eligible for scoring (e.g., fewer than 1,000 messages sent in the trailing 30 days, or open tracking disabled). A response of HTTP 202 means scores for the requested range aren't calculated yet — SEQ scores are computed asynchronously, so retry later.

Retrieve all of your Event Webhooks configured in SendGrid. Each webhook is returned as an object in the webhooks array with its configuration (which event types it sends, its destination URL, enabled state, friendly_name, OAuth settings if configured, and public_key if signature verification is enabled) plus its unique id. Also returns max_allowed, the maximum number of Event Webhooks permitted on your current SendGrid plan. Use a returned webhook's id with the Get/Update/Delete Event Webhook tools or the signed-webhook tools.

Retrieve details of all current contact export jobs, whether in flight or recently completed. Each returned object's export_type field indicates the kind of export (contacts_export, list_export, or segment_export) and its status field indicates the processing stage (pending, ready, or failure). Exports that are ready include a urls field listing the downloadable file URLs. Use this tool if you have exports in flight but don't know their IDs, which are otherwise required by the Export Contacts Status tool. Takes no input parameters.

Retrieve all Custom Field and Reserved Field definitions configured for SendGrid Marketing Contacts. custom_fields lists the fields you've created (each with id, name, field_type); reserved_fields lists SendGrid's built-in fields (e.g. first_name, email, created_at), some of which are read_only and cannot be set via the API. Use the returned custom field id values with the Update Custom Field Definition and Delete Custom Field Definition tools. Takes no input parameters.

Retrieve the account's current Footer mail setting: whether it is enabled, plus the HTML and plain-text content that gets appended to the bottom of every text and HTML email message body. Returns an object with 'enabled' (boolean), 'html_content' (string), and 'plain_content' (string).

Retrieve the account's current Forward Bounce mail setting: whether it is enabled, and the email address (if any) that bounce reports are being forwarded to. Returns an object with 'enabled' (boolean) and 'email' (string, nullable).

Retrieve the account's current Forward Spam mail setting: whether it is enabled, and the email address(es) (if any) that spam reports are being forwarded to. Returns an object with 'enabled' (boolean) and 'email' (string, possibly a comma-separated list of addresses).

Retrieve email statistics segmented by country and, for the US and CA, state/province. SendGrid only stores up to 7 days of email activity; up to 500 items are returned per request by default (override with limit/offset). Not available for Regional (EU) Subusers due to PII restrictions. Use start_date (required) and optionally end_date to bound the range, country to filter to a single supported country (US or CA), and aggregated_by to group results by day, week, or month. You can also call this on behalf of a Subuser or parent-account customer using on_behalf_of.

Retrieve a paginated list of all email addresses that are globally suppressed -- recipients who will not receive any of your email, regardless of which unsubscribe/suppression (ASM) group is used, until removed. Use limit to set the page size (max 500) and offset to skip past already-retrieved items for subsequent pages. Optionally filter by start_time/end_time (Unix timestamps, inclusive) marking when the recipient was added to the list, or by an email address prefix/substring (use '%25' as a wildcard, with reserved characters percent-encoded, e.g. '@' as '%40'). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve the account's current setting for Google Analytics tracking on outgoing emails. Returns 'enabled' (whether Google Analytics tagging is on) plus the default UTM parameters applied to tracked links: utm_source (referrer source), utm_medium (marketing medium, e.g. 'email'), utm_campaign (campaign name), utm_term (paid keywords), and utm_content (used to differentiate ads/links). See Google's URL Builder and Campaign Building best practices for how these values are used. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a paginated list of email addresses that SendGrid has marked as invalid (e.g. malformed or with an unknown mail domain), along with the reason and the Unix timestamp each was added. Use limit to set the page size (max 500) and offset to skip past already-retrieved items for subsequent pages. Optionally filter by start_time/end_time (Unix timestamps, inclusive) or by a specific email address.

Retrieve the IP addresses assigned to a specific IP Pool on this SendGrid account, identified by the Pool's unique ID. Each entry includes the ip, its region (when include_region is set), and the Pools it belongs to. Use limit together with after_key to paginate through results.

Retrieve a list of all IP addresses associated with this SendGrid account. Each entry includes the ip, the IP Pools it's assigned to, whether it warms up automatically, when it was added/last updated, and whether it is leased/enabled/parent-assigned. Supports filtering by ip, is_leased, is_enabled, is_parent_assigned, pool, a start_added_at/end_added_at time window, and region. Note: is_parent_assigned and pool cannot both be set (an IP can't be assigned to a pool unless a parent is assigned first). Use limit together with after_key or before_key (not both) to paginate through results.

Retrieve a paginated list of all IP addresses on this SendGrid account, both assigned and unassigned. Each result includes warm-up status, the IP pools it belongs to, assigned subusers, and reverse DNS (whitelabel) info; start_date reflects when warmup began for that IP. Use limit to control page size and offset to page through results, and optionally filter to a single ip, a specific subuser, or exclude whitelist/reverse-DNS records with exclude_whitelabels. Results can be sorted with sort_by_direction.

Retrieve a list of this account's IP Pools along with a sample of each Pool's associated IP addresses (up to 10 IPs per Pool by default). Use the Get IPs Assigned to an IP Pool tool to retrieve additional IPs beyond the sample. Each account may have a maximum of 100 IP Pools. Supports filtering by ip and region, and pagination via limit/after_key.

Retrieve all IP pools that exist on this SendGrid account. Each result returns the pool's name. Use the 'Retrieve all the IPs in a specified pool' tool to see which IP addresses belong to a given pool.

Retrieve a paginated list of all mail settings for the account (e.g. Address Whitelist, Bounce Purge, Event Notification, Footer, Forward Bounce, Forward Spam, Legacy Email Template, Plain Content, Spam Checker). Each setting is returned with a name, title, description, and an 'enabled' status (true/false). Use 'limit' to control page size and 'offset' to page through results if the list is larger than 'limit'.

Retrieve email statistics segmented by recipient mailbox provider (e.g. Gmail, Yahoo, Outlook). SendGrid only stores up to 7 days of email activity; up to 500 items are returned per request by default (override with limit/offset). Use start_date (required) and optionally end_date to bound the range, mailbox_providers to filter to specific providers (up to 10), and aggregated_by to group results by day, week, or month. You can also call this on behalf of a Subuser or parent-account customer using on_behalf_of.

Retrieve a paginated array of all of your SendGrid Marketing Campaigns contact lists, including each list's id, name, and contact_count. Use page_size and page_token to page through results when you have many lists.

Search your Email Activity by filtering messages with a SendGrid query string. The query must use the format query={query_type}="{query_content}", URL-encoded — for example, to find messages sent to a specific address, use query=to_email%3D%22example%40example.com%22. Combine up to 160 filter conditions in a single query using AND/OR (see SendGrid's Query Reference docs for the full list of query types such as to_email, from_email, subject, status, msg_id, and date ranges). Returns up to `limit` abbreviated message records (from_email, msg_id, subject, to_email, status, opens_count, clicks_count, last_event_time) — use the Get Message tool with a msg_id to fetch full details for one message.

List recent messages within Email Logs, or search for messages using a filter query. Allowed query fields and operators: sg_message_id (=), subject (=), to_email (=), status (IN), reason (=), categories (IN), sg_message_id_created_at (>, <, >=, <=). Up to 160 conditions can be combined with AND (nesting is not allowed); the IN operator accepts a list of string values, e.g. status IN ('delivered', 'processed'). Returns a page of up to 'limit' messages, each with from_email, sg_message_id, subject, to_email, status, reason, and sg_message_id_created_at — use the Get Message By ID tool with an sg_message_id to fetch full event details for one message. Omit 'query' to list recent messages without filtering.

Retrieve the monthly email statistics for all Subusers over the given month. date (required, format YYYY-MM-DD) selects the month to report on. Optionally narrow results with subuser (a substring search of Subuser usernames), sort with sort_by_metric and sort_by_direction, and page with limit and offset. Note: you cannot sort by bounce_drops, deferred, invalid_emails, processed, spam_report_drops, spam_reports, or unsubscribe_drops.

Retrieve the full catalog of offerings available under your Twilio SendGrid partner organization. Each catalog entry describes an offering (its name, type — package or addon, and quantity) along with the entitlements it grants, such as monthly email send limits, dedicated IP count, and maximum teammates/subusers. Use this to discover valid offering names before assigning them to an account via Create Account or Update Account Offerings.

Retrieve the account's current Open Tracking setting. Open Tracking adds an invisible tracking image at the end of outgoing emails; when the recipient's email client loads images, a request is made to SendGrid's servers and an open event is logged (visible in the Statistics portal, Email Activity interface, and reported via the Event Webhook). Returns a single 'enabled' boolean indicating whether open tracking is currently on. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve all of your current Inbound Parse settings. Each entry in the result array describes one parse setting: the hostname whose incoming mail is parsed, the destination url where parsed message data is POSTed, whether spam_check is enabled, and whether send_raw (raw MIME content) is enabled.

Retrieve usage statistics for your Inbound Parse Webhook, showing how many emails were received and parsed over a given date range. Requires start_date (YYYY-MM-DD); end_date defaults to the day the request is made if omitted. Optionally group results by day, week, or month with aggregated_by, and paginate through results with limit/offset. Each returned entry includes a date and a stats array with a received count. Useful for monitoring Parse Webhook volume and spotting drops in inbound email processing.

Retrieve a paginated list of all partner integration settings available to be enabled on this SendGrid account. Each entry includes the partner's title, name, description, and whether it is currently enabled. Use limit to control the page size and offset to move through additional pages (e.g. offset=10 with limit=10 requests the second page).

Retrieve a list of all pending Teammate invitations on your SendGrid account -- invites that have been sent but not yet accepted. Each entry includes the invited email address, the scopes/admin flag they will receive on acceptance, the invite token (used to resend or delete the invite), and the Unix timestamp when the invite expires. Invitations are valid for 7 days from creation and can be resent at any time to reset the expiration window. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a paginated list of pre-built designs provided by Twilio SendGrid (not the designs stored in your own Design Library — use the List Designs tool for those). Useful for finding the ID of a SendGrid pre-built design you want to duplicate and customize. Returns up to page_size results per call (default 100), plus a _metadata object with a page_token for the next page.

Retrieve your current profile details on file for your SendGrid account, including address, city, state, zip, country, company, phone, and website.

Get the number of IP addresses that can still be added to your SendGrid account during the current billing period, along with the price per additional IP. Returns a results array containing an object with remaining (how many more IPs you can add), period (the time window this limit resets on, e.g. 'month'), and price_per_ip (the current cost to add one more IP). Useful before calling IP-provisioning tools like 'Add IPs' to confirm you have headroom.

Retrieve sender reputation scores for your Subusers. A Subuser's reputation reflects how recipients and recipient mail servers have reacted to mail sent from that Subuser; bounces, spam reports, and other negative signals lower it. Use usernames to filter to a comma-separated list of specific Subuser usernames, or leave it blank to retrieve reputations for all Subusers. Note: for Regional (EU) Subusers, reputation scores do not calculate accurately due to data-residency restrictions. Returns an array of {username, reputation} objects.

Retrieve a paginated list of all Reverse DNS records created for this SendGrid account's dedicated IP addresses. Use limit to set the page size and offset to control the starting position within the list (e.g. limit=10, offset=10 requests the second page). Supports a prefix search on the ip field, e.g. '192.' to match all IPs starting with that segment. Returns an array of Reverse DNS record objects (id, ip, rdns, domain, subdomain, valid, a_record, etc.).

Retrieve all cancelled and paused scheduled send information for this account. Only returns scheduled sends that were assigned a batch_id — if a send was scheduled via the Mail Send endpoint's send_at field but without a batch_id, it will not appear here even though it is still scheduled for delivery. Assign a batch_id to any scheduled send you may need to pause or cancel in the future. Returns an array of {batch_id, status} objects.

Retrieve the full list of permission scopes (e.g. mail.send, alerts.create, alerts.read) assigned to the API key used to authenticate this request. API keys in SendGrid can be restricted to a subset of scopes; this endpoint reports exactly which scopes the calling key currently has. To inspect the scopes of a different API key, use the 'Retrieve an existing API key' tool with that key's ID instead.

Retrieve a list of SendGrid Marketing Campaigns segments (v1, legacy query-DSL segments scoped to a single parent list). Filter by ids (returns only segments with those IDs and ignores the other filters), by parent_list_ids (comma-separated list IDs; returns segments whose parent_list_id matches any of them), and/or no_parent_list_id (true to include segments with no parent list). With no filters supplied, all segments are returned. Zero matches returns HTTP 200 with an empty results array. Note: this is the legacy Segments v1 API — for segments built with the newer SQL query_dsl language, use the Segmenting Contacts V2 tools instead.

Retrieve a list of SendGrid Marketing Campaigns segments (v2, SQL-based query_dsl segments). Filter by ids (returns only segments with those IDs and ignores the other filters), by parent_list_ids (comma-separated list IDs, up to 50; returns segments whose parent list matches any of them), and/or no_parent_list_id (true to include segments with no parent list). With no filters supplied, all segments are returned. Zero matches returns HTTP 200 with an empty result set. Note: this is the Segmenting Contacts V2 (SQL query_dsl) API — for legacy segments, use the v1 Segment tools instead.

Retrieve a list of all Sender identities configured for SendGrid Marketing Campaigns single sends on this account. Each returned Sender includes its id, nickname, from/reply_to addresses, physical address, verified and locked flags, and timestamps. No parameters are required. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a list of all Sender Identities configured for SendGrid's legacy Marketing Campaigns 'Campaigns' feature on this account. Each returned Sender Identity includes its id, nickname, from/reply_to addresses, physical address, verified and locked flags, and timestamps. No parameters are required. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Get a List of All Senders', for /v3/marketing/senders). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve all of your Twilio SendGrid Marketing Campaigns Single Sends (one-time marketing email campaigns). Returns condensed details for each Single Send, including its id, name, status (draft/scheduled/triggered), categories, is_abtest, send_at, and timestamps. Use page_size and page_token to page through results when you have many Single Sends. For the full details of one Single Send (including its email_config and send_to targeting), pass its id to the Get Single Send by ID tool.

Retrieve stats for all Single Sends in this SendGrid Marketing Campaigns account. By default, all Single Sends are returned; pass a comma-separated list of Single Send IDs in singlesend_ids to scope the results (up to 25 IDs). Each result entry includes the Single Send id, ab_variation/ab_phase (for A/B tests), the aggregation period, and a stats object with counters such as delivered, opens, unique_opens, clicks, unique_clicks, bounces, spam_reports, and unsubscribes. Results are paginated: use page_size (1-50, default 25) and page_token (from the response's _metadata.next URL).

Retrieve click-tracking stats for a single Single Send's embedded links. Each result entry gives the clicked URL (including any {{custom_fields}} substitutions), its url_location (0-indexed position within the message or variation), the A/B ab_variation/ab_phase it belongs to, and the number of clicks it received. Optionally group/filter by A/B variation and/or phase. Results are paginated with page_size/page_token, and the response also includes a total_clicks count.

Retrieve a paginated list of spam reports: recipients who marked your email as spam, the Unix timestamp when they did so, and the sending IP address. Use limit to set the page size (max 500) and offset to skip past already-retrieved items for subsequent pages. Optionally filter by start_time/end_time (Unix timestamps, inclusive) or by an email address prefix/substring (supports '%25' as a wildcard, with reserved characters percent-encoded).

Retrieve all Single Sign-On (SAML) integrations configured on this Twilio SendGrid account. Each integration includes its name, enabled state, signin_url, signout_url, entity_id, id, single_signon_url, and audience_url. The returned 'id' values can be used with the other SSO Certificate and SSO Integration tools to manage this account's SAML configuration. Set include_completed_integration_field to true to also receive the completed_integration field on each integration.

Retrieve all Single Sign-On (SAML) certificates associated with a specific SSO Integration, identified by integration_id. Each returned certificate includes its numeric id, public_certificate (PEM), not_before/not_after validity as unix timestamps, and intergration_id (sic, per SendGrid's API field name). Obtain the integration_id from the 'Get All SSO Integrations' tool's response.

Retrieve global email statistics for the account across a given date range. Parent accounts see either their own aggregated stats or, when the on_behalf_of field is set, the aggregated stats of a specific Subuser; Subuser accounts always see only their own stats. Use start_date (required) and optionally end_date to bound the range, and aggregated_by to group results by day, week, or month.

Retrieve email statistics for one or more specific Subusers over a date range. subusers (required) lists which Subuser usernames to retrieve stats for — you may include up to 10. start_date (required, format YYYY-MM-DD) is the beginning of the range; end_date defaults to today. Use aggregated_by to group results by day, week, or month, and limit/offset to page through results. Returns an array of {date, stats: [{type, name, metrics: {...}}]} objects.

Retrieve the total sums of each email statistic metric across all Subusers over a given date range. start_date (required, format YYYY-MM-DD) is the beginning of the range; end_date defaults to today. Use aggregated_by to group totals by day, week, or month, sort_by_metric/sort_by_direction to sort, and limit/offset to page through results.

Retrieve the list of Subuser IDs that have been assigned the specified IP address on this SendGrid account. Use the SendGrid Subusers API separately to retrieve more details about each returned Subuser. Use after_key together with limit (maximum 100) to paginate through results — if the response's after_key is non-null, more Subusers remain to be fetched.

Retrieve your account's current settings for subscription tracking. Subscription tracking adds links to the bottom of your emails that allow recipients to subscribe to, or unsubscribe from, your emails. Returns whether the setting is enabled, the HTML/plain-text unsubscribe link content, the landing page HTML, the custom replacement tag, and the unsubscribe redirect URL.

Retrieve a paginated list of your account's Subusers. Filter to a specific Subuser with username, restrict to a region with region (all/global/eu), and include each Subuser's region in the response with include_region. Use limit to set the page size and offset to page through additional results.

Retrieve the branded link (link branding / click-tracking domain) associated with a specific subuser. Branded links can be associated with subusers from a parent account so the subuser can send mail using the parent's branded link; to associate one, the parent account must first create and validate a branded link, then assign it via the 'Associate Branded Link With Subuser' tool or the Subuser Management page of the SendGrid app.

Retrieve the Subusers that a specified Teammate can access and act on behalf of, including the scopes available for each Subuser. If the Teammate is an administrator, every Subuser on the account is returned. Use after_subuser_id (the last Subuser ID from a previous response's _metadata.next_params.after_subuser_id) together with limit to paginate through large result sets, and optionally filter to a single Subuser by username.

Retrieve SendGrid Engagement Quality (SEQ) scores for your Subusers or customer accounts for a specific date (YYYY-MM-DD, UTC). SEQ scores summarize how well an account's email program is performing, ranging from 1 (worst) to 5 (best), based on metrics like open rate, spam rate, bounce rate, bounce classification, and engagement recency. A response of HTTP 200 includes a 'result' array with one entry per Subuser/customer account belonging to the requesting parent or reseller account; the 'score' and 'metrics' fields are omitted for any account not eligible for scoring on that date. Use 'limit' and 'after_key' together to paginate through large result sets (the response's '_metadata.next_params.after_key' gives you the next after_key to request). A response of HTTP 202 means scores for the requested date aren't calculated yet — SEQ scores are computed asynchronously, so retry later.

Retrieve the monthly email statistics for a single Subuser. date (required, format YYYY-MM-DD) selects the month to report on. Optionally sort results with sort_by_metric and sort_by_direction, and page through results with limit and offset. Note: you cannot sort by bounce_drops, deferred, invalid_emails, processed, spam_report_drops, spam_reports, or unsubscribe_drops.

Retrieve a paginated list of all email addresses currently on this account's blocks suppression list. Each entry includes the email address, a created Unix timestamp, the block reason, and an SMTP status code. Use limit to set the page size (max 500, default determined by the API) and offset to page through additional results. Optionally filter by start_time/end_time (Unix timestamps bounding when the block was created) or by email (supports the '%25' wildcard, e.g. '%25market' matches any address containing 'market'). You can submit this request as one of your subusers by including their value in the on_behalf_of field.

Retrieve a paginated list of all email addresses currently on this account's bounces suppression list. Each entry includes the bounced email address, a created Unix timestamp, the bounce reason (typically a bounce code, enhanced code, and description), and an enhanced SMTP status. Use limit to set the page size (max 500) and offset to page through additional results. Optionally filter by start_time/end_time (Unix timestamps bounding when the bounce was created) or by email (supports the '%25' wildcard, e.g. '%25market' matches any address containing 'market'). You can submit this request as one of your subusers by including their value in the on_behalf_of field.

Retrieve the total number of bounces by classification (e.g. Content, Invalid Address, Mailbox Unavailable, Reputation, Technical Failure, Unclassified, Frequency or Volume Too High), broken down per day and returned in descending order for each day. Optionally bound the range with start_date/end_date (YYYY-MM-DD format). Set response_format to 'text/csv' to receive the data as CSV instead of the default JSON object. You can submit this request as one of your subusers by including their value in the on_behalf_of field.

Retrieve all suppressed email addresses that belong to a given unsubscribe/suppression (ASM) group. Returns a simple array of email address strings. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a paginated list of all current Teammates on your SendGrid account, including each teammate's username, name, email, user_type (admin, owner, or teammate), admin flag, and contact details (phone, website, address, city, state, zip, country). Use limit to set the page size (max 500, defaults to 500) and offset to skip past already-retrieved items for subsequent pages. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve the account's current legacy email template mail setting: whether it is enabled, and the wrapper HTML content (containing the '<% body %>' placeholder token) used to wrap outgoing email bodies. This refers to SendGrid's original (legacy) email templates; Dynamic Transactional Templates are now recommended for most use cases. Returns an object with 'enabled' (boolean) and 'html_content' (string).

Retrieve a paged list of transactional templates in your SendGrid account, including each template's versions. Filter by generation ('legacy', 'dynamic', or 'legacy,dynamic' for both) and control page length with page_size (1-200, required). Use page_token (taken from the previous response's _metadata.next or _metadata.prev URL) to move between pages. Returns a 'result' array of template objects plus a '_metadata' object describing pagination (self/next/prev URLs and total count). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve a list of all tracking settings on the account (open tracking, click tracking, subscription tracking, and Google Analytics tracking). Each entry includes the setting's short name (e.g. 'open', 'click'), a human-readable title, a description of what it tracks, and whether it is currently enabled. Use the 'Get Click Tracking Settings', 'Get Open Tracking Settings', or 'Get Google Analytics Settings' tools to retrieve and update the full detail of an individual setting. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Retrieve your current SendGrid account username and its associated numeric user ID.

Retrieve all the Sender Identities (verified and unverified) associated with your SendGrid account. Use limit to cap the number of results returned; use last_seen_id to page through results (returns senders with an ID occurring after the given value); use id to retrieve information about only one specific Sender Identity. Returns a 'results' array of Sender Identity objects, each including id, nickname, from_email, from_name, reply_to, reply_to_name, address, city, state, zip, country, verified, and locked.

Retrieve a list of domains known to implement DMARC, categorized by failure type: hard failures (mail will not be delivered when the domain is used as a Sender Identity, e.g. yahoo.com) and soft failures (mail may sometimes be rejected, e.g. gmail.com). Use this to check whether a domain you're about to use as a Sender Identity is likely to have deliverability problems due to its DMARC policy. Returns a 'results' object with 'soft_failures' and 'hard_failures' string arrays.

Determine which of SendGrid's sender verification processes have been completed for this account. Returns a 'results' object with two booleans: 'domain_verified' (Domain Authentication completed) and 'sender_verified' (Single Sender Verification completed). An account may have one, both, or neither completed. If neither is complete, sending may be restricted until you authenticate a domain or verify a single sender.

Retrieve all of your account's IP addresses that are currently in warmup mode. Each result includes the IP address and the Unix timestamp when it entered warmup mode. Use Get Warm Up IP to check a single IP, or Stop IP Warm Up to remove one from warmup mode.

Search SendGrid Marketing Contacts using a Segmentation Query Language (SGQL) query string. Returns only the first 50 contacts that match the search criteria, along with a contact_count of the total number matched. Because contact emails are stored in lower case, comparing by email in your query requires the email in the query to be lower case (use SGQL's lower() function if needed). If the query takes longer than 20 seconds, a 408 Request Timeout status is returned. Use the Get Contacts by Emails or Get Contacts by Identifiers tools instead when you have exact values and don't need SGQL filtering. Example query: "email LIKE 'jane%' AND CONTAINS(list_ids, 'e2f2f214-6c17-4562-add9-4a4b41ea6d90')".

Search recipients in SendGrid's legacy Marketing Campaigns contact database (contactdb) using the same condition structure as segments, without creating a saved segment. Provide 'list_id' to scope the search to one list, and 'conditions' (field, value, operator, and_or) to filter — valid operators depend on field type: dates support eq/ne/lt(before)/gt(after)/empty/not_empty; text supports contains/eq/ne/empty/not_empty; numbers support eq/lt/gt/empty/not_empty; email clicks/opens (field 'clicks.campaign_identifier' or 'opens.campaign_identifier') support eq(opened)/ne(not opened). The first condition must have and_or of '' and every subsequent condition must specify 'and' or 'or'. All condition values must be strings. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Search Contacts', for /v3/marketing/contacts/search). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Search SendGrid's legacy Marketing Campaigns contact database (contactdb) for recipients matching one or more exact field=value pairs passed directly as the request's query string, e.g. GET /v3/contactdb/recipients/search?first_name=John. Field names can be reserved fields (first_name, last_name, email, etc.) or any custom field defined on this account. This is distinct from the sendgrid_search_contactdb_recipient tool, which requires 'list_id' and a structured 'conditions' array and cannot express a simple exact-match lookup. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Search Contacts', for /v3/marketing/contacts/search). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Search your Twilio SendGrid Marketing Campaigns Single Sends by any combination of name (leading/trailing wildcard match), status, and categories. For example, to find all Single Sends that are drafts or scheduled AND associated with the category 'shoes', set status to ["draft", "scheduled"] and categories to ["shoes"]. All fields are optional filters — omit a field to not filter on it. Use page_size and page_token to page through results. Returns condensed details for each matching Single Send, the same shape as the Get All Single Sends tool.

Search an unsubscribe/suppression (ASM) group for multiple suppressed email addresses at once. Given a group_id and a list of candidate email addresses, this read-only lookup (implemented as a POST with a search body) returns only the subset of those addresses that are actually unsubscribed from the given group. Useful for checking suppression status of many recipients before sending a campaign. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

Verify a pending Sender Identity using the verification token SendGrid generated and included in the verification email sent to the address pending verification. Completing this marks the Sender Identity as verified. Returns an empty body on success (HTTP 204). The token is single-use and tied to a specific Sender Identity; it cannot be looked up separately from the verification email.

Activate a specific version of a transactional template in SendGrid, identified by the parent template_id and the version_id. Activating a version deactivates any other currently active version for the same template, since only one version can be active at a time. Safe to re-run: activating an already-active version produces the same end state. Obtain the template_id and version_id from the 'List Templates', 'Get Template', or 'Create Template Version' tool. Returns the activated version object, including any warnings about the template. You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

• Idempotent

Provision new IP address(es) to a specific Twilio SendGrid sub-account (via the Partners/Accounts provisioning API). Requires a count (how many IPs to add, maximum 10 per request) and a region (all IPs added in one request must be from the same region: eu or us). Returns the list of newly assigned IP addresses and the region they belong to.

Add one or more recipients to SendGrid's legacy Marketing Campaigns contact database (contactdb), or update them if a recipient with the same email already exists. Each recipient object must include 'email'; you can also set 'first_name', 'last_name', and any of your own custom field names as additional keys on the same object — unlike the 'first_name'/'last_name' shown here, arbitrary custom field keys are NOT declared individually by this tool's schema, so add them directly by name. Rate limit: 3 requests per 2 seconds, up to 1000 recipients per request (so up to 1500/second sustained). This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Add or Update a Contact', for /v3/marketing/contacts). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

• Idempotent

Create a new External Integration for forwarding SendGrid email events to a third-party destination (currently only 'Segment' is supported). Requires destination, filters (which SendGrid email events to forward), and properties (the destination-specific connection details — for Segment, write_key and destination_region). Each destination has a maximum number of allowed Integration instances per user (e.g. up to 10 Segment Integrations). Returns the created Integration, including its generated integration_id.

Add a Twilio SendGrid IP address to this account. You must specify whether the IP should automatically warm up (is_auto_warmup) and whether a parent account is able to send email from it (is_parent_assigned). Optionally assign up to 100 Subuser IDs to the IP at creation time, choose its region (eu or us), and request that the response include region information. Returns the newly added IP's details on success (HTTP 201). This does not return Subuser assignment details for existing IPs — use the "Get a List of Subusers Assigned to an IP" tool for that.

Add new dedicated IP address(es) to your Twilio SendGrid account. Specify how many IPs to purchase/add (count), optionally assign the new IPs to specific subusers, and optionally start them in warmup mode. Returns the list of added IPs (each with any assigned subusers), the number of IPs remaining that can still be added to the account, and whether the IPs are in warmup.

Add one or more IP addresses to this SendGrid account's access allow list, granting them permission to access the account through the User Interface or API. Pass an array of objects, each with an "ip" field (a plain IP, a CIDR range like 192.168.1.0/24, or a wildcard like 192.*.*.*). Once added, each IP is assigned a numeric id (returned in the response) that can later be used to remove it via the Get/Delete Allowed IP tools. Returns HTTP 201 with the created allow-list entries, including their ids and created_at/updated_at timestamps.

Add an IP address to an existing authenticated domain in SendGrid, identified by domain_id. This is used to manually specify additional IP addresses for a domain's custom SPF record (relevant when the domain uses manual security with custom_spf enabled). Returns the updated authenticated domain object, including its full list of associated IPs.

Add a single IP address to an existing IP pool on this SendGrid account. The same IP address can be added to multiple pools. It may take up to 60 seconds for the IP to actually appear in the pool after this call succeeds. Before adding an IP to a pool, it must already be activated for sending in the SendGrid dashboard (Settings > IP Addresses > Edit > 'Allow my account to send mail using this IP address'). Use the 'List IP Addresses' tool to see all available IPs on the account.

Append a batch of IP addresses to an existing SendGrid IP Pool by pool ID. This operation requires all IP assignments in the batch to succeed; if any single IP fails to be assigned (e.g., it doesn't exist on the account or is already in the pool), the entire call returns an error and none of the IPs are added. Returns the pool's name, id, and full list of assigned IPs on success.

Add a single existing recipient to a list in SendGrid's legacy Marketing Campaigns contact database (contactdb). The recipient must already exist in your contactdb; use the 'Add recipients' tool first if they don't. No request body is needed. Obtain list_id from the 'Retrieve all lists' tool and recipient_id from the 'Retrieve recipients' tool. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Add a Contact to a List', for /v3/marketing/lists). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

• Idempotent

Add multiple existing recipients to a list in SendGrid's legacy Marketing Campaigns contact database (contactdb), by their recipient IDs (base64-encoded email addresses — pass them exactly as returned from recipient endpoints). The recipients must already exist in your contactdb; use the 'Add recipients' tool first if they don't. Obtain list_id from the 'Retrieve all lists' tool and recipient_ids from the 'Retrieve recipients' tool. This is part of SendGrid's legacy Marketing Campaigns API (Contact DB / Campaigns). It remains fully operational, but SendGrid recommends new integrations use the current Marketing Campaigns tool instead ('Add Multiple Contacts to a List', for /v3/marketing/lists). You can submit this request as one of your subusers by including their ID in the on_behalf_of field.

• Idempotent

Append a batch of Subuser IDs to a specified IP address on this SendGrid account. This operation requires all Subuser assignments in the batch to succeed — if any single assignment fails, the whole request returns an error and no changes are made. Returns the IP address and the array of Subuser IDs that were assigned.

Add one or more email addresses to an unsubscribe/suppression (ASM) group, so that future sends associated with that group will skip these recipients. If group_id refers to a group that has been deleted or does not exist, the supplied addresses are added to the global suppressions list instead. You can submit this request as one of your subusers by including their ID in the on_behalf_of field. Returns the recipient_emails that were added (HTTP 201).

Associate (assign) an already-authenticated and validated branded link owned by a parent account with a single subuser, so the subuser can send mail using the parent's branded link for click-tracking. The parent account must first create the branded link and validate it before it can be associated. Once associated, the subuser will use the parent's branded link but will not be able to see or modify it (unless the subuser separately creates their own branded link). Returns the branded link object now associated with the subuser.

Associate (assign) an already-authenticated domain owned by a parent account with a single subuser, so the subuser can send mail using the parent's domain. The parent account must first authenticate and validate the domain before it can be associated. The subuser will default to using the assigned domain but will not be able to see or modify it (unless the subuser separately authenticates their own domain, which overrides the assignment). To associate more than one domain with a subuser, use the 'Associate Subuser With Domain (Multiple)' tool instead. Returns the authenticated domain object now associated with the subuser.