SendGrid

Email delivery. Send now or on a schedule, build dynamic templates, verify senders, keep marketing lists, and read delivery stats.

Measured routing accuracy

80 golden cases replayed through the router over the whole index: measured over corpus ea4f12ad2948 (65 toolkits, 2283 tools indexed and 13 declared uncallable), 40 cases written by hand and 40 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. just eval-live measures the same cases through the live reranker.

Authentication

Connect an entity with ConnectionsService.InitiateConnection, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

api_key

Submit the key with ConnectionsService rather than putting it in a request; it is sealed at rest and never returned.

Tools

40 action tools. The catalog-wide slug is sendgrid.<tool>, which is what search_tools returns and call_tool takes.

sendgrid.send_email

Send a transactional email through SendGrid right now, as raw text/HTML or rendered from a dynamic template. Use when the user wants to send, email, deliver, or mail someone directly. Pass send_at to schedule it ahead instead, and batch_id (from create_mail_batch_id) to keep the option to pause or cancel it before it goes out. Distinct from create_single_send, which is a marketing campaign to a list rather than one message.

Class write (writes, no confirmation needed). Scopes mail.send. Calls POST /v3/mail/send.

Arguments:

Also retrieved by: "shoot someone an email right now", "fire off a message to this address", "get this out to the customer immediately", "mail someone through sendgrid", "render a template and email it to someone".

sendgrid.create_mail_batch_id

Create a new SendGrid batch id for grouping scheduled sends, so a future message (or group of them sharing this batch_id) can be paused or canceled with pause_scheduled_send or cancel_scheduled_send before it goes out. Call this before send_email when the user wants the option to stop a scheduled message later.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/mail/batch.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "set up a group id so I can pull this back later", "give me a handle to cancel these messages if needed", "start a batch I can hold before it goes out".

sendgrid.list_scheduled_sends

List every SendGrid batch id currently paused or canceled, with its status. Use to check what scheduled mail is currently held back from sending.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/user/scheduled_sends.

Takes no arguments.

Also retrieved by: "what's queued up and held back from going out", "show every batch that's currently paused", "what mail is on ice right now".

sendgrid.pause_scheduled_send

Pause a scheduled SendGrid batch so it stops short of sending, without discarding it. Use resume_scheduled_send to let it go out again, or cancel_scheduled_send to stop it for good.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/user/scheduled_sends.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "put this queued batch on hold", "freeze that scheduled mail for now", "don't let this batch go out yet, but don't kill it".

sendgrid.cancel_scheduled_send

Permanently cancel a scheduled SendGrid batch. Use when the user wants to stop, cancel, or kill a scheduled send for good, not just hold it (that's pause_scheduled_send). Once canceled a batch cannot be resumed.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls POST /v3/user/scheduled_sends.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "stop this batch from ever going out", "kill the scheduled mail for good", "pull the plug on that queued send permanently".

sendgrid.resume_scheduled_send

Remove the pause or cancel status from a SendGrid batch, letting it send normally again at its original send_at time. Use when the user changes their mind about a held or canceled scheduled send.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls DELETE /v3/user/scheduled_sends/{{params.batch_id}}.

Arguments:

Also retrieved by: "let that held batch go out after all", "take the hold off and let it send", "never mind, let the queued mail through".

sendgrid.list_api_keys

List every SendGrid API key on the account by id and name (not the key value; SendGrid never returns that again after creation). Use to audit what programmatic access exists.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/api_keys.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what programmatic keys exist on this account", "show every credential set up for automation", "audit access to the sending account".

sendgrid.create_api_key

Create a new SendGrid API key with a name and a set of permission scopes. Its secret value is returned exactly once, in this response, and can never be retrieved again.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/api_keys.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "set up a new key for our deploy bot", "mint a fresh credential with limited access", "give the ci pipeline its own key".

sendgrid.get_api_key

Look up one SendGrid API key's name and granted scopes by its id.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/api_keys/{{params.api_key_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what permissions does this credential have", "check what one key is scoped to do", "look up the details behind this credential".

sendgrid.update_api_key

Rename a SendGrid API key and replace its granted scopes entirely.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls PUT /v3/api_keys/{{params.api_key_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "rename this credential and tighten its scopes", "change what this key is allowed to do", "narrow down what this credential can access".

sendgrid.delete_api_key

Permanently revoke a SendGrid API key. Use when the user wants to delete, revoke, or kill a key. Any integration still using it stops authenticating immediately.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls DELETE /v3/api_keys/{{params.api_key_id}}.

Arguments:

Also retrieved by: "revoke that credential, it's compromised", "kill this key so it stops working", "cut off access for that integration".

sendgrid.list_templates

List SendGrid dynamic transactional templates by id, name, and how many versions each has. Use to see what templates already exist before creating or sending one.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/templates.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what dynamic templates do we already have", "show every reusable email layout on the account", "browse the saved message designs".

sendgrid.create_template

Create a new, empty SendGrid dynamic transactional template shell by name. Add its subject and body afterward with create_template_version; a template with no version has nothing to send yet.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/templates.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "start a new reusable email design", "set up a fresh template shell", "build a new layout we can reuse for sends".

sendgrid.get_template

Get one SendGrid template's details, including every saved version and which one is active (the one send_email's template_id renders).

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/templates/{{params.template_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "pull up the details for one email design", "which version of this template is live right now", "show me every saved draft of this layout".

sendgrid.update_template

Rename a SendGrid template.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls PATCH /v3/templates/{{params.template_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "rename this email design", "change what this template is called", "give this layout a clearer name".

sendgrid.delete_template

Permanently delete a SendGrid template and every version of it. Any send_email call that references its template_id afterward fails.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls DELETE /v3/templates/{{params.template_id}}.

Arguments:

Also retrieved by: "get rid of this email design for good", "remove this template and every version of it", "scrap this layout, we don't use it anymore".

sendgrid.create_template_version

Add a new content version to an existing SendGrid template: the subject line and the HTML or plain-text body that dynamic_template_data fills in at send time. Set active to make it the version send_email renders immediately.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/templates/{{params.template_id}}/versions.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "add a new draft of this email's copy", "save a fresh subject and body for this design", "make this the live version of the template".

sendgrid.list_verified_senders

List every SendGrid verified single sender identity (a from address cleared to send) and whether each has completed verification. Use before send_email to confirm a from address is actually usable.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/verified_senders.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "which from addresses are actually cleared to send", "show every sender identity on the account", "who are we allowed to mail from".

sendgrid.create_verified_sender

Request verification of a new SendGrid sender identity. SendGrid emails the from_email address a confirmation link; the identity cannot send until it's clicked. Use when the user wants to add, verify, or set up a new from address.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/verified_senders.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "get this address approved to send from", "set up a new from address for outbound mail", "register a sender identity so we can email from it".

sendgrid.delete_verified_sender

Remove a verified sender identity from SendGrid. Any send_email call using that from address then fails until it's re-verified.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls DELETE /v3/verified_senders/{{params.sender_id}}.

Arguments:

Also retrieved by: "remove this from address, we don't use it anymore", "take this sender identity off the account", "this from address shouldn't be able to send anymore".

sendgrid.list_authenticated_domains

List SendGrid's authenticated sending domains and whether each has finished DNS verification (DKIM and SPF records). Distinct from a verified single sender: authenticating a domain covers every address at that domain, not just one.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/whitelabel/domains.

Takes no arguments.

Also retrieved by: "which domains have finished dns setup for mail", "show every domain hooked up for authenticated sending", "what hostnames are cleared to send from at the domain level".

sendgrid.authenticate_domain

Register a new sending domain for SendGrid domain authentication and get back the DNS records to add. The domain isn't authenticated until validate_domain_authentication succeeds afterward.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/whitelabel/domains.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "hook up a new domain to send authenticated mail from", "get the dns records for a domain we want to send from", "register a domain so we can send with proper dkim and spf".

sendgrid.validate_domain_authentication

Re-check DNS for a SendGrid authenticated domain now that its records have been added, and mark it valid if they resolve correctly. Use when the user says the DNS records are in place and wants to confirm or finish domain authentication.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/whitelabel/domains/{{params.domain_id}}/validate.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "recheck the dns now that records are in place", "confirm this domain's authentication went through", "the records are added, please verify the domain now".

sendgrid.add_or_update_contacts

Add new SendGrid marketing contacts or update existing ones by email, optionally adding them to one or more lists in the same call. This runs as a background job; the response is a job id, not the finished contacts.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls PUT /v3/marketing/contacts.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "upload a batch of subscribers to the account", "add these people to our mailing list", "import contacts and put them on a list".

sendgrid.search_contacts

Search SendGrid marketing contacts with a query expression, e.g. by email, list membership, or a custom field. Use to look up a contact when the user doesn't have its contact id.

Class read (reads only). No scopes beyond the connection's defaults. Calls POST /v3/marketing/contacts/search.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "find a contact by their email address", "look up who's on this list", "dig up a subscriber's profile".

sendgrid.get_contact_by_id

Get one SendGrid marketing contact's full profile, including list membership, by its contact id.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/marketing/contacts/{{params.contact_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "pull up everything we know about this contact", "show one subscriber's full profile", "what info do we have on record for this person".

sendgrid.delete_contacts

Permanently delete SendGrid marketing contacts by id, or every contact on the account. A removed contact's engagement history goes with it.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls DELETE /v3/marketing/contacts.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "wipe these subscribers off the account entirely", "remove every contact we have on file", "purge these people from our subscriber database".

sendgrid.list_contact_lists

List every SendGrid marketing contact list by id, name, and contact count.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/marketing/lists.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what mailing lists do we have set up", "show every subscriber list on the account", "browse our newsletter and campaign groupings".

sendgrid.create_contact_list

Create a new SendGrid marketing contact list to group contacts under, e.g. a newsletter or a webinar signup list.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/marketing/lists.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "start a new subscriber list", "set up a fresh mailing list for the newsletter", "make a new grouping to organize subscribers under".

sendgrid.delete_contact_list

Delete a SendGrid marketing contact list. Only the list grouping is removed; pass delete_contacts to also delete every contact on it, otherwise they stay on the account, just off this list.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls DELETE /v3/marketing/lists/{{params.list_id}}.

Arguments:

Also retrieved by: "get rid of this subscriber list", "remove this mailing list, keep the contacts if possible", "shut down this grouping, we don't need it anymore".

sendgrid.list_single_sends

List SendGrid marketing single sends (one-off campaign emails) by id, name, and status. Distinct from send_email, which is a transactional message rather than a scheduled campaign to a list.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/marketing/singlesends.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what one-off campaigns have we sent or scheduled", "show every marketing blast on the account", "browse our past and upcoming email campaigns".

sendgrid.create_single_send

Create a SendGrid marketing single send: a one-off campaign email to a contact list or segment, built from a template or raw content. It stays a draft until scheduled or sent from the dashboard; this call only creates it.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/marketing/singlesends.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "set up a one-time campaign to our newsletter list", "draft a marketing blast to a segment", "build a one-off promo email for our subscribers".

sendgrid.get_single_send

Get one SendGrid single send's configuration and current status by id.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/marketing/singlesends/{{params.singlesend_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what's the status of this campaign", "pull up the details for one marketing send", "check how this one-off blast is configured".

sendgrid.delete_single_send

Permanently delete a SendGrid single send. If it was scheduled, deleting it cancels the send; it can never go out afterward.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls DELETE /v3/marketing/singlesends/{{params.singlesend_id}}.

Arguments:

Also retrieved by: "scrap this campaign draft", "cancel this scheduled marketing blast for good", "kill this one-off promo email before it goes out".

sendgrid.get_global_email_stats

Get account-wide SendGrid delivery stats (sent, delivered, opens, clicks, bounces, spam reports) over a date range. Use for an overall sending health check, not one specific campaign or message.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/stats.

Arguments:

Also retrieved by: "how's our sending been doing lately", "check overall delivery and open numbers", "give me a health check on our email sending".

sendgrid.get_category_stats

Get SendGrid delivery stats broken down by the categories a send was tagged with (send_email's categories field). Use to compare how different campaigns or message types are performing against each other.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/categories/stats.

Arguments:

Also retrieved by: "compare how these two campaigns performed", "break delivery numbers down by tag", "show me stats grouped by the labels we used".

sendgrid.get_email_activity

Search recent individual SendGrid message events (delivered, opened, clicked, bounced) by recipient, subject, or a filter query. Use when the user asks what happened to one specific email, rather than aggregate stats over a period.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/messages.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what happened to that one email I sent", "did this specific message actually get delivered", "look up the status of a single message".

sendgrid.get_event_webhook_settings

Get the SendGrid Event Webhook configuration: the URL SendGrid posts delivery events to and which event types are enabled.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/user/webhooks/event/settings.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "where are delivery events currently posted to", "check the event webhook configuration", "what notifications are currently turned on for deliveries".

sendgrid.update_event_webhook_settings

Change where SendGrid posts delivery events and which event types it sends, e.g. turn on bounce and spam report notifications or point delivery at a new URL.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls PATCH /v3/user/webhooks/event/settings.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "turn on bounce notifications", "point delivery events at a new endpoint", "change which notifications get sent out on delivery events".

sendgrid.get_account_details

Get the SendGrid account's plan type and sender reputation score. Use to check what tier or limits the account is on, or how healthy its sending reputation currently is.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/user/account.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what plan are we on", "check our sender reputation score", "how healthy is our sending reputation right now".