SendGrid

Send a transactional email through SendGrid. ⚠️ This sends real email to real recipients immediately (or at send_at). There is no undo. Confirm the recipient list with the user before calling. The sender address must already be a verified sender identity or belong to an authenticated domain — otherwise SendGrid rejects the request with a 403. Args: - personalizations (array, required): One entry per recipient group, each with to/cc/bcc, and optionally its own subject and dynamic_template_data - from (object, required): {email, name?} - subject (string): Default subject when a personalization omits one - content (array): Body blocks [{type, value}], plain text first. Omit when using template_id. - template_id (string): Dynamic template ID ('d-...'); supplies the body instead of content - reply_to (object): {email, name?} - categories (string[]): Up to 10 tags for stats grouping - custom_args (object): Key/values echoed on event webhooks - send_at (number): Unix timestamp, up to 72 hours out - asm_group_id (number): Unsubscribe group - response_format ('markdown' | 'json') Returns: Confirmation with the X-Message-Id assigned by SendGrid, which is the ID to use with sendgrid_get_message_details and to correlate event webhooks. Examples: - Plain email: {"from": {"email": "me@example.com"}, "personalizations": [{"to": [{"email": "you@example.com"}]}], "subject": "Hello", "content": [{"type": "text/plain", "value": "Hi there"}]} - Dynamic template: {"from": {"email": "me@example.com"}, "template_id": "d-abc123", "personalizations": [{"to": [{"email": "you@example.com"}], "dynamic_template_data": {"first_name": "Ada"}}]} Error Handling: - 400 if neither content nor template_id is supplied - 403 if the from address is not a verified sender

List marketing contact lists. Contact lists are static groupings of contacts, as opposed to segments, which are query-driven and refresh automatically. Args: - page_size (number): Results per page (1-100, default: 20) - page_token (string): Cursor from a previous response's next_page_token - response_format ('markdown' | 'json') Returns: Lists with id, name, and contact_count, plus next_page_token when more pages exist.

Create a new marketing contact list. Args: - name (string, required): List name, must be unique within the account - response_format ('markdown' | 'json') Returns: The new list's id, which you then pass to sendgrid_upsert_contacts to populate it.

Rename an existing marketing contact list. Args: - list_id (string, required) - name (string, required): The new name - response_format ('markdown' | 'json')

Delete a marketing contact list. ⚠️ Destructive and not reversible. By default only the list itself is removed and its contacts remain in the account. Pass delete_contacts=true to also delete every contact that belongs to it — that removes those contacts from ALL lists and from the account entirely. Args: - list_id (string, required) - delete_contacts (boolean, default false): Also delete the contacts on the list - response_format ('markdown' | 'json')

List contacts in the account (a sample of up to 50, newest first). SendGrid's contacts endpoint is not a full paginated export — for anything targeted, use sendgrid_search_contacts with a query instead. Args: - response_format ('markdown' | 'json') Returns: Contacts with id, email, names, and the lists each belongs to, plus the account's total contact_count.

Retrieve a single contact by its SendGrid contact ID. If you have an email address rather than an ID, use sendgrid_search_contacts_by_email instead. Args: - contact_id (string, required) - response_format ('markdown' | 'json') Error Handling: - Returns NOT_FOUND if the contact ID doesn't exist

Create or update contacts, optionally adding them to lists. This is an upsert keyed on email: an existing contact with the same address is updated in place rather than duplicated, and fields you omit keep their current values. The operation is ASYNCHRONOUS. Success returns a job_id, not the contacts — they typically appear within a few seconds. Verify with sendgrid_search_contacts_by_email rather than assuming immediate availability. Args: - contacts (array, required): Up to 30,000 contacts. Each needs at least an email. - list_ids (string[]): Lists to add these contacts to - response_format ('markdown' | 'json') Examples: - Single contact: {"contacts": [{"email": "ada@example.com", "first_name": "Ada"}]} - Onto a list: {"contacts": [{"email": "ada@example.com"}], "list_ids": ["abc-123"]} - With custom fields: {"contacts": [{"email": "ada@example.com", "custom_fields": {"e1_T": "enterprise"}}]} Error Handling: - 400 if a custom field key isn't a valid field ID — check sendgrid_list_custom_fields

Permanently delete contacts from the account. ⚠️ Destructive and not reversible. This removes the contacts from every list and from the account. To take contacts off one list while keeping them, use sendgrid_remove_contacts_from_list instead. Args: - contact_ids (string[]): Contact IDs to delete. Required unless delete_all_contacts is true. - delete_all_contacts (boolean, default false): Delete EVERY contact in the account - response_format ('markdown' | 'json')

Remove contacts from one list without deleting them. The contacts stay in the account and on any other lists. Use this rather than sendgrid_delete_contacts when you only want to change list membership. Args: - list_id (string, required) - contact_ids (string[], required): Up to 100 contact IDs - response_format ('markdown' | 'json')

Search contacts with a SendGrid SGQL query. SGQL is SQL-like and runs against the contacts table. String comparisons are case-sensitive, and the query is limited to 50 results. Args: - query (string, required): SGQL WHERE-clause expression - response_format ('markdown' | 'json') Examples: - By domain: {"query": "email LIKE '%@example.com'"} - By field: {"query": "first_name = 'Ada'"} - Recently added: {"query": "created_at > TIMESTAMP '2026-01-01T00:00:00Z'"} - On a list: {"query": "CONTAINS(list_ids, 'abc-123')"} Error Handling: - 400 if the SGQL is malformed; the message names the offending token

Look up contacts by exact email address. This is the fastest way to turn an email address into a contact ID, and the right way to confirm that a sendgrid_upsert_contacts job has landed. Args: - emails (string[], required): Up to 50 exact addresses - response_format ('markdown' | 'json') Returns: A result keyed by email. Addresses with no matching contact come back under errors rather than causing the call to fail.

List contact segments (Segments 2.0). Segments are defined by an SGQL query and refresh automatically, unlike lists, which hold a fixed membership. Args: - parent_list_ids (string[]): Only return segments built on these lists - response_format ('markdown' | 'json')

Retrieve one segment, including its SGQL query definition and current contact count. Args: - segment_id (string, required) - contacts_sample (boolean, default false): Include a sample of matching contacts - response_format ('markdown' | 'json')

Create a contact segment from an SGQL query. The segment refreshes on its own as contacts change, so it always reflects who currently matches the query. Args: - name (string, required): Segment name - query_dsl (string, required): SGQL query defining membership - parent_list_ids (string[]): Restrict the segment to these lists. Omit to query all contacts. - response_format ('markdown' | 'json') Examples: - Engaged users: {"name": "Recent openers", "query_dsl": "last_opened > TIMESTAMP '2026-08-01T00:00:00Z'"} - Domain segment: {"name": "Example.com", "query_dsl": "email LIKE '%@example.com'"}

Update a segment's name and/or its SGQL query. Changing query_dsl re-evaluates membership, so contacts can enter or leave the segment immediately. Args: - segment_id (string, required) - name (string): New name - query_dsl (string): New SGQL query - response_format ('markdown' | 'json')

Delete a contact segment. ⚠️ Destructive and not reversible. Only the segment definition is removed — the contacts it matched are not deleted. Args: - segment_id (string, required) - response_format ('markdown' | 'json')

List custom and reserved contact field definitions. Call this before writing custom_fields on a contact — the keys in that object are field IDs (like 'e1_T'), not the field names. Args: - response_format ('markdown' | 'json')

Define a new custom contact field. The field type is fixed at creation and cannot be changed later — only the name can be updated. Args: - name (string, required): Field name (letters, numbers, underscores) - field_type ('Text' | 'Number' | 'Date', required) - response_format ('markdown' | 'json') Returns: The field's generated id, which is the key to use in a contact's custom_fields object.

Rename a custom contact field. The field's type cannot be changed. Args: - field_id (string, required) - name (string, required): New field name - response_format ('markdown' | 'json')

Delete a custom contact field definition. ⚠️ Destructive and not reversible. The stored values for this field are removed from every contact. Args: - field_id (string, required) - response_format ('markdown' | 'json')

List verified sender identities. Marketing campaigns can only be sent from a verified sender. Check the 'verified' flag on each result — an unverified sender will be rejected at send time. Args: - response_format ('markdown' | 'json')

Create a sender identity. SendGrid emails the 'from' address a verification link; the sender cannot be used until someone clicks it. A physical mailing address is legally required on marketing mail (CAN-SPAM), which is why the address fields are mandatory. Args: - nickname (string, required): Internal label for this identity - from (object, required): {email, name} the mail is sent from - reply_to (object, required): {email, name} replies go to - address (string, required), city (string, required), country (string, required) - address_2, state, zip (string, optional) - response_format ('markdown' | 'json')

Delete a sender identity. ⚠️ Destructive and not reversible. Campaigns still referencing this sender will fail to send. Args: - sender_id (string, required) - response_format ('markdown' | 'json')

List dynamic email templates. Args: - page_size (number): Results per page (1-200, default: 50) - page_token (string): Cursor from a previous response - generations ('legacy' | 'dynamic' | 'legacy,dynamic'): Template engine. Defaults to 'dynamic' (Handlebars), which is what new templates use. - response_format ('markdown' | 'json') Returns: Templates with id, name, and their versions (including which one is active).

Retrieve one template with all of its versions. The response includes each version's HTML content and subject, and flags which version is active. Args: - template_id (string, required): Template ID (starts with 'd-' for dynamic templates) - response_format ('markdown' | 'json')

Create an empty template container. A template on its own has no content and cannot be sent. Follow this with sendgrid_create_template_version (active=1) to give it HTML and a subject. Args: - name (string, required): Template name - generation ('dynamic' | 'legacy', default 'dynamic'): Use 'dynamic' for Handlebars templates - response_format ('markdown' | 'json')

Rename a template. To change its content, update a version instead. Args: - template_id (string, required) - name (string, required): New name - response_format ('markdown' | 'json')

Delete a template and all of its versions. ⚠️ Destructive and not reversible. Any mail send or campaign referencing this template_id will start failing. Args: - template_id (string, required) - response_format ('markdown' | 'json')

Add a version (the actual content) to a template. Setting active=1 makes this the version that sends, and deactivates the previous one — that is how you publish new content. In dynamic templates, use Handlebars placeholders like {{first_name}} in the subject and HTML; supply their values through dynamic_template_data when sending. Args: - template_id (string, required) - name (string, required): Version name - subject (string, required): Subject line; may contain Handlebars placeholders - html_content (string): HTML body - plain_content (string): Plain-text body. If omitted, SendGrid generates it from the HTML. - active (0 | 1, default 1): Whether this version becomes the live one - response_format ('markdown' | 'json') Examples: - {"template_id": "d-abc", "name": "v1", "subject": "Welcome {{first_name}}!", "html_content": "<p>Hi {{first_name}}</p>"}

Retrieve one template version, including its full HTML and subject. Args: - template_id (string, required) - version_id (string, required) - response_format ('markdown' | 'json')

Update a template version's content, subject, name, or active flag. Editing the active version changes what goes out on the very next send, with no separate publish step. Setting active=1 on a different version switches which one is live. Args: - template_id (string, required), version_id (string, required) - name, subject, html_content, plain_content (string, optional) - active (0 | 1, optional) - response_format ('markdown' | 'json')

Delete one version of a template. ⚠️ Destructive and not reversible. Deleting the active version leaves the template with no live content until another is activated. Args: - template_id (string, required), version_id (string, required) - response_format ('markdown' | 'json')

List Single Send campaigns. Args: - page_size (number): Results per page (1-100, default: 20) - page_token (string): Cursor from a previous response - status ('draft' | 'scheduled' | 'triggered'): Filter by campaign status - response_format ('markdown' | 'json') Returns: Campaigns with id, name, status, and send/schedule timestamps.

Retrieve one Single Send campaign, including its content, sender, and list/segment targeting. Args: - singlesend_id (string, required) - response_format ('markdown' | 'json')

Get performance statistics for specific Single Send campaigns. Returns per-campaign delivery and engagement metrics (delivered, opens, clicks, bounces, unsubscribes), which is how you compare how individual campaigns performed. Args: - singlesend_ids (string[], required): Up to 50 campaign IDs - aggregated_by ('day' | 'week' | 'total', default 'total') - page_size (number): Results per page (1-100, default: 50) - response_format ('markdown' | 'json')

Schedule a Single Send campaign to go out, or send it immediately. ⚠️ This sends real marketing email to every contact on the campaign's lists and segments. Confirm the campaign and its audience with the user before calling — pass send_at "now" only when they've explicitly asked to send immediately. The campaign must already be a complete draft (sender, subject, content and audience set); this only schedules it. Args: - singlesend_id (string, required) - send_at (string, required): ISO 8601 timestamp (e.g. "2026-09-15T14:00:00Z"), or the literal "now" - response_format ('markdown' | 'json') Error Handling: - 400 if the campaign is an incomplete draft or the timestamp is in the past

Get overall email performance statistics for the account. Returns the core deliverability metrics — requests, delivered, opens, unique_opens, clicks, unique_clicks, bounces, blocks, spam_reports and unsubscribes — rolled up by day, week or month. Note that open tracking undercounts: recipients with images disabled, and Apple Mail Privacy Protection, both distort open rates. Click metrics are more reliable. Args: - start_date (string, required): YYYY-MM-DD, up to 13 months back - end_date (string): YYYY-MM-DD, defaults to today - aggregated_by ('day' | 'week' | 'month', default 'day') - response_format ('markdown' | 'json') Examples: - Last month by day: {"start_date": "2026-08-01", "end_date": "2026-08-31"} - Yearly trend: {"start_date": "2026-01-01", "aggregated_by": "month"}

Break email statistics down by browser, client type, device type, country, or mailbox provider. Use this to answer questions like "which mailbox providers are bouncing us?" or "how much of our audience reads on mobile?". Args: - dimension ('browser' | 'client_type' | 'device_type' | 'country' | 'mailbox_provider', required) - start_date (string, required): YYYY-MM-DD - end_date (string): YYYY-MM-DD, defaults to today - aggregated_by ('day' | 'week' | 'month', default 'day') - filters (string[]): Restrict to specific values, e.g. ["Gmail", "Yahoo"] for mailbox_provider or ["US", "CA"] for country - response_format ('markdown' | 'json') Examples: - Provider deliverability: {"dimension": "mailbox_provider", "start_date": "2026-08-01"} - Mobile vs desktop: {"dimension": "device_type", "start_date": "2026-08-01", "aggregated_by": "month"} - Specific countries: {"dimension": "country", "start_date": "2026-08-01", "filters": ["US", "GB"]}

Get statistics for specific email categories. Categories are the tags attached at send time (the 'categories' argument of sendgrid_send_mail), which makes this the way to compare the performance of different mail streams — receipts vs. newsletters, for instance. Args: - categories (string[], required): Up to 10 category names - start_date (string, required): YYYY-MM-DD - end_date (string): YYYY-MM-DD, defaults to today - aggregated_by ('day' | 'week' | 'month', default 'day') - response_format ('markdown' | 'json') Examples: - {"categories": ["welcome", "receipt"], "start_date": "2026-08-01", "aggregated_by": "week"}

Get a combined performance overview in one call. Fetches global stats plus the country, mailbox-provider and device-type breakdowns together, which is the usual starting point for "how is our email doing?" — it avoids four separate round trips. Because it merges four datasets, prefer a month-or-longer window aggregated by week or month; a long daily window can be truncated. Args: - start_date (string, required): YYYY-MM-DD - end_date (string): YYYY-MM-DD, defaults to today - aggregated_by ('day' | 'week' | 'month', default 'week') - response_format ('markdown' | 'json')

List unsubscribe groups (also called ASM groups). Unsubscribe groups let recipients opt out of one kind of mail — say, newsletters — without suppressing everything you send them. Pass a group's ID as asm_group_id on sendgrid_send_mail to associate a message with it. Args: - response_format ('markdown' | 'json')

Retrieve one unsubscribe group, including how many addresses have opted out of it. Args: - group_id (string | number, required) - response_format ('markdown' | 'json')

Create an unsubscribe group. The name and description are shown to recipients on the unsubscribe preferences page, so write them for that audience. Args: - name (string, required): Shown on the preferences page (max 30 chars) - description (string, required): Explains what this group sends (max 100 chars) - is_default (boolean, default false): Preselect this group on the preferences page - response_format ('markdown' | 'json')

Update an unsubscribe group's name, description, or default flag. Args: - group_id (string | number, required) - name (string, max 30), description (string, max 100), is_default (boolean) — at least one required - response_format ('markdown' | 'json')

Delete an unsubscribe group. ⚠️ Destructive and not reversible. The opt-outs recorded against this group are discarded, so recipients who unsubscribed from it are no longer suppressed. Any mail configured with this asm_group_id will fail. Args: - group_id (string | number, required) - response_format ('markdown' | 'json')

List the email addresses that have unsubscribed from one group. Args: - group_id (string | number, required) - response_format ('markdown' | 'json')

Add email addresses to an unsubscribe group — i.e. opt them out of that kind of mail. SendGrid will stop delivering mail associated with this group to these addresses. Args: - group_id (string | number, required) - emails (string[], required): Addresses to suppress - response_format ('markdown' | 'json')

Remove one address from an unsubscribe group, re-enabling that mail for them. ⚠️ This resubscribes someone who chose to opt out. Only do it on the recipient's explicit request — sending to a recipient who unsubscribed is a compliance problem, not just a deliverability one. Args: - group_id (string | number, required) - email (string, required) - response_format ('markdown' | 'json')

List globally unsubscribed addresses. A global unsubscribe blocks ALL mail from the account to that address, regardless of unsubscribe group. Args: - start_time (number): Unix timestamp lower bound - end_time (number): Unix timestamp upper bound - limit (number, default 20), offset (number, default 0) - response_format ('markdown' | 'json')

Globally suppress email addresses. This blocks ALL mail from the account to these addresses — transactional included. It is the strongest suppression available, so prefer an unsubscribe group when the recipient only wants to opt out of one kind of mail. Args: - emails (string[], required): Addresses to globally suppress - response_format ('markdown' | 'json')

Remove an address from the global unsubscribe list, re-enabling all mail to it. ⚠️ This resubscribes someone who opted out of everything. Only do it on the recipient's explicit request. Args: - email (string, required) - response_format ('markdown' | 'json')

List entries on one of SendGrid's automatic suppression lists. These are populated by SendGrid itself, not by you: - bounces: the receiving server rejected the message (a hard bounce means the address is bad) - blocks: the receiving server refused it for reputation or content reasons - spam_reports: the recipient hit "report spam" - invalid_emails: the address is malformed or the domain doesn't exist This is the first place to look when someone says a message never arrived. Args: - list ('bounces' | 'blocks' | 'spam_reports' | 'invalid_emails', required) - start_time (number): Unix timestamp lower bound - end_time (number): Unix timestamp upper bound - limit (number, default 20), offset (number, default 0) - response_format ('markdown' | 'json') Examples: - Recent bounces: {"list": "bounces", "limit": 50} - Why didn't it arrive: {"list": "blocks"}

Remove one address from a bounce, block, spam-report or invalid-email list. ⚠️ Destructive. SendGrid suppressed this address for a reason, and removing the entry re-enables sending to it. Doing that for a hard bounce or spam report damages sender reputation — only clear an entry when the underlying cause is genuinely fixed (a mailbox that was full, a domain that was misconfigured). Args: - list ('bounces' | 'blocks' | 'spam_reports' | 'invalid_emails', required) - email (string, required) - response_format ('markdown' | 'json')

Search the Email Activity feed for individual messages and what happened to them. This is the tool for "did my email actually arrive?". It covers the last 30 days and shows per-message status (processed, delivered, bounced, opened, clicked, dropped). Requires the Email Activity feature on the account — without it SendGrid returns 403, and a plan upgrade is the only fix. The query uses SendGrid's filter syntax: field comparisons combined with AND/OR, with string literals in double quotes. Args: - query (string, required): Activity filter expression - limit (number): Max messages to return (1-1000, default: 20) - response_format ('markdown' | 'json') Examples: - One recipient: {"query": "to_email=\"ada@example.com\""} - Recent bounces: {"query": "status=\"bounce\""} - Subject match: {"query": "subject LIKE \"%invoice%\""} - Combined: {"query": "to_email=\"ada@example.com\" AND status=\"delivered\""} Error Handling: - 403 if Email Activity isn't enabled on the plan

Get the full event timeline for a single message. Returns every event SendGrid recorded for it — processed, delivered, deferred, bounced, opened, clicked — with timestamps and the receiving server's response. Use this after sendgrid_search_email_activity narrows things down to one message. Args: - message_id (string, required): The msg_id from a search result, or the X-Message-Id returned by sendgrid_send_mail - response_format ('markdown' | 'json')

Validate an email address before sending to it. Returns a verdict (Valid / Risky / Invalid), a 0-1 score, and checks on the domain, MX records and whether the address looks disposable or role-based. Screening addresses at signup is the cheapest way to protect sender reputation. This is a paid add-on billed per validation and requires a dedicated Email Validation API key — it returns 403 on accounts without it. Args: - email (string, required): Address to validate - source (string): Label recording where the address came from, e.g. "signup_form" - response_format ('markdown' | 'json') Error Handling: - 403 if Email Validation isn't provisioned on the account or the key lacks the scope

List the permission scopes granted to the API key in use. Run this first when a tool fails with a 403 — it shows whether the key simply lacks the required permission, which is the usual cause. Args: - response_format ('markdown' | 'json')