twilio-sendgrid-email-send

Overview

Agent safety: Always confirm recipients, subject, and content with the user before sending. Email is irreversible once delivered. Never send email autonomously without explicit user approval — especially for batch sends to multiple recipients.

All email sending goes through POST /v3/mail/send. This endpoint returns 202 Accepted (queued) — NOT 200 OK (delivered). Delivery confirmation comes asynchronously via Event Webhook. See twilio-sendgrid-webhooks.

Basic Send

Python

import os, sendgrid
from sendgrid.helpers.mail import Mail

sg = sendgrid.SendGridAPIClient(os.environ["SENDGRID_API_KEY"])
message = Mail(
    from_email="verified@yourdomain.com",
    to_emails="recipient@example.com",
    subject="Order Confirmation",
    html_content="<p>Your order #1234 is confirmed.</p>"
)
response = sg.send(message)
print(f"Status: {response.status_code}")  # 202 = queued

Node.js

const sgMail = require("@sendgrid/mail");
sgMail.setApiKey(process.env.SENDGRID_API_KEY);

const [response] = await sgMail.send({
    to: "recipient@example.com",
    from: "verified@yourdomain.com",
    subject: "Order Confirmation",
    html: "<p>Your order #1234 is confirmed.</p>",
});
console.log(`Status: ${response.statusCode}`); // 202 = queued

Personalized Batch Send with Dynamic Templates

Dynamic templates use Handlebars syntax. Template IDs start with d-. Create templates in SendGrid Console > Email API > Dynamic Templates.

Python

from sendgrid.helpers.mail import Mail, To

message = Mail(
    from_email="noreply@yourdomain.com",
    to_emails=[
        To("alice@example.com", dynamic_template_data={"name": "Alice", "order_id": "123"}),
        To("bob@example.com", dynamic_template_data={"name": "Bob", "order_id": "456"}),
    ],
)
message.template_id = "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
sg.send(message)

Node.js

await sgMail.send({
    from: { email: "noreply@yourdomain.com" },
    template_id: "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    personalizations: [
        { to: [{ email: "alice@example.com" }], dynamic_template_data: { name: "Alice", order_id: "123" } },
        { to: [{ email: "bob@example.com" }], dynamic_template_data: { name: "Bob", order_id: "456" } },
    ],
});

Recipients in the same to array within a single personalization can see each other. For private sends, use separate personalizations (one per recipient).

Scheduled Sends

Schedule up to 72 hours in advance. Cancellation requires a batch ID assigned before sending.

Python

import time, requests

headers = {"Authorization": f"Bearer {os.environ['SENDGRID_API_KEY']}", "Content-Type": "application/json"}

# Get batch ID first
batch = requests.post("https://api.sendgrid.com/v3/mail/batch", headers=headers).json()

# Include batch_id and send_at in the message
send_at = int(time.time()) + 3600  # Unix SECONDS, not ms

# Cancel if needed (before send_at)
requests.post("https://api.sendgrid.com/v3/user/scheduled_sends",
    headers=headers,
    json={"batch_id": batch["batch_id"], "status": "cancel"})

Attachments

Base64-encode files in the attachments array. Total limit: 30MB per request (~22MB before encoding overhead).

import base64
from sendgrid.helpers.mail import Mail, Attachment, FileContent, FileName, FileType, Disposition

with open("invoice.pdf", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()

message = Mail(from_email="billing@yourdomain.com", to_emails="customer@example.com",
               subject="Your Invoice", html_content="<p>Invoice attached.</p>")
message.attachment = Attachment(FileContent(encoded), FileName("invoice.pdf"),
                                FileType("application/pdf"), Disposition("attachment"))
sg.send(message)

Categories and Custom Args

Categories tag sends for analytics segmentation (up to 10 per message):

message.category = ["transactional", "order-confirmation"]

Custom Args pass metadata through to Event Webhooks (key-value strings only):

message.custom_args = {"order_id": "1234", "env": "production"}

These appear in webhook event payloads, enabling you to correlate delivery events back to your application data.

Sandbox Mode (Testing)

Validates the request without delivering. Returns 200 OK (not 202).

message.mail_settings = {"sandbox_mode": {"enable": True}}
response = sg.send(message)  # 200 = validated, not sent

CANNOT

• Cannot send more than 1,000 recipients per API call — Hard limit. Split into multiple requests.
• Cannot schedule sends more than 72 hours in advance — send_at rejects timestamps beyond 72h.
• Cannot cancel a send after processing — Only scheduled messages with a pre-assigned batch ID can be cancelled.
• Cannot use send_at with milliseconds — JS Date.now() returns ms. Divide by 1000 or the timestamp is silently rejected (>72h).
• The subject field in personalizations is a plain string override — To use dynamic subjects, set Handlebars variables (e.g., {{{subject}}}) in the Dynamic Template's subject field and pass values via dynamic_template_data. The personalizations subject key bypasses the template subject entirely.
• Undefined template variables render as empty strings — No error for typos in dynamic_template_data keys. Silent failures.
• 413 Payload Too Large returns nginx HTML, not JSON — Exceeding 30MB returns HTML error page. Check Content-Type before parsing.
• Empty content when using template_id — Omit the content field. If you include both, template_id takes precedence and content is ignored.

Agent usage: When sending email on behalf of a user, always report back what was sent — recipients, subject, and the API response status code. Maintain an application-level audit log for all sends.

Next Steps

• Account setup and domain auth: twilio-sendgrid-account-setup
• Templates and settings: twilio-sendgrid-email-settings
• Delivery tracking via webhooks: twilio-sendgrid-webhooks
• Manage bounces and unsubscribes: twilio-sendgrid-suppressions