Subversion Repositories cheapmusic

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
103 - 1
This documentation is based on our [OAI specification](https://github.com/sendgrid/sendgrid-oai).
2
 
3
# INITIALIZATION
4
 
5
```php
6
// If you are using Composer
7
require 'vendor/autoload.php';
8
 
9
 
10
$apiKey = getenv('SENDGRID_API_KEY');
11
$sg = new \SendGrid($apiKey);
12
```
13
 
14
# Table of Contents
15
 
16
* [ACCESS SETTINGS](#access_settings)
17
* [ALERTS](#alerts)
18
* [API KEYS](#api_keys)
19
* [ASM](#asm)
20
* [BROWSERS](#browsers)
21
* [CAMPAIGNS](#campaigns)
22
* [CATEGORIES](#categories)
23
* [CLIENTS](#clients)
24
* [CONTACTDB](#contactdb)
25
* [DEVICES](#devices)
26
* [GEO](#geo)
27
* [IPS](#ips)
28
* [MAIL](#mail)
29
* [MAIL SETTINGS](#mail_settings)
30
* [MAILBOX PROVIDERS](#mailbox_providers)
31
* [PARTNER SETTINGS](#partner_settings)
32
* [SCOPES](#scopes)
33
* [SENDERS](#senders)
34
* [STATS](#stats)
35
* [SUBUSERS](#subusers)
36
* [SUPPRESSION](#suppression)
37
* [TEMPLATES](#templates)
38
* [TRACKING SETTINGS](#tracking_settings)
39
* [USER](#user)
40
* [WHITELABEL](#whitelabel)
41
 
42
 
43
<a name="access_settings"></a>
44
# ACCESS SETTINGS
45
 
46
## Retrieve all recent access attempts
47
 
48
**This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API.**
49
 
50
IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.
51
 
52
For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).
53
 
54
### GET /access_settings/activity
55
 
56
 
57
```php
58
$query_params = json_decode('{"limit": 1}');
59
$response = $sg->client->access_settings()->activity()->get(null, $query_params);
60
echo $response->statusCode();
61
echo $response->body();
62
echo $response->headers();
63
```
64
## Add one or more IPs to the whitelist
65
 
66
**This endpoint allows you to add one or more IP addresses to your IP whitelist.**
67
 
68
When adding an IP to your whitelist, include the IP address in an array. You can whitelist one IP at a time, or you can whitelist multiple IPs at once.
69
 
70
IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.
71
 
72
For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).
73
 
74
### POST /access_settings/whitelist
75
 
76
 
77
```php
78
$request_body = json_decode('{
79
  "ips": [
80
    {
81
      "ip": "192.168.1.1"
82
    },
83
    {
84
      "ip": "192.*.*.*"
85
    },
86
    {
87
      "ip": "192.168.1.3/32"
88
    }
89
  ]
90
}');
91
$response = $sg->client->access_settings()->whitelist()->post($request_body);
92
echo $response->statusCode();
93
echo $response->body();
94
echo $response->headers();
95
```
96
## Retrieve a list of currently whitelisted IPs
97
 
98
**This endpoint allows you to retrieve a list of IP addresses that are currently whitelisted.**
99
 
100
IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.
101
 
102
For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).
103
 
104
### GET /access_settings/whitelist
105
 
106
 
107
```php
108
$response = $sg->client->access_settings()->whitelist()->get();
109
echo $response->statusCode();
110
echo $response->body();
111
echo $response->headers();
112
```
113
## Remove one or more IPs from the whitelist
114
 
115
**This endpoint allows you to remove one or more IPs from your IP whitelist.**
116
 
117
You can remove one IP at a time, or you can remove multiple IP addresses.
118
 
119
IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.
120
 
121
For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).
122
 
123
### DELETE /access_settings/whitelist
124
 
125
 
126
```php
127
$request_body = json_decode('{
128
  "ids": [
129
    1,
130
    2,
131
    3
132
  ]
133
}');
134
$response = $sg->client->access_settings()->whitelist()->delete($request_body);
135
echo $response->statusCode();
136
echo $response->body();
137
echo $response->headers();
138
```
139
## Retrieve a specific whitelisted IP
140
 
141
**This endpoint allows you to retreive a specific IP address that has been whitelisted.**
142
 
143
You must include the ID for the specific IP address you want to retrieve in your call.
144
 
145
IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.
146
 
147
For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).
148
 
149
### GET /access_settings/whitelist/{rule_id}
150
 
151
 
152
```php
153
$rule_id = "test_url_param";
154
$response = $sg->client->access_settings()->whitelist()->_($rule_id)->get();
155
echo $response->statusCode();
156
echo $response->body();
157
echo $response->headers();
158
```
159
## Remove a specific IP from the whitelist
160
 
161
**This endpoint allows you to remove a specific IP address from your IP whitelist.**
162
 
163
When removing a specific IP address from your whitelist, you must include the ID in your call.
164
 
165
IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.
166
 
167
For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).
168
 
169
### DELETE /access_settings/whitelist/{rule_id}
170
 
171
 
172
```php
173
$rule_id = "test_url_param";
174
$response = $sg->client->access_settings()->whitelist()->_($rule_id)->delete();
175
echo $response->statusCode();
176
echo $response->body();
177
echo $response->headers();
178
```
179
<a name="alerts"></a>
180
# ALERTS
181
 
182
## Create a new Alert
183
 
184
**This endpoint allows you to create a new alert.**
185
 
186
Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics.
187
* Usage alerts allow you to set the threshold at which an alert will be sent.
188
* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".
189
 
190
For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).
191
 
192
### POST /alerts
193
 
194
 
195
```php
196
$request_body = json_decode('{
197
  "email_to": "example@example.com",
198
  "frequency": "daily",
199
  "type": "stats_notification"
200
}');
201
$response = $sg->client->alerts()->post($request_body);
202
echo $response->statusCode();
203
echo $response->body();
204
echo $response->headers();
205
```
206
## Retrieve all alerts
207
 
208
**This endpoint allows you to retieve all of your alerts.**
209
 
210
Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics.
211
* Usage alerts allow you to set the threshold at which an alert will be sent.
212
* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".
213
 
214
For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).
215
 
216
### GET /alerts
217
 
218
 
219
```php
220
$response = $sg->client->alerts()->get();
221
echo $response->statusCode();
222
echo $response->body();
223
echo $response->headers();
224
```
225
## Update an alert
226
 
227
**This endpoint allows you to update an alert.**
228
 
229
Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics.
230
* Usage alerts allow you to set the threshold at which an alert will be sent.
231
* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".
232
 
233
For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).
234
 
235
### PATCH /alerts/{alert_id}
236
 
237
 
238
```php
239
$request_body = json_decode('{
240
  "email_to": "example@example.com"
241
}');
242
$alert_id = "test_url_param";
243
$response = $sg->client->alerts()->_($alert_id)->patch($request_body);
244
echo $response->statusCode();
245
echo $response->body();
246
echo $response->headers();
247
```
248
## Retrieve a specific alert
249
 
250
**This endpoint allows you to retrieve a specific alert.**
251
 
252
Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics.
253
* Usage alerts allow you to set the threshold at which an alert will be sent.
254
* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".
255
 
256
For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).
257
 
258
### GET /alerts/{alert_id}
259
 
260
 
261
```php
262
$alert_id = "test_url_param";
263
$response = $sg->client->alerts()->_($alert_id)->get();
264
echo $response->statusCode();
265
echo $response->body();
266
echo $response->headers();
267
```
268
## Delete an alert
269
 
270
**This endpoint allows you to delete an alert.**
271
 
272
Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics.
273
* Usage alerts allow you to set the threshold at which an alert will be sent.
274
* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".
275
 
276
For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).
277
 
278
### DELETE /alerts/{alert_id}
279
 
280
 
281
```php
282
$alert_id = "test_url_param";
283
$response = $sg->client->alerts()->_($alert_id)->delete();
284
echo $response->statusCode();
285
echo $response->body();
286
echo $response->headers();
287
```
288
<a name="api_keys"></a>
289
# API KEYS
290
 
291
## Create API keys
292
 
293
**This enpoint allows you to create a new random API Key for the user.**
294
 
295
A JSON request body containing a "name" property is required. If number of maximum keys is reached, HTTP 403 will be returned.
296
 
297
There is a limit of 100 API Keys on your account.
298
 
299
The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).
300
 
301
See the [API Key Permissions List](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) for a list of all available scopes.
302
 
303
### POST /api_keys
304
 
305
 
306
```php
307
$request_body = json_decode('{
308
  "name": "My API Key",
309
  "sample": "data",
310
  "scopes": [
311
    "mail.send",
312
    "alerts.create",
313
    "alerts.read"
314
  ]
315
}');
316
$response = $sg->client->api_keys()->post($request_body);
317
echo $response->statusCode();
318
echo $response->body();
319
echo $response->headers();
320
```
321
## Retrieve all API Keys belonging to the authenticated user
322
 
323
**This endpoint allows you to retrieve all API Keys that belong to the authenticated user.**
324
 
325
The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).
326
 
327
### GET /api_keys
328
 
329
 
330
```php
331
$query_params = json_decode('{"limit": 1}');
332
$response = $sg->client->api_keys()->get(null, $query_params);
333
echo $response->statusCode();
334
echo $response->body();
335
echo $response->headers();
336
```
337
## Update the name & scopes of an API Key
338
 
339
**This endpoint allows you to update the name and scopes of a given API key.**
340
 
341
A JSON request body with a "name" property is required.
342
Most provide the list of all the scopes an api key should have.
343
 
344
The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).
345
 
346
 
347
### PUT /api_keys/{api_key_id}
348
 
349
 
350
```php
351
$request_body = json_decode('{
352
  "name": "A New Hope",
353
  "scopes": [
354
    "user.profile.read",
355
    "user.profile.update"
356
  ]
357
}');
358
$api_key_id = "test_url_param";
359
$response = $sg->client->api_keys()->_($api_key_id)->put($request_body);
360
echo $response->statusCode();
361
echo $response->body();
362
echo $response->headers();
363
```
364
## Update API keys
365
 
366
**This endpoint allows you to update the name of an existing API Key.**
367
 
368
A JSON request body with a "name" property is required.
369
 
370
The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).
371
 
372
## URI Parameters
373
 
374
| URI Parameter   | Type  | Required?  | Description  |
375
|---|---|---|---|
376
|api_key_id |string | required | The ID of the API Key you are updating.|
377
 
378
### PATCH /api_keys/{api_key_id}
379
 
380
 
381
```php
382
$request_body = json_decode('{
383
  "name": "A New Hope"
384
}');
385
$api_key_id = "test_url_param";
386
$response = $sg->client->api_keys()->_($api_key_id)->patch($request_body);
387
echo $response->statusCode();
388
echo $response->body();
389
echo $response->headers();
390
```
391
## Retrieve an existing API Key
392
 
393
**This endpoint allows you to retrieve a single api key.**
394
 
395
If the API Key ID does not exist an HTTP 404 will be returned.
396
 
397
### GET /api_keys/{api_key_id}
398
 
399
 
400
```php
401
$api_key_id = "test_url_param";
402
$response = $sg->client->api_keys()->_($api_key_id)->get();
403
echo $response->statusCode();
404
echo $response->body();
405
echo $response->headers();
406
```
407
## Delete API keys
408
 
409
**This endpoint allows you to revoke an existing API Key**
410
 
411
Authentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned.
412
 
413
The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).
414
 
415
## URI Parameters
416
 
417
| URI Parameter   | Type  | Required?  | Description  |
418
|---|---|---|---|
419
|api_key_id |string | required | The ID of the API Key you are deleting.|
420
 
421
### DELETE /api_keys/{api_key_id}
422
 
423
 
424
```php
425
$api_key_id = "test_url_param";
426
$response = $sg->client->api_keys()->_($api_key_id)->delete();
427
echo $response->statusCode();
428
echo $response->body();
429
echo $response->headers();
430
```
431
<a name="asm"></a>
432
# ASM
433
 
434
## Create a new suppression group
435
 
436
**This endpoint allows you to create a new suppression group.**
437
 
438
Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.
439
 
440
The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.
441
 
442
Each user can create up to 25 different suppression groups.
443
 
444
### POST /asm/groups
445
 
446
 
447
```php
448
$request_body = json_decode('{
449
  "description": "Suggestions for products our users might like.",
450
  "is_default": true,
451
  "name": "Product Suggestions"
452
}');
453
$response = $sg->client->asm()->groups()->post($request_body);
454
echo $response->statusCode();
455
echo $response->body();
456
echo $response->headers();
457
```
458
## Retrieve information about multiple suppression groups
459
 
460
**This endpoint allows you to retrieve information about multiple suppression groups.**
461
 
462
This endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append `&id=` followed by the group ID.
463
 
464
Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).
465
 
466
Suppression groups, or [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html), allow you to label a category of content that you regularly send. This gives your recipients the ability to opt out of a specific set of your email. For example, you might define a group for your transactional email, and one for your marketing email so that your users can continue recieving your transactional email witout having to receive your marketing content.
467
 
468
### GET /asm/groups
469
 
470
 
471
```php
472
$query_params = json_decode('{"id": 1}');
473
$response = $sg->client->asm()->groups()->get(null, $query_params);
474
echo $response->statusCode();
475
echo $response->body();
476
echo $response->headers();
477
```
478
## Update a suppression group.
479
 
480
**This endpoint allows you to update or change a suppression group.**
481
 
482
Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.
483
 
484
The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.
485
 
486
Each user can create up to 25 different suppression groups.
487
 
488
### PATCH /asm/groups/{group_id}
489
 
490
 
491
```php
492
$request_body = json_decode('{
493
  "description": "Suggestions for items our users might like.",
494
  "id": 103,
495
  "name": "Item Suggestions"
496
}');
497
$group_id = "test_url_param";
498
$response = $sg->client->asm()->groups()->_($group_id)->patch($request_body);
499
echo $response->statusCode();
500
echo $response->body();
501
echo $response->headers();
502
```
503
## Get information on a single suppression group.
504
 
505
**This endpoint allows you to retrieve a single suppression group.**
506
 
507
Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.
508
 
509
The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.
510
 
511
Each user can create up to 25 different suppression groups.
512
 
513
### GET /asm/groups/{group_id}
514
 
515
 
516
```php
517
$group_id = "test_url_param";
518
$response = $sg->client->asm()->groups()->_($group_id)->get();
519
echo $response->statusCode();
520
echo $response->body();
521
echo $response->headers();
522
```
523
## Delete a suppression group.
524
 
525
**This endpoint allows you to delete a suppression group.**
526
 
527
You can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the "one-click unsubscribe" option on an email associated with a deleted group, that recipient will be added to the global suppression list.
528
 
529
Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.
530
 
531
The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.
532
 
533
Each user can create up to 25 different suppression groups.
534
 
535
### DELETE /asm/groups/{group_id}
536
 
537
 
538
```php
539
$group_id = "test_url_param";
540
$response = $sg->client->asm()->groups()->_($group_id)->delete();
541
echo $response->statusCode();
542
echo $response->body();
543
echo $response->headers();
544
```
545
## Add suppressions to a suppression group
546
 
547
**This endpoint allows you to add email addresses to an unsubscribe group.**
548
 
549
If you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list.
550
 
551
Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.
552
 
553
### POST /asm/groups/{group_id}/suppressions
554
 
555
 
556
```php
557
$request_body = json_decode('{
558
  "recipient_emails": [
559
    "test1@example.com",
560
    "test2@example.com"
561
  ]
562
}');
563
$group_id = "test_url_param";
564
$response = $sg->client->asm()->groups()->_($group_id)->suppressions()->post($request_body);
565
echo $response->statusCode();
566
echo $response->body();
567
echo $response->headers();
568
```
569
## Retrieve all suppressions for a suppression group
570
 
571
**This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.**
572
 
573
Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.
574
 
575
### GET /asm/groups/{group_id}/suppressions
576
 
577
 
578
```php
579
$group_id = "test_url_param";
580
$response = $sg->client->asm()->groups()->_($group_id)->suppressions()->get();
581
echo $response->statusCode();
582
echo $response->body();
583
echo $response->headers();
584
```
585
## Search for suppressions within a group
586
 
587
**This endpoint allows you to search a suppression group for multiple suppressions.**
588
 
589
When given a list of email addresses and a group ID, this endpoint will return only the email addresses that have been unsubscribed from the given group.
590
 
591
Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).
592
 
593
### POST /asm/groups/{group_id}/suppressions/search
594
 
595
 
596
```php
597
$request_body = json_decode('{
598
  "recipient_emails": [
599
    "exists1@example.com",
600
    "exists2@example.com",
601
    "doesnotexists@example.com"
602
  ]
603
}');
604
$group_id = "test_url_param";
605
$response = $sg->client->asm()->groups()->_($group_id)->suppressions()->search()->post($request_body);
606
echo $response->statusCode();
607
echo $response->body();
608
echo $response->headers();
609
```
610
## Delete a suppression from a suppression group
611
 
612
**This endpoint allows you to remove a suppressed email address from the given suppression group.**
613
 
614
Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.
615
 
616
### DELETE /asm/groups/{group_id}/suppressions/{email}
617
 
618
 
619
```php
620
$group_id = "test_url_param";
621
$email = "test_url_param";
622
$response = $sg->client->asm()->groups()->_($group_id)->suppressions()->_($email)->delete();
623
echo $response->statusCode();
624
echo $response->body();
625
echo $response->headers();
626
```
627
## Retrieve all suppressions
628
 
629
**This endpoint allows you to retrieve a list of all suppressions.**
630
 
631
Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).
632
 
633
### GET /asm/suppressions
634
 
635
 
636
```php
637
$response = $sg->client->asm()->suppressions()->get();
638
echo $response->statusCode();
639
echo $response->body();
640
echo $response->headers();
641
```
642
## Add recipient addresses to the global suppression group.
643
 
644
**This endpoint allows you to add one or more email addresses to the global suppressions group.**
645
 
646
A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).
647
 
648
### POST /asm/suppressions/global
649
 
650
 
651
```php
652
$request_body = json_decode('{
653
  "recipient_emails": [
654
    "test1@example.com",
655
    "test2@example.com"
656
  ]
657
}');
658
$response = $sg->client->asm()->suppressions()->global()->post($request_body);
659
echo $response->statusCode();
660
echo $response->body();
661
echo $response->headers();
662
```
663
## Retrieve a Global Suppression
664
 
665
**This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.**
666
 
667
If the email address you include in the URL path parameter `{email}` is alreayd globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned.
668
 
669
A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).
670
 
671
### GET /asm/suppressions/global/{email}
672
 
673
 
674
```php
675
$email = "test_url_param";
676
$response = $sg->client->asm()->suppressions()->global()->_($email)->get();
677
echo $response->statusCode();
678
echo $response->body();
679
echo $response->headers();
680
```
681
## Delete a Global Suppression
682
 
683
**This endpoint allows you to remove an email address from the global suppressions group.**
684
 
685
A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).
686
 
687
### DELETE /asm/suppressions/global/{email}
688
 
689
 
690
```php
691
$email = "test_url_param";
692
$response = $sg->client->asm()->suppressions()->global()->_($email)->delete();
693
echo $response->statusCode();
694
echo $response->body();
695
echo $response->headers();
696
```
697
## Retrieve all suppression groups for an email address
698
 
699
**This endpoint returns the list of all groups that the given email address has been unsubscribed from.**
700
 
701
Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).
702
 
703
### GET /asm/suppressions/{email}
704
 
705
 
706
```php
707
$email = "test_url_param";
708
$response = $sg->client->asm()->suppressions()->_($email)->get();
709
echo $response->statusCode();
710
echo $response->body();
711
echo $response->headers();
712
```
713
<a name="browsers"></a>
714
# BROWSERS
715
 
716
## Retrieve email statistics by browser.
717
 
718
**This endpoint allows you to retrieve your email statistics segmented by browser type.**
719
 
720
**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.
721
 
722
Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).
723
 
724
### GET /browsers/stats
725
 
726
 
727
```php
728
$query_params = json_decode('{"end_date": "2016-04-01", "aggregated_by": "day", "browsers": "test_string", "limit": "test_string", "offset": "test_string", "start_date": "2016-01-01"}');
729
$response = $sg->client->browsers()->stats()->get(null, $query_params);
730
echo $response->statusCode();
731
echo $response->body();
732
echo $response->headers();
733
```
734
<a name="campaigns"></a>
735
# CAMPAIGNS
736
 
737
## Create a Campaign
738
 
739
**This endpoint allows you to create a campaign.**
740
 
741
Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.
742
 
743
Note: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign.
744
 
745
For more information:
746
 
747
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
748
 
749
### POST /campaigns
750
 
751
 
752
```php
753
$request_body = json_decode('{
754
  "categories": [
755
    "spring line"
756
  ],
757
  "custom_unsubscribe_url": "",
758
  "html_content": "<html><head><title></title></head><body><p>Check out our spring line!</p></body></html>",
759
  "ip_pool": "marketing",
760
  "list_ids": [
761
    110,
762
    124
763
  ],
764
  "plain_content": "Check out our spring line!",
765
  "segment_ids": [
766
    110
767
  ],
768
  "sender_id": 124451,
769
  "subject": "New Products for Spring!",
770
  "suppression_group_id": 42,
771
  "title": "March Newsletter"
772
}');
773
$response = $sg->client->campaigns()->post($request_body);
774
echo $response->statusCode();
775
echo $response->body();
776
echo $response->headers();
777
```
778
## Retrieve all Campaigns
779
 
780
**This endpoint allows you to retrieve a list of all of your campaigns.**
781
 
782
Returns campaigns in reverse order they were created (newest first).
783
 
784
Returns an empty array if no campaigns exist.
785
 
786
For more information:
787
 
788
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
789
 
790
### GET /campaigns
791
 
792
 
793
```php
794
$query_params = json_decode('{"limit": 1, "offset": 1}');
795
$response = $sg->client->campaigns()->get(null, $query_params);
796
echo $response->statusCode();
797
echo $response->body();
798
echo $response->headers();
799
```
800
## Update a Campaign
801
 
802
Update a campaign. This is especially useful if you only set up the campaign using POST /campaigns, but didn't set many of the parameters.
803
 
804
For more information:
805
 
806
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
807
 
808
### PATCH /campaigns/{campaign_id}
809
 
810
 
811
```php
812
$request_body = json_decode('{
813
  "categories": [
814
    "summer line"
815
  ],
816
  "html_content": "<html><head><title></title></head><body><p>Check out our summer line!</p></body></html>",
817
  "plain_content": "Check out our summer line!",
818
  "subject": "New Products for Summer!",
819
  "title": "May Newsletter"
820
}');
821
$campaign_id = "test_url_param";
822
$response = $sg->client->campaigns()->_($campaign_id)->patch($request_body);
823
echo $response->statusCode();
824
echo $response->body();
825
echo $response->headers();
826
```
827
## Retrieve a single campaign
828
 
829
**This endpoint allows you to retrieve a specific campaign.**
830
 
831
Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.
832
 
833
For more information:
834
 
835
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
836
 
837
### GET /campaigns/{campaign_id}
838
 
839
 
840
```php
841
$campaign_id = "test_url_param";
842
$response = $sg->client->campaigns()->_($campaign_id)->get();
843
echo $response->statusCode();
844
echo $response->body();
845
echo $response->headers();
846
```
847
## Delete a Campaign
848
 
849
**This endpoint allows you to delete a specific campaign.**
850
 
851
Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.
852
 
853
For more information:
854
 
855
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
856
 
857
### DELETE /campaigns/{campaign_id}
858
 
859
 
860
```php
861
$campaign_id = "test_url_param";
862
$response = $sg->client->campaigns()->_($campaign_id)->delete();
863
echo $response->statusCode();
864
echo $response->body();
865
echo $response->headers();
866
```
867
## Update a Scheduled Campaign
868
 
869
**This endpoint allows to you change the scheduled time and date for a campaign to be sent.**
870
 
871
For more information:
872
 
873
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
874
 
875
### PATCH /campaigns/{campaign_id}/schedules
876
 
877
 
878
```php
879
$request_body = json_decode('{
880
  "send_at": 1489451436
881
}');
882
$campaign_id = "test_url_param";
883
$response = $sg->client->campaigns()->_($campaign_id)->schedules()->patch($request_body);
884
echo $response->statusCode();
885
echo $response->body();
886
echo $response->headers();
887
```
888
## Schedule a Campaign
889
 
890
**This endpoint allows you to schedule a specific date and time for your campaign to be sent.**
891
 
892
For more information:
893
 
894
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
895
 
896
### POST /campaigns/{campaign_id}/schedules
897
 
898
 
899
```php
900
$request_body = json_decode('{
901
  "send_at": 1489771528
902
}');
903
$campaign_id = "test_url_param";
904
$response = $sg->client->campaigns()->_($campaign_id)->schedules()->post($request_body);
905
echo $response->statusCode();
906
echo $response->body();
907
echo $response->headers();
908
```
909
## View Scheduled Time of a Campaign
910
 
911
**This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent.**
912
 
913
For more information:
914
 
915
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
916
 
917
### GET /campaigns/{campaign_id}/schedules
918
 
919
 
920
```php
921
$campaign_id = "test_url_param";
922
$response = $sg->client->campaigns()->_($campaign_id)->schedules()->get();
923
echo $response->statusCode();
924
echo $response->body();
925
echo $response->headers();
926
```
927
## Unschedule a Scheduled Campaign
928
 
929
**This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.**
930
 
931
A successful unschedule will return a 204.
932
If the specified campaign is in the process of being sent, the only option is to cancel (a different method).
933
 
934
For more information:
935
 
936
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
937
 
938
### DELETE /campaigns/{campaign_id}/schedules
939
 
940
 
941
```php
942
$campaign_id = "test_url_param";
943
$response = $sg->client->campaigns()->_($campaign_id)->schedules()->delete();
944
echo $response->statusCode();
945
echo $response->body();
946
echo $response->headers();
947
```
948
## Send a Campaign
949
 
950
**This endpoint allows you to immediately send a campaign at the time you make the API call.**
951
 
952
Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed.
953
 
954
For more information:
955
 
956
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
957
 
958
### POST /campaigns/{campaign_id}/schedules/now
959
 
960
 
961
```php
962
$campaign_id = "test_url_param";
963
$response = $sg->client->campaigns()->_($campaign_id)->schedules()->now()->post();
964
echo $response->statusCode();
965
echo $response->body();
966
echo $response->headers();
967
```
968
## Send a Test Campaign
969
 
970
**This endpoint allows you to send a test campaign.**
971
 
972
To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"]
973
 
974
For more information:
975
 
976
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
977
 
978
### POST /campaigns/{campaign_id}/schedules/test
979
 
980
 
981
```php
982
$request_body = json_decode('{
983
  "to": "your.email@example.com"
984
}');
985
$campaign_id = "test_url_param";
986
$response = $sg->client->campaigns()->_($campaign_id)->schedules()->test()->post($request_body);
987
echo $response->statusCode();
988
echo $response->body();
989
echo $response->headers();
990
```
991
<a name="categories"></a>
992
# CATEGORIES
993
 
994
## Retrieve all categories
995
 
996
**This endpoint allows you to retrieve a list of all of your categories.**
997
 
998
Categories can help organize your email analytics by enabling you to tag emails by type or broad topic. You can define your own custom categories. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html).
999
 
1000
### GET /categories
1001
 
1002
 
1003
```php
1004
$query_params = json_decode('{"category": "test_string", "limit": 1, "offset": 1}');
1005
$response = $sg->client->categories()->get(null, $query_params);
1006
echo $response->statusCode();
1007
echo $response->body();
1008
echo $response->headers();
1009
```
1010
## Retrieve Email Statistics for Categories
1011
 
1012
**This endpoint allows you to retrieve all of your email statistics for each of your categories.**
1013
 
1014
If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.
1015
 
1016
Categories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html).
1017
 
1018
### GET /categories/stats
1019
 
1020
 
1021
```php
1022
$query_params = json_decode('{"end_date": "2016-04-01", "aggregated_by": "day", "limit": 1, "offset": 1, "start_date": "2016-01-01", "categories": "test_string"}');
1023
$response = $sg->client->categories()->stats()->get(null, $query_params);
1024
echo $response->statusCode();
1025
echo $response->body();
1026
echo $response->headers();
1027
```
1028
## Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]
1029
 
1030
**This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.**
1031
 
1032
If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.
1033
 
1034
Categories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html).
1035
 
1036
### GET /categories/stats/sums
1037
 
1038
 
1039
```php
1040
$query_params = json_decode('{"end_date": "2016-04-01", "aggregated_by": "day", "limit": 1, "sort_by_metric": "test_string", "offset": 1, "start_date": "2016-01-01", "sort_by_direction": "asc"}');
1041
$response = $sg->client->categories()->stats()->sums()->get(null, $query_params);
1042
echo $response->statusCode();
1043
echo $response->body();
1044
echo $response->headers();
1045
```
1046
<a name="clients"></a>
1047
# CLIENTS
1048
 
1049
## Retrieve email statistics by client type.
1050
 
1051
**This endpoint allows you to retrieve your email statistics segmented by client type.**
1052
 
1053
**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.
1054
 
1055
Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).
1056
 
1057
### GET /clients/stats
1058
 
1059
 
1060
```php
1061
$query_params = json_decode('{"aggregated_by": "day", "start_date": "2016-01-01", "end_date": "2016-04-01"}');
1062
$response = $sg->client->clients()->stats()->get(null, $query_params);
1063
echo $response->statusCode();
1064
echo $response->body();
1065
echo $response->headers();
1066
```
1067
## Retrieve stats by a specific client type.
1068
 
1069
**This endpoint allows you to retrieve your email statistics segmented by a specific client type.**
1070
 
1071
**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.
1072
 
1073
## Available Client Types
1074
- phone
1075
- tablet
1076
- webmail
1077
- desktop
1078
 
1079
Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).
1080
 
1081
### GET /clients/{client_type}/stats
1082
 
1083
 
1084
```php
1085
$query_params = json_decode('{"aggregated_by": "day", "start_date": "2016-01-01", "end_date": "2016-04-01"}');
1086
$client_type = "test_url_param";
1087
$response = $sg->client->clients()->_($client_type)->stats()->get(null, $query_params);
1088
echo $response->statusCode();
1089
echo $response->body();
1090
echo $response->headers();
1091
```
1092
<a name="contactdb"></a>
1093
# CONTACTDB
1094
 
1095
## Create a Custom Field
1096
 
1097
**This endpoint allows you to create a custom field.**
1098
 
1099
The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).
1100
 
1101
### POST /contactdb/custom_fields
1102
 
1103
 
1104
```php
1105
$request_body = json_decode('{
1106
  "name": "pet",
1107
  "type": "text"
1108
}');
1109
$response = $sg->client->contactdb()->custom_fields()->post($request_body);
1110
echo $response->statusCode();
1111
echo $response->body();
1112
echo $response->headers();
1113
```
1114
## Retrieve all custom fields
1115
 
1116
**This endpoint allows you to retrieve all custom fields.**
1117
 
1118
The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).
1119
 
1120
### GET /contactdb/custom_fields
1121
 
1122
 
1123
```php
1124
$response = $sg->client->contactdb()->custom_fields()->get();
1125
echo $response->statusCode();
1126
echo $response->body();
1127
echo $response->headers();
1128
```
1129
## Retrieve a Custom Field
1130
 
1131
**This endpoint allows you to retrieve a custom field by ID.**
1132
 
1133
The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).
1134
 
1135
### GET /contactdb/custom_fields/{custom_field_id}
1136
 
1137
 
1138
```php
1139
$custom_field_id = "test_url_param";
1140
$response = $sg->client->contactdb()->custom_fields()->_($custom_field_id)->get();
1141
echo $response->statusCode();
1142
echo $response->body();
1143
echo $response->headers();
1144
```
1145
## Delete a Custom Field
1146
 
1147
**This endpoint allows you to delete a custom field by ID.**
1148
 
1149
The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).
1150
 
1151
### DELETE /contactdb/custom_fields/{custom_field_id}
1152
 
1153
 
1154
```php
1155
$custom_field_id = "test_url_param";
1156
$response = $sg->client->contactdb()->custom_fields()->_($custom_field_id)->delete();
1157
echo $response->statusCode();
1158
echo $response->body();
1159
echo $response->headers();
1160
```
1161
## Create a List
1162
 
1163
**This endpoint allows you to create a list for your recipients.**
1164
 
1165
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1166
 
1167
### POST /contactdb/lists
1168
 
1169
 
1170
```php
1171
$request_body = json_decode('{
1172
  "name": "your list name"
1173
}');
1174
$response = $sg->client->contactdb()->lists()->post($request_body);
1175
echo $response->statusCode();
1176
echo $response->body();
1177
echo $response->headers();
1178
```
1179
## Retrieve all lists
1180
 
1181
**This endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned.**
1182
 
1183
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1184
 
1185
### GET /contactdb/lists
1186
 
1187
 
1188
```php
1189
$response = $sg->client->contactdb()->lists()->get();
1190
echo $response->statusCode();
1191
echo $response->body();
1192
echo $response->headers();
1193
```
1194
## Delete Multiple lists
1195
 
1196
**This endpoint allows you to delete multiple recipient lists.**
1197
 
1198
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1199
 
1200
### DELETE /contactdb/lists
1201
 
1202
 
1203
```php
1204
$request_body = json_decode('[
1205
  1,
1206
  2,
1207
  3,
1208
  4
1209
]');
1210
$response = $sg->client->contactdb()->lists()->delete($request_body);
1211
echo $response->statusCode();
1212
echo $response->body();
1213
echo $response->headers();
1214
```
1215
## Update a List
1216
 
1217
**This endpoint allows you to update the name of one of your recipient lists.**
1218
 
1219
 
1220
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1221
 
1222
### PATCH /contactdb/lists/{list_id}
1223
 
1224
 
1225
```php
1226
$request_body = json_decode('{
1227
  "name": "newlistname"
1228
}');
1229
$query_params = json_decode('{"list_id": 1}');
1230
$list_id = "test_url_param";
1231
$response = $sg->client->contactdb()->lists()->_($list_id)->patch($request_body, $query_params);
1232
echo $response->statusCode();
1233
echo $response->body();
1234
echo $response->headers();
1235
```
1236
## Retrieve a single list
1237
 
1238
This endpoint allows you to retrieve a single recipient list.
1239
 
1240
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1241
 
1242
### GET /contactdb/lists/{list_id}
1243
 
1244
 
1245
```php
1246
$query_params = json_decode('{"list_id": 1}');
1247
$list_id = "test_url_param";
1248
$response = $sg->client->contactdb()->lists()->_($list_id)->get(null, $query_params);
1249
echo $response->statusCode();
1250
echo $response->body();
1251
echo $response->headers();
1252
```
1253
## Delete a List
1254
 
1255
**This endpoint allows you to delete a specific recipient list with the given ID.**
1256
 
1257
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1258
 
1259
### DELETE /contactdb/lists/{list_id}
1260
 
1261
 
1262
```php
1263
$query_params = json_decode('{"delete_contacts": "true"}');
1264
$list_id = "test_url_param";
1265
$response = $sg->client->contactdb()->lists()->_($list_id)->delete(null, $query_params);
1266
echo $response->statusCode();
1267
echo $response->body();
1268
echo $response->headers();
1269
```
1270
## Add Multiple Recipients to a List
1271
 
1272
**This endpoint allows you to add multiple recipients to a list.**
1273
 
1274
Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they are returned from recipient endpoints.
1275
 
1276
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1277
 
1278
### POST /contactdb/lists/{list_id}/recipients
1279
 
1280
 
1281
```php
1282
$request_body = json_decode('[
1283
  "recipient_id1",
1284
  "recipient_id2"
1285
]');
1286
$list_id = "test_url_param";
1287
$response = $sg->client->contactdb()->lists()->_($list_id)->recipients()->post($request_body);
1288
echo $response->statusCode();
1289
echo $response->body();
1290
echo $response->headers();
1291
```
1292
## Retrieve all recipients on a List
1293
 
1294
**This endpoint allows you to retrieve all recipients on the list with the given ID.**
1295
 
1296
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1297
 
1298
### GET /contactdb/lists/{list_id}/recipients
1299
 
1300
 
1301
```php
1302
$query_params = json_decode('{"page": 1, "page_size": 1, "list_id": 1}');
1303
$list_id = "test_url_param";
1304
$response = $sg->client->contactdb()->lists()->_($list_id)->recipients()->get(null, $query_params);
1305
echo $response->statusCode();
1306
echo $response->body();
1307
echo $response->headers();
1308
```
1309
## Add a Single Recipient to a List
1310
 
1311
**This endpoint allows you to add a single recipient to a list.**
1312
 
1313
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1314
 
1315
### POST /contactdb/lists/{list_id}/recipients/{recipient_id}
1316
 
1317
 
1318
```php
1319
$list_id = "test_url_param";
1320
$recipient_id = "test_url_param";
1321
$response = $sg->client->contactdb()->lists()->_($list_id)->recipients()->_($recipient_id)->post();
1322
echo $response->statusCode();
1323
echo $response->body();
1324
echo $response->headers();
1325
```
1326
## Delete a Single Recipient from a Single List
1327
 
1328
**This endpoint allows you to delete a single recipient from a list.**
1329
 
1330
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1331
 
1332
### DELETE /contactdb/lists/{list_id}/recipients/{recipient_id}
1333
 
1334
 
1335
```php
1336
$query_params = json_decode('{"recipient_id": 1, "list_id": 1}');
1337
$list_id = "test_url_param";
1338
$recipient_id = "test_url_param";
1339
$response = $sg->client->contactdb()->lists()->_($list_id)->recipients()->_($recipient_id)->delete(null, $query_params);
1340
echo $response->statusCode();
1341
echo $response->body();
1342
echo $response->headers();
1343
```
1344
## Update Recipient
1345
 
1346
**This endpoint allows you to update one or more recipients.**
1347
 
1348
The body of an API call to this endpoint must include an array of one or more recipient objects.
1349
 
1350
It is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides.
1351
 
1352
The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).
1353
 
1354
### PATCH /contactdb/recipients
1355
 
1356
 
1357
```php
1358
$request_body = json_decode('[
1359
  {
1360
    "email": "jones@example.com",
1361
    "first_name": "Guy",
1362
    "last_name": "Jones"
1363
  }
1364
]');
1365
$response = $sg->client->contactdb()->recipients()->patch($request_body);
1366
echo $response->statusCode();
1367
echo $response->body();
1368
echo $response->headers();
1369
```
1370
## Add recipients
1371
 
1372
**This endpoint allows you to add a Marketing Campaigns recipient.**
1373
 
1374
It is of note that you can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides.
1375
 
1376
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1377
 
1378
### POST /contactdb/recipients
1379
 
1380
 
1381
```php
1382
$request_body = json_decode('[
1383
  {
1384
    "age": 25,
1385
    "email": "example@example.com",
1386
    "first_name": "",
1387
    "last_name": "User"
1388
  },
1389
  {
1390
    "age": 25,
1391
    "email": "example2@example.com",
1392
    "first_name": "Example",
1393
    "last_name": "User"
1394
  }
1395
]');
1396
$response = $sg->client->contactdb()->recipients()->post($request_body);
1397
echo $response->statusCode();
1398
echo $response->body();
1399
echo $response->headers();
1400
```
1401
## Retrieve recipients
1402
 
1403
**This endpoint allows you to retrieve all of your Marketing Campaigns recipients.**
1404
 
1405
Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of
1406
the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved.
1407
 
1408
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1409
 
1410
### GET /contactdb/recipients
1411
 
1412
 
1413
```php
1414
$query_params = json_decode('{"page": 1, "page_size": 1}');
1415
$response = $sg->client->contactdb()->recipients()->get(null, $query_params);
1416
echo $response->statusCode();
1417
echo $response->body();
1418
echo $response->headers();
1419
```
1420
## Delete Recipient
1421
 
1422
**This endpoint allows you to deletes one or more recipients.**
1423
 
1424
The body of an API call to this endpoint must include an array of recipient IDs of the recipients you want to delete.
1425
 
1426
The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).
1427
 
1428
### DELETE /contactdb/recipients
1429
 
1430
 
1431
```php
1432
$request_body = json_decode('[
1433
  "recipient_id1",
1434
  "recipient_id2"
1435
]');
1436
$response = $sg->client->contactdb()->recipients()->delete($request_body);
1437
echo $response->statusCode();
1438
echo $response->body();
1439
echo $response->headers();
1440
```
1441
## Retrieve the count of billable recipients
1442
 
1443
**This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.**
1444
 
1445
You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value.
1446
 
1447
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1448
 
1449
### GET /contactdb/recipients/billable_count
1450
 
1451
 
1452
```php
1453
$response = $sg->client->contactdb()->recipients()->billable_count()->get();
1454
echo $response->statusCode();
1455
echo $response->body();
1456
echo $response->headers();
1457
```
1458
## Retrieve a Count of Recipients
1459
 
1460
**This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.**
1461
 
1462
The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).
1463
 
1464
### GET /contactdb/recipients/count
1465
 
1466
 
1467
```php
1468
$response = $sg->client->contactdb()->recipients()->count()->get();
1469
echo $response->statusCode();
1470
echo $response->body();
1471
echo $response->headers();
1472
```
1473
## Retrieve recipients matching search criteria
1474
 
1475
**This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.**
1476
 
1477
field_name:
1478
 
1479
* is a variable that is substituted for your actual custom field name from your recipient.
1480
* Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200)
1481
* If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert
1482
your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to
1483
Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through
1484
Mon, 02 Feb 2015 23:59:59 GMT.
1485
 
1486
The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).
1487
 
1488
### GET /contactdb/recipients/search
1489
 
1490
 
1491
```php
1492
$query_params = json_decode('{"{field_name}": "test_string"}');
1493
$response = $sg->client->contactdb()->recipients()->search()->get(null, $query_params);
1494
echo $response->statusCode();
1495
echo $response->body();
1496
echo $response->headers();
1497
```
1498
## Retrieve a single recipient
1499
 
1500
**This endpoint allows you to retrieve a single recipient by ID from your contact database.**
1501
 
1502
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1503
 
1504
### GET /contactdb/recipients/{recipient_id}
1505
 
1506
 
1507
```php
1508
$recipient_id = "test_url_param";
1509
$response = $sg->client->contactdb()->recipients()->_($recipient_id)->get();
1510
echo $response->statusCode();
1511
echo $response->body();
1512
echo $response->headers();
1513
```
1514
## Delete a Recipient
1515
 
1516
**This endpoint allows you to delete a single recipient with the given ID from your contact database.**
1517
 
1518
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1519
 
1520
### DELETE /contactdb/recipients/{recipient_id}
1521
 
1522
 
1523
```php
1524
$recipient_id = "test_url_param";
1525
$response = $sg->client->contactdb()->recipients()->_($recipient_id)->delete();
1526
echo $response->statusCode();
1527
echo $response->body();
1528
echo $response->headers();
1529
```
1530
## Retrieve the lists that a recipient is on
1531
 
1532
**This endpoint allows you to retrieve the lists that a given recipient belongs to.**
1533
 
1534
Each recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to.
1535
 
1536
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1537
 
1538
### GET /contactdb/recipients/{recipient_id}/lists
1539
 
1540
 
1541
```php
1542
$recipient_id = "test_url_param";
1543
$response = $sg->client->contactdb()->recipients()->_($recipient_id)->lists()->get();
1544
echo $response->statusCode();
1545
echo $response->body();
1546
echo $response->headers();
1547
```
1548
## Retrieve reserved fields
1549
 
1550
**This endpoint allows you to list all fields that are reserved and can't be used for custom field names.**
1551
 
1552
The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).
1553
 
1554
### GET /contactdb/reserved_fields
1555
 
1556
 
1557
```php
1558
$response = $sg->client->contactdb()->reserved_fields()->get();
1559
echo $response->statusCode();
1560
echo $response->body();
1561
echo $response->headers();
1562
```
1563
## Create a Segment
1564
 
1565
**This endpoint allows you to create a segment.**
1566
 
1567
All recipients in your contactdb will be added or removed automatically depending on whether they match the criteria for this segment.
1568
 
1569
List Id:
1570
 
1571
* Send this to segment from an existing list
1572
* Don't send this in order to segment from your entire contactdb.
1573
 
1574
Valid operators for create and update depend on the type of the field you are segmenting:
1575
 
1576
* **Dates:** "eq", "ne", "lt" (before), "gt" (after)
1577
* **Text:** "contains", "eq" (is - matches the full field), "ne" (is not - matches any field where the entire field is not the condition value)
1578
* **Numbers:** "eq", "lt", "gt"
1579
* **Email Clicks and Opens:** "eq" (opened), "ne" (not opened)
1580
 
1581
Segment conditions using "eq" or "ne" for email clicks and opens should provide a "field" of either *clicks.campaign_identifier* or *opens.campaign_identifier*. The condition value should be a string containing the id of a completed campaign.
1582
 
1583
Segments may contain multiple condtions, joined by an "and" or "or" in the "and_or" field. The first condition in the conditions list must have an empty "and_or", and subsequent conditions must all specify an "and_or".
1584
 
1585
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1586
 
1587
For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).
1588
 
1589
### POST /contactdb/segments
1590
 
1591
 
1592
```php
1593
$request_body = json_decode('{
1594
  "conditions": [
1595
    {
1596
      "and_or": "",
1597
      "field": "last_name",
1598
      "operator": "eq",
1599
      "value": "Miller"
1600
    },
1601
    {
1602
      "and_or": "and",
1603
      "field": "last_clicked",
1604
      "operator": "gt",
1605
      "value": "01/02/2015"
1606
    },
1607
    {
1608
      "and_or": "or",
1609
      "field": "clicks.campaign_identifier",
1610
      "operator": "eq",
1611
      "value": "513"
1612
    }
1613
  ],
1614
  "list_id": 4,
1615
  "name": "Last Name Miller"
1616
}');
1617
$response = $sg->client->contactdb()->segments()->post($request_body);
1618
echo $response->statusCode();
1619
echo $response->body();
1620
echo $response->headers();
1621
```
1622
## Retrieve all segments
1623
 
1624
**This endpoint allows you to retrieve all of your segments.**
1625
 
1626
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1627
 
1628
For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).
1629
 
1630
### GET /contactdb/segments
1631
 
1632
 
1633
```php
1634
$response = $sg->client->contactdb()->segments()->get();
1635
echo $response->statusCode();
1636
echo $response->body();
1637
echo $response->headers();
1638
```
1639
## Update a segment
1640
 
1641
**This endpoint allows you to update a segment.**
1642
 
1643
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1644
 
1645
For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).
1646
 
1647
### PATCH /contactdb/segments/{segment_id}
1648
 
1649
 
1650
```php
1651
$request_body = json_decode('{
1652
  "conditions": [
1653
    {
1654
      "and_or": "",
1655
      "field": "last_name",
1656
      "operator": "eq",
1657
      "value": "Miller"
1658
    }
1659
  ],
1660
  "list_id": 5,
1661
  "name": "The Millers"
1662
}');
1663
$query_params = json_decode('{"segment_id": "test_string"}');
1664
$segment_id = "test_url_param";
1665
$response = $sg->client->contactdb()->segments()->_($segment_id)->patch($request_body, $query_params);
1666
echo $response->statusCode();
1667
echo $response->body();
1668
echo $response->headers();
1669
```
1670
## Retrieve a segment
1671
 
1672
**This endpoint allows you to retrieve a single segment with the given ID.**
1673
 
1674
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1675
 
1676
For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).
1677
 
1678
### GET /contactdb/segments/{segment_id}
1679
 
1680
 
1681
```php
1682
$query_params = json_decode('{"segment_id": 1}');
1683
$segment_id = "test_url_param";
1684
$response = $sg->client->contactdb()->segments()->_($segment_id)->get(null, $query_params);
1685
echo $response->statusCode();
1686
echo $response->body();
1687
echo $response->headers();
1688
```
1689
## Delete a segment
1690
 
1691
**This endpoint allows you to delete a segment from your recipients database.**
1692
 
1693
You also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment.
1694
 
1695
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1696
 
1697
For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).
1698
 
1699
### DELETE /contactdb/segments/{segment_id}
1700
 
1701
 
1702
```php
1703
$query_params = json_decode('{"delete_contacts": "true"}');
1704
$segment_id = "test_url_param";
1705
$response = $sg->client->contactdb()->segments()->_($segment_id)->delete(null, $query_params);
1706
echo $response->statusCode();
1707
echo $response->body();
1708
echo $response->headers();
1709
```
1710
## Retrieve recipients on a segment
1711
 
1712
**This endpoint allows you to retrieve all of the recipients in a segment with the given ID.**
1713
 
1714
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
1715
 
1716
For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).
1717
 
1718
### GET /contactdb/segments/{segment_id}/recipients
1719
 
1720
 
1721
```php
1722
$query_params = json_decode('{"page": 1, "page_size": 1}');
1723
$segment_id = "test_url_param";
1724
$response = $sg->client->contactdb()->segments()->_($segment_id)->recipients()->get(null, $query_params);
1725
echo $response->statusCode();
1726
echo $response->body();
1727
echo $response->headers();
1728
```
1729
<a name="devices"></a>
1730
# DEVICES
1731
 
1732
## Retrieve email statistics by device type.
1733
 
1734
**This endpoint allows you to retrieve your email statistics segmented by the device type.**
1735
 
1736
**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.
1737
 
1738
## Available Device Types
1739
| **Device** | **Description** | **Example** |
1740
|---|---|---|
1741
| Desktop | Email software on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. |
1742
| Webmail |	A web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com. |
1743
| Phone | A smart phone. | iPhone, Android, Blackberry, etc.
1744
| Tablet | A tablet computer. | iPad, android based tablet, etc. |
1745
| Other | An unrecognized device. |
1746
 
1747
Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).
1748
 
1749
### GET /devices/stats
1750
 
1751
 
1752
```php
1753
$query_params = json_decode('{"aggregated_by": "day", "limit": 1, "start_date": "2016-01-01", "end_date": "2016-04-01", "offset": 1}');
1754
$response = $sg->client->devices()->stats()->get(null, $query_params);
1755
echo $response->statusCode();
1756
echo $response->body();
1757
echo $response->headers();
1758
```
1759
<a name="geo"></a>
1760
# GEO
1761
 
1762
## Retrieve email statistics by country and state/province.
1763
 
1764
**This endpoint allows you to retrieve your email statistics segmented by country and state/province.**
1765
 
1766
**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.
1767
 
1768
Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).
1769
 
1770
### GET /geo/stats
1771
 
1772
 
1773
```php
1774
$query_params = json_decode('{"end_date": "2016-04-01", "country": "US", "aggregated_by": "day", "limit": 1, "offset": 1, "start_date": "2016-01-01"}');
1775
$response = $sg->client->geo()->stats()->get(null, $query_params);
1776
echo $response->statusCode();
1777
echo $response->body();
1778
echo $response->headers();
1779
```
1780
<a name="ips"></a>
1781
# IPS
1782
 
1783
## Retrieve all IP addresses
1784
 
1785
**This endpoint allows you to retrieve a list of all assigned and unassigned IPs.**
1786
 
1787
Response includes warm up status, pools, assigned subusers, and whitelabel info. The start_date field corresponds to when warmup started for that IP.
1788
 
1789
A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.
1790
 
1791
### GET /ips
1792
 
1793
 
1794
```php
1795
$query_params = json_decode('{"subuser": "test_string", "ip": "test_string", "limit": 1, "exclude_whitelabels": "true", "offset": 1}');
1796
$response = $sg->client->ips()->get(null, $query_params);
1797
echo $response->statusCode();
1798
echo $response->body();
1799
echo $response->headers();
1800
```
1801
## Retrieve all assigned IPs
1802
 
1803
**This endpoint allows you to retrieve only assigned IP addresses.**
1804
 
1805
A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.
1806
 
1807
### GET /ips/assigned
1808
 
1809
 
1810
```php
1811
$response = $sg->client->ips()->assigned()->get();
1812
echo $response->statusCode();
1813
echo $response->body();
1814
echo $response->headers();
1815
```
1816
## Create an IP pool.
1817
 
1818
**This endpoint allows you to create an IP pool.**
1819
 
1820
**Each user can create up to 10 different IP pools.**
1821
 
1822
IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.
1823
 
1824
IP pools can only be used with whitelabeled IP addresses.
1825
 
1826
If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.
1827
 
1828
### POST /ips/pools
1829
 
1830
 
1831
```php
1832
$request_body = json_decode('{
1833
  "name": "marketing"
1834
}');
1835
$response = $sg->client->ips()->pools()->post($request_body);
1836
echo $response->statusCode();
1837
echo $response->body();
1838
echo $response->headers();
1839
```
1840
## Retrieve all IP pools.
1841
 
1842
**This endpoint allows you to retreive all of your IP pools.**
1843
 
1844
IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.
1845
 
1846
IP pools can only be used with whitelabeled IP addresses.
1847
 
1848
If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.
1849
 
1850
### GET /ips/pools
1851
 
1852
 
1853
```php
1854
$response = $sg->client->ips()->pools()->get();
1855
echo $response->statusCode();
1856
echo $response->body();
1857
echo $response->headers();
1858
```
1859
## Update an IP pools name.
1860
 
1861
**This endpoint allows you to update the name of an IP pool.**
1862
 
1863
IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.
1864
 
1865
IP pools can only be used with whitelabeled IP addresses.
1866
 
1867
If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.
1868
 
1869
### PUT /ips/pools/{pool_name}
1870
 
1871
 
1872
```php
1873
$request_body = json_decode('{
1874
  "name": "new_pool_name"
1875
}');
1876
$pool_name = "test_url_param";
1877
$response = $sg->client->ips()->pools()->_($pool_name)->put($request_body);
1878
echo $response->statusCode();
1879
echo $response->body();
1880
echo $response->headers();
1881
```
1882
## Retrieve all IPs in a specified pool.
1883
 
1884
**This endpoint allows you to list all of the IP addresses that are in a specific IP pool.**
1885
 
1886
IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.
1887
 
1888
IP pools can only be used with whitelabeled IP addresses.
1889
 
1890
If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.
1891
 
1892
### GET /ips/pools/{pool_name}
1893
 
1894
 
1895
```php
1896
$pool_name = "test_url_param";
1897
$response = $sg->client->ips()->pools()->_($pool_name)->get();
1898
echo $response->statusCode();
1899
echo $response->body();
1900
echo $response->headers();
1901
```
1902
## Delete an IP pool.
1903
 
1904
**This endpoint allows you to delete an IP pool.**
1905
 
1906
IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.
1907
 
1908
IP pools can only be used with whitelabeled IP addresses.
1909
 
1910
If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.
1911
 
1912
### DELETE /ips/pools/{pool_name}
1913
 
1914
 
1915
```php
1916
$pool_name = "test_url_param";
1917
$response = $sg->client->ips()->pools()->_($pool_name)->delete();
1918
echo $response->statusCode();
1919
echo $response->body();
1920
echo $response->headers();
1921
```
1922
## Add an IP address to a pool
1923
 
1924
**This endpoint allows you to add an IP address to an IP pool.**
1925
 
1926
You can add the same IP address to multiple pools. It may take up to 60 seconds for your IP address to be added to a pool after your request is made.
1927
 
1928
A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.
1929
 
1930
### POST /ips/pools/{pool_name}/ips
1931
 
1932
 
1933
```php
1934
$request_body = json_decode('{
1935
  "ip": "0.0.0.0"
1936
}');
1937
$pool_name = "test_url_param";
1938
$response = $sg->client->ips()->pools()->_($pool_name)->ips()->post($request_body);
1939
echo $response->statusCode();
1940
echo $response->body();
1941
echo $response->headers();
1942
```
1943
## Remove an IP address from a pool.
1944
 
1945
**This endpoint allows you to remove an IP address from an IP pool.**
1946
 
1947
The same IP address can be added to multiple IP pools.
1948
 
1949
A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.
1950
 
1951
### DELETE /ips/pools/{pool_name}/ips/{ip}
1952
 
1953
 
1954
```php
1955
$pool_name = "test_url_param";
1956
$ip = "test_url_param";
1957
$response = $sg->client->ips()->pools()->_($pool_name)->ips()->_($ip)->delete();
1958
echo $response->statusCode();
1959
echo $response->body();
1960
echo $response->headers();
1961
```
1962
## Add an IP to warmup
1963
 
1964
**This endpoint allows you to enter an IP address into warmup mode.**
1965
 
1966
SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup.
1967
 
1968
For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html).
1969
 
1970
### POST /ips/warmup
1971
 
1972
 
1973
```php
1974
$request_body = json_decode('{
1975
  "ip": "0.0.0.0"
1976
}');
1977
$response = $sg->client->ips()->warmup()->post($request_body);
1978
echo $response->statusCode();
1979
echo $response->body();
1980
echo $response->headers();
1981
```
1982
## Retrieve all IPs currently in warmup
1983
 
1984
**This endpoint allows you to retrieve all of your IP addresses that are currently warming up.**
1985
 
1986
SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup.
1987
 
1988
For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html).
1989
 
1990
### GET /ips/warmup
1991
 
1992
 
1993
```php
1994
$response = $sg->client->ips()->warmup()->get();
1995
echo $response->statusCode();
1996
echo $response->body();
1997
echo $response->headers();
1998
```
1999
## Retrieve warmup status for a specific IP address
2000
 
2001
**This endpoint allows you to retrieve the warmup status for a specific IP address.**
2002
 
2003
SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup.
2004
 
2005
For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html).
2006
 
2007
### GET /ips/warmup/{ip_address}
2008
 
2009
 
2010
```php
2011
$ip_address = "test_url_param";
2012
$response = $sg->client->ips()->warmup()->_($ip_address)->get();
2013
echo $response->statusCode();
2014
echo $response->body();
2015
echo $response->headers();
2016
```
2017
## Remove an IP from warmup
2018
 
2019
**This endpoint allows you to remove an IP address from warmup mode.**
2020
 
2021
SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup.
2022
 
2023
For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html).
2024
 
2025
### DELETE /ips/warmup/{ip_address}
2026
 
2027
 
2028
```php
2029
$ip_address = "test_url_param";
2030
$response = $sg->client->ips()->warmup()->_($ip_address)->delete();
2031
echo $response->statusCode();
2032
echo $response->body();
2033
echo $response->headers();
2034
```
2035
## Retrieve all IP pools an IP address belongs to
2036
 
2037
**This endpoint allows you to see which IP pools a particular IP address has been added to.**
2038
 
2039
The same IP address can be added to multiple IP pools.
2040
 
2041
A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.
2042
 
2043
### GET /ips/{ip_address}
2044
 
2045
 
2046
```php
2047
$ip_address = "test_url_param";
2048
$response = $sg->client->ips()->_($ip_address)->get();
2049
echo $response->statusCode();
2050
echo $response->body();
2051
echo $response->headers();
2052
```
2053
<a name="mail"></a>
2054
# MAIL
2055
 
2056
## Create a batch ID
2057
 
2058
**This endpoint allows you to generate a new batch ID. This batch ID can be associated with scheduled sends via the mail/send endpoint.**
2059
 
2060
If you set the SMTPAPI header `batch_id`, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint.
2061
 
2062
More Information:
2063
 
2064
* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)
2065
 
2066
### POST /mail/batch
2067
 
2068
 
2069
```php
2070
$response = $sg->client->mail()->batch()->post();
2071
echo $response->statusCode();
2072
echo $response->body();
2073
echo $response->headers();
2074
```
2075
## Validate batch ID
2076
 
2077
**This endpoint allows you to validate a batch ID.**
2078
 
2079
If you set the SMTPAPI header `batch_id`, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint.
2080
 
2081
More Information:
2082
 
2083
* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)
2084
 
2085
### GET /mail/batch/{batch_id}
2086
 
2087
 
2088
```php
2089
$batch_id = "test_url_param";
2090
$response = $sg->client->mail()->batch()->_($batch_id)->get();
2091
echo $response->statusCode();
2092
echo $response->body();
2093
echo $response->headers();
2094
```
2095
## v3 Mail Send
2096
 
2097
This endpoint allows you to send email over SendGrids v3 Web API, the most recent version of our API. If you are looking for documentation about the v2 Mail Send endpoint, please see our [v2 API Reference](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).
2098
 
2099
* Top level parameters are referred to as "global".
2100
* Individual fields within the personalizations array will override any other global, or message level, parameters that are defined outside of personalizations.
2101
 
2102
For an overview of the v3 Mail Send endpoint, please visit our [v3 API Reference](https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/index.html)
2103
 
2104
For more detailed information about how to use the v3 Mail Send endpoint, please visit our [Classroom](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/index.html).
2105
 
2106
### POST /mail/send
2107
 
2108
This endpoint has a helper, check it out [here](https://github.com/sendgrid/sendgrid-php/blob/master/lib/helpers/mail/README.md).
2109
 
2110
```php
2111
$request_body = json_decode('{
2112
  "asm": {
2113
    "group_id": 1,
2114
    "groups_to_display": [
2115
      1,
2116
      2,
2117
      3
2118
    ]
2119
  },
2120
  "attachments": [
2121
    {
2122
      "content": "[BASE64 encoded content block here]",
2123
      "content_id": "ii_139db99fdb5c3704",
2124
      "disposition": "inline",
2125
      "filename": "file1.jpg",
2126
      "name": "file1",
2127
      "type": "jpg"
2128
    }
2129
  ],
2130
  "batch_id": "[YOUR BATCH ID GOES HERE]",
2131
  "categories": [
2132
    "category1",
2133
    "category2"
2134
  ],
2135
  "content": [
2136
    {
2137
      "type": "text/html",
2138
      "value": "<html><p>Hello, world!</p><img src=[CID GOES HERE]></img></html>"
2139
    }
2140
  ],
2141
  "custom_args": {
2142
    "New Argument 1": "New Value 1",
2143
    "activationAttempt": "1",
2144
    "customerAccountNumber": "[CUSTOMER ACCOUNT NUMBER GOES HERE]"
2145
  },
2146
  "from": {
2147
    "email": "sam.smith@example.com",
2148
    "name": "Sam Smith"
2149
  },
2150
  "headers": {},
2151
  "ip_pool_name": "[YOUR POOL NAME GOES HERE]",
2152
  "mail_settings": {
2153
    "bcc": {
2154
      "email": "ben.doe@example.com",
2155
      "enable": true
2156
    },
2157
    "bypass_list_management": {
2158
      "enable": true
2159
    },
2160
    "footer": {
2161
      "enable": true,
2162
      "html": "<p>Thanks</br>The SendGrid Team</p>",
2163
      "text": "Thanks,/n The SendGrid Team"
2164
    },
2165
    "sandbox_mode": {
2166
      "enable": false
2167
    },
2168
    "spam_check": {
2169
      "enable": true,
2170
      "post_to_url": "http://example.com/compliance",
2171
      "threshold": 3
2172
    }
2173
  },
2174
  "personalizations": [
2175
    {
2176
      "bcc": [
2177
        {
2178
          "email": "sam.doe@example.com",
2179
          "name": "Sam Doe"
2180
        }
2181
      ],
2182
      "cc": [
2183
        {
2184
          "email": "jane.doe@example.com",
2185
          "name": "Jane Doe"
2186
        }
2187
      ],
2188
      "custom_args": {
2189
        "New Argument 1": "New Value 1",
2190
        "activationAttempt": "1",
2191
        "customerAccountNumber": "[CUSTOMER ACCOUNT NUMBER GOES HERE]"
2192
      },
2193
      "headers": {
2194
        "X-Accept-Language": "en",
2195
        "X-Mailer": "MyApp"
2196
      },
2197
      "send_at": 1409348513,
2198
      "subject": "Hello, World!",
2199
      "substitutions": {
2200
        "id": "substitutions",
2201
        "type": "object"
2202
      },
2203
      "to": [
2204
        {
2205
          "email": "john.doe@example.com",
2206
          "name": "John Doe"
2207
        }
2208
      ]
2209
    }
2210
  ],
2211
  "reply_to": {
2212
    "email": "sam.smith@example.com",
2213
    "name": "Sam Smith"
2214
  },
2215
  "sections": {
2216
    "section": {
2217
      ":sectionName1": "section 1 text",
2218
      ":sectionName2": "section 2 text"
2219
    }
2220
  },
2221
  "send_at": 1409348513,
2222
  "subject": "Hello, World!",
2223
  "template_id": "[YOUR TEMPLATE ID GOES HERE]",
2224
  "tracking_settings": {
2225
    "click_tracking": {
2226
      "enable": true,
2227
      "enable_text": true
2228
    },
2229
    "ganalytics": {
2230
      "enable": true,
2231
      "utm_campaign": "[NAME OF YOUR REFERRER SOURCE]",
2232
      "utm_content": "[USE THIS SPACE TO DIFFERENTIATE YOUR EMAIL FROM ADS]",
2233
      "utm_medium": "[NAME OF YOUR MARKETING MEDIUM e.g. email]",
2234
      "utm_name": "[NAME OF YOUR CAMPAIGN]",
2235
      "utm_term": "[IDENTIFY PAID KEYWORDS HERE]"
2236
    },
2237
    "open_tracking": {
2238
      "enable": true,
2239
      "substitution_tag": "%opentrack"
2240
    },
2241
    "subscription_tracking": {
2242
      "enable": true,
2243
      "html": "If you would like to unsubscribe and stop receiving these emails <% clickhere %>.",
2244
      "substitution_tag": "<%click here%>",
2245
      "text": "If you would like to unsubscribe and stop receiveing these emails <% click here %>."
2246
    }
2247
  }
2248
}');
2249
$response = $sg->client->mail()->send()->post($request_body);
2250
echo $response->statusCode();
2251
echo $response->body();
2252
echo $response->headers();
2253
```
2254
<a name="mail_settings"></a>
2255
# MAIL SETTINGS
2256
 
2257
## Retrieve all mail settings
2258
 
2259
**This endpoint allows you to retrieve a list of all mail settings.**
2260
 
2261
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2262
 
2263
### GET /mail_settings
2264
 
2265
 
2266
```php
2267
$query_params = json_decode('{"limit": 1, "offset": 1}');
2268
$response = $sg->client->mail_settings()->get(null, $query_params);
2269
echo $response->statusCode();
2270
echo $response->body();
2271
echo $response->headers();
2272
```
2273
## Update address whitelist mail settings
2274
 
2275
**This endpoint allows you to update your current email address whitelist settings.**
2276
 
2277
The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain example.com, and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions.
2278
 
2279
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2280
 
2281
### PATCH /mail_settings/address_whitelist
2282
 
2283
 
2284
```php
2285
$request_body = json_decode('{
2286
  "enabled": true,
2287
  "list": [
2288
    "email1@example.com",
2289
    "example.com"
2290
  ]
2291
}');
2292
$response = $sg->client->mail_settings()->address_whitelist()->patch($request_body);
2293
echo $response->statusCode();
2294
echo $response->body();
2295
echo $response->headers();
2296
```
2297
## Retrieve address whitelist mail settings
2298
 
2299
**This endpoint allows you to retrieve your current email address whitelist settings.**
2300
 
2301
The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain example.com, and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions.
2302
 
2303
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2304
 
2305
### GET /mail_settings/address_whitelist
2306
 
2307
 
2308
```php
2309
$response = $sg->client->mail_settings()->address_whitelist()->get();
2310
echo $response->statusCode();
2311
echo $response->body();
2312
echo $response->headers();
2313
```
2314
## Update BCC mail settings
2315
 
2316
**This endpoint allows you to update your current BCC mail settings.**
2317
 
2318
When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules.
2319
 
2320
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2321
 
2322
### PATCH /mail_settings/bcc
2323
 
2324
 
2325
```php
2326
$request_body = json_decode('{
2327
  "email": "email@example.com",
2328
  "enabled": false
2329
}');
2330
$response = $sg->client->mail_settings()->bcc()->patch($request_body);
2331
echo $response->statusCode();
2332
echo $response->body();
2333
echo $response->headers();
2334
```
2335
## Retrieve all BCC mail settings
2336
 
2337
**This endpoint allows you to retrieve your current BCC mail settings.**
2338
 
2339
When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules.
2340
 
2341
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2342
 
2343
### GET /mail_settings/bcc
2344
 
2345
 
2346
```php
2347
$response = $sg->client->mail_settings()->bcc()->get();
2348
echo $response->statusCode();
2349
echo $response->body();
2350
echo $response->headers();
2351
```
2352
## Update bounce purge mail settings
2353
 
2354
**This endpoint allows you to update your current bounce purge settings.**
2355
 
2356
This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists.
2357
 
2358
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2359
 
2360
### PATCH /mail_settings/bounce_purge
2361
 
2362
 
2363
```php
2364
$request_body = json_decode('{
2365
  "enabled": true,
2366
  "hard_bounces": 5,
2367
  "soft_bounces": 5
2368
}');
2369
$response = $sg->client->mail_settings()->bounce_purge()->patch($request_body);
2370
echo $response->statusCode();
2371
echo $response->body();
2372
echo $response->headers();
2373
```
2374
## Retrieve bounce purge mail settings
2375
 
2376
**This endpoint allows you to retrieve your current bounce purge settings.**
2377
 
2378
This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists.
2379
 
2380
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2381
 
2382
### GET /mail_settings/bounce_purge
2383
 
2384
 
2385
```php
2386
$response = $sg->client->mail_settings()->bounce_purge()->get();
2387
echo $response->statusCode();
2388
echo $response->body();
2389
echo $response->headers();
2390
```
2391
## Update footer mail settings
2392
 
2393
**This endpoint allows you to update your current Footer mail settings.**
2394
 
2395
The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails.
2396
 
2397
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2398
 
2399
### PATCH /mail_settings/footer
2400
 
2401
 
2402
```php
2403
$request_body = json_decode('{
2404
  "enabled": true,
2405
  "html_content": "...",
2406
  "plain_content": "..."
2407
}');
2408
$response = $sg->client->mail_settings()->footer()->patch($request_body);
2409
echo $response->statusCode();
2410
echo $response->body();
2411
echo $response->headers();
2412
```
2413
## Retrieve footer mail settings
2414
 
2415
**This endpoint allows you to retrieve your current Footer mail settings.**
2416
 
2417
The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails.
2418
 
2419
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2420
 
2421
### GET /mail_settings/footer
2422
 
2423
 
2424
```php
2425
$response = $sg->client->mail_settings()->footer()->get();
2426
echo $response->statusCode();
2427
echo $response->body();
2428
echo $response->headers();
2429
```
2430
## Update forward bounce mail settings
2431
 
2432
**This endpoint allows you to update your current bounce forwarding mail settings.**
2433
 
2434
Activating this setting allows you to specify an email address to which bounce reports are forwarded.
2435
 
2436
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2437
 
2438
### PATCH /mail_settings/forward_bounce
2439
 
2440
 
2441
```php
2442
$request_body = json_decode('{
2443
  "email": "example@example.com",
2444
  "enabled": true
2445
}');
2446
$response = $sg->client->mail_settings()->forward_bounce()->patch($request_body);
2447
echo $response->statusCode();
2448
echo $response->body();
2449
echo $response->headers();
2450
```
2451
## Retrieve forward bounce mail settings
2452
 
2453
**This endpoint allows you to retrieve your current bounce forwarding mail settings.**
2454
 
2455
Activating this setting allows you to specify an email address to which bounce reports are forwarded.
2456
 
2457
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2458
 
2459
### GET /mail_settings/forward_bounce
2460
 
2461
 
2462
```php
2463
$response = $sg->client->mail_settings()->forward_bounce()->get();
2464
echo $response->statusCode();
2465
echo $response->body();
2466
echo $response->headers();
2467
```
2468
## Update forward spam mail settings
2469
 
2470
**This endpoint allows you to update your current Forward Spam mail settings.**
2471
 
2472
Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded.
2473
 
2474
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2475
 
2476
### PATCH /mail_settings/forward_spam
2477
 
2478
 
2479
```php
2480
$request_body = json_decode('{
2481
  "email": "",
2482
  "enabled": false
2483
}');
2484
$response = $sg->client->mail_settings()->forward_spam()->patch($request_body);
2485
echo $response->statusCode();
2486
echo $response->body();
2487
echo $response->headers();
2488
```
2489
## Retrieve forward spam mail settings
2490
 
2491
**This endpoint allows you to retrieve your current Forward Spam mail settings.**
2492
 
2493
Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded.
2494
 
2495
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2496
 
2497
### GET /mail_settings/forward_spam
2498
 
2499
 
2500
```php
2501
$response = $sg->client->mail_settings()->forward_spam()->get();
2502
echo $response->statusCode();
2503
echo $response->body();
2504
echo $response->headers();
2505
```
2506
## Update plain content mail settings
2507
 
2508
**This endpoint allows you to update your current Plain Content mail settings.**
2509
 
2510
The plain content setting will automatically convert any plain text emails that you send to HTML before sending.
2511
 
2512
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2513
 
2514
### PATCH /mail_settings/plain_content
2515
 
2516
 
2517
```php
2518
$request_body = json_decode('{
2519
  "enabled": false
2520
}');
2521
$response = $sg->client->mail_settings()->plain_content()->patch($request_body);
2522
echo $response->statusCode();
2523
echo $response->body();
2524
echo $response->headers();
2525
```
2526
## Retrieve plain content mail settings
2527
 
2528
**This endpoint allows you to retrieve your current Plain Content mail settings.**
2529
 
2530
The plain content setting will automatically convert any plain text emails that you send to HTML before sending.
2531
 
2532
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2533
 
2534
### GET /mail_settings/plain_content
2535
 
2536
 
2537
```php
2538
$response = $sg->client->mail_settings()->plain_content()->get();
2539
echo $response->statusCode();
2540
echo $response->body();
2541
echo $response->headers();
2542
```
2543
## Update spam check mail settings
2544
 
2545
**This endpoint allows you to update your current spam checker mail settings.**
2546
 
2547
The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold.
2548
 
2549
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2550
 
2551
### PATCH /mail_settings/spam_check
2552
 
2553
 
2554
```php
2555
$request_body = json_decode('{
2556
  "enabled": true,
2557
  "max_score": 5,
2558
  "url": "url"
2559
}');
2560
$response = $sg->client->mail_settings()->spam_check()->patch($request_body);
2561
echo $response->statusCode();
2562
echo $response->body();
2563
echo $response->headers();
2564
```
2565
## Retrieve spam check mail settings
2566
 
2567
**This endpoint allows you to retrieve your current Spam Checker mail settings.**
2568
 
2569
The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold.
2570
 
2571
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2572
 
2573
### GET /mail_settings/spam_check
2574
 
2575
 
2576
```php
2577
$response = $sg->client->mail_settings()->spam_check()->get();
2578
echo $response->statusCode();
2579
echo $response->body();
2580
echo $response->headers();
2581
```
2582
## Update template mail settings
2583
 
2584
**This endpoint allows you to update your current legacy email template settings.**
2585
 
2586
This setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).
2587
 
2588
The legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages.
2589
 
2590
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2591
 
2592
### PATCH /mail_settings/template
2593
 
2594
 
2595
```php
2596
$request_body = json_decode('{
2597
  "enabled": true,
2598
  "html_content": "<% body %>"
2599
}');
2600
$response = $sg->client->mail_settings()->template()->patch($request_body);
2601
echo $response->statusCode();
2602
echo $response->body();
2603
echo $response->headers();
2604
```
2605
## Retrieve legacy template mail settings
2606
 
2607
**This endpoint allows you to retrieve your current legacy email template settings.**
2608
 
2609
This setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).
2610
 
2611
The legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages.
2612
 
2613
Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).
2614
 
2615
### GET /mail_settings/template
2616
 
2617
 
2618
```php
2619
$response = $sg->client->mail_settings()->template()->get();
2620
echo $response->statusCode();
2621
echo $response->body();
2622
echo $response->headers();
2623
```
2624
<a name="mailbox_providers"></a>
2625
# MAILBOX PROVIDERS
2626
 
2627
## Retrieve email statistics by mailbox provider.
2628
 
2629
**This endpoint allows you to retrieve your email statistics segmented by recipient mailbox provider.**
2630
 
2631
**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.
2632
 
2633
Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).
2634
 
2635
### GET /mailbox_providers/stats
2636
 
2637
 
2638
```php
2639
$query_params = json_decode('{"end_date": "2016-04-01", "mailbox_providers": "test_string", "aggregated_by": "day", "limit": 1, "offset": 1, "start_date": "2016-01-01"}');
2640
$response = $sg->client->mailbox_providers()->stats()->get(null, $query_params);
2641
echo $response->statusCode();
2642
echo $response->body();
2643
echo $response->headers();
2644
```
2645
<a name="partner_settings"></a>
2646
# PARTNER SETTINGS
2647
 
2648
## Returns a list of all partner settings.
2649
 
2650
**This endpoint allows you to retrieve a list of all partner settings that you can enable.**
2651
 
2652
Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html).
2653
 
2654
### GET /partner_settings
2655
 
2656
 
2657
```php
2658
$query_params = json_decode('{"limit": 1, "offset": 1}');
2659
$response = $sg->client->partner_settings()->get(null, $query_params);
2660
echo $response->statusCode();
2661
echo $response->body();
2662
echo $response->headers();
2663
```
2664
## Updates New Relic partner settings.
2665
 
2666
**This endpoint allows you to update or change your New Relic partner settings.**
2667
 
2668
Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html).
2669
 
2670
By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html).
2671
 
2672
### PATCH /partner_settings/new_relic
2673
 
2674
 
2675
```php
2676
$request_body = json_decode('{
2677
  "enable_subuser_statistics": true,
2678
  "enabled": true,
2679
  "license_key": ""
2680
}');
2681
$response = $sg->client->partner_settings()->new_relic()->patch($request_body);
2682
echo $response->statusCode();
2683
echo $response->body();
2684
echo $response->headers();
2685
```
2686
## Returns all New Relic partner settings.
2687
 
2688
**This endpoint allows you to retrieve your current New Relic partner settings.**
2689
 
2690
Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html).
2691
 
2692
By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html).
2693
 
2694
### GET /partner_settings/new_relic
2695
 
2696
 
2697
```php
2698
$response = $sg->client->partner_settings()->new_relic()->get();
2699
echo $response->statusCode();
2700
echo $response->body();
2701
echo $response->headers();
2702
```
2703
<a name="scopes"></a>
2704
# SCOPES
2705
 
2706
## Retrieve a list of scopes for which this user has access.
2707
 
2708
**This endpoint returns a list of all scopes that this user has access to.**
2709
 
2710
API Keys can be used to authenticate the use of [SendGrids v3 Web API](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html), or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. For a more detailed explanation of how you can use API Key permissios, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/api_keys.html#-API-Key-Permissions) or [Classroom](https://sendgrid.com/docs/Classroom/Basics/API/api_key_permissions.html).
2711
 
2712
### GET /scopes
2713
 
2714
 
2715
```php
2716
$response = $sg->client->scopes()->get();
2717
echo $response->statusCode();
2718
echo $response->body();
2719
echo $response->headers();
2720
```
2721
<a name="senders"></a>
2722
# SENDERS
2723
 
2724
## Create a Sender Identity
2725
 
2726
**This endpoint allows you to create a new sender identity.**
2727
 
2728
*You may create up to 100 unique sender identities.*
2729
 
2730
Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`.
2731
 
2732
### POST /senders
2733
 
2734
 
2735
```php
2736
$request_body = json_decode('{
2737
  "address": "123 Elm St.",
2738
  "address_2": "Apt. 456",
2739
  "city": "Denver",
2740
  "country": "United States",
2741
  "from": {
2742
    "email": "from@example.com",
2743
    "name": "Example INC"
2744
  },
2745
  "nickname": "My Sender ID",
2746
  "reply_to": {
2747
    "email": "replyto@example.com",
2748
    "name": "Example INC"
2749
  },
2750
  "state": "Colorado",
2751
  "zip": "80202"
2752
}');
2753
$response = $sg->client->senders()->post($request_body);
2754
echo $response->statusCode();
2755
echo $response->body();
2756
echo $response->headers();
2757
```
2758
## Get all Sender Identities
2759
 
2760
**This endpoint allows you to retrieve a list of all sender identities that have been created for your account.**
2761
 
2762
Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`.
2763
 
2764
### GET /senders
2765
 
2766
 
2767
```php
2768
$response = $sg->client->senders()->get();
2769
echo $response->statusCode();
2770
echo $response->body();
2771
echo $response->headers();
2772
```
2773
## Update a Sender Identity
2774
 
2775
**This endpoint allows you to update a sender identity.**
2776
 
2777
Updates to `from.email` require re-verification. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`.
2778
 
2779
Partial updates are allowed, but fields that are marked as "required" in the POST (create) endpoint must not be nil if that field is included in the PATCH request.
2780
 
2781
### PATCH /senders/{sender_id}
2782
 
2783
 
2784
```php
2785
$request_body = json_decode('{
2786
  "address": "123 Elm St.",
2787
  "address_2": "Apt. 456",
2788
  "city": "Denver",
2789
  "country": "United States",
2790
  "from": {
2791
    "email": "from@example.com",
2792
    "name": "Example INC"
2793
  },
2794
  "nickname": "My Sender ID",
2795
  "reply_to": {
2796
    "email": "replyto@example.com",
2797
    "name": "Example INC"
2798
  },
2799
  "state": "Colorado",
2800
  "zip": "80202"
2801
}');
2802
$sender_id = "test_url_param";
2803
$response = $sg->client->senders()->_($sender_id)->patch($request_body);
2804
echo $response->statusCode();
2805
echo $response->body();
2806
echo $response->headers();
2807
```
2808
## View a Sender Identity
2809
 
2810
**This endpoint allows you to retrieve a specific sender identity.**
2811
 
2812
Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`.
2813
 
2814
### GET /senders/{sender_id}
2815
 
2816
 
2817
```php
2818
$sender_id = "test_url_param";
2819
$response = $sg->client->senders()->_($sender_id)->get();
2820
echo $response->statusCode();
2821
echo $response->body();
2822
echo $response->headers();
2823
```
2824
## Delete a Sender Identity
2825
 
2826
**This endoint allows you to delete one of your sender identities.**
2827
 
2828
Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`.
2829
 
2830
### DELETE /senders/{sender_id}
2831
 
2832
 
2833
```php
2834
$sender_id = "test_url_param";
2835
$response = $sg->client->senders()->_($sender_id)->delete();
2836
echo $response->statusCode();
2837
echo $response->body();
2838
echo $response->headers();
2839
```
2840
## Resend Sender Identity Verification
2841
 
2842
**This enpdoint allows you to resend a sender identity verification email.**
2843
 
2844
Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`.
2845
 
2846
### POST /senders/{sender_id}/resend_verification
2847
 
2848
 
2849
```php
2850
$sender_id = "test_url_param";
2851
$response = $sg->client->senders()->_($sender_id)->resend_verification()->post();
2852
echo $response->statusCode();
2853
echo $response->body();
2854
echo $response->headers();
2855
```
2856
<a name="stats"></a>
2857
# STATS
2858
 
2859
## Retrieve global email statistics
2860
 
2861
**This endpoint allows you to retrieve all of your global email statistics between a given date range.**
2862
 
2863
Parent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their own stats.
2864
 
2865
### GET /stats
2866
 
2867
 
2868
```php
2869
$query_params = json_decode('{"aggregated_by": "day", "limit": 1, "start_date": "2016-01-01", "end_date": "2016-04-01", "offset": 1}');
2870
$response = $sg->client->stats()->get(null, $query_params);
2871
echo $response->statusCode();
2872
echo $response->body();
2873
echo $response->headers();
2874
```
2875
<a name="subusers"></a>
2876
# SUBUSERS
2877
 
2878
## Create Subuser
2879
 
2880
This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API.
2881
 
2882
For more information about Subusers:
2883
 
2884
* [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html)
2885
* [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html)
2886
 
2887
### POST /subusers
2888
 
2889
 
2890
```php
2891
$request_body = json_decode('{
2892
  "email": "John@example.com",
2893
  "ips": [
2894
    "1.1.1.1",
2895
    "2.2.2.2"
2896
  ],
2897
  "password": "johns_password",
2898
  "username": "John@example.com"
2899
}');
2900
$response = $sg->client->subusers()->post($request_body);
2901
echo $response->statusCode();
2902
echo $response->body();
2903
echo $response->headers();
2904
```
2905
## List all Subusers
2906
 
2907
This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API.
2908
 
2909
For more information about Subusers:
2910
 
2911
* [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html)
2912
* [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html)
2913
 
2914
### GET /subusers
2915
 
2916
 
2917
```php
2918
$query_params = json_decode('{"username": "test_string", "limit": 1, "offset": 1}');
2919
$response = $sg->client->subusers()->get(null, $query_params);
2920
echo $response->statusCode();
2921
echo $response->body();
2922
echo $response->headers();
2923
```
2924
## Retrieve Subuser Reputations
2925
 
2926
Subuser sender reputations give a good idea how well a sender is doing with regards to how recipients and recipient servers react to the mail that is being received. When a bounce, spam report, or other negative action happens on a sent email, it will effect your sender rating.
2927
 
2928
This endpoint allows you to request the reputations for your subusers.
2929
 
2930
### GET /subusers/reputations
2931
 
2932
 
2933
```php
2934
$query_params = json_decode('{"usernames": "test_string"}');
2935
$response = $sg->client->subusers()->reputations()->get(null, $query_params);
2936
echo $response->statusCode();
2937
echo $response->body();
2938
echo $response->headers();
2939
```
2940
## Retrieve email statistics for your subusers.
2941
 
2942
**This endpoint allows you to retrieve the email statistics for the given subusers.**
2943
 
2944
You may retrieve statistics for up to 10 different subusers by including an additional _subusers_ parameter for each additional subuser.
2945
 
2946
While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.
2947
 
2948
For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).
2949
 
2950
### GET /subusers/stats
2951
 
2952
 
2953
```php
2954
$query_params = json_decode('{"end_date": "2016-04-01", "aggregated_by": "day", "limit": 1, "offset": 1, "start_date": "2016-01-01", "subusers": "test_string"}');
2955
$response = $sg->client->subusers()->stats()->get(null, $query_params);
2956
echo $response->statusCode();
2957
echo $response->body();
2958
echo $response->headers();
2959
```
2960
## Retrieve monthly stats for all subusers
2961
 
2962
**This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.**
2963
 
2964
While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.
2965
 
2966
When using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics:
2967
`bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`.
2968
 
2969
For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).
2970
 
2971
### GET /subusers/stats/monthly
2972
 
2973
 
2974
```php
2975
$query_params = json_decode('{"subuser": "test_string", "limit": 1, "sort_by_metric": "test_string", "offset": 1, "date": "test_string", "sort_by_direction": "asc"}');
2976
$response = $sg->client->subusers()->stats()->monthly()->get(null, $query_params);
2977
echo $response->statusCode();
2978
echo $response->body();
2979
echo $response->headers();
2980
```
2981
##  Retrieve the totals for each email statistic metric for all subusers.
2982
 
2983
**This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.**
2984
 
2985
 
2986
While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.
2987
 
2988
For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).
2989
 
2990
### GET /subusers/stats/sums
2991
 
2992
 
2993
```php
2994
$query_params = json_decode('{"end_date": "2016-04-01", "aggregated_by": "day", "limit": 1, "sort_by_metric": "test_string", "offset": 1, "start_date": "2016-01-01", "sort_by_direction": "asc"}');
2995
$response = $sg->client->subusers()->stats()->sums()->get(null, $query_params);
2996
echo $response->statusCode();
2997
echo $response->body();
2998
echo $response->headers();
2999
```
3000
## Enable/disable a subuser
3001
 
3002
This endpoint allows you to enable or disable a subuser.
3003
 
3004
For more information about Subusers:
3005
 
3006
* [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html)
3007
* [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html)
3008
 
3009
### PATCH /subusers/{subuser_name}
3010
 
3011
 
3012
```php
3013
$request_body = json_decode('{
3014
  "disabled": false
3015
}');
3016
$subuser_name = "test_url_param";
3017
$response = $sg->client->subusers()->_($subuser_name)->patch($request_body);
3018
echo $response->statusCode();
3019
echo $response->body();
3020
echo $response->headers();
3021
```
3022
## Delete a subuser
3023
 
3024
This endpoint allows you to delete a subuser. This is a permanent action, once deleted a subuser cannot be retrieved.
3025
 
3026
For more information about Subusers:
3027
 
3028
* [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html)
3029
* [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html)
3030
 
3031
### DELETE /subusers/{subuser_name}
3032
 
3033
 
3034
```php
3035
$subuser_name = "test_url_param";
3036
$response = $sg->client->subusers()->_($subuser_name)->delete();
3037
echo $response->statusCode();
3038
echo $response->body();
3039
echo $response->headers();
3040
```
3041
## Update IPs assigned to a subuser
3042
 
3043
Each subuser should be assigned to an IP address, from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have their own, or multiple, IP addresses as well.
3044
 
3045
More information:
3046
 
3047
* [How to request more IPs](https://sendgrid.com/docs/Classroom/Basics/Account/adding_an_additional_dedicated_ip_to_your_account.html)
3048
* [IPs can be whitelabeled](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/ips.html)
3049
 
3050
### PUT /subusers/{subuser_name}/ips
3051
 
3052
 
3053
```php
3054
$request_body = json_decode('[
3055
  "127.0.0.1"
3056
]');
3057
$subuser_name = "test_url_param";
3058
$response = $sg->client->subusers()->_($subuser_name)->ips()->put($request_body);
3059
echo $response->statusCode();
3060
echo $response->body();
3061
echo $response->headers();
3062
```
3063
## Update Monitor Settings for a subuser
3064
 
3065
Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.
3066
 
3067
### PUT /subusers/{subuser_name}/monitor
3068
 
3069
 
3070
```php
3071
$request_body = json_decode('{
3072
  "email": "example@example.com",
3073
  "frequency": 500
3074
}');
3075
$subuser_name = "test_url_param";
3076
$response = $sg->client->subusers()->_($subuser_name)->monitor()->put($request_body);
3077
echo $response->statusCode();
3078
echo $response->body();
3079
echo $response->headers();
3080
```
3081
## Create monitor settings
3082
 
3083
Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.
3084
 
3085
### POST /subusers/{subuser_name}/monitor
3086
 
3087
 
3088
```php
3089
$request_body = json_decode('{
3090
  "email": "example@example.com",
3091
  "frequency": 50000
3092
}');
3093
$subuser_name = "test_url_param";
3094
$response = $sg->client->subusers()->_($subuser_name)->monitor()->post($request_body);
3095
echo $response->statusCode();
3096
echo $response->body();
3097
echo $response->headers();
3098
```
3099
## Retrieve monitor settings for a subuser
3100
 
3101
Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.
3102
 
3103
### GET /subusers/{subuser_name}/monitor
3104
 
3105
 
3106
```php
3107
$subuser_name = "test_url_param";
3108
$response = $sg->client->subusers()->_($subuser_name)->monitor()->get();
3109
echo $response->statusCode();
3110
echo $response->body();
3111
echo $response->headers();
3112
```
3113
## Delete monitor settings
3114
 
3115
Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.
3116
 
3117
### DELETE /subusers/{subuser_name}/monitor
3118
 
3119
 
3120
```php
3121
$subuser_name = "test_url_param";
3122
$response = $sg->client->subusers()->_($subuser_name)->monitor()->delete();
3123
echo $response->statusCode();
3124
echo $response->body();
3125
echo $response->headers();
3126
```
3127
## Retrieve the monthly email statistics for a single subuser
3128
 
3129
**This endpoint allows you to retrive the monthly email statistics for a specific subuser.**
3130
 
3131
While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.
3132
 
3133
When using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics:
3134
`bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`.
3135
 
3136
For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).
3137
 
3138
### GET /subusers/{subuser_name}/stats/monthly
3139
 
3140
 
3141
```php
3142
$query_params = json_decode('{"date": "test_string", "sort_by_direction": "asc", "limit": 1, "sort_by_metric": "test_string", "offset": 1}');
3143
$subuser_name = "test_url_param";
3144
$response = $sg->client->subusers()->_($subuser_name)->stats()->monthly()->get(null, $query_params);
3145
echo $response->statusCode();
3146
echo $response->body();
3147
echo $response->headers();
3148
```
3149
<a name="suppression"></a>
3150
# SUPPRESSION
3151
 
3152
## Retrieve all blocks
3153
 
3154
**This endpoint allows you to retrieve a list of all email addresses that are currently on your blocks list.**
3155
 
3156
[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.
3157
 
3158
For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html).
3159
 
3160
### GET /suppression/blocks
3161
 
3162
 
3163
```php
3164
$query_params = json_decode('{"start_time": 1, "limit": 1, "end_time": 1, "offset": 1}');
3165
$response = $sg->client->suppression()->blocks()->get(null, $query_params);
3166
echo $response->statusCode();
3167
echo $response->body();
3168
echo $response->headers();
3169
```
3170
## Delete blocks
3171
 
3172
**This endpoint allows you to delete all email addresses on your blocks list.**
3173
 
3174
There are two options for deleting blocked emails:
3175
 
3176
1. You can delete all blocked emails by setting `delete_all` to true in the request body.
3177
2. You can delete some blocked emails by specifying the email addresses in an array in the request body.
3178
 
3179
[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.
3180
 
3181
For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html).
3182
 
3183
### DELETE /suppression/blocks
3184
 
3185
 
3186
```php
3187
$request_body = json_decode('{
3188
  "delete_all": false,
3189
  "emails": [
3190
    "example1@example.com",
3191
    "example2@example.com"
3192
  ]
3193
}');
3194
$response = $sg->client->suppression()->blocks()->delete($request_body);
3195
echo $response->statusCode();
3196
echo $response->body();
3197
echo $response->headers();
3198
```
3199
## Retrieve a specific block
3200
 
3201
**This endpoint allows you to retrieve a specific email address from your blocks list.**
3202
 
3203
[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.
3204
 
3205
For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html).
3206
 
3207
### GET /suppression/blocks/{email}
3208
 
3209
 
3210
```php
3211
$email = "test_url_param";
3212
$response = $sg->client->suppression()->blocks()->_($email)->get();
3213
echo $response->statusCode();
3214
echo $response->body();
3215
echo $response->headers();
3216
```
3217
## Delete a specific block
3218
 
3219
**This endpoint allows you to delete a specific email address from your blocks list.**
3220
 
3221
[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.
3222
 
3223
For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html).
3224
 
3225
### DELETE /suppression/blocks/{email}
3226
 
3227
 
3228
```php
3229
$email = "test_url_param";
3230
$response = $sg->client->suppression()->blocks()->_($email)->delete();
3231
echo $response->statusCode();
3232
echo $response->body();
3233
echo $response->headers();
3234
```
3235
## Retrieve all bounces
3236
 
3237
**This endpoint allows you to retrieve all of your bounces.**
3238
 
3239
Bounces are messages that are returned to the server that sent it.
3240
 
3241
For more information see:
3242
 
3243
* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information
3244
* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)
3245
 
3246
### GET /suppression/bounces
3247
 
3248
 
3249
```php
3250
$query_params = json_decode('{"start_time": 1, "end_time": 1}');
3251
$response = $sg->client->suppression()->bounces()->get(null, $query_params);
3252
echo $response->statusCode();
3253
echo $response->body();
3254
echo $response->headers();
3255
```
3256
## Delete bounces
3257
 
3258
**This endpoint allows you to delete all of your bounces. You can also use this endpoint to remove a specific email address from your bounce list.**
3259
 
3260
Bounces are messages that are returned to the server that sent it.
3261
 
3262
For more information see:
3263
 
3264
* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information
3265
* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)
3266
* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)
3267
 
3268
Note: the `delete_all` and `emails` parameters should be used independently of each other as they have different purposes.
3269
 
3270
### DELETE /suppression/bounces
3271
 
3272
 
3273
```php
3274
$request_body = json_decode('{
3275
  "delete_all": true,
3276
  "emails": [
3277
    "example@example.com",
3278
    "example2@example.com"
3279
  ]
3280
}');
3281
$response = $sg->client->suppression()->bounces()->delete($request_body);
3282
echo $response->statusCode();
3283
echo $response->body();
3284
echo $response->headers();
3285
```
3286
## Retrieve a Bounce
3287
 
3288
**This endpoint allows you to retrieve a specific bounce for a given email address.**
3289
 
3290
Bounces are messages that are returned to the server that sent it.
3291
 
3292
For more information see:
3293
 
3294
* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information
3295
* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)
3296
* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)
3297
 
3298
### GET /suppression/bounces/{email}
3299
 
3300
 
3301
```php
3302
$email = "test_url_param";
3303
$response = $sg->client->suppression()->bounces()->_($email)->get();
3304
echo $response->statusCode();
3305
echo $response->body();
3306
echo $response->headers();
3307
```
3308
## Delete a bounce
3309
 
3310
**This endpoint allows you to remove an email address from your bounce list.**
3311
 
3312
Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete a single email addresses from your bounce list.
3313
 
3314
For more information see:
3315
 
3316
* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information
3317
* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)
3318
* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)
3319
 
3320
### DELETE /suppression/bounces/{email}
3321
 
3322
 
3323
```php
3324
$query_params = json_decode('{"email_address": "example@example.com"}');
3325
$email = "test_url_param";
3326
$response = $sg->client->suppression()->bounces()->_($email)->delete(null, $query_params);
3327
echo $response->statusCode();
3328
echo $response->body();
3329
echo $response->headers();
3330
```
3331
## Retrieve all invalid emails
3332
 
3333
**This endpoint allows you to retrieve a list of all invalid email addresses.**
3334
 
3335
An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server.
3336
 
3337
Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.
3338
 
3339
For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html).
3340
 
3341
### GET /suppression/invalid_emails
3342
 
3343
 
3344
```php
3345
$query_params = json_decode('{"start_time": 1, "limit": 1, "end_time": 1, "offset": 1}');
3346
$response = $sg->client->suppression()->invalid_emails()->get(null, $query_params);
3347
echo $response->statusCode();
3348
echo $response->body();
3349
echo $response->headers();
3350
```
3351
## Delete invalid emails
3352
 
3353
**This endpoint allows you to remove email addresses from your invalid email address list.**
3354
 
3355
There are two options for deleting invalid email addresses:
3356
 
3357
1) You can delete all invalid email addresses by setting `delete_all` to true in the request body.
3358
2) You can delete some invalid email addresses by specifying certain addresses in an array in the request body.
3359
 
3360
An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server.
3361
 
3362
Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.
3363
 
3364
For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html).
3365
 
3366
### DELETE /suppression/invalid_emails
3367
 
3368
 
3369
```php
3370
$request_body = json_decode('{
3371
  "delete_all": false,
3372
  "emails": [
3373
    "example1@example.com",
3374
    "example2@example.com"
3375
  ]
3376
}');
3377
$response = $sg->client->suppression()->invalid_emails()->delete($request_body);
3378
echo $response->statusCode();
3379
echo $response->body();
3380
echo $response->headers();
3381
```
3382
## Retrieve a specific invalid email
3383
 
3384
**This endpoint allows you to retrieve a specific invalid email addresses.**
3385
 
3386
An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server.
3387
 
3388
Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.
3389
 
3390
For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html).
3391
 
3392
### GET /suppression/invalid_emails/{email}
3393
 
3394
 
3395
```php
3396
$email = "test_url_param";
3397
$response = $sg->client->suppression()->invalid_emails()->_($email)->get();
3398
echo $response->statusCode();
3399
echo $response->body();
3400
echo $response->headers();
3401
```
3402
## Delete a specific invalid email
3403
 
3404
**This endpoint allows you to remove a specific email address from the invalid email address list.**
3405
 
3406
An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server.
3407
 
3408
Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.
3409
 
3410
For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html).
3411
 
3412
### DELETE /suppression/invalid_emails/{email}
3413
 
3414
 
3415
```php
3416
$email = "test_url_param";
3417
$response = $sg->client->suppression()->invalid_emails()->_($email)->delete();
3418
echo $response->statusCode();
3419
echo $response->body();
3420
echo $response->headers();
3421
```
3422
## Retrieve a specific spam report
3423
 
3424
**This endpoint allows you to retrieve a specific spam report.**
3425
 
3426
[Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid.
3427
 
3428
For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html).
3429
 
3430
### GET /suppression/spam_report/{email}
3431
 
3432
 
3433
```php
3434
$email = "test_url_param";
3435
$response = $sg->client->suppression()->spam_report()->_($email)->get();
3436
echo $response->statusCode();
3437
echo $response->body();
3438
echo $response->headers();
3439
```
3440
## Delete a specific spam report
3441
 
3442
**This endpoint allows you to delete a specific spam report.**
3443
 
3444
[Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid.
3445
 
3446
For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html).
3447
 
3448
### DELETE /suppression/spam_report/{email}
3449
 
3450
 
3451
```php
3452
$email = "test_url_param";
3453
$response = $sg->client->suppression()->spam_report()->_($email)->delete();
3454
echo $response->statusCode();
3455
echo $response->body();
3456
echo $response->headers();
3457
```
3458
## Retrieve all spam reports
3459
 
3460
**This endpoint allows you to retrieve all spam reports.**
3461
 
3462
[Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid.
3463
 
3464
For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html).
3465
 
3466
### GET /suppression/spam_reports
3467
 
3468
 
3469
```php
3470
$query_params = json_decode('{"start_time": 1, "limit": 1, "end_time": 1, "offset": 1}');
3471
$response = $sg->client->suppression()->spam_reports()->get(null, $query_params);
3472
echo $response->statusCode();
3473
echo $response->body();
3474
echo $response->headers();
3475
```
3476
## Delete spam reports
3477
 
3478
**This endpoint allows you to delete your spam reports.**
3479
 
3480
There are two options for deleting spam reports:
3481
 
3482
1) You can delete all spam reports by setting "delete_all" to true in the request body.
3483
2) You can delete some spam reports by specifying the email addresses in an array in the request body.
3484
 
3485
[Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid.
3486
 
3487
For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html).
3488
 
3489
### DELETE /suppression/spam_reports
3490
 
3491
 
3492
```php
3493
$request_body = json_decode('{
3494
  "delete_all": false,
3495
  "emails": [
3496
    "example1@example.com",
3497
    "example2@example.com"
3498
  ]
3499
}');
3500
$response = $sg->client->suppression()->spam_reports()->delete($request_body);
3501
echo $response->statusCode();
3502
echo $response->body();
3503
echo $response->headers();
3504
```
3505
## Retrieve all global suppressions
3506
 
3507
**This endpoint allows you to retrieve a list of all email address that are globally suppressed.**
3508
 
3509
A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).
3510
 
3511
### GET /suppression/unsubscribes
3512
 
3513
 
3514
```php
3515
$query_params = json_decode('{"start_time": 1, "limit": 1, "end_time": 1, "offset": 1}');
3516
$response = $sg->client->suppression()->unsubscribes()->get(null, $query_params);
3517
echo $response->statusCode();
3518
echo $response->body();
3519
echo $response->headers();
3520
```
3521
<a name="templates"></a>
3522
# TEMPLATES
3523
 
3524
## Create a transactional template.
3525
 
3526
**This endpoint allows you to create a transactional template.**
3527
 
3528
Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.
3529
 
3530
Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).
3531
 
3532
### POST /templates
3533
 
3534
 
3535
```php
3536
$request_body = json_decode('{
3537
  "name": "example_name"
3538
}');
3539
$response = $sg->client->templates()->post($request_body);
3540
echo $response->statusCode();
3541
echo $response->body();
3542
echo $response->headers();
3543
```
3544
## Retrieve all transactional templates.
3545
 
3546
**This endpoint allows you to retrieve all transactional templates.**
3547
 
3548
Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.
3549
 
3550
Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).
3551
 
3552
### GET /templates
3553
 
3554
 
3555
```php
3556
$response = $sg->client->templates()->get();
3557
echo $response->statusCode();
3558
echo $response->body();
3559
echo $response->headers();
3560
```
3561
## Edit a transactional template.
3562
 
3563
**This endpoint allows you to edit a transactional template.**
3564
 
3565
Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.
3566
 
3567
Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).
3568
 
3569
 
3570
### PATCH /templates/{template_id}
3571
 
3572
 
3573
```php
3574
$request_body = json_decode('{
3575
  "name": "new_example_name"
3576
}');
3577
$template_id = "test_url_param";
3578
$response = $sg->client->templates()->_($template_id)->patch($request_body);
3579
echo $response->statusCode();
3580
echo $response->body();
3581
echo $response->headers();
3582
```
3583
## Retrieve a single transactional template.
3584
 
3585
**This endpoint allows you to retrieve a single transactional template.**
3586
 
3587
Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.
3588
 
3589
Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).
3590
 
3591
 
3592
### GET /templates/{template_id}
3593
 
3594
 
3595
```php
3596
$template_id = "test_url_param";
3597
$response = $sg->client->templates()->_($template_id)->get();
3598
echo $response->statusCode();
3599
echo $response->body();
3600
echo $response->headers();
3601
```
3602
## Delete a template.
3603
 
3604
**This endpoint allows you to delete a transactional template.**
3605
 
3606
Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.
3607
 
3608
Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).
3609
 
3610
 
3611
### DELETE /templates/{template_id}
3612
 
3613
 
3614
```php
3615
$template_id = "test_url_param";
3616
$response = $sg->client->templates()->_($template_id)->delete();
3617
echo $response->statusCode();
3618
echo $response->body();
3619
echo $response->headers();
3620
```
3621
## Create a new transactional template version.
3622
 
3623
**This endpoint allows you to create a new version of a template.**
3624
 
3625
Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.
3626
 
3627
For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).
3628
 
3629
 
3630
### POST /templates/{template_id}/versions
3631
 
3632
 
3633
```php
3634
$request_body = json_decode('{
3635
  "active": 1,
3636
  "html_content": "<%body%>",
3637
  "name": "example_version_name",
3638
  "plain_content": "<%body%>",
3639
  "subject": "<%subject%>",
3640
  "template_id": "ddb96bbc-9b92-425e-8979-99464621b543"
3641
}');
3642
$template_id = "test_url_param";
3643
$response = $sg->client->templates()->_($template_id)->versions()->post($request_body);
3644
echo $response->statusCode();
3645
echo $response->body();
3646
echo $response->headers();
3647
```
3648
## Edit a transactional template version.
3649
 
3650
**This endpoint allows you to edit a version of one of your transactional templates.**
3651
 
3652
Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.
3653
 
3654
For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).
3655
 
3656
## URI Parameters
3657
| URI Parameter | Type | Description |
3658
|---|---|---|
3659
| template_id | string | The ID of the original template |
3660
| version_id | string | The ID of the template version |
3661
 
3662
### PATCH /templates/{template_id}/versions/{version_id}
3663
 
3664
 
3665
```php
3666
$request_body = json_decode('{
3667
  "active": 1,
3668
  "html_content": "<%body%>",
3669
  "name": "updated_example_name",
3670
  "plain_content": "<%body%>",
3671
  "subject": "<%subject%>"
3672
}');
3673
$template_id = "test_url_param";
3674
$version_id = "test_url_param";
3675
$response = $sg->client->templates()->_($template_id)->versions()->_($version_id)->patch($request_body);
3676
echo $response->statusCode();
3677
echo $response->body();
3678
echo $response->headers();
3679
```
3680
## Retrieve a specific transactional template version.
3681
 
3682
**This endpoint allows you to retrieve a specific version of a template.**
3683
 
3684
Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.
3685
 
3686
For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).
3687
 
3688
## URI Parameters
3689
| URI Parameter | Type | Description |
3690
|---|---|---|
3691
| template_id | string | The ID of the original template |
3692
| version_id | string |  The ID of the template version |
3693
 
3694
### GET /templates/{template_id}/versions/{version_id}
3695
 
3696
 
3697
```php
3698
$template_id = "test_url_param";
3699
$version_id = "test_url_param";
3700
$response = $sg->client->templates()->_($template_id)->versions()->_($version_id)->get();
3701
echo $response->statusCode();
3702
echo $response->body();
3703
echo $response->headers();
3704
```
3705
## Delete a transactional template version.
3706
 
3707
**This endpoint allows you to delete one of your transactional template versions.**
3708
 
3709
Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.
3710
 
3711
For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).
3712
 
3713
## URI Parameters
3714
| URI Parameter | Type | Description |
3715
|---|---|---|
3716
| template_id | string | The ID of the original template |
3717
| version_id | string | The ID of the template version |
3718
 
3719
### DELETE /templates/{template_id}/versions/{version_id}
3720
 
3721
 
3722
```php
3723
$template_id = "test_url_param";
3724
$version_id = "test_url_param";
3725
$response = $sg->client->templates()->_($template_id)->versions()->_($version_id)->delete();
3726
echo $response->statusCode();
3727
echo $response->body();
3728
echo $response->headers();
3729
```
3730
## Activate a transactional template version.
3731
 
3732
**This endpoint allows you to activate a version of one of your templates.**
3733
 
3734
Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.
3735
 
3736
 
3737
For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).
3738
 
3739
## URI Parameters
3740
| URI Parameter | Type | Description |
3741
|---|---|---|
3742
| template_id | string | The ID of the original template |
3743
| version_id | string |  The ID of the template version |
3744
 
3745
### POST /templates/{template_id}/versions/{version_id}/activate
3746
 
3747
 
3748
```php
3749
$template_id = "test_url_param";
3750
$version_id = "test_url_param";
3751
$response = $sg->client->templates()->_($template_id)->versions()->_($version_id)->activate()->post();
3752
echo $response->statusCode();
3753
echo $response->body();
3754
echo $response->headers();
3755
```
3756
<a name="tracking_settings"></a>
3757
# TRACKING SETTINGS
3758
 
3759
## Retrieve Tracking Settings
3760
 
3761
**This endpoint allows you to retrieve a list of all tracking settings that you can enable on your account.**
3762
 
3763
You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.
3764
 
3765
For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).
3766
 
3767
### GET /tracking_settings
3768
 
3769
 
3770
```php
3771
$query_params = json_decode('{"limit": 1, "offset": 1}');
3772
$response = $sg->client->tracking_settings()->get(null, $query_params);
3773
echo $response->statusCode();
3774
echo $response->body();
3775
echo $response->headers();
3776
```
3777
## Update Click Tracking Settings
3778
 
3779
**This endpoint allows you to change your current click tracking setting. You can enable, or disable, click tracking using this endpoint.**
3780
 
3781
You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.
3782
 
3783
For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).
3784
 
3785
### PATCH /tracking_settings/click
3786
 
3787
 
3788
```php
3789
$request_body = json_decode('{
3790
  "enabled": true
3791
}');
3792
$response = $sg->client->tracking_settings()->click()->patch($request_body);
3793
echo $response->statusCode();
3794
echo $response->body();
3795
echo $response->headers();
3796
```
3797
## Retrieve Click Track Settings
3798
 
3799
**This endpoint allows you to retrieve your current click tracking setting.**
3800
 
3801
You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.
3802
 
3803
For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).
3804
 
3805
### GET /tracking_settings/click
3806
 
3807
 
3808
```php
3809
$response = $sg->client->tracking_settings()->click()->get();
3810
echo $response->statusCode();
3811
echo $response->body();
3812
echo $response->headers();
3813
```
3814
## Update Google Analytics Settings
3815
 
3816
**This endpoint allows you to update your current setting for Google Analytics.**
3817
 
3818
For more information about using Google Analytics, please refer to [Googles URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on ["Best Practices for Campaign Building"](https://support.google.com/analytics/answer/1037445).
3819
 
3820
We default the settings to Googles recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html).
3821
 
3822
You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.
3823
 
3824
For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).
3825
 
3826
### PATCH /tracking_settings/google_analytics
3827
 
3828
 
3829
```php
3830
$request_body = json_decode('{
3831
  "enabled": true,
3832
  "utm_campaign": "website",
3833
  "utm_content": "",
3834
  "utm_medium": "email",
3835
  "utm_source": "sendgrid.com",
3836
  "utm_term": ""
3837
}');
3838
$response = $sg->client->tracking_settings()->google_analytics()->patch($request_body);
3839
echo $response->statusCode();
3840
echo $response->body();
3841
echo $response->headers();
3842
```
3843
## Retrieve Google Analytics Settings
3844
 
3845
**This endpoint allows you to retrieve your current setting for Google Analytics.**
3846
 
3847
For more information about using Google Analytics, please refer to [Googles URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on ["Best Practices for Campaign Building"](https://support.google.com/analytics/answer/1037445).
3848
 
3849
We default the settings to Googles recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html).
3850
 
3851
You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.
3852
 
3853
For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).
3854
 
3855
### GET /tracking_settings/google_analytics
3856
 
3857
 
3858
```php
3859
$response = $sg->client->tracking_settings()->google_analytics()->get();
3860
echo $response->statusCode();
3861
echo $response->body();
3862
echo $response->headers();
3863
```
3864
## Update Open Tracking Settings
3865
 
3866
**This endpoint allows you to update your current settings for open tracking.**
3867
 
3868
Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrids server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook.
3869
 
3870
You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.
3871
 
3872
For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).
3873
 
3874
### PATCH /tracking_settings/open
3875
 
3876
 
3877
```php
3878
$request_body = json_decode('{
3879
  "enabled": true
3880
}');
3881
$response = $sg->client->tracking_settings()->open()->patch($request_body);
3882
echo $response->statusCode();
3883
echo $response->body();
3884
echo $response->headers();
3885
```
3886
## Get Open Tracking Settings
3887
 
3888
**This endpoint allows you to retrieve your current settings for open tracking.**
3889
 
3890
Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrids server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook.
3891
 
3892
You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.
3893
 
3894
For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).
3895
 
3896
### GET /tracking_settings/open
3897
 
3898
 
3899
```php
3900
$response = $sg->client->tracking_settings()->open()->get();
3901
echo $response->statusCode();
3902
echo $response->body();
3903
echo $response->headers();
3904
```
3905
## Update Subscription Tracking Settings
3906
 
3907
**This endpoint allows you to update your current settings for subscription tracking.**
3908
 
3909
Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails.
3910
 
3911
You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.
3912
 
3913
For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).
3914
 
3915
### PATCH /tracking_settings/subscription
3916
 
3917
 
3918
```php
3919
$request_body = json_decode('{
3920
  "enabled": true,
3921
  "html_content": "html content",
3922
  "landing": "landing page html",
3923
  "plain_content": "text content",
3924
  "replace": "replacement tag",
3925
  "url": "url"
3926
}');
3927
$response = $sg->client->tracking_settings()->subscription()->patch($request_body);
3928
echo $response->statusCode();
3929
echo $response->body();
3930
echo $response->headers();
3931
```
3932
## Retrieve Subscription Tracking Settings
3933
 
3934
**This endpoint allows you to retrieve your current settings for subscription tracking.**
3935
 
3936
Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails.
3937
 
3938
You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.
3939
 
3940
For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).
3941
 
3942
### GET /tracking_settings/subscription
3943
 
3944
 
3945
```php
3946
$response = $sg->client->tracking_settings()->subscription()->get();
3947
echo $response->statusCode();
3948
echo $response->body();
3949
echo $response->headers();
3950
```
3951
<a name="user"></a>
3952
# USER
3953
 
3954
## Get a user's account information.
3955
 
3956
**This endpoint allows you to retrieve your user account details.**
3957
 
3958
Your user's account information includes the user's account type and reputation.
3959
 
3960
Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.
3961
 
3962
For more information about your user profile:
3963
 
3964
* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)
3965
 
3966
### GET /user/account
3967
 
3968
 
3969
```php
3970
$response = $sg->client->user()->account()->get();
3971
echo $response->statusCode();
3972
echo $response->body();
3973
echo $response->headers();
3974
```
3975
## Retrieve your credit balance
3976
 
3977
**This endpoint allows you to retrieve the current credit balance for your account.**
3978
 
3979
Your monthly credit allotment limits the number of emails you may send before incurring overage charges. For more information about credits and billing, please visit our [Clssroom](https://sendgrid.com/docs/Classroom/Basics/Billing/billing_info_and_faqs.html).
3980
 
3981
### GET /user/credits
3982
 
3983
 
3984
```php
3985
$response = $sg->client->user()->credits()->get();
3986
echo $response->statusCode();
3987
echo $response->body();
3988
echo $response->headers();
3989
```
3990
## Update your account email address
3991
 
3992
**This endpoint allows you to update the email address currently on file for your account.**
3993
 
3994
Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.
3995
 
3996
For more information about your user profile:
3997
 
3998
* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)
3999
 
4000
### PUT /user/email
4001
 
4002
 
4003
```php
4004
$request_body = json_decode('{
4005
  "email": "example@example.com"
4006
}');
4007
$response = $sg->client->user()->email()->put($request_body);
4008
echo $response->statusCode();
4009
echo $response->body();
4010
echo $response->headers();
4011
```
4012
## Retrieve your account email address
4013
 
4014
**This endpoint allows you to retrieve the email address currently on file for your account.**
4015
 
4016
Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.
4017
 
4018
For more information about your user profile:
4019
 
4020
* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)
4021
 
4022
### GET /user/email
4023
 
4024
 
4025
```php
4026
$response = $sg->client->user()->email()->get();
4027
echo $response->statusCode();
4028
echo $response->body();
4029
echo $response->headers();
4030
```
4031
## Update your password
4032
 
4033
**This endpoint allows you to update your password.**
4034
 
4035
Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.
4036
 
4037
For more information about your user profile:
4038
 
4039
* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)
4040
 
4041
### PUT /user/password
4042
 
4043
 
4044
```php
4045
$request_body = json_decode('{
4046
  "new_password": "new_password",
4047
  "old_password": "old_password"
4048
}');
4049
$response = $sg->client->user()->password()->put($request_body);
4050
echo $response->statusCode();
4051
echo $response->body();
4052
echo $response->headers();
4053
```
4054
## Update a user's profile
4055
 
4056
**This endpoint allows you to update your current profile details.**
4057
 
4058
Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.
4059
 
4060
For more information about your user profile:
4061
 
4062
* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)
4063
 
4064
It should be noted that any one or more of the parameters can be updated via the PATCH /user/profile endpoint. The only requirement is that you include at least one when you PATCH.
4065
 
4066
### PATCH /user/profile
4067
 
4068
 
4069
```php
4070
$request_body = json_decode('{
4071
  "city": "Orange",
4072
  "first_name": "Example",
4073
  "last_name": "User"
4074
}');
4075
$response = $sg->client->user()->profile()->patch($request_body);
4076
echo $response->statusCode();
4077
echo $response->body();
4078
echo $response->headers();
4079
```
4080
## Get a user's profile
4081
 
4082
Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.
4083
 
4084
For more information about your user profile:
4085
 
4086
* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)
4087
 
4088
### GET /user/profile
4089
 
4090
 
4091
```php
4092
$response = $sg->client->user()->profile()->get();
4093
echo $response->statusCode();
4094
echo $response->body();
4095
echo $response->headers();
4096
```
4097
## Cancel or pause a scheduled send
4098
 
4099
**This endpoint allows you to cancel or pause an email that has been scheduled to be sent.**
4100
 
4101
If the maximum number of cancellations/pauses are added, HTTP 400 will
4102
be returned.
4103
 
4104
The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.
4105
 
4106
### POST /user/scheduled_sends
4107
 
4108
 
4109
```php
4110
$request_body = json_decode('{
4111
  "batch_id": "YOUR_BATCH_ID",
4112
  "status": "pause"
4113
}');
4114
$response = $sg->client->user()->scheduled_sends()->post($request_body);
4115
echo $response->statusCode();
4116
echo $response->body();
4117
echo $response->headers();
4118
```
4119
## Retrieve all scheduled sends
4120
 
4121
**This endpoint allows you to retrieve all cancel/paused scheduled send information.**
4122
 
4123
The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.
4124
 
4125
### GET /user/scheduled_sends
4126
 
4127
 
4128
```php
4129
$response = $sg->client->user()->scheduled_sends()->get();
4130
echo $response->statusCode();
4131
echo $response->body();
4132
echo $response->headers();
4133
```
4134
## Update user scheduled send information
4135
 
4136
**This endpoint allows you to update the status of a scheduled send for the given `batch_id`.**
4137
 
4138
The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.
4139
 
4140
### PATCH /user/scheduled_sends/{batch_id}
4141
 
4142
 
4143
```php
4144
$request_body = json_decode('{
4145
  "status": "pause"
4146
}');
4147
$batch_id = "test_url_param";
4148
$response = $sg->client->user()->scheduled_sends()->_($batch_id)->patch($request_body);
4149
echo $response->statusCode();
4150
echo $response->body();
4151
echo $response->headers();
4152
```
4153
## Retrieve scheduled send
4154
 
4155
**This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific `batch_id`.**
4156
 
4157
The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.
4158
 
4159
### GET /user/scheduled_sends/{batch_id}
4160
 
4161
 
4162
```php
4163
$batch_id = "test_url_param";
4164
$response = $sg->client->user()->scheduled_sends()->_($batch_id)->get();
4165
echo $response->statusCode();
4166
echo $response->body();
4167
echo $response->headers();
4168
```
4169
## Delete a cancellation or pause of a scheduled send
4170
 
4171
**This endpoint allows you to delete the cancellation/pause of a scheduled send.**
4172
 
4173
The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.
4174
 
4175
### DELETE /user/scheduled_sends/{batch_id}
4176
 
4177
 
4178
```php
4179
$batch_id = "test_url_param";
4180
$response = $sg->client->user()->scheduled_sends()->_($batch_id)->delete();
4181
echo $response->statusCode();
4182
echo $response->body();
4183
echo $response->headers();
4184
```
4185
## Update Enforced TLS settings
4186
 
4187
**This endpoint allows you to update your current Enforced TLS settings.**
4188
 
4189
The Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the [SMTP Ports User Guide](https://sendgrid.com/docs/Classroom/Basics/Email_Infrastructure/smtp_ports.html) for more information on opportunistic TLS.
4190
 
4191
**Note:** If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with TLS required but not supported as the description.
4192
 
4193
### PATCH /user/settings/enforced_tls
4194
 
4195
 
4196
```php
4197
$request_body = json_decode('{
4198
  "require_tls": true,
4199
  "require_valid_cert": false
4200
}');
4201
$response = $sg->client->user()->settings()->enforced_tls()->patch($request_body);
4202
echo $response->statusCode();
4203
echo $response->body();
4204
echo $response->headers();
4205
```
4206
## Retrieve current Enforced TLS settings.
4207
 
4208
**This endpoint allows you to retrieve your current Enforced TLS settings.**
4209
 
4210
The Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the [SMTP Ports User Guide](https://sendgrid.com/docs/Classroom/Basics/Email_Infrastructure/smtp_ports.html) for more information on opportunistic TLS.
4211
 
4212
**Note:** If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with TLS required but not supported as the description.
4213
 
4214
### GET /user/settings/enforced_tls
4215
 
4216
 
4217
```php
4218
$response = $sg->client->user()->settings()->enforced_tls()->get();
4219
echo $response->statusCode();
4220
echo $response->body();
4221
echo $response->headers();
4222
```
4223
## Update your username
4224
 
4225
**This endpoint allows you to update the username for your account.**
4226
 
4227
Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.
4228
 
4229
For more information about your user profile:
4230
 
4231
* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)
4232
 
4233
### PUT /user/username
4234
 
4235
 
4236
```php
4237
$request_body = json_decode('{
4238
  "username": "test_username"
4239
}');
4240
$response = $sg->client->user()->username()->put($request_body);
4241
echo $response->statusCode();
4242
echo $response->body();
4243
echo $response->headers();
4244
```
4245
## Retrieve your username
4246
 
4247
**This endpoint allows you to retrieve your current account username.**
4248
 
4249
Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.
4250
 
4251
For more information about your user profile:
4252
 
4253
* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)
4254
 
4255
### GET /user/username
4256
 
4257
 
4258
```php
4259
$response = $sg->client->user()->username()->get();
4260
echo $response->statusCode();
4261
echo $response->body();
4262
echo $response->headers();
4263
```
4264
## Update Event Notification Settings
4265
 
4266
**This endpoint allows you to update your current event webhook settings.**
4267
 
4268
If an event type is marked as `true`, then the event webhook will include information about that event.
4269
 
4270
SendGrids Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email.
4271
 
4272
Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program.
4273
 
4274
### PATCH /user/webhooks/event/settings
4275
 
4276
 
4277
```php
4278
$request_body = json_decode('{
4279
  "bounce": true,
4280
  "click": true,
4281
  "deferred": true,
4282
  "delivered": true,
4283
  "dropped": true,
4284
  "enabled": true,
4285
  "group_resubscribe": true,
4286
  "group_unsubscribe": true,
4287
  "open": true,
4288
  "processed": true,
4289
  "spam_report": true,
4290
  "unsubscribe": true,
4291
  "url": "url"
4292
}');
4293
$response = $sg->client->user()->webhooks()->event()->settings()->patch($request_body);
4294
echo $response->statusCode();
4295
echo $response->body();
4296
echo $response->headers();
4297
```
4298
## Retrieve Event Webhook settings
4299
 
4300
**This endpoint allows you to retrieve your current event webhook settings.**
4301
 
4302
If an event type is marked as `true`, then the event webhook will include information about that event.
4303
 
4304
SendGrids Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email.
4305
 
4306
Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program.
4307
 
4308
### GET /user/webhooks/event/settings
4309
 
4310
 
4311
```php
4312
$response = $sg->client->user()->webhooks()->event()->settings()->get();
4313
echo $response->statusCode();
4314
echo $response->body();
4315
echo $response->headers();
4316
```
4317
## Test Event Notification Settings
4318
 
4319
**This endpoint allows you to test your event webhook by sending a fake event notification post to the provided URL.**
4320
 
4321
SendGrids Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email.
4322
 
4323
Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program.
4324
 
4325
### POST /user/webhooks/event/test
4326
 
4327
 
4328
```php
4329
$request_body = json_decode('{
4330
  "url": "url"
4331
}');
4332
$response = $sg->client->user()->webhooks()->event()->test()->post($request_body);
4333
echo $response->statusCode();
4334
echo $response->body();
4335
echo $response->headers();
4336
```
4337
## Create a parse setting
4338
 
4339
**This endpoint allows you to create a new inbound parse setting.**
4340
 
4341
The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).
4342
 
4343
### POST /user/webhooks/parse/settings
4344
 
4345
 
4346
```php
4347
$request_body = json_decode('{
4348
  "hostname": "myhostname.com",
4349
  "send_raw": false,
4350
  "spam_check": true,
4351
  "url": "http://email.myhosthame.com"
4352
}');
4353
$response = $sg->client->user()->webhooks()->parse()->settings()->post($request_body);
4354
echo $response->statusCode();
4355
echo $response->body();
4356
echo $response->headers();
4357
```
4358
## Retrieve all parse settings
4359
 
4360
**This endpoint allows you to retrieve all of your current inbound parse settings.**
4361
 
4362
The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).
4363
 
4364
### GET /user/webhooks/parse/settings
4365
 
4366
 
4367
```php
4368
$response = $sg->client->user()->webhooks()->parse()->settings()->get();
4369
echo $response->statusCode();
4370
echo $response->body();
4371
echo $response->headers();
4372
```
4373
## Update a parse setting
4374
 
4375
**This endpoint allows you to update a specific inbound parse setting.**
4376
 
4377
The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).
4378
 
4379
### PATCH /user/webhooks/parse/settings/{hostname}
4380
 
4381
 
4382
```php
4383
$request_body = json_decode('{
4384
  "send_raw": true,
4385
  "spam_check": false,
4386
  "url": "http://newdomain.com/parse"
4387
}');
4388
$hostname = "test_url_param";
4389
$response = $sg->client->user()->webhooks()->parse()->settings()->_($hostname)->patch($request_body);
4390
echo $response->statusCode();
4391
echo $response->body();
4392
echo $response->headers();
4393
```
4394
## Retrieve a specific parse setting
4395
 
4396
**This endpoint allows you to retrieve a specific inbound parse setting.**
4397
 
4398
The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).
4399
 
4400
### GET /user/webhooks/parse/settings/{hostname}
4401
 
4402
 
4403
```php
4404
$hostname = "test_url_param";
4405
$response = $sg->client->user()->webhooks()->parse()->settings()->_($hostname)->get();
4406
echo $response->statusCode();
4407
echo $response->body();
4408
echo $response->headers();
4409
```
4410
## Delete a parse setting
4411
 
4412
**This endpoint allows you to delete a specific inbound parse setting.**
4413
 
4414
The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).
4415
 
4416
### DELETE /user/webhooks/parse/settings/{hostname}
4417
 
4418
 
4419
```php
4420
$hostname = "test_url_param";
4421
$response = $sg->client->user()->webhooks()->parse()->settings()->_($hostname)->delete();
4422
echo $response->statusCode();
4423
echo $response->body();
4424
echo $response->headers();
4425
```
4426
## Retrieves Inbound Parse Webhook statistics.
4427
 
4428
**This endpoint allows you to retrieve the statistics for your Parse Webhook useage.**
4429
 
4430
SendGrid's Inbound Parse Webhook allows you to parse the contents and attachments of incomming emails. The Parse API can then POST the parsed emails to a URL that you specify. The Inbound Parse Webhook cannot parse messages greater than 20MB in size, including all attachments.
4431
 
4432
There are a number of pre-made integrations for the SendGrid Parse Webhook which make processing events easy. You can find these integrations in the [Library Index](https://sendgrid.com/docs/Integrate/libraries.html#-Webhook-Libraries).
4433
 
4434
### GET /user/webhooks/parse/stats
4435
 
4436
 
4437
```php
4438
$query_params = json_decode('{"aggregated_by": "day", "limit": "test_string", "start_date": "2016-01-01", "end_date": "2016-04-01", "offset": "test_string"}');
4439
$response = $sg->client->user()->webhooks()->parse()->stats()->get(null, $query_params);
4440
echo $response->statusCode();
4441
echo $response->body();
4442
echo $response->headers();
4443
```
4444
<a name="whitelabel"></a>
4445
# WHITELABEL
4446
 
4447
## Create a domain whitelabel.
4448
 
4449
**This endpoint allows you to create a whitelabel for one of your domains.**
4450
 
4451
If you are creating a domain whitelabel that you would like a subuser to use, you have two options:
4452
1. Use the "username" parameter. This allows you to create a whitelabel on behalf of your subuser. This means the subuser is able to see and modify the created whitelabel.
4453
2. Use the Association workflow (see Associate Domain section). This allows you to assign a whitelabel created by the parent to a subuser. This means the subuser will default to the assigned whitelabel, but will not be able to see or modify that whitelabel. However, if the subuser creates their own whitelabel it will overwrite the assigned whitelabel.
4454
 
4455
A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.
4456
 
4457
For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)
4458
 
4459
### POST /whitelabel/domains
4460
 
4461
 
4462
```php
4463
$request_body = json_decode('{
4464
  "automatic_security": false,
4465
  "custom_spf": true,
4466
  "default": true,
4467
  "domain": "example.com",
4468
  "ips": [
4469
    "192.168.1.1",
4470
    "192.168.1.2"
4471
  ],
4472
  "subdomain": "news",
4473
  "username": "john@example.com"
4474
}');
4475
$response = $sg->client->whitelabel()->domains()->post($request_body);
4476
echo $response->statusCode();
4477
echo $response->body();
4478
echo $response->headers();
4479
```
4480
## List all domain whitelabels.
4481
 
4482
**This endpoint allows you to retrieve a list of all domain whitelabels you have created.**
4483
 
4484
A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.
4485
 
4486
For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)
4487
 
4488
 
4489
### GET /whitelabel/domains
4490
 
4491
 
4492
```php
4493
$query_params = json_decode('{"username": "test_string", "domain": "test_string", "exclude_subusers": "true", "limit": 1, "offset": 1}');
4494
$response = $sg->client->whitelabel()->domains()->get(null, $query_params);
4495
echo $response->statusCode();
4496
echo $response->body();
4497
echo $response->headers();
4498
```
4499
## Get the default domain whitelabel.
4500
 
4501
**This endpoint allows you to retrieve the default whitelabel for a domain.**
4502
 
4503
A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.
4504
 
4505
For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)
4506
 
4507
## URI Parameters
4508
| URI Parameter   | Type   | Description  |
4509
|---|---|---|
4510
| domain | string  |The domain to find a default domain whitelabel for. |
4511
 
4512
### GET /whitelabel/domains/default
4513
 
4514
 
4515
```php
4516
$response = $sg->client->whitelabel()->domains()->default()->get();
4517
echo $response->statusCode();
4518
echo $response->body();
4519
echo $response->headers();
4520
```
4521
## List the domain whitelabel associated with the given user.
4522
 
4523
**This endpoint allows you to retrieve all of the whitelabels that have been assigned to a specific subuser.**
4524
 
4525
A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.
4526
 
4527
Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools.
4528
 
4529
For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)
4530
 
4531
## URI Parameters
4532
| URI Parameter   | Type  | Description  |
4533
|---|---|---|
4534
| username | string  | Username of the subuser to find associated whitelabels for. |
4535
 
4536
### GET /whitelabel/domains/subuser
4537
 
4538
 
4539
```php
4540
$response = $sg->client->whitelabel()->domains()->subuser()->get();
4541
echo $response->statusCode();
4542
echo $response->body();
4543
echo $response->headers();
4544
```
4545
## Disassociate a domain whitelabel from a given user.
4546
 
4547
**This endpoint allows you to disassociate a specific whitelabel from a subuser.**
4548
 
4549
A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.
4550
 
4551
Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools.
4552
 
4553
For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)
4554
 
4555
## URI Parameters
4556
| URI Parameter   | Type  | Required?  | Description  |
4557
|---|---|---|---|
4558
| username | string  | required  | Username for the subuser to find associated whitelabels for. |
4559
 
4560
### DELETE /whitelabel/domains/subuser
4561
 
4562
 
4563
```php
4564
$response = $sg->client->whitelabel()->domains()->subuser()->delete();
4565
echo $response->statusCode();
4566
echo $response->body();
4567
echo $response->headers();
4568
```
4569
## Update a domain whitelabel.
4570
 
4571
**This endpoint allows you to update the settings for a domain whitelabel.**
4572
 
4573
A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.
4574
 
4575
For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)
4576
 
4577
### PATCH /whitelabel/domains/{domain_id}
4578
 
4579
 
4580
```php
4581
$request_body = json_decode('{
4582
  "custom_spf": true,
4583
  "default": false
4584
}');
4585
$domain_id = "test_url_param";
4586
$response = $sg->client->whitelabel()->domains()->_($domain_id)->patch($request_body);
4587
echo $response->statusCode();
4588
echo $response->body();
4589
echo $response->headers();
4590
```
4591
## Retrieve a domain whitelabel.
4592
 
4593
**This endpoint allows you to retrieve a specific domain whitelabel.**
4594
 
4595
A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.
4596
 
4597
For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)
4598
 
4599
 
4600
### GET /whitelabel/domains/{domain_id}
4601
 
4602
 
4603
```php
4604
$domain_id = "test_url_param";
4605
$response = $sg->client->whitelabel()->domains()->_($domain_id)->get();
4606
echo $response->statusCode();
4607
echo $response->body();
4608
echo $response->headers();
4609
```
4610
## Delete a domain whitelabel.
4611
 
4612
**This endpoint allows you to delete a domain whitelabel.**
4613
 
4614
A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.
4615
 
4616
For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)
4617
 
4618
### DELETE /whitelabel/domains/{domain_id}
4619
 
4620
 
4621
```php
4622
$domain_id = "test_url_param";
4623
$response = $sg->client->whitelabel()->domains()->_($domain_id)->delete();
4624
echo $response->statusCode();
4625
echo $response->body();
4626
echo $response->headers();
4627
```
4628
## Associate a domain whitelabel with a given user.
4629
 
4630
**This endpoint allows you to associate a specific domain whitelabel with a subuser.**
4631
 
4632
A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.
4633
 
4634
Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools.
4635
 
4636
For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)
4637
 
4638
## URI Parameters
4639
| URI Parameter   | Type   | Description  |
4640
|---|---|---|
4641
| domain_id | integer   | ID of the domain whitelabel to associate with the subuser. |
4642
 
4643
### POST /whitelabel/domains/{domain_id}/subuser
4644
 
4645
 
4646
```php
4647
$request_body = json_decode('{
4648
  "username": "jane@example.com"
4649
}');
4650
$domain_id = "test_url_param";
4651
$response = $sg->client->whitelabel()->domains()->_($domain_id)->subuser()->post($request_body);
4652
echo $response->statusCode();
4653
echo $response->body();
4654
echo $response->headers();
4655
```
4656
## Add an IP to a domain whitelabel.
4657
 
4658
**This endpoint allows you to add an IP address to a domain whitelabel.**
4659
 
4660
A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.
4661
 
4662
For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)
4663
 
4664
## URI Parameters
4665
| URI Parameter   | Type  |  Description  |
4666
|---|---|---|
4667
| id | integer  | ID of the domain to which you are adding an IP |
4668
 
4669
### POST /whitelabel/domains/{id}/ips
4670
 
4671
 
4672
```php
4673
$request_body = json_decode('{
4674
  "ip": "192.168.0.1"
4675
}');
4676
$id = "test_url_param";
4677
$response = $sg->client->whitelabel()->domains()->_($id)->ips()->post($request_body);
4678
echo $response->statusCode();
4679
echo $response->body();
4680
echo $response->headers();
4681
```
4682
## Remove an IP from a domain whitelabel.
4683
 
4684
**This endpoint allows you to remove a domain's IP address from that domain's whitelabel.**
4685
 
4686
A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.
4687
 
4688
For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)
4689
 
4690
## URI Parameters
4691
| URI Parameter   | Type  | Description  |
4692
|---|---|---|
4693
| id | integer  | ID of the domain whitelabel to delete the IP from. |
4694
| ip | string | IP to remove from the domain whitelabel. |
4695
 
4696
### DELETE /whitelabel/domains/{id}/ips/{ip}
4697
 
4698
 
4699
```php
4700
$id = "test_url_param";
4701
$ip = "test_url_param";
4702
$response = $sg->client->whitelabel()->domains()->_($id)->ips()->_($ip)->delete();
4703
echo $response->statusCode();
4704
echo $response->body();
4705
echo $response->headers();
4706
```
4707
## Validate a domain whitelabel.
4708
 
4709
**This endpoint allows you to validate a domain whitelabel. If it fails, it will return an error message describing why the whitelabel could not be validated.**
4710
 
4711
A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.
4712
 
4713
For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)
4714
 
4715
## URI Parameters
4716
| URI Parameter   | Type   | Description  |
4717
|---|---|---|
4718
| id | integer  |ID of the domain whitelabel to validate. |
4719
 
4720
### POST /whitelabel/domains/{id}/validate
4721
 
4722
 
4723
```php
4724
$id = "test_url_param";
4725
$response = $sg->client->whitelabel()->domains()->_($id)->validate()->post();
4726
echo $response->statusCode();
4727
echo $response->body();
4728
echo $response->headers();
4729
```
4730
## Create an IP whitelabel
4731
 
4732
**This endpoint allows you to create an IP whitelabel.**
4733
 
4734
When creating an IP whitelable, you should use the same subdomain that you used when you created a domain whitelabel.
4735
 
4736
A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.
4737
 
4738
For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).
4739
 
4740
### POST /whitelabel/ips
4741
 
4742
 
4743
```php
4744
$request_body = json_decode('{
4745
  "domain": "example.com",
4746
  "ip": "192.168.1.1",
4747
  "subdomain": "email"
4748
}');
4749
$response = $sg->client->whitelabel()->ips()->post($request_body);
4750
echo $response->statusCode();
4751
echo $response->body();
4752
echo $response->headers();
4753
```
4754
## Retrieve all IP whitelabels
4755
 
4756
**This endpoint allows you to retrieve all of the IP whitelabels that have been createdy by this account.**
4757
 
4758
You may include a search key by using the "ip" parameter. This enables you to perform a prefix search for a given IP segment (e.g. "192.").
4759
 
4760
A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.
4761
 
4762
For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).
4763
 
4764
### GET /whitelabel/ips
4765
 
4766
 
4767
```php
4768
$query_params = json_decode('{"ip": "test_string", "limit": 1, "offset": 1}');
4769
$response = $sg->client->whitelabel()->ips()->get(null, $query_params);
4770
echo $response->statusCode();
4771
echo $response->body();
4772
echo $response->headers();
4773
```
4774
## Retrieve an IP whitelabel
4775
 
4776
**This endpoint allows you to retrieve an IP whitelabel.**
4777
 
4778
A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.
4779
 
4780
For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).
4781
 
4782
### GET /whitelabel/ips/{id}
4783
 
4784
 
4785
```php
4786
$id = "test_url_param";
4787
$response = $sg->client->whitelabel()->ips()->_($id)->get();
4788
echo $response->statusCode();
4789
echo $response->body();
4790
echo $response->headers();
4791
```
4792
## Delete an IP whitelabel
4793
 
4794
**This endpoint allows you to delete an IP whitelabel.**
4795
 
4796
A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.
4797
 
4798
For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).
4799
 
4800
### DELETE /whitelabel/ips/{id}
4801
 
4802
 
4803
```php
4804
$id = "test_url_param";
4805
$response = $sg->client->whitelabel()->ips()->_($id)->delete();
4806
echo $response->statusCode();
4807
echo $response->body();
4808
echo $response->headers();
4809
```
4810
## Validate an IP whitelabel
4811
 
4812
**This endpoint allows you to validate an IP whitelabel.**
4813
 
4814
A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.
4815
 
4816
For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).
4817
 
4818
### POST /whitelabel/ips/{id}/validate
4819
 
4820
 
4821
```php
4822
$id = "test_url_param";
4823
$response = $sg->client->whitelabel()->ips()->_($id)->validate()->post();
4824
echo $response->statusCode();
4825
echo $response->body();
4826
echo $response->headers();
4827
```
4828
## Create a Link Whitelabel
4829
 
4830
**This endpoint allows you to create a new link whitelabel.**
4831
 
4832
Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.
4833
 
4834
For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).
4835
 
4836
### POST /whitelabel/links
4837
 
4838
 
4839
```php
4840
$request_body = json_decode('{
4841
  "default": true,
4842
  "domain": "example.com",
4843
  "subdomain": "mail"
4844
}');
4845
$query_params = json_decode('{"limit": 1, "offset": 1}');
4846
$response = $sg->client->whitelabel()->links()->post($request_body, $query_params);
4847
echo $response->statusCode();
4848
echo $response->body();
4849
echo $response->headers();
4850
```
4851
## Retrieve all link whitelabels
4852
 
4853
**This endpoint allows you to retrieve all link whitelabels.**
4854
 
4855
Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.
4856
 
4857
For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).
4858
 
4859
### GET /whitelabel/links
4860
 
4861
 
4862
```php
4863
$query_params = json_decode('{"limit": 1}');
4864
$response = $sg->client->whitelabel()->links()->get(null, $query_params);
4865
echo $response->statusCode();
4866
echo $response->body();
4867
echo $response->headers();
4868
```
4869
## Retrieve a Default Link Whitelabel
4870
 
4871
**This endpoint allows you to retrieve the default link whitelabel.**
4872
 
4873
Default link whitelabel is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the default is determined by the following order:
4874
<ul>
4875
  <li>Validated link whitelabels marked as "default"</li>
4876
  <li>Legacy link whitelabels (migrated from the whitelabel wizard)</li>
4877
  <li>Default SendGrid link whitelabel (i.e. 100.ct.sendgrid.net)</li>
4878
</ul>
4879
 
4880
Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.
4881
 
4882
For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).
4883
 
4884
### GET /whitelabel/links/default
4885
 
4886
 
4887
```php
4888
$query_params = json_decode('{"domain": "test_string"}');
4889
$response = $sg->client->whitelabel()->links()->default()->get(null, $query_params);
4890
echo $response->statusCode();
4891
echo $response->body();
4892
echo $response->headers();
4893
```
4894
## Retrieve Associated Link Whitelabel
4895
 
4896
**This endpoint allows you to retrieve the associated link whitelabel for a subuser.**
4897
 
4898
Link whitelables can be associated with subusers from the parent account. This functionality allows
4899
subusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account
4900
must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface.
4901
 
4902
Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.
4903
 
4904
For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).
4905
 
4906
### GET /whitelabel/links/subuser
4907
 
4908
 
4909
```php
4910
$query_params = json_decode('{"username": "test_string"}');
4911
$response = $sg->client->whitelabel()->links()->subuser()->get(null, $query_params);
4912
echo $response->statusCode();
4913
echo $response->body();
4914
echo $response->headers();
4915
```
4916
## Disassociate a Link Whitelabel
4917
 
4918
**This endpoint allows you to disassociate a link whitelabel from a subuser.**
4919
 
4920
Link whitelables can be associated with subusers from the parent account. This functionality allows
4921
subusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account
4922
must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface.
4923
 
4924
Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.
4925
 
4926
For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).
4927
 
4928
### DELETE /whitelabel/links/subuser
4929
 
4930
 
4931
```php
4932
$query_params = json_decode('{"username": "test_string"}');
4933
$response = $sg->client->whitelabel()->links()->subuser()->delete(null, $query_params);
4934
echo $response->statusCode();
4935
echo $response->body();
4936
echo $response->headers();
4937
```
4938
## Update a Link Whitelabel
4939
 
4940
**This endpoint allows you to update a specific link whitelabel. You can use this endpoint to change a link whitelabel's default status.**
4941
 
4942
Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.
4943
 
4944
For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).
4945
 
4946
### PATCH /whitelabel/links/{id}
4947
 
4948
 
4949
```php
4950
$request_body = json_decode('{
4951
  "default": true
4952
}');
4953
$id = "test_url_param";
4954
$response = $sg->client->whitelabel()->links()->_($id)->patch($request_body);
4955
echo $response->statusCode();
4956
echo $response->body();
4957
echo $response->headers();
4958
```
4959
## Retrieve a Link Whitelabel
4960
 
4961
**This endpoint allows you to retrieve a specific link whitelabel.**
4962
 
4963
Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.
4964
 
4965
For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).
4966
 
4967
### GET /whitelabel/links/{id}
4968
 
4969
 
4970
```php
4971
$id = "test_url_param";
4972
$response = $sg->client->whitelabel()->links()->_($id)->get();
4973
echo $response->statusCode();
4974
echo $response->body();
4975
echo $response->headers();
4976
```
4977
## Delete a Link Whitelabel
4978
 
4979
**This endpoint allows you to delete a link whitelabel.**
4980
 
4981
Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.
4982
 
4983
For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).
4984
 
4985
### DELETE /whitelabel/links/{id}
4986
 
4987
 
4988
```php
4989
$id = "test_url_param";
4990
$response = $sg->client->whitelabel()->links()->_($id)->delete();
4991
echo $response->statusCode();
4992
echo $response->body();
4993
echo $response->headers();
4994
```
4995
## Validate a Link Whitelabel
4996
 
4997
**This endpoint allows you to validate a link whitelabel.**
4998
 
4999
Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.
5000
 
5001
For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).
5002
 
5003
### POST /whitelabel/links/{id}/validate
5004
 
5005
 
5006
```php
5007
$id = "test_url_param";
5008
$response = $sg->client->whitelabel()->links()->_($id)->validate()->post();
5009
echo $response->statusCode();
5010
echo $response->body();
5011
echo $response->headers();
5012
```
5013
## Associate a Link Whitelabel
5014
 
5015
**This endpoint allows you to associate a link whitelabel with a subuser account.**
5016
 
5017
Link whitelables can be associated with subusers from the parent account. This functionality allows
5018
subusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account
5019
must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface.
5020
 
5021
Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.
5022
 
5023
For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).
5024
 
5025
### POST /whitelabel/links/{link_id}/subuser
5026
 
5027
 
5028
```php
5029
$request_body = json_decode('{
5030
  "username": "jane@example.com"
5031
}');
5032
$link_id = "test_url_param";
5033
$response = $sg->client->whitelabel()->links()->_($link_id)->subuser()->post($request_body);
5034
echo $response->statusCode();
5035
echo $response->body();
5036
echo $response->headers();
5037
```
5038