Mattering Automations SendGrid integration
Connect SendGrid to Mattering Automations: transactional sends with a sandbox test mode, dynamic templates, marketing contacts and lists, the deliverability and suppression toolkit, and stats as workflow steps, authenticated with a SendGrid API key.
The Mattering Automations SendGrid integration adds Twilio SendGrid to your automation canvas: send transactional email through dynamic templates or raw content, manage templates and versions, upsert and search marketing contacts and lists, read segments and custom field definitions, work the deliverability toolkit (bounces, blocks, spam reports, invalid emails, global unsubscribes, and suppression groups), pull global and per-category statistics, validate addresses, and check verified senders.
Setup takes a few minutes: create an API key in SendGrid, attach it as a credential in Mattering, and test the connection. This guide walks through each step and ends with the full node reference.
Real delivery is a deliberate act here. The one node that sends is labeled SendGrid: Send Email (Sends Real Email), and its first field is sandbox_mode: with it on, SendGrid validates the entire request and returns success without delivering anything, the documented safe test path. Verify the integration with read nodes and sandboxed sends, and keep live delivery behind a condition, an approval step, or a manual run.
Before you start
- A Twilio SendGrid account. The free tier includes API access sufficient to set up and verify the integration; SendGrid sign-up includes identity verification, which can add a short review delay.
- Access to SendGrid's Settings > API Keys page to create an API key.
- For sending: a verified sender identity or an authenticated domain, since SendGrid rejects sends from an unverified from address.
- A Mattering workspace with access to the Automations app.
Create a SendGrid API key
Mattering authenticates to SendGrid with an API key, sent as a bearer credential on every request. Keys are created in the SendGrid dashboard, start with SG., and carry the permission scopes you choose at creation; scopes cannot be changed later, only replaced by creating a new key.
Connect SendGrid to Mattering
Verify it works
After connecting, open any automation canvas and check the palette: a SendGrid section should list the query and action nodes. Drop SendGrid: List API Key Scopes onto the canvas and run a test step. It takes no parameters, works for any valid key however restricted, and returns the scope names the key holds, so it verifies the credential and documents its grants in one run. Follow with SendGrid: List Verified Senders to see which from addresses SendGrid will accept.
To rehearse sending without delivering anything, run SendGrid: Send Email (Sends Real Email) with sandbox_mode set to true: SendGrid validates the whole request and returns success without sending. A successful send returns a 202 with an empty body, so an empty response from this node is normal, not a fault. Everything else in the verify path is read-only.
Node reference
41 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 24
SendGrid: Get Bounce
sendgrid_get_bounce
Look up whether one specific address has bounced and why. Returns an array (empty when the address has no bounce record).
SendGrid: Get Category Stats
sendgrid_get_category_stats
Email statistics broken down by message category (the labels set on sends, e.g. by the Mail Send node's categories field). Up to 10 categories per call; category data covers the previous 13 months only.
SendGrid: Get Contact
sendgrid_get_contact
Fetch one marketing contact by its contact ID (a UUID), including list memberships and custom field values. Get the ID from SendGrid: Search Contacts.
SendGrid: Get Contact Import Status
sendgrid_get_contact_import_status
Check an asynchronous contact job (upsert or delete) by the job_id those nodes return. status is pending, completed, errored, or failed; results carries created, updated, deleted and errored counts plus an errors_url when rows failed.
SendGrid: Get Contact List
sendgrid_get_list
Fetch one marketing list. Set contact_sample true to include a small sample of the list's contacts in the response.
SendGrid: Get Global Stats
sendgrid_get_global_stats
Account-wide email statistics (requests, delivered, opens, clicks, bounces, spam reports, unsubscribes) over a date window, optionally aggregated by day, week, or month. Needs the stats scope.
SendGrid: Get Segment
sendgrid_get_segment
Fetch one segment including its query definition. Set contacts_sample true to include a sample of matching contacts (the sample refreshes on SendGrid's 1-to-24-hour schedule, not live).
SendGrid: Get Suppression Group
sendgrid_get_suppression_group
Fetch one unsubscribe group with its unsubscribe count.
SendGrid: Get Template
sendgrid_get_template
Fetch one template with its versions array (each version carries id, name, subject, active flag and editor; use the version id with the version nodes below).
SendGrid: Get User Profile
sendgrid_get_user_profile
Read the account holder's profile (name, company, address, phone, website). Needs the user.profile read scope on a restricted key. A 403 from this endpoint usually means the API key was created with Restricted Access and lacks the needed permission scope, not that the key is invalid; check the key in SendGrid Settings > API Keys.
SendGrid: List API Key Scopes
sendgrid_list_scopes
List the permission scopes granted to the API key making the call (e.g. mail.send, templates.read). Takes no parameters, works for any valid key regardless of its restrictions, and returns only scope-name strings, so it doubles as the credential health check. If another SendGrid node returns 403, run this to see what the key is actually allowed to do.
SendGrid: List Blocks
sendgrid_list_blocks
List blocked sends: messages a receiving server refused for reasons about the MESSAGE or connection (content, reputation, timeouts) rather than the address. Unlike bounces, blocks do not suppress future sends.
SendGrid: List Bounces
sendgrid_list_bounces
List bounced addresses with the bounce reason and SMTP status code. SendGrid auto-suppresses future sends to these addresses. Filter by a Unix time window.
SendGrid: List Contact Lists
sendgrid_list_lists
List marketing contact lists with their contact counts. Page with page_size and the page_token from the previous response's _metadata.next.
SendGrid: List Field Definitions
sendgrid_list_field_definitions
List all contact field definitions: your custom fields (with the IDs needed by Add or Update Contacts) and SendGrid's reserved fields. Field types are Text, Number, and Date.
SendGrid: List Global Unsubscribes
sendgrid_list_global_unsubscribes
List addresses on the global unsubscribe list (recipients who opted out of ALL email from this account). Filter by a Unix time window and page with limit and offset. Needs the suppression scope.
SendGrid: List Group Suppressions
sendgrid_list_group_suppressions
List the email addresses suppressed (unsubscribed) from one group. The response is a plain array of address strings.
SendGrid: List Invalid Emails
sendgrid_list_invalid_emails
List addresses SendGrid found malformed or nonexistent at send time. Useful as a cleanup feed for the contact base.
SendGrid: List Segments
sendgrid_list_segments
List marketing segments (the 2.0 segmentation API) with their contact counts. Segment counts and samples refresh on SendGrid's own schedule (1 to 24 hours), so counts can lag reality.
SendGrid: List Spam Reports
sendgrid_list_spam_reports
List recipients who marked mail from this account as spam. SendGrid suppresses future sends to them; treat these as hard opt-outs in any sync.
SendGrid: List Suppression Groups
sendgrid_list_suppression_groups
List unsubscribe (suppression) groups: the per-mail-stream opt-out categories recipients see, e.g. Newsletter vs Product Updates. Accounts can hold up to 200 groups. Group IDs feed the Mail Send node's asm_group_id.
SendGrid: List Templates
sendgrid_list_templates
List transactional email templates (up to 300 per account). NOTE the API's own default only returns LEGACY templates, so this node defaults generations to 'legacy,dynamic' to show everything; modern Handlebars templates are the 'dynamic' generation with IDs starting 'd-'.
SendGrid: List Verified Senders
sendgrid_list_verified_senders
List the account's sender identities with their verification state. Useful before Mail Send: the from address must be a verified sender (or on an authenticated domain) or the send is rejected.
SendGrid: Search Contacts
sendgrid_search_contacts
Search marketing contacts with an SGQL query. Returns at most 50 contacts plus the total contact_count matching. Emails are stored lowercase, so compare against lowercase values. Queries that run past 20 seconds return a 408.
Action nodes 17
SendGrid: Add Global Unsubscribes
sendgrid_add_global_unsubscribes
Add addresses to the global unsubscribe list so they receive no further email from this account. The safe direction of suppression management: use it to honor opt-outs collected elsewhere.
SendGrid: Add Group Suppressions
sendgrid_add_group_suppressions
Add addresses to one unsubscribe group's suppression list so they stop receiving that mail stream (they can still receive email attributed to other groups).
SendGrid: Add or Update Contacts
sendgrid_upsert_contacts
Add new marketing contacts or update existing ones by email (upsert). Up to 30,000 contacts or 6MB per call. Processing is asynchronous: the response is a 202 with a job_id, not the finished result. Poll SendGrid: Get Contact Import Status with that job_id to confirm completion. Omitted fields on an existing contact are left unchanged, and email addresses are lowercased by SendGrid. Custom fields must already exist (see SendGrid: List Field Definitions for their IDs). Needs the marketing.contacts scope.
SendGrid: Create Contact List
sendgrid_create_list
Create a new (empty) marketing list. Add contacts to it with SendGrid: Add or Update Contacts using list_ids; the Lists API itself cannot add contacts.
SendGrid: Create Template
sendgrid_create_template
Create a new transactional template shell. Content lives in versions: follow with SendGrid: Create Template Version to add subject and body. Accounts are limited to 300 templates.
SendGrid: Create Template Version
sendgrid_create_template_version
Add a version (subject + body content) to a template. Setting active 1 makes it the live version served when the template is sent. Dynamic templates use Handlebars, e.g. {{first_name}}, filled at send time via dynamic_template_data.
SendGrid: Delete Bounce
sendgrid_delete_bounce
Delete one address's bounce record, re-enabling sends to it. DESTRUCTIVE: the bounce record (reason, timestamp) is gone for good, and re-sending to an address that hard-bounced hurts sender reputation. Only use after the underlying problem (typo fixed, mailbox restored) is genuinely resolved.
SendGrid: Delete Contact List
sendgrid_delete_list
Delete a marketing list. DESTRUCTIVE: the list is gone; with delete_contacts true its member contacts are also deleted from the account (asynchronously, returning a job_id). With delete_contacts false (default) the contacts survive and only the list is removed.
SendGrid: Delete Contacts
sendgrid_delete_contacts
Permanently delete marketing contacts by ID. DESTRUCTIVE: deleted contacts and their field data are gone (SendGrid recommends exporting contacts as a backup first). Processing is asynchronous: the response is a 202 with a job_id, not the finished result. Poll SendGrid: Get Contact Import Status with that job_id to confirm completion. The API's delete-all-contacts switch is deliberately not exposed on this node.
SendGrid: Delete Global Unsubscribe
sendgrid_delete_global_unsubscribe
Remove one address from the global unsubscribe list. CAUTION: removing a suppression re-enables email to an address whose owner may have unsubscribed on purpose. Only remove addresses you have a documented, lawful basis to email again.
SendGrid: Delete Group Suppression
sendgrid_delete_group_suppression
Remove one address from one group's suppression list. CAUTION: removing a suppression re-enables email to an address whose owner may have unsubscribed on purpose. Only remove addresses you have a documented, lawful basis to email again.
SendGrid: Remove Contacts from List
sendgrid_remove_contacts_from_list
Remove contacts from a list WITHOUT deleting them from the account (re-add them any time with Add or Update Contacts). Asynchronous: returns a job_id.
SendGrid: Send Email (Sends Real Email)
sendgrid_send_email
Send a real email through SendGrid to real recipients. DESTRUCTIVE in the way that matters: once SendGrid accepts the request (202) the message cannot be recalled. For testing, set sandbox_mode true: SendGrid then validates the whole request and returns success WITHOUT delivering anything, which is the documented safe test path. Provide html_content or text_content, or a template_id (dynamic templates start with 'd-') with dynamic_template_data. The from address must be a verified sender or on an authenticated domain, or SendGrid rejects the send with a 403. A successful response has an EMPTY body (the message id travels in the X-Message-Id response header, which the connector envelope does not surface). Needs the mail.send scope.
SendGrid: Update Contact List
sendgrid_update_list
Rename a marketing list.
SendGrid: Update Template
sendgrid_update_template
Rename a template. Version content is edited through the template version nodes, not here.
SendGrid: Update Template Version
sendgrid_update_template_version
Edit an existing template version: subject, content, or the active flag (set active 1 here to activate this version). Only the fields provided are changed.
SendGrid: Validate Email Address
sendgrid_validate_email
Validate one email address in real time: verdict (Valid, Risky, Invalid), confidence score, and checks for syntax, MX records, disposable domains, role addresses, and known bounces. PAID GATE: Email Address Validation is only available on Email API Pro and Premier plans, AND it requires its own dedicated validation API key (a key created with the Email Address Validation permission), so the connector's regular key may get a 403 here even on a qualifying plan. Rate limited to 7 requests per second. Note the path is /v3/validations/email (plural).
Using the integration
On the automation canvas
SendGrid nodes chain with every other node: a scheduled sweep over SendGrid: List Bounces, SendGrid: List Blocks, and SendGrid: List Spam Reports can update records in a Mattering database and open remediation tasks in Mattering Productivity, and SendGrid: Get Global Stats can land a weekly deliverability summary wherever the team reads it. Mailgun is also available as a Mattering connector, so teams can automate whichever email platform they already send through.
From AI assistants over MCP
Every node speaks MCP, the open protocol for connecting AI assistants to tools. Claude, ChatGPT, and Matter can read bounce reasons, check verified senders, search contacts, and pull stats through the same nodes your workflows use. The deliverability, stats, and scope introspection nodes are read-only, which makes them the safest SendGrid surface to hand an agent.
Real email and the sandbox switch
SendGrid: Send Email (Sends Real Email) is the one node that delivers, and a live send cannot be recalled once SendGrid accepts it. Its first field is sandbox_mode, the documented safe test switch: SendGrid validates the entire request and returns success without delivering. The from address must be a verified sender or on an authenticated domain or SendGrid rejects the send with a 403; SendGrid: List Verified Senders is the pre-send check. A successful send returns a 202 with an empty body, with the message id traveling in a response header the workflow envelope does not surface, so do not build downstream steps that expect an id in the send output.
Asynchronous marketing jobs
SendGrid: Add or Update Contacts, SendGrid: Delete Contacts, and SendGrid: Remove Contacts from List return a 202 with a job id rather than the finished result, and processing can take minutes. Poll SendGrid: Get Contact Import Status with the job id until the status is completed; it reports created, updated, deleted, and errored counts, with an errors report when rows fail. SendGrid: Search Contacts runs SGQL queries: at most 50 contacts return per call alongside the total match count, emails are stored lowercase, and a query running past 20 seconds returns a 408.
Permission scopes on API keys
SendGrid keys carry permission scopes chosen at creation: Full Access, or Restricted Access with per-family toggles. A restricted key returns 403 on any endpoint outside its grants, which looks exactly like a bad credential. The connection test is scope-proof because the scopes endpoint works for every valid key, so a key can pass the test and still refuse individual nodes. SendGrid: List API Key Scopes introspects the key's actual grants from the canvas; when a permission is missing, create a new key, because scopes cannot be added to an existing one.
The deliverability toolkit and consent
Bounced addresses are suppressed from future sends automatically; blocks record refusals about the message or connection and do not suppress. Spam reports and global unsubscribes are hard opt-outs and should be treated that way in any sync. SendGrid: Add Global Unsubscribes and SendGrid: Add Group Suppressions are the safe direction, honoring opt-outs collected elsewhere; SendGrid: Delete Global Unsubscribe and SendGrid: Delete Group Suppression re-enable email to someone who may have opted out on purpose, so only remove addresses you have a documented, lawful basis to email again. There is no inbound SendGrid trigger in this integration; to react to deliverability events, poll these nodes on a schedule.
Troubleshooting
Test Connection fails with a 401
Test Connection passes but a node returns a 403
SendGrid: Validate Email Address returns 403 on a key that works everywhere else
A send is rejected with a 403 mentioning the from address
A send succeeded but the response has no message id
Contacts were upserted but do not appear in searches
SendGrid: Search Contacts returns fewer results than the match count, or a 408
An address never receives mail even though sends succeed
Related
The SendGrid MCP
What connecting SendGrid unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
SendGrid is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.