0
# SendGrid Mail
1

2
SendGrid Mail is a comprehensive Node.js library for sending transactional and marketing emails using the Twilio SendGrid Web API v3. It provides a powerful, feature-rich API for email delivery with support for templates, attachments, personalizations, tracking, scheduling, and advanced delivery features.
3

4
## Package Information
5

6
- **Package Name**: @sendgrid/mail
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install @sendgrid/mail`
10

11
## Core Imports
12

13
```javascript
14
const sgMail = require('@sendgrid/mail');
15
```
16

17
For TypeScript:
18

19
```typescript
20
import MailService = require("@sendgrid/mail/src/mail");
21
```
22

23
Access to the MailService class:
24

25
```javascript
26
const { MailService } = require('@sendgrid/mail');
27
```
28

29
## Basic Usage
30

31
```javascript
32
const sgMail = require('@sendgrid/mail');
33

34
// Set your SendGrid API key
35
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
36

37
// Simple email
38
const msg = {
39
  to: 'recipient@example.com',
40
  from: 'sender@example.com',
41
  subject: 'Hello from SendGrid',
42
  text: 'Hello from SendGrid!',
43
  html: '<strong>Hello from SendGrid!</strong>',
44
};
45

46
// Send email
47
sgMail.send(msg)
48
  .then(() => console.log('Email sent'))
49
  .catch((error) => console.error(error));
50
```
51

52
## Architecture
53

54
SendGrid Mail is built around several key components:
55

56
- **MailService**: Main service class providing configuration and sending functionality
57
- **Mail Class**: Email message builder from @sendgrid/helpers for constructing complex emails
58
- **Data Types**: Rich type system for emails, attachments, personalizations, and settings
59
- **Template System**: Support for both legacy and dynamic templates with substitutions
60
- **Personalization**: Per-recipient customization of content, headers, and metadata
61
- **Delivery Control**: Scheduling, batching, IP pools, and suppression management
62

63
## Capabilities
64

65
### Email Sending Service
66

67
Core email sending functionality with configuration, authentication, and delivery features. The main interface for sending single or multiple emails.
68

69
```javascript { .api }
70
// Default singleton instance
71
const sgMail = require('@sendgrid/mail');
72

73
// Configuration methods
74
sgMail.setApiKey(apiKey);
75
sgMail.setTwilioEmailAuth(username, password);
76
sgMail.setTimeout(timeout);
77
sgMail.setSubstitutionWrappers(left, right);
78
sgMail.setSecretRules(rules);
79

80
// Sending methods  
81
sgMail.send(data, isMultiple, callback);
82
sgMail.sendMultiple(data, callback);
83
```
84

85
[Email Sending Service](./email-service.md)
86

87
### Message Construction
88

89
Email message building using the Mail class for complex email structures with attachments, personalizations, templates, and advanced settings.
90

91
```javascript { .api }
92
const { Mail } = require('@sendgrid/helpers').classes;
93

94
// Constructor and factory
95
const mail = new Mail(data);
96
const mail = Mail.create(data);
97

98
// Core setters
99
mail.setFrom(from);
100
mail.setSubject(subject);
101
mail.addTo(to, cc, bcc);
102
mail.setContent(content);
103
mail.setTemplateId(templateId);
104
```
105

106
[Message Construction](./message-construction.md)
107

108
### Templates and Personalization
109

110
Template integration with dynamic data, substitutions, and per-recipient personalizations for customized email content.
111

112
```javascript { .api }
113
// Template data
114
const msg = {
115
  to: recipients,
116
  from: 'sender@example.com',
117
  templateId: 'd-1234567890abcdef',
118
  dynamicTemplateData: { name: 'John', total: '$25.00' }
119
};
120

121
// Personalization for individual recipients
122
const personalization = {
123
  to: ['user@example.com'],
124
  dynamicTemplateData: { name: 'Alice' }
125
};
126
```
127

128
[Templates and Personalization](./templates-personalization.md)
129

130
### Attachments and Content
131

132
File attachment handling and content management including inline images, multiple content types, and rich media support.
133

134
```javascript { .api }
135
// Attachment structure
136
interface AttachmentData {
137
  content: string;    // Base64-encoded content
138
  filename: string;   // File name
139
  type?: string;      // MIME type
140
  disposition?: string; // "attachment" or "inline"
141
  contentId?: string; // For inline images
142
}
143
```
144

145
[Attachments and Content](./attachments-content.md)
146

147
### Tracking and Analytics
148

149
Email tracking configuration including open tracking, click tracking, subscription management, and Google Analytics integration.
150

151
```javascript { .api }
152
// Tracking settings structure
153
interface TrackingSettings {
154
  clickTracking?: { enable?: boolean; enableText?: boolean };
155
  openTracking?: { enable?: boolean; substitutionTag?: string };
156
  subscriptionTracking?: { enable?: boolean; text?: string; html?: string };
157
  ganalytics?: { enable?: boolean; utmSource?: string; utmCampaign?: string };
158
}
159
```
160

161
[Tracking and Analytics](./tracking-analytics.md)
162

163
### Advanced Delivery
164

165
Advanced email delivery features including scheduling, batching, IP pools, suppression management, and mail settings.
166

167
```javascript { .api }
168
// Advanced delivery options
169
const msg = {
170
  to: 'recipient@example.com',
171
  from: 'sender@example.com',
172
  subject: 'Scheduled Email',
173
  text: 'This email was scheduled',
174
  sendAt: 1640995200,  // Unix timestamp
175
  batchId: 'batch_123',
176
  ipPoolName: 'marketing_pool',
177
  asm: { groupId: 123 }
178
};
179
```
180

181
[Advanced Delivery](./advanced-delivery.md)
182

183
## Core Types
184

185
```javascript { .api }
186
// Email address data
187
type EmailData = string | { name?: string; email: string };
188

189
// Mail content structure
190
interface MailContent {
191
  type: string;   // "text/plain" or "text/html"
192
  value: string;  // Content body
193
}
194

195
// Core mail data interface
196
interface MailData {
197
  // Required: sender and content
198
  from: EmailData;
199
  text?: string;
200
  html?: string;
201
  templateId?: string;
202
  content?: MailContent[];
203
  
204
  // Recipients
205
  to?: EmailData | EmailData[];
206
  cc?: EmailData | EmailData[];
207
  bcc?: EmailData | EmailData[];
208
  
209
  // Message properties
210
  subject?: string;
211
  replyTo?: EmailData;
212
  sendAt?: number;
213
  
214
  // Advanced features
215
  personalizations?: PersonalizationData[];
216
  attachments?: AttachmentData[];
217
  categories?: string[];
218
  headers?: { [key: string]: string };
219
  customArgs?: { [key: string]: any };
220
  
221
  // Settings
222
  mailSettings?: MailSettings;
223
  trackingSettings?: TrackingSettings;
224
  asm?: ASMOptions;
225
}
226
```
227

228
## Error Handling
229

230
SendGrid Mail uses Promises and provides detailed error information through ResponseError objects. Common error scenarios include authentication failures, invalid email addresses, template errors, and API rate limits.
231

232
```javascript
233
sgMail.send(msg)
234
  .then(() => {
235
    console.log('Email sent successfully');
236
  })
237
  .catch((error) => {
238
    console.error('Error sending email:', error);
239
    
240
    if (error.response) {
241
      console.error('Response body:', error.response.body);
242
    }
243
  });
244
```