0
# Transport Configuration
1

2
Transport configuration defines how emails are delivered. Nodemailer supports multiple transport types for different email sending scenarios and providers.
3

4
## Capabilities
5

6
### SMTP Transport
7

8
Standard SMTP transport for connecting to email servers with authentication and security options.
9

10
```javascript { .api }
11
/**
12
 * Creates SMTP transport configuration
13
 * @param {Object} options - SMTP configuration options
14
 * @returns {SMTPTransport} SMTP transport instance
15
 */
16
const transporter = nodemailer.createTransport({
17
    host: string,
18
    port?: number,
19
    secure?: boolean,
20
    auth?: {
21
        user: string,
22
        pass: string
23
    },
24
    tls?: {
25
        rejectUnauthorized?: boolean,
26
        ciphers?: string,
27
        minVersion?: string
28
    },
29
    connectionTimeout?: number,
30
    greetingTimeout?: number,
31
    socketTimeout?: number,
32
    logger?: boolean,
33
    debug?: boolean
34
});
35

36
interface SMTPOptions {
37
    host: string;                    // SMTP server hostname
38
    port?: number;                   // SMTP server port (587, 465, 25)
39
    secure?: boolean;                // true for 465, false for other ports
40
    auth?: AuthOptions;              // Authentication credentials
41
    tls?: TLSOptions;               // TLS/SSL options
42
    name?: string;                  // Client hostname for HELO/EHLO
43
    localAddress?: string;          // Local interface to bind to
44
    connectionTimeout?: number;     // Connection timeout in ms
45
    greetingTimeout?: number;       // Greeting timeout in ms
46
    socketTimeout?: number;         // Socket timeout in ms
47
    logger?: boolean | Object;      // Logger configuration
48
    debug?: boolean;                // Debug mode
49
    authMethod?: string;            // Preferred authentication method
50
    ignoreTLS?: boolean;            // Ignore STARTTLS support
51
    requireTLS?: boolean;           // Require TLS connection
52
    opportunisticTLS?: boolean;     // Use STARTTLS if available
53
    proxy?: string;                 // Proxy URL
54
    dkim?: DKIMOptions | DKIMOptions[]; // DKIM signing configuration
55
}
56

57
interface DKIMOptions {
58
    domainName: string;             // Domain name for DKIM signature
59
    keySelector: string;            // DKIM key selector
60
    privateKey: string | Buffer;    // Private key for signing
61
    headers?: string[];             // Headers to include in signature
62
    hashAlgo?: string;              // Hash algorithm (default: 'sha256')
63
}
64
```
65

66
**Usage Example:**
67

68
```javascript
69
// Gmail SMTP
70
const transporter = nodemailer.createTransport({
71
    host: 'smtp.gmail.com',
72
    port: 587,
73
    secure: false,
74
    auth: {
75
        user: 'your.email@gmail.com',
76
        pass: 'your-app-password'
77
    }
78
});
79

80
// Custom SMTP server with TLS
81
const customTransporter = nodemailer.createTransport({
82
    host: 'mail.example.com',
83
    port: 465,
84
    secure: true,
85
    auth: {
86
        user: 'username',
87
        pass: 'password'
88
    },
89
    tls: {
90
        rejectUnauthorized: false
91
    },
92
    dkim: {
93
        domainName: 'example.com',
94
        keySelector: 'default',
95
        privateKey: require('fs').readFileSync('./dkim-private-key.pem')
96
    }
97
});
98
```
99

100
### SMTP Pool Transport
101

102
Connection pooling transport for high-volume email sending with connection reuse and rate limiting.
103

104
```javascript { .api }
105
/**
106
 * Creates SMTP pool transport configuration
107
 * @param {Object} options - SMTP pool configuration options
108
 * @returns {SMTPPool} SMTP pool transport instance
109
 */
110
const poolTransporter = nodemailer.createTransport({
111
    pool: true,
112
    host: string,
113
    port?: number,
114
    secure?: boolean,
115
    auth?: AuthOptions,
116
    maxConnections?: number,
117
    maxMessages?: number,
118
    rateDelta?: number,
119
    rateLimit?: number,
120
    maxRequeues?: number
121
});
122

123
interface SMTPPoolOptions extends SMTPOptions {
124
    pool: true;                     // Enable connection pooling
125
    maxConnections?: number;        // Max concurrent connections (default: 5)
126
    maxMessages?: number;           // Max messages per connection (default: 100)
127
    rateDelta?: number;            // Rate limiting time window in ms (default: 1000)
128
    rateLimit?: number;            // Max messages per rate window (default: 0 = disabled)
129
    maxRequeues?: number;          // Max requeue attempts on connection close
130
}
131
```
132

133
**Usage Example:**
134

135
```javascript
136
const poolTransporter = nodemailer.createTransport({
137
    pool: true,
138
    host: 'smtp.example.com',
139
    port: 587,
140
    secure: false,
141
    auth: {
142
        user: 'sender@example.com',
143
        pass: 'password'
144
    },
145
    maxConnections: 10,
146
    maxMessages: 50,
147
    rateLimit: 100 // 100 emails per second
148
});
149
```
150

151
### AWS SES Transport
152

153
Amazon Simple Email Service transport for cloud-based email delivery.
154

155
```javascript { .api }
156
/**
157
 * Creates AWS SES transport configuration
158
 * @param {Object} options - SES configuration options
159
 * @returns {SESTransport} SES transport instance
160
 */
161
const sesTransporter = nodemailer.createTransport({
162
    SES: {
163
        sesClient: SESv2Client,
164
        aws?: {
165
            accessKeyId?: string,
166
            secretAccessKey?: string,
167
            region?: string
168
        }
169
    }
170
});
171

172
interface SESOptions {
173
    SES: {
174
        sesClient: Object;          // AWS SES v2 client instance
175
        aws?: {                     // AWS credentials (optional if using IAM roles)
176
            accessKeyId?: string;
177
            secretAccessKey?: string;
178
            region?: string;
179
        };
180
    };
181
}
182
```
183

184
**Usage Example:**
185

186
```javascript
187
const { SESv2Client } = require('@aws-sdk/client-sesv2');
188

189
const sesTransporter = nodemailer.createTransport({
190
    SES: {
191
        sesClient: new SESv2Client({
192
            region: 'us-east-1',
193
            credentials: {
194
                accessKeyId: 'YOUR_ACCESS_KEY',
195
                secretAccessKey: 'YOUR_SECRET_KEY'
196
            }
197
        })
198
    }
199
});
200
```
201

202
### Sendmail Transport
203

204
Local sendmail binary transport for Unix/Linux systems.
205

206
```javascript { .api }
207
/**
208
 * Creates Sendmail transport configuration
209
 * @param {Object|string} options - Sendmail configuration options or path
210
 * @returns {SendmailTransport} Sendmail transport instance
211
 */
212
const sendmailTransporter = nodemailer.createTransport({
213
    sendmail: true,
214
    path?: string,
215
    newline?: string,
216
    args?: string[]
217
});
218

219
interface SendmailOptions {
220
    sendmail: true;                 // Enable sendmail transport
221
    path?: string;                  // Path to sendmail binary (default: 'sendmail')
222
    newline?: string;               // Line ending style ('unix' or 'windows')
223
    args?: string[];                // Additional sendmail arguments
224
}
225
```
226

227
**Usage Example:**
228

229
```javascript
230
const sendmailTransporter = nodemailer.createTransport({
231
    sendmail: true,
232
    path: '/usr/sbin/sendmail',
233
    args: ['-f', 'sender@example.com']
234
});
235

236
// Or simple string format
237
const simpleTransporter = nodemailer.createTransport('/usr/bin/sendmail');
238
```
239

240
### Stream Transport
241

242
Development transport that outputs emails to streams instead of sending them.
243

244
```javascript { .api }
245
/**
246
 * Creates Stream transport configuration
247
 * @param {Object} options - Stream configuration options
248
 * @returns {StreamTransport} Stream transport instance
249
 */
250
const streamTransporter = nodemailer.createTransport({
251
    streamTransport: true,
252
    buffer?: boolean,
253
    newline?: string
254
});
255

256
interface StreamOptions {
257
    streamTransport: true;          // Enable stream transport
258
    buffer?: boolean;               // Buffer message content (default: false)
259
    newline?: string;               // Line ending style ('unix' or 'windows')
260
}
261
```
262

263
**Usage Example:**
264

265
```javascript
266
const streamTransporter = nodemailer.createTransport({
267
    streamTransport: true,
268
    buffer: true
269
});
270

271
streamTransporter.sendMail(mailOptions, (error, info) => {
272
    if (error) {
273
        return console.log(error);
274
    }
275
    console.log('Message stream:', info.message.toString());
276
});
277
```
278

279
### JSON Transport
280

281
Development transport that outputs email data as JSON objects.
282

283
```javascript { .api }
284
/**
285
 * Creates JSON transport configuration
286
 * @param {Object} options - JSON configuration options
287
 * @returns {JSONTransport} JSON transport instance
288
 */
289
const jsonTransporter = nodemailer.createTransport({
290
    jsonTransport: true,
291
    skipTextLines?: boolean
292
});
293

294
interface JSONOptions {
295
    jsonTransport: true;            // Enable JSON transport
296
    skipTextLines?: boolean;        // Skip text content lines in output
297
}
298
```
299

300
**Usage Example:**
301

302
```javascript
303
const jsonTransporter = nodemailer.createTransport({
304
    jsonTransport: true
305
});
306

307
jsonTransporter.sendMail(mailOptions, (error, info) => {
308
    if (error) {
309
        return console.log(error);
310
    }
311
    console.log('Message JSON:', JSON.stringify(info.message, null, 2));
312
});
313
```
314

315
### Connection URL Format
316

317
Simplified configuration using connection URL strings.
318

319
```javascript { .api }
320
/**
321
 * Creates transport from connection URL
322
 * @param {string} url - Connection URL
323
 * @returns {Transport} Transport instance based on URL scheme
324
 */
325
const transporter = nodemailer.createTransport(connectionUrl);
326

327
// URL formats:
328
// smtp://username:password@smtp.example.com:587
329
// smtps://username:password@smtp.example.com:465
330
// smtp://smtp.example.com:587?pool=true&maxConnections=10
331
```
332

333
**Usage Example:**
334

335
```javascript
336
// Basic SMTP URL
337
const transporter1 = nodemailer.createTransport(
338
    'smtp://user%40example.com:password@smtp.example.com:587'
339
);
340

341
// SMTP with pool and query parameters
342
const transporter2 = nodemailer.createTransport(
343
    'smtp://user:pass@smtp.example.com:587?pool=true&maxConnections=5'
344
);
345

346
// Secure SMTP
347
const transporter3 = nodemailer.createTransport(
348
    'smtps://user:pass@smtp.example.com:465'
349
);
350
```
351

352
### Well-known Services
353

354
Pre-configured settings for popular email services.
355

356
```javascript { .api }
357
/**
358
 * Creates transport using well-known service configuration
359
 * @param {Object} options - Service configuration with service name
360
 * @returns {Transport} Transport instance with service settings
361
 */
362
const transporter = nodemailer.createTransport({
363
    service: serviceName,
364
    auth: {
365
        user: string,
366
        pass: string
367
    }
368
});
369

370
// Supported services: Gmail, Outlook365, Yahoo, Hotmail, iCloud, etc.
371
```
372

373
**Usage Example:**
374

375
```javascript
376
// Gmail service
377
const gmailTransporter = nodemailer.createTransport({
378
    service: 'gmail',
379
    auth: {
380
        user: 'your.email@gmail.com',
381
        pass: 'your-app-password'
382
    }
383
});
384

385
// Outlook 365
386
const outlookTransporter = nodemailer.createTransport({
387
    service: 'Outlook365',
388
    auth: {
389
        user: 'your.email@outlook.com',
390
        pass: 'your-password'
391
    }
392
});
393
```
394

395
## Transport Methods
396

397
### Verification
398

399
```javascript { .api }
400
/**
401
 * Verifies transport configuration by testing connection
402
 * @param {Function} [callback] - Optional callback function
403
 * @returns {Promise<boolean>} Promise resolving to true if connection successful
404
 */
405
transporter.verify(callback);
406
```
407

408
### Connection Status
409

410
```javascript { .api }
411
/**
412
 * Checks if transport is idle (for pooled transports)
413
 * @returns {boolean} True if transport is idle and ready to send
414
 */
415
transporter.isIdle();
416
```
417

418
### Connection Cleanup
419

420
```javascript { .api }
421
/**
422
 * Closes transport connections and cleans up resources
423
 * @returns {void}
424
 */
425
transporter.close();
426
```