@sendgrid/mail

@sendgrid/mail is Twilio SendGrid’s dedicated Node.js client for the mail-sending endpoint of the SendGrid v3 Web API. It provides a small, focused API — setApiKey() plus send()/sendMultiple() — for constructing and dispatching transactional or marketing email, including HTML/text bodies, attachments, templates, personalization, and scheduled sends, without requiring consumers to hand-build HTTP requests against the SendGrid REST API.

The package is one of several published from the sendgrid-nodejs monorepo, which also includes @sendgrid/client (for calling the rest of SendGrid’s v3 API beyond mail), @sendgrid/eventwebhook (webhook signature verification), and @sendgrid/inbound-mail-parser. @sendgrid/mail is the entry point the SendGrid documentation recommends for the most common use case — sending email — and depends internally on @sendgrid/client for the underlying HTTP transport.

What You Get

• setApiKey() and send()/sendMultiple() methods for dispatching one or many emails via the SendGrid v3 mail-send endpoint
• Support for HTML and plain-text bodies, file attachments, CC/BCC, custom headers, and categories on a single message object
• Dynamic template support for SendGrid’s transactional templates, with per-recipient personalization substitutions
• Scheduled sends (sendAt) and batch IDs for coordinating and later canceling groups of scheduled emails
• Built-in retry-friendly error objects surfacing SendGrid API response codes and body details for debugging failed sends
• TypeScript type definitions (mail.d.ts) describing the message payload shape

Common Use Cases

• Sending transactional emails — password resets, order confirmations, welcome emails — from a Node.js backend or serverless function
• Triggering marketing or lifecycle email campaigns using SendGrid dynamic templates with per-user personalization
• Batch-sending emails to many recipients in a single API call via sendMultiple()
• Scheduling emails for future delivery and canceling scheduled batches through the sendAt/batch-id workflow
• Attaching generated documents (invoices, receipts) to outbound email without managing raw MIME encoding

Under The Hood

Architecture - @sendgrid/mail (packages/mail/src/mail.js) is a thin façade over @sendgrid/client, which performs the actual authenticated HTTP requests to the SendGrid v3 API; @sendgrid/mail is responsible for validating and normalizing the message object (recipients, content, attachments, personalizations) via helper classes from the shared @sendgrid/helpers package before handing the request off to the client package’s request() method. This layering is what lets the monorepo publish a narrow @sendgrid/mail package for the common case while @sendgrid/client remains available separately for the full breadth of SendGrid’s API surface (contacts, stats, templates management, etc.).

Tech Stack - Written in JavaScript with accompanying TypeScript declaration files, structured as an npm/Lerna-style monorepo workspace where packages/mail depends on the sibling packages/client and packages/helpers via workspace references rather than published npm versions during development. Node.js 10+ is required per the package’s engines field, with no other runtime dependencies beyond its sibling SendGrid packages.

Code Quality - mail.spec.js sits alongside the implementation file under packages/mail/src, and the monorepo’s CI (historically Travis CI, referenced in the README badge) runs the shared test suite across all packages. The library has a documented breaking-change migration guide (v6 to v7) in docs/migration-guides/, showing an established process for communicating API changes to consumers rather than silent breaking releases.

API Design - The two-call quick start (setApiKey() then send()) is deliberately minimal for the common transactional-email case, and the message object’s field names map closely to the underlying SendGrid v3 API JSON schema, so developers reading SendGrid’s REST API docs can apply that knowledge directly to the Node.js message object. The tradeoff is that anything outside mail sending — managing contacts, templates, or stats — requires switching to the separate @sendgrid/client package, which has a lower-level, more general request-based API.