@sendgrid/client
Version:
Twilio SendGrid NodeJS API client
1,566 lines (1,181 loc) • 225 kB
Markdown
This documentation is based on our [OAI specification](https://github.com/sendgrid/sendgrid-oai).
# INITIALIZATION
```javascript
const client = require('@sendgrid/client');
client.setApiKey(process.env.SENDGRID_API_KEY);
```
# Table of Contents
* [ACCESS SETTINGS](#access-settings)
* [ALERTS](#alerts)
* [API KEYS](#api-keys)
* [ASM](#asm)
* [BROWSERS](#browsers)
* [CAMPAIGNS](#campaigns)
* [CATEGORIES](#categories)
* [CLIENTS](#clients)
* [CONTACTDB](#contactdb)
* [DEVICES](#devices)
* [GEO](#geo)
* [IPS](#ips)
* [MAIL](#mail)
* [MAIL SETTINGS](#mail-settings)
* [MAILBOX PROVIDERS](#mailbox-providers)
* [MESSAGES](#messages)
* [PARTNER SETTINGS](#partner-settings)
* [SCOPES](#scopes)
* [SENDERS](#senders)
* [SENDER AUTHENTICATION](#sender-authentication)
* [STATS](#stats)
* [SUBUSERS](#subusers)
* [SUPPRESSION](#suppression)
* [TEAMMATES](#teammates)
* [TEMPLATES](#templates)
* [TRACKING SETTINGS](#tracking-settings)
* [USER](#user)
# On behalf of subusers
Most API calls will accept an `on-behalf-of` header
in order to make API calls as a given subuser:
```javascript
// create an API key for the given subuser
const data = {
name: 'subuser API key',
scopes: ['mail.send'],
};
request.body = data;
request.method = 'POST';
request.url = '/v3/api_keys';
request.headers = { 'On-Behalf-Of': 'subuser username' };
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
});
```
<a name="access-settings"></a>
# ACCESS SETTINGS
## Retrieve all recent access attempts
**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.**
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 IP address from the whitelist, thus preventing yourself from accessing your account.
For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).
### GET /access_settings/activity
```javascript
const queryParams = {
'limit': 1
};
request.qs = queryParams;
request.method = 'GET';
request.url = '/v3/access_settings/activity';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Add one or more IPs to the whitelist
**This endpoint allows you to add one or more IP addresses to your IP whitelist.**
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.
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 IP address from the whitelist, thus preventing yourself from accessing your account.
For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).
### POST /access_settings/whitelist
```javascript
const data = {
"ips": [
{
"ip": "192.168.1.1"
},
{
"ip": "192.*.*.*"
},
{
"ip": "192.168.1.3/32"
}
]
};
request.body = data;
request.method = 'POST';
request.url = '/v3/access_settings/whitelist';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Remove one or more IPs from the whitelist
**This endpoint allows you to remove one or more IPs from your IP whitelist.**
You can remove one IP at a time, or you can remove multiple IP addresses.
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 IP address from the whitelist, thus preventing yourself from accessing your account.
For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).
### DELETE /access_settings/whitelist
```javascript
const data = {
"ids": [
1,
2,
3
]
};
request.body = data;
request.method = 'DELETE';
request.url = '/v3/access_settings/whitelist';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve a list of currently whitelisted IPs
**This endpoint allows you to retrieve a list of IP addresses that are currently whitelisted.**
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 IP address from the whitelist, thus preventing yourself from accessing your account.
For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).
### GET /access_settings/whitelist
```javascript
request.method = 'GET';
request.url = '/v3/access_settings/whitelist';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Remove a specific IP from the whitelist
**This endpoint allows you to remove a specific IP address from your IP whitelist.**
When removing a specific IP address from your whitelist, you must include the ID in your call.
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 IP address from the whitelist, thus preventing yourself from accessing your account.
For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).
### DELETE /access_settings/whitelist/{rule_id}
```javascript
request.method = 'DELETE';
request.url = '/v3/access_settings/whitelist/{rule_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve a specific whitelisted IP
**This endpoint allows you to retrieve a specific IP address that has been whitelisted.**
You must include the ID for the specific IP address you want to retrieve in your call.
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 IP address from the whitelist, thus preventing yourself from accessing your account.
For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).
### GET /access_settings/whitelist/{rule_id}
```javascript
request.method = 'GET';
request.url = '/v3/access_settings/whitelist/{rule_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
<a name="alerts"></a>
# ALERTS
## Create a new Alert
**This endpoint allows you to create a new alert.**
Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. There are two types of alerts available with this endpoint:
* `usage_limit` allows you to set the threshold at which an alert will be sent.
* `stats_notification` allows you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".
For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).
### POST /alerts
```javascript
const data = {
"email_to": "example@example.com",
"frequency": "daily",
"type": "stats_notification"
};
request.body = data;
request.method = 'POST';
request.url = '/v3/alerts';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve all alerts
**This endpoint allows you to retrieve all of your alerts.**
Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics.
* Usage alerts allow you to set the threshold at which an alert will be sent.
* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".
For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).
### GET /alerts
```javascript
request.method = 'GET';
request.url = '/v3/alerts';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Update an alert
**This endpoint allows you to update an alert.**
Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics.
* Usage alerts allow you to set the threshold at which an alert will be sent.
* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".
For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).
### PATCH /alerts/{alert_id}
```javascript
const data = {
"email_to": "example@example.com"
};
request.body = data;
request.method = 'PATCH';
request.url = '/v3/alerts/{alert_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Delete an alert
**This endpoint allows you to delete an alert.**
Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics.
* Usage alerts allow you to set the threshold at which an alert will be sent.
* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".
For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).
### DELETE /alerts/{alert_id}
```javascript
request.method = 'DELETE';
request.url = '/v3/alerts/{alert_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve a specific alert
**This endpoint allows you to retrieve a specific alert.**
Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics.
* Usage alerts allow you to set the threshold at which an alert will be sent.
* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".
For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).
### GET /alerts/{alert_id}
```javascript
request.method = 'GET';
request.url = '/v3/alerts/{alert_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
<a name="api-keys"></a>
# API KEYS
## Create API keys
**This endpoint allows you to create a new random API Key for the user.**
A JSON request body containing a "name" property is required. If the number of maximum keys is reached, HTTP 403 will be returned.
There is a limit of 100 API Keys on your account.
The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the Twilio SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).
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.
### POST /api_keys
```javascript
const data = {
"name": "My API Key",
"sample": "data",
"scopes": [
"mail.send",
"alerts.create",
"alerts.read"
]
};
request.body = data;
request.method = 'POST';
request.url = '/v3/api_keys';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve all API Keys belonging to the authenticated user
**This endpoint allows you to retrieve all API Keys that belong to the authenticated user.**
The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the Twilio SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).
### GET /api_keys
```javascript
const queryParams = {
'limit': 1
};
request.qs = queryParams;
request.method = 'GET';
request.url = '/v3/api_keys';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Update the name & scopes of an API Key
**This endpoint allows you to update the name and scopes of a given API key.**
A JSON request body with a "name" property is required.
Most provide the list of all the scopes an API key should have.
The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the Twilio SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).
### PUT /api_keys/{api_key_id}
```javascript
const data = {
"name": "A New Hope",
"scopes": [
"user.profile.read",
"user.profile.update"
]
};
request.body = data;
request.method = 'PUT';
request.url = '/v3/api_keys/{api_key_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Update API keys
**This endpoint allows you to update the name of an existing API Key.**
A JSON request body with a "name" property is required.
The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the Twilio SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).
## URI Parameters
| URI Parameter | Type | Required? | Description |
|---|---|---|---|
|api_key_id |string | required | The ID of the API Key you are updating.|
### PATCH /api_keys/{api_key_id}
```javascript
const data = {
"name": "A New Hope"
};
request.body = data;
request.method = 'PATCH';
request.url = '/v3/api_keys/{api_key_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Delete API keys
**This endpoint allows you to revoke an existing API Key**
Authentications using this API Key will fail after this request is made, with some small propagation delay. If the API Key ID does not exist an HTTP 404 will be returned.
The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the Twilio SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).
## URI Parameters
| URI Parameter | Type | Required? | Description |
|---|---|---|---|
|api_key_id |string | required | The ID of the API Key you are deleting.|
### DELETE /api_keys/{api_key_id}
```javascript
request.method = 'DELETE';
request.url = '/v3/api_keys/{api_key_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve an existing API Key
**This endpoint allows you to retrieve a single API key.**
If the API Key ID does not exist an HTTP 404 will be returned.
### GET /api_keys/{api_key_id}
```javascript
request.method = 'GET';
request.url = '/v3/api_keys/{api_key_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
<a name="asm"></a>
# ASM
## Create a new suppression group
**This endpoint allows you to create a new suppression group.**
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.
The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.
Each user can create up to 25 different suppression groups.
### POST /asm/groups
```javascript
const data = {
"description": "Suggestions for products our users might like.",
"is_default": true,
"name": "Product Suggestions"
};
request.body = data;
request.method = 'POST';
request.url = '/v3/asm/groups';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve information about multiple suppression groups
**This endpoint allows you to retrieve information about multiple suppression groups.**
This endpoint will return information for each group ID that you include in your request. To add a group ID to your request, just append `&id=` followed by the group ID.
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).
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 receiving your transactional email without having to receive your marketing content.
### GET /asm/groups
```javascript
const queryParams = {
'id': 1
};
request.qs = queryParams;
request.method = 'GET';
request.url = '/v3/asm/groups';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Delete a suppression group.
**This endpoint allows you to delete a suppression group.**
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.
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.
The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.
Each user can create up to 25 different suppression groups.
### DELETE /asm/groups/{group_id}
```javascript
request.method = 'DELETE';
request.url = '/v3/asm/groups/{group_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Update a suppression group.
**This endpoint allows you to update or change a suppression group.**
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.
The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.
Each user can create up to 25 different suppression groups.
### PATCH /asm/groups/{group_id}
```javascript
const data = {
"description": "Suggestions for items our users might like.",
"id": 103,
"name": "Item Suggestions"
};
request.body = data;
request.method = 'PATCH';
request.url = '/v3/asm/groups/{group_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Get information on a single suppression group.
**This endpoint allows you to retrieve a single suppression group.**
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.
The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.
Each user can create up to 25 different suppression groups.
### GET /asm/groups/{group_id}
```javascript
request.method = 'GET';
request.url = '/v3/asm/groups/{group_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Add suppressions to a suppression group
**This endpoint allows you to add email addresses to an unsubscribe group.**
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.
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.
### POST /asm/groups/{group_id}/suppressions
```javascript
const data = {
"recipient_emails": [
"test1@example.com",
"test2@example.com"
]
};
request.body = data;
request.method = 'POST';
request.url = '/v3/asm/groups/{group_id}/suppressions';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve all suppressions for a suppression group
**This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.**
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.
### GET /asm/groups/{group_id}/suppressions
```javascript
request.method = 'GET';
request.url = '/v3/asm/groups/{group_id}/suppressions';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Search for suppressions within a group
**This endpoint allows you to search a suppression group for multiple suppressions.**
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.
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).
### POST /asm/groups/{group_id}/suppressions/search
```javascript
const data = {
"recipient_emails": [
"exists1@example.com",
"exists2@example.com",
"doesnotexists@example.com"
]
};
request.body = data;
request.method = 'POST';
request.url = '/v3/asm/groups/{group_id}/suppressions/search';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Delete a suppression from a suppression group
**This endpoint allows you to remove a suppressed email address from the given suppression group.**
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.
### DELETE /asm/groups/{group_id}/suppressions/{email}
```javascript
request.method = 'DELETE';
request.url = '/v3/asm/groups/{group_id}/suppressions/{email}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve all suppressions
**This endpoint allows you to retrieve a list of all suppressions.**
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).
### GET /asm/suppressions
```javascript
request.method = 'GET';
request.url = '/v3/asm/suppressions';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Add recipient addresses to the global suppression group.
**This endpoint allows you to add one or more email addresses to the global suppressions group.**
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).
### POST /asm/suppressions/global
```javascript
const data = {
"recipient_emails": [
"test1@example.com",
"test2@example.com"
]
};
request.body = data;
request.method = 'POST';
request.url = '/v3/asm/suppressions/global';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Delete a Global Suppression
**This endpoint allows you to remove an email address from the global suppressions group.**
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).
### DELETE /asm/suppressions/global/{email}
```javascript
request.method = 'DELETE';
request.url = '/v3/asm/suppressions/global/{email}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve a Global Suppression
**This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppressed.**
If the email address you include in the URL path parameter `{email}` is already 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.
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).
### GET /asm/suppressions/global/{email}
```javascript
request.method = 'GET';
request.url = '/v3/asm/suppressions/global/{email}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve all suppression groups for an email address
**This endpoint returns the list of all groups that the given email address has been unsubscribed from.**
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).
### GET /asm/suppressions/{email}
```javascript
request.method = 'GET';
request.url = '/v3/asm/suppressions/{email}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
<a name="browsers"></a>
# BROWSERS
## Retrieve email statistics from a browser.
**This endpoint allows you to retrieve your email statistics segmented by browser type.**
**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.
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).
### GET /browsers/stats
```javascript
const queryParams = {
'aggregated_by': 'day',
'browsers': 'test_string',
'end_date': '2016-04-01',
'limit': 'test_string',
'offset': 'test_string',
'start_date': '2016-01-01'
};
request.qs = queryParams;
request.method = 'GET';
request.url = '/v3/browsers/stats';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
<a name="campaigns"></a>
# CAMPAIGNS
## Create a Campaign
**This endpoint allows you to create a campaign.**
Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.
Note: 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.
For more information:
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
### POST /campaigns
```javascript
const data = {
"categories": [
"spring line"
],
"custom_unsubscribe_url": "",
"html_content": "<html><head><title></title></head><body><p>Check out our spring line!</p></body></html>",
"ip_pool": "marketing",
"list_ids": [
110,
124
],
"plain_content": "Check out our spring line!",
"segment_ids": [
110
],
"sender_id": 124451,
"subject": "New Products for Spring!",
"suppression_group_id": 42,
"title": "March Newsletter"
};
request.body = data;
request.method = 'POST';
request.url = '/v3/campaigns';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve all Campaigns
**This endpoint allows you to retrieve a list of all of your campaigns.**
Returns campaigns in reverse order they were created (newest first).
Returns an empty array if no campaigns exist.
For more information:
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
### GET /campaigns
```javascript
const queryParams = {
'limit': 1,
'offset': 1
};
request.qs = queryParams;
request.method = 'GET';
request.url = '/v3/campaigns';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Update a Campaign
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.
For more information:
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
### PATCH /campaigns/{campaign_id}
```javascript
const data = {
"categories": [
"summer line"
],
"html_content": "<html><head><title></title></head><body><p>Check out our summer line!</p></body></html>",
"plain_content": "Check out our summer line!",
"subject": "New Products for Summer!",
"title": "May Newsletter"
};
request.body = data;
request.method = 'PATCH';
request.url = '/v3/campaigns/{campaign_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Delete a Campaign
**This endpoint allows you to delete a specific campaign.**
Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.
For more information:
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
### DELETE /campaigns/{campaign_id}
```javascript
request.method = 'DELETE';
request.url = '/v3/campaigns/{campaign_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve a single campaign
**This endpoint allows you to retrieve a specific campaign.**
Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.
For more information:
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
### GET /campaigns/{campaign_id}
```javascript
request.method = 'GET';
request.url = '/v3/campaigns/{campaign_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Unschedule a Scheduled Campaign
**This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.**
A successful unschedule will return a 204.
If the specified campaign is in the process of being sent, the only option is to cancel (a different method).
For more information:
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
### DELETE /campaigns/{campaign_id}/schedules
```javascript
request.method = 'DELETE';
request.url = '/v3/campaigns/{campaign_id}/schedules';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Schedule a Campaign
**This endpoint allows you to schedule a specific date and time for your campaign to be sent.**
For more information:
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
### POST /campaigns/{campaign_id}/schedules
```javascript
const data = {
"send_at": 1489771528
};
request.body = data;
request.method = 'POST';
request.url = '/v3/campaigns/{campaign_id}/schedules';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## View Scheduled Time of a Campaign
**This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent.**
For more information:
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
### GET /campaigns/{campaign_id}/schedules
```javascript
request.method = 'GET';
request.url = '/v3/campaigns/{campaign_id}/schedules';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Update a Scheduled Campaign
**This endpoint allows to you change the scheduled time and date for a campaign to be sent.**
For more information:
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
### PATCH /campaigns/{campaign_id}/schedules
```javascript
const data = {
"send_at": 1489451436
};
request.body = data;
request.method = 'PATCH';
request.url = '/v3/campaigns/{campaign_id}/schedules';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Send a Campaign
**This endpoint allows you to immediately send a campaign at the time you make the API call.**
Usually, 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.
For more information:
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
### POST /campaigns/{campaign_id}/schedules/now
```javascript
request.method = 'POST';
request.url = '/v3/campaigns/{campaign_id}/schedules/now';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Send a Test Campaign
**This endpoint allows you to send a test campaign.**
To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"]
For more information:
* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)
### POST /campaigns/{campaign_id}/schedules/test
```javascript
const data = {
"to": "your.email@example.com"
};
request.body = data;
request.method = 'POST';
request.url = '/v3/campaigns/{campaign_id}/schedules/test';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
<a name="categories"></a>
# CATEGORIES
## Retrieve all categories
**This endpoint allows you to retrieve a list of all of your categories.**
Categories can help organize your email analytics by enabling you to tag emails by type or broad topic. You can define your custom categories. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html).
### GET /categories
```javascript
const queryParams = {
'category': 'test_string',
'limit': 1,
'offset': 1
};
request.qs = queryParams;
request.method = 'GET';
request.url = '/v3/categories';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve Email Statistics for Categories
**This endpoint allows you to retrieve all of your email statistics for each of your categories.**
If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.
Categories allow you to group your emails according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html).
### GET /categories/stats
```javascript
const queryParams = {
'aggregated_by': 'day',
'categories': 'test_string',
'end_date': '2016-04-01',
'limit': 1,
'offset': 1,
'start_date': '2016-01-01'
};
request.qs = queryParams;
request.method = 'GET';
request.url = '/v3/categories/stats';
client
.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
**Attention:** in order to receive the email statistics for multiple categories at once, you need to set the `qsStringifyOptions` as follows:
```javascript
const client = require('@sendgrid/client')
client.setDefaultRequest('qsStringifyOptions', {arrayFormat: 'repeat'});
const request = {}
const queryParams = {
'aggregated_by': 'day',
'categories': ['test_category_1', 'cat facts'],
'end_date': '2016-04-01',
'limit': 1,
'offset': 1,
'start_date': '2016-01-01'
};
request.qs = queryParams;
request.method = 'GET';
request.url = '/v3/categories/stats';
client
.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]
**This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.**
If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.
Categories allow you to group your emails according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html).
### GET /categories/stats/sums
```javascript
const queryParams = {
'aggregated_by': 'day',
'end_date': '2016-04-01',
'limit': 1,
'offset': 1,
'sort_by_direction': 'asc',
'sort_by_metric': 'test_string',
'start_date': '2016-01-01'
};
request.qs = queryParams;
request.method = 'GET';
request.url = '/v3/categories/stats/sums';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
<a name="clients"></a>
# CLIENTS
## Retrieve email statistics by client type.
**This endpoint allows you to retrieve your email statistics segmented by client type.**
**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.
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).
### GET /clients/stats
```javascript
const queryParams = {
'aggregated_by': 'day',
'end_date': '2016-04-01',
'start_date': '2016-01-01'
};
request.qs = queryParams;
request.method = 'GET';
request.url = '/v3/clients/stats';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve stats by a specific client type.
**This endpoint allows you to retrieve your email statistics segmented by a specific client type.**
**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.
## Available Client Types
- phone
- tablet
- webmail
- desktop
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).
### GET /clients/{client_type}/stats
```javascript
const queryParams = {
'aggregated_by': 'day',
'end_date': '2016-04-01',
'start_date': '2016-01-01'
};
request.qs = queryParams;
request.method = 'GET';
request.url = '/v3/clients/{client_type}/stats';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
<a name="contactdb"></a>
# CONTACTDB
## Create a Custom Field
**This endpoint allows you to create a custom field.**
The contactdb is a database of your contacts for [Twilio SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).
### POST /contactdb/custom_fields
```javascript
const data = {
"name": "pet",
"type": "text"
};
request.body = data;
request.method = 'POST';
request.url = '/v3/contactdb/custom_fields';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve all custom fields
**This endpoint allows you to retrieve all custom fields.**
The contactdb is a database of your contacts for [Twilio SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).
### GET /contactdb/custom_fields
```javascript
request.method = 'GET';
request.url = '/v3/contactdb/custom_fields';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Delete a Custom Field
**This endpoint allows you to delete a custom field by ID.**
The contactdb is a database of your contacts for [Twilio SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).
### DELETE /contactdb/custom_fields/{custom_field_id}
```javascript
request.method = 'DELETE';
request.url = '/v3/contactdb/custom_fields/{custom_field_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve a Custom Field
**This endpoint allows you to retrieve a custom field by ID.**
The contactdb is a database of your contacts for [Twilio SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).
### GET /contactdb/custom_fields/{custom_field_id}
```javascript
request.method = 'GET';
request.url = '/v3/contactdb/custom_fields/{custom_field_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Create a List
**This endpoint allows you to create a list for your recipients.**
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
### POST /contactdb/lists
```javascript
const data = {
"name": "your list name"
};
request.body = data;
request.method = 'POST';
request.url = '/v3/contactdb/lists';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Delete Multiple lists
**This endpoint allows you to delete multiple recipient lists.**
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
### DELETE /contactdb/lists
```javascript
const data = [
1,
2,
3,
4
];
request.body = data;
request.method = 'DELETE';
request.url = '/v3/contactdb/lists';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve all lists
**This endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned.**
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
### GET /contactdb/lists
```javascript
request.method = 'GET';
request.url = '/v3/contactdb/lists';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Delete a List
**This endpoint allows you to delete a specific recipient list with the given ID.**
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
### DELETE /contactdb/lists/{list_id}
```javascript
const queryParams = {
'delete_contacts': 'true'
};
request.qs = queryParams;
request.method = 'DELETE';
request.url = '/v3/contactdb/lists/{list_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Update a List
**This endpoint allows you to update the name of one of your recipient lists.**
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
### PATCH /contactdb/lists/{list_id}
```javascript
const data = {
"name": "newlistname"
};
request.body = data;
const queryParams = {
'list_id': 1
};
request.qs = queryParams;
request.method = 'PATCH';
request.url = '/v3/contactdb/lists/{list_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve a single list
This endpoint allows you to retrieve a single recipient list.
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
### GET /contactdb/lists/{list_id}
```javascript
const queryParams = {
'list_id': 1
};
request.qs = queryParams;
request.method = 'GET';
request.url = '/v3/contactdb/lists/{list_id}';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Add Multiple Recipients to a List
**This endpoint allows you to add multiple recipients to a list.**
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.
The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.
### POST /contactdb/lists/{list_id}/recipients
```javascript
const data = [
"recipient_id1",
"recipient_id2"
];
request.body = data;
request.method = 'POST';
request.url = '/v3/contactdb/lists/{list_id}/recipients';
client.request(request)
.then(([response, body]) => {
console.log(response.statusCode);
console.log(response.body);
})
```
## Retrieve all recipients on a List
**This endpoint allows you to retrieve all recipients on the list with t