0
# Email Sending
1

2
Core email sending functionality with comprehensive support for various message formats, attachments, headers, and delivery options.
3

4
## Capabilities
5

6
### Send Mail
7

8
Primary method for sending email messages with extensive configuration options.
9

10
```javascript { .api }
11
/**
12
 * Sends an email message
13
 * @param {Object} mailOptions - Email message configuration
14
 * @param {Function} [callback] - Optional callback function (error, info) => void
15
 * @returns {Promise<SentMessageInfo>} Promise if no callback provided
16
 */
17
transporter.sendMail(mailOptions, callback);
18

19
interface MailOptions {
20
    // Recipients
21
    from?: string | Address;        // Sender address
22
    to: string | string[] | Address | Address[];  // Recipients
23
    cc?: string | string[] | Address | Address[]; // Carbon copy recipients
24
    bcc?: string | string[] | Address | Address[]; // Blind carbon copy recipients
25
    replyTo?: string | string[] | Address | Address[]; // Reply-to addresses
26
    
27
    // Message content
28
    subject?: string;               // Subject line
29
    text?: string | Buffer | NodeJS.ReadableStream; // Plain text body
30
    html?: string | Buffer | NodeJS.ReadableStream; // HTML body
31
    watchHtml?: string | Buffer | NodeJS.ReadableStream; // Apple Watch HTML
32
    amp?: string | Buffer | NodeJS.ReadableStream; // AMP4EMAIL content
33
    
34
    // Attachments and alternatives
35
    attachments?: Attachment[];     // File attachments
36
    alternatives?: Alternative[];   // Alternative representations
37
    
38
    // Headers
39
    headers?: Object | Array;       // Custom headers
40
    messageId?: string;             // Message-ID header
41
    date?: Date | string;          // Date header
42
    encoding?: string;              // Text encoding (default: 'utf8')
43
    
44
    // References
45
    inReplyTo?: string | string[];  // In-Reply-To header
46
    references?: string | string[]; // References header
47
    
48
    // Priority and handling
49
    priority?: 'high' | 'normal' | 'low'; // Message priority
50
    envelope?: Envelope;            // SMTP envelope
51
    
52
    // List management
53
    list?: ListHeaders;             // List-* headers
54
    
55
    // Delivery options
56
    dsn?: DSNOptions;              // Delivery Status Notification options
57
    
58
    // Security options
59
    dkim?: DKIMOptions;            // DKIM signing configuration
60
    
61
    // Processing options
62
    textEncoding?: string;          // Text content transfer encoding
63
    normalizeHeaderKey?: Function;  // Header key normalization function
64
}
65

66
interface Address {
67
    name?: string;                  // Display name
68
    address: string;                // Email address
69
}
70

71
interface SentMessageInfo {
72
    messageId: string;              // Message ID
73
    envelope: {                     // SMTP envelope
74
        from: string;
75
        to: string[];
76
    };
77
    accepted: string[];             // Accepted recipients
78
    rejected: string[];             // Rejected recipients
79
    pending: string[];              // Pending recipients
80
    response: string;               // Server response
81
}
82
```
83

84
**Usage Examples:**
85

86
Basic email:
87
```javascript
88
const mailOptions = {
89
    from: '"Sender Name" <sender@example.com>',
90
    to: 'recipient@example.com',
91
    subject: 'Hello World',
92
    text: 'Hello world?',
93
    html: '<b>Hello world?</b>'
94
};
95

96
transporter.sendMail(mailOptions, (error, info) => {
97
    if (error) {
98
        return console.log(error);
99
    }
100
    console.log('Message sent: %s', info.messageId);
101
});
102
```
103

104
Multiple recipients:
105
```javascript
106
const mailOptions = {
107
    from: 'sender@example.com',
108
    to: ['recipient1@example.com', 'recipient2@example.com'],
109
    cc: 'cc@example.com',
110
    bcc: ['bcc1@example.com', 'bcc2@example.com'],
111
    subject: 'Multiple Recipients',
112
    text: 'This email has multiple recipients'
113
};
114
```
115

116
Using Promises:
117
```javascript
118
async function sendEmail() {
119
    try {
120
        const info = await transporter.sendMail(mailOptions);
121
        console.log('Message sent: %s', info.messageId);
122
    } catch (error) {
123
        console.error('Error sending email:', error);
124
    }
125
}
126
```
127

128
### Attachments
129

130
File attachments support including files, buffers, streams, and embedded content.
131

132
```javascript { .api }
133
interface Attachment {
134
    filename?: string;              // Attachment filename
135
    content?: string | Buffer | NodeJS.ReadableStream; // Attachment content
136
    path?: string;                  // File path
137
    href?: string;                  // URL to file
138
    httpHeaders?: Object;           // HTTP headers for href
139
    contentType?: string;           // MIME type
140
    contentDisposition?: string;    // Content disposition ('attachment' or 'inline')
141
    cid?: string;                   // Content-ID for embedded images
142
    encoding?: string;              // Content transfer encoding
143
    headers?: Object;               // Attachment-specific headers
144
    raw?: string | Buffer;          // Raw attachment data
145
}
146
```
147

148
**Usage Examples:**
149

150
File attachment:
151
```javascript
152
const mailOptions = {
153
    from: 'sender@example.com',
154
    to: 'recipient@example.com',
155
    subject: 'File Attachment',
156
    text: 'Please find the attached file.',
157
    attachments: [
158
        {
159
            filename: 'document.pdf',
160
            path: '/path/to/document.pdf'
161
        },
162
        {
163
            filename: 'image.png',
164
            path: '/path/to/image.png',
165
            cid: 'embedded-image' // For embedding in HTML
166
        }
167
    ]
168
};
169
```
170

171
Buffer attachment:
172
```javascript
173
const attachment = {
174
    filename: 'data.txt',
175
    content: Buffer.from('Hello world', 'utf8'),
176
    contentType: 'text/plain'
177
};
178
```
179

180
URL attachment:
181
```javascript
182
const attachment = {
183
    filename: 'remote-image.jpg',
184
    href: 'https://example.com/image.jpg',
185
    httpHeaders: {
186
        'User-Agent': 'My Application'
187
    }
188
};
189
```
190

191
Embedded image:
192
```javascript
193
const mailOptions = {
194
    from: 'sender@example.com',
195
    to: 'recipient@example.com',
196
    subject: 'Embedded Image',
197
    html: '<p>Here is an image: <img src="cid:my-image"/></p>',
198
    attachments: [
199
        {
200
            filename: 'image.png',
201
            path: '/path/to/image.png',
202
            cid: 'my-image'
203
        }
204
    ]
205
};
206
```
207

208
### Custom Headers
209

210
Support for custom email headers and header manipulation.
211

212
```javascript { .api }
213
interface HeaderOptions {
214
    headers?: Object | Array<{key: string, value: string}>; // Custom headers
215
    messageId?: string;             // Message-ID header
216
    date?: Date | string;          // Date header
217
    normalizeHeaderKey?: Function;  // Header key normalization
218
}
219
```
220

221
**Usage Examples:**
222

223
Object headers:
224
```javascript
225
const mailOptions = {
226
    from: 'sender@example.com',
227
    to: 'recipient@example.com',
228
    subject: 'Custom Headers',
229
    text: 'Email with custom headers',
230
    headers: {
231
        'X-Custom-Header': 'custom-value',
232
        'X-Priority': '1',
233
        'X-Mailer': 'My Application'
234
    }
235
};
236
```
237

238
Array headers:
239
```javascript
240
const mailOptions = {
241
    headers: [
242
        {key: 'X-Custom-Header', value: 'value1'},
243
        {key: 'X-Custom-Header', value: 'value2'} // Multiple values for same header
244
    ]
245
};
246
```
247

248
Custom Message-ID:
249
```javascript
250
const mailOptions = {
251
    messageId: '<custom-message-id@example.com>',
252
    // ... other options
253
};
254
```
255

256
### List Headers
257

258
Support for mailing list headers for proper list management.
259

260
```javascript { .api }
261
interface ListHeaders {
262
    help?: string;                  // List-Help header
263
    unsubscribe?: string | string[] | UnsubscribeOptions[]; // List-Unsubscribe
264
    subscribe?: string | string[];  // List-Subscribe header
265
    post?: string | string[];       // List-Post header
266
    owner?: string | string[];      // List-Owner header
267
    archive?: string | string[];    // List-Archive header 
268
    id?: string | {                 // List-ID header
269
        url: string;
270
        comment?: string;
271
    };
272
}
273

274
interface UnsubscribeOptions {
275
    url: string;                    // Unsubscribe URL
276
    comment?: string;               // Comment for the URL
277
}
278
```
279

280
**Usage Examples:**
281

282
```javascript
283
const mailOptions = {
284
    from: 'newsletter@example.com',
285
    to: 'subscriber@example.com',
286
    subject: 'Newsletter Issue #123',
287
    text: 'Newsletter content...',
288
    list: {
289
        help: 'help@example.com?subject=help',
290
        unsubscribe: [
291
            {
292
                url: 'https://example.com/unsubscribe?id=12345',
293
                comment: 'Unsubscribe from this list'
294
            },
295
            'mailto:unsubscribe@example.com?subject=unsubscribe'
296
        ],
297
        id: {
298
            url: 'newsletter.example.com',
299
            comment: 'Example Newsletter'
300
        }
301
    }
302
};
303
```
304

305
### Envelope Configuration
306

307
SMTP envelope configuration for advanced routing and delivery options.
308

309
```javascript { .api }
310
interface Envelope {
311
    from?: string;                  // SMTP envelope sender (MAIL FROM)
312
    to?: string | string[];         // SMTP envelope recipients (RCPT TO)
313
    size?: number;                  // Message size hint
314
    use8BitMime?: boolean;          // Use 8-bit MIME encoding
315
    dsn?: DSNOptions;              // Delivery Status Notification options
316
}
317

318
interface DSNOptions {
319
    id?: string;                    // Original recipient ID
320
    return?: 'full' | 'headers';   // Return full message or headers only
321
    notify?: string | string[];     // Notification conditions ('never', 'success', 'failure', 'delay')
322
    recipient?: string;             // Original recipient address
323
}
324

325
interface DKIMOptions {
326
    domainName: string;             // Domain name for DKIM signature
327
    keySelector: string;            // DKIM key selector
328
    privateKey: string | Buffer;    // Private key for signing
329
    headers?: string[];             // Headers to include in signature
330
    hashAlgo?: string;              // Hash algorithm (default: 'sha256')
331
    bodyHash?: string;              // Body hash algorithm
332
    skip?: boolean;                 // Skip DKIM signing for this message
333
}
334
```
335

336
**Usage Examples:**
337

338
```javascript
339
const mailOptions = {
340
    from: 'display-sender@example.com',
341
    to: 'recipient@example.com',
342
    subject: 'Envelope Example',
343
    text: 'Message with custom envelope',
344
    envelope: {
345
        from: 'bounce-handler@example.com', // Bounce emails go here
346
        to: ['recipient@example.com']
347
    },
348
    dsn: {
349
        id: 'msg-12345',
350
        return: 'headers',
351
        notify: ['failure', 'delay']
352
    }
353
};
354
```
355

356
### Alternative Content
357

358
Support for alternative message representations and content types.
359

360
```javascript { .api }
361
interface Alternative {
362
    contentType: string;            // MIME content type
363
    content: string | Buffer | NodeJS.ReadableStream; // Alternative content
364
    encoding?: string;              // Content encoding
365
    headers?: Object;               // Alternative-specific headers
366
}
367
```
368

369
**Usage Examples:**
370

371
```javascript
372
const mailOptions = {
373
    from: 'sender@example.com',
374
    to: 'recipient@example.com',
375
    subject: 'Alternative Content',
376
    text: 'Plain text version',
377
    html: '<p>HTML version</p>',
378
    alternatives: [
379
        {
380
            contentType: 'text/calendar',
381
            content: 'BEGIN:VCALENDAR\nVERSION:2.0\n...\nEND:VCALENDAR'
382
        }
383
    ]
384
};
385
```
386

387
### DKIM Signing
388

389
Digital signature support for email authentication and security using DKIM (DomainKeys Identified Mail).
390

391
```javascript { .api }
392
interface DKIMConfiguration {
393
    domainName: string;             // Domain name for DKIM signature
394
    keySelector: string;            // DKIM key selector
395
    privateKey: string | Buffer;    // Private key for signing
396
    headers?: string[];             // Headers to include in signature (default: common headers)
397
    hashAlgo?: string;              // Hash algorithm (default: 'sha256')
398
    skip?: boolean;                 // Skip DKIM signing for this message
399
}
400

401
// Transport-level DKIM (applies to all messages)
402
const transporter = nodemailer.createTransporter({
403
    // ... transport config
404
    dkim: {
405
        domainName: 'example.com',
406
        keySelector: 'default',
407
        privateKey: fs.readFileSync('/path/to/private-key.pem')
408
    }
409
});
410

411
// Per-message DKIM (overrides transport settings)
412
const mailOptions = {
413
    // ... other options
414
    dkim: {
415
        domainName: 'custom.example.com',
416
        keySelector: 'selector1',
417
        privateKey: privateKeyBuffer,
418
        headers: ['from', 'to', 'subject', 'date']
419
    }
420
};
421
```
422

423
**Usage Examples:**
424

425
Transport-level DKIM:
426
```javascript
427
const fs = require('fs');
428

429
const transporter = nodemailer.createTransport({
430
    host: 'smtp.example.com',
431
    port: 587,
432
    secure: false,
433
    auth: {
434
        user: 'user@example.com',
435
        pass: 'password'
436
    },
437
    dkim: {
438
        domainName: 'example.com',
439
        keySelector: 'default',
440
        privateKey: fs.readFileSync('./dkim-private-key.pem')
441
    }
442
});
443

444
// All emails sent through this transporter will be DKIM signed
445
```
446

447
Per-message DKIM:
448
```javascript
449
const mailOptions = {
450
    from: 'sender@example.com',
451
    to: 'recipient@example.com',
452
    subject: 'DKIM Signed Message',
453
    text: 'This message will be DKIM signed',
454
    dkim: {
455
        domainName: 'example.com',
456
        keySelector: 'marketing',
457
        privateKey: marketingDkimKey,
458
        headers: ['from', 'to', 'subject', 'date', 'message-id']
459
    }
460
};
461
```
462

463
Multiple DKIM keys:
464
```javascript
465
const transporter = nodemailer.createTransport({
466
    // ... transport config
467
    dkim: [
468
        {
469
            domainName: 'example.com',
470
            keySelector: 'default',
471
            privateKey: defaultKey
472
        },
473
        {
474
            domainName: 'marketing.example.com',
475
            keySelector: 'promo',
476
            privateKey: promoKey
477
        }
478
    ]
479
});
480
```
481

482
### Calendar Events
483

484
Support for calendar event attachments and invitations.
485

486
```javascript { .api }
487
interface CalendarEvent {
488
    method?: string;                // METHOD property (REQUEST, REPLY, CANCEL)
489
    content: string;                // iCalendar content
490
    filename?: string;              // Attachment filename
491
    encoding?: string;              // Content encoding
492
}
493
```
494

495
**Usage Examples:**
496

497
```javascript
498
const mailOptions = {
499
    from: 'organizer@example.com',
500
    to: 'attendee@example.com',
501
    subject: 'Meeting Invitation',
502
    text: 'Please find the meeting invitation attached.',
503
    icalEvent: {
504
        method: 'REQUEST',
505
        content: `BEGIN:VCALENDAR
506
VERSION:2.0
507
PRODID:-//Example Corp//CalDAV Client//EN
508
BEGIN:VEVENT
509
UID:meeting-12345@example.com
510
DTSTART:20240101T100000Z
511
DTEND:20240101T110000Z
512
SUMMARY:Team Meeting
513
DESCRIPTION:Monthly team sync
514
ORGANIZER:MAILTO:organizer@example.com
515
ATTENDEE:MAILTO:attendee@example.com
516
END:VEVENT
517
END:VCALENDAR`,
518
        filename: 'meeting.ics'
519
    }
520
};
521
```