Send Mail
sendgrid.send_mail
ActionEmailconnection required
Calls the SendGrid API with the connection's credentials.
Send one message through the SendGrid v3 mail send API, with optional cc/bcc, reply-to, categories, attachments, a dynamic template and a scheduled send time.
Connection
- Required
- Yes — the node will not save without one
- Auth type
- API key
- Providers
- SendGrid
- Secret shape
- {"api_key": "…"}, or the API key on its own
- Config it needs
- from_email, from_name
- Resolved by
- config.connection_id, else node.connection_id
Configuration
16 fields, 1 required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.
| Field | Type | Required | Default | Constraints | Example |
|---|---|---|---|---|---|
to Recipient address, or several separated by commas. | string | Yes | — | — | ops@example.com |
subject Subject line. Required unless a template_id supplies one. | string | No | — | — | Your order has shipped |
body_text Plain-text body of the message. | string | No | — | — | Your order has shipped and is on its way. |
body_html HTML body of the message; sent alongside body_text when both are set. | string | No | — | — | — |
from_email Verified sender address. Falls back to the connection's from_email. | string | No | — | email format | — |
from_name Display name for the sender. Falls back to the connection's from_name. | string | No | — | — | — |
cc Carbon-copy addresses, separated by commas. | string | No | — | — | — |
bcc Blind-carbon-copy addresses, separated by commas. | string | No | — | — | — |
reply_to Reply-to address; give several, comma separated, to send a reply_to_list. | string | No | — | — | — |
template_id Dynamic template to render, for example d-1234567890abcdef. | string | No | — | — | — |
dynamic_template_data Handlebars variables the dynamic template renders, as a JSON object. | object | No | — | — | — |
categories Up to ten category names for reporting, separated by commas. | string | No | — | — | — |
custom_args Custom key/value arguments echoed back on every event webhook. | object | No | — | — | — |
attachments SendGrid attachment objects, each with base64 content, filename and type. | array | No | — | array of object | — |
send_at Unix timestamp to deliver at, up to 72 hours ahead. Omit to send now. | number | No | — | ≥ 0 | — |
batch_id Batch identifier, so a scheduled send can be cancelled as a group. | string | No | — | — | — |
- At least one of body_text, body_html, template_id must be set.
- At least one of subject, template_id must be set.
Example configuration
Every value below is the contract’s own example or default — nothing invented.
{
"body_text": "Your order has shipped and is on its way.",
"subject": "Your order has shipped",
"to": "ops@example.com"
}Output
One shape.
result
| Field | Type | Example |
|---|---|---|
message_id The X-Message-Id header SendGrid returns; the handle for event webhooks. | string | — |
status_code HTTP status SendGrid answered with, 202 on accept. | number | — |
accepted True when SendGrid accepted the message for delivery. | boolean | — |
to The recipient addresses the message was submitted for. | array | — |
{
"accepted": false,
"message_id": "",
"status_code": 0,
"to": []
}Notes
- SendGrid answers a successful send with 202 and an empty body; the only identifier is the X-Message-Id response header, surfaced as message_id.
- The sender address must be a verified single sender or a domain you have authenticated in SendGrid, or the call is rejected with a 403.
Templates that use SendGrid
See Send Mail run in a workflow.
In a technical demo we add the SendGrid connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.