Skip to main content

How to Send Emails from Node.js Using SendGrid API: Step-by-Step Guide

· 4 min read
Dopebase
Engineering Team

Send transactional email from Node.js through a server-only SendGrid integration with restricted API keys, verified domains, templates, idempotency, and delivery webhooks. This revised guide emphasizes supported APIs, production tradeoffs, and an upgrade-friendly path without tying the advice to a calendar year.

How to Send Emails from Node.js Using SendGrid API: Step-by-Step Guide

Modern implementation baseline​

Send transactional email from Node.js through a server-only SendGrid integration with restricted API keys, verified domains, templates, idempotency, and delivery webhooks.

Keep credentials on the server, grant the smallest useful scope, validate every input, and make retries idempotent. Production integrations also need structured logs, delivery metrics, webhook verification, and a recovery path.

  • Use the Web API and a restricted Mail Send key.
  • Authenticate the sending domain before production traffic.
  • Process webhook events idempotently and verify signatures.

Production checklist​

  • Store secrets outside source control and rotate them safely.
  • Retry transient failures with backoff and an idempotency key.
  • Monitor accepted, delivered, bounced, and rejected outcomes separately.

Authoritative references​

Why Use SendGrid with Node.js?​

  • High Deliverability: SendGrid ensures emails reach inboxes (not spam folders).
  • Scalability: Handles millions of emails monthly.
  • Features: Templates, analytics, and SMTP/API options.
  • Free Tier: 100 emails/day forever.

Prerequisites​

  1. Node.js v18+ installed
  2. A SendGrid account (Sign up here)
  3. API Key from SendGrid (we'll create this below)

Step 1: Get Your SendGrid API Key​

  1. Go to SendGrid's API Keys page.
  2. Click Create API Key.
  3. Name it (e.g., NodeJS_Email_Service), select Full Access, and save the key securely.

Step 2: Set Up a Node.js Project​

Initialize a project and install the SendGrid package:

mkdir node-sendgrid && cd node-sendgrid
npm init -y
npm install @sendgrid/mail dotenv

Step 3: Send Your First Email​

Create an .env file to store your API key:

SENDGRID_API_KEY=your_api_key_here

Create index.js:

const sgMail = require('@sendgrid/mail');
require('dotenv').config();

sgMail.setApiKey(process.env.SENDGRID_API_KEY);

const msg = {
  to: 'recipient@example.com',
  from: 'your-verified-email@yourdomain.com', // Must match SendGrid's Single Sender Verification
  subject: 'First SendGrid Email from Node.js!',
  text: 'Plain text content',
  html: '<strong>HTML content</strong>',
};

sgMail
  .send(msg)
  .then(() => console.log('Email sent!'))
  .catch((error) => console.error(error));

Run it:

node index.js

Step 4: Advanced Use Cases​

A. Send Emails with Attachments​

const msg = {
  // ... (previous fields)
  attachments: [
    {
      content: Buffer.from('File content here').toString('base64'),
      filename: 'document.pdf',
      type: 'application/pdf',
      disposition: 'attachment',
    },
  ],
};

B. Use Dynamic Templates​

  1. Create a template in SendGrid's Template Engine.
  2. Use it in Node.js:
const msg = {
  to: 'user@example.com',
  from: 'noreply@yourdomain.com',
  templateId: 'd-your-template-id-123',
  dynamicTemplateData: {
    name: 'John Doe',
    resetLink: 'https://yourdomain.com/reset-password',
  },
};

Best Practices​

  1. Rate Limiting: Handle 429 errors with retries (use libraries like axios-retry).
  2. Validate Emails: Use tools like validator.js to check email formats before sending.
  3. Templates: Store reusable HTML in SendGrid instead of hardcoding in Node.js.
  4. Monitoring: Track email stats via SendGrid's dashboard or webhooks.
  5. Security: Never expose your API key in client-side code.

Troubleshooting Common Errors​

  • 403 Forbidden: Verify your API key and sender email.
  • Bad Request (400): Check for missing required fields (e.g., to, from).
  • Unverified Sender: Complete SendGrid's Single Sender Verification.

Alternatives to SendGrid​

  • Nodemailer (for SMTP with Gmail, Outlook, etc.)
  • AWS SES (cost-effective for high volume)
  • Mailgun (similar features to SendGrid)

\

Faq​

Q: Is SendGrid free for Node.js?

A: Yes! SendGrid offers 100 emails/day for free, perfect for small projects.


Q: Can I use SendGrid with Express.js?

A: Absolutely. Follow the same setup in your Express routes.


Q: How do I track email opens?

A: Enable Open Tracking in SendGrid's Settings.


Q: What’s the difference between SendGrid API and SMTP?

A: The API offers more features (e.g., analytics), while SMTP is simpler for basic use cases.