name: send-email
description: Use when sending simple transactional emails or notifications via the SendGrid v3 Mail Send API.

Send Email with SendGrid

Overview

SendGrid provides a single Mail Send endpoint for sending email via the v3 API. The Node SDK (@sendgrid/mail) is the recommended integration for JavaScript/TypeScript.

Use this skill when:
- Sending transactional emails (welcome, password reset, receipts)
- Sending simple notifications
- You need basic text/HTML emails with optional attachments

Quick Start

1. Detect project language (package.json, requirements.txt, go.mod, etc.)
2. Install SDK (preferred) or use cURL - See references/installation.md
3. Prepare message with from, to, subject, and text or html
4. Send and handle errors (retry on 429/5xx)

Required Parameters

Optional Parameters

Minimal Example (Node.js)

import sgMail from '@sendgrid/mail';

sgMail.setApiKey(process.env.SENDGRID_API_KEY!);

await sgMail.send({
  from: 'Support <[email protected]>',
  to: '[email protected]',
  subject: 'Hello from SendGrid',
  text: 'This is a test email.',
  html: '<p>This is a test email.</p>',
});

Templates (Dynamic Templates)

If using SendGrid Dynamic Templates, supply template_id and dynamic_template_data instead of html/text.

await sgMail.send({
  from: 'Support <[email protected]>',
  to: '[email protected]',
  templateId: 'd-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  dynamicTemplateData: { first_name: 'Vince' },
});

Best Practices (Short)

• Always set both text and html when possible (deliverability + accessibility).
• Retry only on 429 or 5xx errors with exponential backoff.
• Use verified senders; unverified domains will fail.
• Avoid fake addresses at real providers; test with addresses you control.

For deeper details, see:
- references/best-practices.md
- references/single-email-examples.md