SendGrid Email
Send transactional email (plain or from a dynamic template), look up templates, check bounces and unsubscribes before sending, and search or upsert Marketing Campaigns contacts. Based on the SendGrid API specification.
Connect this API to an AI agent Browse all specs
What you can do with SendGrid Email via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /templates |
listTemplates | List transactional email templates |
| GET | /templates/{template_id} |
getTemplate | Get a template with its versions |
| GET | /suppression/bounces |
listBounces | List bounced email addresses |
| GET | /suppression/bounces/{email} |
getBounce | Check whether an address has bounced |
| GET | /suppression/unsubscribes |
listGlobalUnsubscribes | List addresses that unsubscribed from all email |
| GET | /asm/suppressions/{email} |
getSuppressionGroupsForEmail | Show which unsubscribe groups an address has left |
| POST | /marketing/contacts/search |
searchContacts | Search marketing contacts with a query |
| POST | /marketing/contacts/search/emails |
getContactsByEmails | Find marketing contacts by email address |
| PUT | /marketing/contacts |
upsertContacts | Add or update marketing contacts |
| POST | /mail/send |
sendMail | Send an email |
Authentication
BearerAuth
Bearer token — sent as Authorization: Bearer <token>
SendGrid API key sent as Authorization: Bearer <API key>.
How to get a credential
- Sign in to SendGrid (app.sendgrid.com).
- Open Settings > API Keys and click Create API Key.
- Choose Restricted Access and grant the permissions below.
- Copy the key (it starts with
SG.). It is shown only once. - Make sure the sender address or domain is verified under Settings > Sender Authentication.
Permissions used
| Permission | Operations |
|---|---|
| Mail Send: Full Access | sendMail |
| Template Engine: Read Access | listTemplates, getTemplate |
| Suppressions: Read Access | listBounces, getBounce, listGlobalUnsubscribes, getSuppressionGroupsForEmail |
| Marketing: Read Access | searchContacts, getContactsByEmails |
| Marketing: Full Access | upsertContacts |
Common errors
- 401 Unauthorized: the key is wrong, deleted or missing the
Bearerprefix. - 403 Forbidden: the key lacks the permission for that call (edit the key's scopes), or the
fromaddress is not a verified sender. - 400 Bad Request: invalid JSON body, e.g. missing
personalizations,from, orcontent/template_id. - 429 Too Many Requests: rate limit hit; wait for the time in
X-RateLimit-Reset.
Store the key as a VX Agents credential (Bearer token); never paste it into chat.
Usage guide
Setup
- Add a SendGrid API key (Settings > API Keys, restricted access) as the Bearer credential.
- Pin your verified sender address (
from.email, plusfrom.name) so every send uses it. Leaveon-behalf-ofempty unless you send for a subuser.
Send a transactional email
- To use a template, call
listTemplateswithgenerations=dynamicandpage_size(required, max 200), thengetTemplateto see the active version and its{{variables}}. - Before sending, check the recipient:
getBounce(bounced address) andgetSuppressionGroupsForEmail(unsubscribe groups). Skip or warn on suppressed addresses. - Show the user the recipient, subject and content (or template + data) and get confirmation.
- Call
sendMailwithpersonalizations(to, optionaldynamic_template_data),from, and eithersubject+content(text/plainand/ortext/html) ortemplate_id. A202with an empty body means accepted for delivery.
Manage marketing contacts
- Look up people with
getContactsByEmails(emailslist) orsearchContacts(queryin SGQL, e.g.email LIKE '%@acme.com'). - Confirm changes with the user, then call
upsertContactswithcontacts(emailrequired; names, custom fields) and optionallist_ids. It returns ajob_id; processing is asynchronous and takes a few minutes.
Deliverability checks
listBouncesandlistGlobalUnsubscribesacceptstart_time/end_time(Unix seconds);listGlobalUnsubscribesalso pages withlimit/offset.
Good to know
- Sending email and changing contacts affect real customers: always confirm
sendMailandupsertContactsbefore calling them. sendMaillimits: up to 1,000 personalizations per request; total message size up to 30 MB.- Template ids look like
d-...for dynamic templates. - Timestamps in suppression lists are Unix seconds.
- 429 responses include
X-RateLimit-Reset; wait before retrying.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “SendGrid Email” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.