0
# Advanced Delivery
1

2
Advanced email delivery features including scheduling, batching, IP pools, suppression management, and mail settings for optimized email delivery control.
3

4
## Capabilities
5

6
### Scheduled Delivery
7

8
Schedule emails to be sent at a specific future time using Unix timestamps.
9

10
```javascript { .api }
11
/**
12
 * Schedule email delivery for a specific time
13
 * @param sendAt - Unix timestamp for when to send the email
14
 */
15
const msg = {
16
  to: 'recipient@example.com',
17
  from: 'sender@example.com',
18
  subject: 'Scheduled Email',
19
  text: 'This email was scheduled for later delivery',
20
  sendAt: 1640995200  // Unix timestamp (e.g., January 1, 2022)
21
};
22
```
23

24
**Usage Example:**
25

26
```javascript
27
const sgMail = require('@sendgrid/mail');
28

29
// Schedule email for specific date/time
30
const futureDate = new Date('2024-12-25T10:00:00Z');
31
const sendAtTimestamp = Math.floor(futureDate.getTime() / 1000);
32

33
const scheduledMsg = {
34
  to: 'recipient@example.com',
35
  from: 'sender@example.com', 
36
  subject: 'Merry Christmas!',
37
  html: '<h1>Season\'s Greetings!</h1>',
38
  sendAt: sendAtTimestamp
39
};
40

41
sgMail.send(scheduledMsg);
42
```
43

44
### Batch Management
45

46
Group related emails together using batch IDs for tracking and management purposes.
47

48
```javascript { .api }
49
/**
50
 * Group emails using batch identifiers
51
 * @param batchId - Unique identifier for grouping related emails
52
 */
53
const msg = {
54
  to: 'recipient@example.com',
55
  from: 'sender@example.com',
56
  subject: 'Batch Email',
57
  text: 'Part of email batch',
58
  batchId: 'newsletter-2024-01'  // Custom batch identifier
59
};
60
```
61

62
**Usage Example:**
63

64
```javascript
65
const sgMail = require('@sendgrid/mail');
66

67
const batchId = 'campaign-' + Date.now();
68

69
// Send multiple emails with same batch ID
70
const emails = [
71
  {
72
    to: 'user1@example.com',
73
    from: 'newsletter@company.com',
74
    subject: 'Weekly Newsletter',
75
    html: '<h2>Newsletter Content</h2>',
76
    batchId: batchId
77
  },
78
  {
79
    to: 'user2@example.com', 
80
    from: 'newsletter@company.com',
81
    subject: 'Weekly Newsletter',
82
    html: '<h2>Newsletter Content</h2>',
83
    batchId: batchId
84
  }
85
];
86

87
// All emails will share the same batch ID for tracking
88
sgMail.send(emails);
89
```
90

91
### IP Pool Management
92

93
Control which IP pool is used for sending emails, useful for reputation management and delivery optimization.
94

95
```javascript { .api }
96
/**
97
 * Specify IP pool for email delivery
98
 * @param ipPoolName - Name of the IP pool to use for sending
99
 */
100
const msg = {
101
  to: 'recipient@example.com',
102
  from: 'sender@example.com',
103
  subject: 'Email via IP Pool',
104
  text: 'Sent using dedicated IP pool',
105
  ipPoolName: 'marketing_pool'  // Specific IP pool name
106
};
107
```
108

109
**Usage Example:**
110

111
```javascript
112
const sgMail = require('@sendgrid/mail');
113

114
// Send transactional email via dedicated IP pool
115
const transactionalMsg = {
116
  to: 'customer@example.com',
117
  from: 'orders@company.com',
118
  subject: 'Order Confirmation',
119
  html: '<h2>Your order has been confirmed</h2>',
120
  ipPoolName: 'transactional_pool'
121
};
122

123
// Send marketing email via different IP pool
124
const marketingMsg = {
125
  to: 'subscriber@example.com',
126
  from: 'marketing@company.com', 
127
  subject: 'Special Offer',
128
  html: '<h2>Limited Time Offer!</h2>',
129
  ipPoolName: 'marketing_pool'
130
};
131

132
sgMail.send([transactionalMsg, marketingMsg]);
133
```
134

135
### Advanced Suppression Management (ASM)
136

137
Control unsubscribe group settings and suppression management for compliance and subscriber management.
138

139
```javascript { .api }
140
/**
141
 * Configure Advanced Suppression Management settings
142
 * @param asm - ASM configuration object
143
 */
144
interface ASMOptions {
145
  groupId: number;           // Unsubscribe group ID
146
  groupsToDisplay?: number[]; // Additional groups to display in unsubscribe
147
}
148

149
const msg = {
150
  to: 'recipient@example.com',
151
  from: 'sender@example.com',
152
  subject: 'Email with ASM',
153
  text: 'Email with suppression management',
154
  asm: {
155
    groupId: 123,              // Primary unsubscribe group
156
    groupsToDisplay: [124, 125] // Additional groups to show
157
  }
158
};
159
```
160

161
**Usage Example:**
162

163
```javascript
164
const sgMail = require('@sendgrid/mail');
165

166
// Marketing email with proper ASM settings
167
const marketingEmail = {
168
  to: 'subscriber@example.com',
169
  from: 'marketing@company.com',
170
  subject: 'Weekly Promotions',
171
  html: '<h2>This Week\'s Deals</h2><p>Great offers await!</p>',
172
  asm: {
173
    groupId: 100,  // Marketing emails unsubscribe group
174
    groupsToDisplay: [100, 101, 102]  // Show marketing, weekly, and promotional options
175
  }
176
};
177

178
sgMail.send(marketingEmail);
179
```
180

181
### Categories and Custom Arguments
182

183
Add metadata for tracking and organization purposes.
184

185
```javascript { .api }
186
/**
187
 * Add categories and custom arguments for tracking
188
 * @param categories - Array of category strings for email classification
189
 * @param customArgs - Custom key-value pairs for additional metadata
190
 */
191
const msg = {
192
  to: 'recipient@example.com',
193
  from: 'sender@example.com',
194
  subject: 'Categorized Email',
195
  text: 'Email with categories and custom args',
196
  categories: ['Newsletter', 'Marketing', 'Q1-2024'],
197
  customArgs: {
198
    campaignId: 'spring-2024',
199
    userId: '12345',
200
    department: 'marketing'
201
  }
202
};
203
```
204

205
**Usage Example:**
206

207
```javascript
208
const sgMail = require('@sendgrid/mail');
209

210
// Email with comprehensive tracking metadata
211
const trackedEmail = {
212
  to: 'customer@example.com',
213
  from: 'support@company.com',
214
  subject: 'Account Update',
215
  html: '<h2>Your account has been updated</h2>',
216
  categories: ['Account', 'Transactional', 'Updates'],
217
  customArgs: {
218
    userId: 'user_67890',
219
    accountType: 'premium',
220
    updateType: 'profile',
221
    triggeredBy: 'user_action'
222
  }
223
};
224

225
sgMail.send(trackedEmail);
226
```
227

228
### Mail Settings
229

230
Configure email behavior settings including spam checking, sandboxing, and footer management.
231

232
```javascript { .api }
233
/**
234
 * Configure mail behavior settings
235
 */
236
interface MailSettings {
237
  sandboxMode?: { enable?: boolean };
238
  spamCheck?: { enable?: boolean; threshold?: number; postToUrl?: string };
239
  bypassListManagement?: { enable?: boolean };
240
  footer?: { enable?: boolean; text?: string; html?: string };
241
}
242

243
const msg = {
244
  to: 'recipient@example.com',
245
  from: 'sender@example.com',
246
  subject: 'Email with Mail Settings',
247
  text: 'Email with custom mail settings',
248
  mailSettings: {
249
    sandboxMode: { enable: false },
250
    spamCheck: { 
251
      enable: true, 
252
      threshold: 3,
253
      postToUrl: 'https://example.com/spam-report'
254
    },
255
    footer: {
256
      enable: true,
257
      text: 'Sent by Company Name',
258
      html: '<p><em>Sent by Company Name</em></p>'
259
    }
260
  }
261
};
262
```
263

264
## Complete Advanced Delivery Example
265

266
```javascript
267
const sgMail = require('@sendgrid/mail');
268

269
// Comprehensive advanced delivery configuration
270
const advancedMsg = {
271
  to: 'recipient@example.com',
272
  from: 'sender@company.com',
273
  subject: 'Advanced Delivery Email',
274
  html: '<h2>Important Update</h2><p>This email uses advanced delivery features.</p>',
275
  
276
  // Scheduling
277
  sendAt: Math.floor(Date.now() / 1000) + 3600, // Send in 1 hour
278
  
279
  // Batch management
280
  batchId: 'quarterly-update-2024-q1',
281
  
282
  // IP pool selection
283
  ipPoolName: 'premium_delivery',
284
  
285
  // Suppression management
286
  asm: {
287
    groupId: 200,
288
    groupsToDisplay: [200, 201, 202]
289
  },
290
  
291
  // Tracking and categorization
292
  categories: ['Updates', 'Quarterly', 'Important'],
293
  customArgs: {
294
    quarter: 'Q1-2024',
295
    department: 'operations',
296
    priority: 'high'
297
  },
298
  
299
  // Mail behavior settings
300
  mailSettings: {
301
    sandboxMode: { enable: false },
302
    spamCheck: { enable: true, threshold: 5 },
303
    footer: {
304
      enable: true,
305
      text: '\n\nCompany Name | Unsubscribe | Privacy Policy',
306
      html: '<hr><p><small>Company Name | <a href="#">Unsubscribe</a> | <a href="#">Privacy Policy</a></small></p>'
307
    }
308
  }
309
};
310

311
sgMail.send(advancedMsg)
312
  .then(() => console.log('Advanced email scheduled successfully'))
313
  .catch(error => console.error('Error:', error));
314
```
315

316
## Types
317

318
```javascript { .api }
319
// Advanced Suppression Management options
320
interface ASMOptions {
321
  groupId: number;              // Primary unsubscribe group ID
322
  groupsToDisplay?: number[];   // Additional unsubscribe groups to display
323
}
324

325
// Mail settings configuration
326
interface MailSettings {
327
  sandboxMode?: { enable?: boolean };
328
  spamCheck?: { 
329
    enable?: boolean; 
330
    threshold?: number; 
331
    postToUrl?: string; 
332
  };
333
  bypassListManagement?: { enable?: boolean };
334
  footer?: { 
335
    enable?: boolean; 
336
    text?: string; 
337
    html?: string; 
338
  };
339
}
340

341
// Advanced delivery data structure
342
interface AdvancedDeliveryData {
343
  sendAt?: number;              // Unix timestamp for scheduled delivery
344
  batchId?: string;            // Batch identifier for grouping
345
  ipPoolName?: string;         // IP pool name for sending
346
  asm?: ASMOptions;            // Advanced Suppression Management
347
  categories?: string[];        // Email categories for tracking
348
  customArgs?: { [key: string]: any }; // Custom tracking arguments
349
  mailSettings?: MailSettings;  // Email behavior settings
350
}
351
```