@datafire/sendgrid

Client library for SendGrid v3 API Documentation

Installation and Usage

npm install --save @datafire/sendgrid

let sendgrid = require('@datafire/sendgrid').create({
  Authorization: ""
});

.then(data => {
  console.log(data);
});

Description

The SendGrid Web API V3 Documentation

This is the entirety of the documented v3 endpoints. We have updated all the descriptions, parameters, requests, and responses.

Authentication

Every endpoint requires Authentication in the form of an Authorization Header:

Authorization: Bearer API_KEY

Actions

access_settings.activity.get

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 own IP address from the whitelist, thus preventing yourself from accessing your account.

For more information, please see our User Guide.

sendgrid.access_settings.activity.get({}, context)

Input

• input object
  • limit integer: Limits the number of IPs to return.
  • on-behalf-of string

Output

• output object
  • result array
    • items object
      • allowed boolean
      • auth_method string
      • first_at integer
      • ip string
      • last_at integer
      • location string

access_settings.whitelist.delete

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 own IP address from the whitelist, thus preventing yourself from accessing your account.

For more information, please see our User Guide.

sendgrid.access_settings.whitelist.delete({}, context)

Input

• input object
  • on-behalf-of string
  • body object
    • ids array: An array of the IDs of the IP address that you want to remove from your whitelist.
      • items integer

Output

• output object

access_settings.whitelist.get

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 own IP address from the whitelist, thus preventing yourself from accessing your account.

For more information, please see our User Guide.

sendgrid.access_settings.whitelist.get({}, context)

Input

• input object
  • on-behalf-of string

Output

• output object
  • result required array: An array listing all of your whitelisted IPs.
    • items object
      • created_at required integer: A Unix timestamp indicating when the IP was whitelisted.
      • id required integer: The ID of the whitelisted IP.
      • ip required string: The whitelisted IP.
      • updated_at required integer: A Unix timestamp indicating when the IPs whitelisting status was most recently updated.

access_settings.whitelist.post

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 own IP address from the whitelist, thus preventing yourself from accessing your account.

For more information, please see our User Guide.

sendgrid.access_settings.whitelist.post({}, context)

Input

• input object
  • on-behalf-of string
  • body object
    • ips required array: An array containing the IP(s) you want to whitelist.
      • items object
        • ip required string: An IP address that you want to whitelist.

Output

• output object
  • result required array: An array listing all of your whitelisted IPs.
    • items object
      • created_at required integer: A Unix timestamp indicating when the IP was whitelisted.
      • id required integer: The ID of the whitelisted IP.
      • ip required string: The whitelisted IP.
      • updated_at required integer: A Unix timestamp indicating when the IPs whitelisting status was most recently updated.

access_settings.whitelist.rule_id.delete

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 own IP address from the whitelist, thus preventing yourself from accessing your account.

For more information, please see our User Guide.

sendgrid.access_settings.whitelist.rule_id.delete({
  "rule_id": ""
}, context)

Input

• input object
  • on-behalf-of string
  • rule_id required string: The ID of the whitelisted IP address that you want to retrieve.

Output

• output object

access_settings.whitelist.rule_id.get

This endpoint allows you to retreive 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 own IP address from the whitelist, thus preventing yourself from accessing your account.

For more information, please see our User Guide.

sendgrid.access_settings.whitelist.rule_id.get({
  "rule_id": ""
}, context)

Input

• input object
  • on-behalf-of string
  • rule_id required string: The ID of the whitelisted IP address that you want to retrieve.

Output

• output object
  • created_at required integer: A Unix timestamp indicating when the IP was whitelisted.
  • id required integer: The ID of the IP address.
  • ip required string: The IP address.
  • updated_at required integer: A Unix timestamp indicating when the IP address was last updated.

GET_alerts

This endpoint allows you to retieve 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.

sendgrid.GET_alerts({}, context)

Input

• input object
  • Authorization string
  • on-behalf-of string

Output

• output array: The list of alerts.
  • items object
    • created_at required integer: A Unix timestamp indicating when the alert was created.
    • email_to required string: The email address that the alert will be sent to.
    • frequency string: If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, "daily", "weekly", or "monthly".
    • id required integer: The ID of the alert.
    • percentage integer: If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.
    • type required string (values: usage_limit, stats_notification): The type of alert.
    • updated_at integer: A Unix timestamp indicating when the alert was last modified.

POST_alerts

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 that can be created 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.

sendgrid.POST_alerts({}, context)

Input

• input object
  • Authorization string
  • on-behalf-of string
  • body object
    • email_to required string: The email address the alert will be sent to.
    • frequency string: Required for stats_notification. How frequently the alert will be sent.
    • percentage integer: Required for usage_alert. When this usage threshold is reached, the alert will be sent.
    • type required string (values: stats_notification, usage_limit): The type of alert you want to create. Can be either usage_limit or stats_notification.

Output

• output object
  • created_at required integer: A Unix timestamp indicating when the alert was created.
  • email_to required string: The email address that the alert will be sent to.
  • frequency string: If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, "daily", "weekly", or "monthly".
  • id required integer: The ID of the alert.
  • percentage integer: "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.
  • type required string: The type of alert.
  • updated_at required integer: A Unix timestamp indicating when the alert was last modified.

alerts.alert_id.delete

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.

sendgrid.alerts.alert_id.delete({
  "alert_id": 0
}, context)

Input

• input object
  • on-behalf-of string
  • alert_id required integer: The ID of the alert you would like to retrieve.

Output

• output object

alerts.alert_id.get

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.

sendgrid.alerts.alert_id.get({
  "alert_id": 0
}, context)

Input

• input object
  • Authorization string
  • on-behalf-of string
  • alert_id required integer: The ID of the alert you would like to retrieve.

Output

• output object
  • created_at required integer: A Unix timestamp indicating when the alert was created.
  • email_to required string: The email address that the alert will be sent to.
  • frequency string: If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: "daily", "weekly", or "monthly".
  • id required integer: The ID of the alert.
  • percentage integer: If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.
  • type required string (values: usage_alert, stats_notification): The type of alert.
  • updated_at required integer: A Unix timestamp indicating when the alert was last modified.

alerts.alert_id.patch

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.

sendgrid.alerts.alert_id.patch({
  "alert_id": 0
}, context)

Input

• input object
  • on-behalf-of string
  • body object
    • email_to string: The new email address you want your alert to be sent to.
    • frequency string: The new frequency at which to send the stats_notification alert.
    • percentage integer: The new percentage threshold at which the usage_limit alert will be sent.
  • alert_id required integer: The ID of the alert you would like to retrieve.

Output

• output object
  • created_at required integer: A Unix timestamp indicating when the alert was created.
  • email_to required string: The email address that the alert will be sent to.
  • frequency string: If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: "daily", "weekly", or "monthly".
  • id required integer: The ID of the alert.
  • percentage integer: If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.
  • type required string (values: usage_alert, stats_notification): The type of alert.
  • updated_at required integer: A Unix timestamp indicating when the alert was last modified.

GET_api_keys

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 SendGrid v3 Web API or the Mail API Endpoint.

sendgrid.GET_api_keys({}, context)

Input

• input object
  • limit integer
  • on-behalf-of string

Output

• output object
  • result array
    • items api_key_name_id

api_keys.post

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 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 SendGrid v3 Web API or the Mail API Endpoint.

See the API Key Permissions List for a list of all available scopes.

sendgrid.api_keys.post({}, context)

Input

• input object
  • on-behalf-of string
  • body object
    • name required string: The name you will use to describe this API Key.
    • sample string
    • scopes array: The individual permissions that you are giving to this API Key.
      • items string

Output

• output object
  • api_key string
  • api_key_id string
  • name string
  • scopes array
    • items string

api_keys.api_key_id.delete

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 propogation 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 SendGrid v3 Web API or the Mail API Endpoint.

URI Parameters

| URI Parameter | Type | Required? | Description | |---|---|---|---| |api_key_id |string | required | The ID of the API Key you are deleting.|

sendgrid.api_keys.api_key_id.delete({
  "api_key_id": ""
}, context)

Input

• input object
  • on-behalf-of string
  • api_key_id required string: The ID of the API Key for which you are requesting information.

Output

Output schema unknown

api_keys.api_key_id.get

This endpoint allows you to retrieve a single api key.

If the API Key ID does not exist an HTTP 404 will be returned.

sendgrid.api_keys.api_key_id.get({
  "api_key_id": ""
}, context)

Input

• input object
  • on-behalf-of string
  • api_key_id required string: The ID of the API Key for which you are requesting information.

Output

• output object
  • result array
    • items api_key_name_id_scopes

api_keys.api_key_id.patch

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 SendGrid v3 Web API or the Mail API Endpoint.

URI Parameters

| URI Parameter | Type | Required? | Description | |---|---|---|---| |api_key_id |string | required | The ID of the API Key you are updating.|

sendgrid.api_keys.api_key_id.patch({
  "api_key_id": ""
}, context)

Input

• input object
  • on-behalf-of string
  • body object
    • name string: The new name of the API Key.
  • api_key_id required string: The ID of the API Key for which you are requesting information.

Output

• output api_key_name_id

api_keys.api_key_id.put

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 SendGrid v3 Web API or the Mail API Endpoint.

sendgrid.api_keys.api_key_id.put({
  "api_key_id": ""
}, context)

Input

• input object
  • on-behalf-of string
  • body object
    • name string
    • scopes array
      • items string
  • api_key_id required string: The ID of the API Key for which you are requesting information.

Output

• output api_key_name_id_scopes

asm.groups.get

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, simply append &id= followed by the group ID.

Suppressions are a list of email addresses that will not receive content sent under a given group.

Suppression groups, or unsubscribe groups, 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.

sendgrid.asm.groups.get({}, context)

Input

• input object
  • id integer: The ID of a suppression group that you want to retrieve information for.
  • on-behalf-of string

Output

• output array
  • items suppression_group

asm.groups.post

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.

sendgrid.asm.groups.post({}, context)

Input

• input object
  • on-behalf-of string
  • body object
    • description required string: A brief description of your new suppression group.
    • is_default boolean: Indicates if you would like this to be your default suppression group.
    • name required string: The name that you would like to use for your new suppression group.

Output

• output object
  • description required string: A brief description of the suppression group.
  • id required integer: The ID of the suppression group.
  • is_default required boolean: Indicates if this is the default suppression group.
  • name required string: The name of the suppression group.

asm.groups.group_id.delete

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.

sendgrid.asm.groups.group_id.delete({
  "group_id": ""
}, context)

Input

• input object
  • on-behalf-of string
  • group_id required string: The ID of the suppression group you would like to retrieve.

Output

• output object

asm.groups.group_id.get

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.

sendgrid.asm.groups.group_id.get({
  "group_id": ""
}, context)

Input

• input object
  • on-behalf-of string
  • group_id required string: The ID of the suppression group you would like to retrieve.

Output

• output object
  • description string: The description of the suppression group.
  • id integer: The ID of the suppression group.
  • is_default boolean: Indicates if this is the default suppression group.
  • name string: The name of the suppression group.
  • unsubscribes integer: The number of unsubscribes, or suppressions, in this group.

asm.groups.group_id.patch

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.

sendgrid.asm.groups.group_id.patch({
  "Authorization": "",
  "group_id": ""
}, context)

Input

• input object
  • Authorization required string
  • on-behalf-of string
  • body object
    • description string: The description of the suppression group.
    • id integer: The id of the suppression group.
    • is_default boolean: Indicates if the suppression group is set as the default group.
    • name required string: The name of the suppression group. Each group created by a user must have a unique name.
  • group_id required string: The ID of the suppression group you would like to retrieve.

Output

• output suppression_group

asm.groups.group_id.suppressions.get

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. 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.

sendgrid.asm.groups.group_id.suppressions.get({
  "group_id": ""
}, context)

Input

• input object
  • on-behalf-of string
  • group_id required string: The id of the unsubscribe group that you are adding suppressions to.

Output

• output array: The list of email addresses belonging to the given suppression group.
  • items string

asm.groups.group_id.suppressions.post

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. 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.

sendgrid.asm.groups.group_id.suppressions.post({
  "group_id": ""
}, context)

Input

• input object
  • on-behalf-of string
  • body object
    • recipient_emails required array: The email address that you want to add to the unsubscribe group.
      • items string
  • group_id required string: The id of the unsubscribe group that you are adding suppressions to.

Output

• output object
  • recipient_emails required array: The email address that were added to the suppressions list.
    • items string

asm.groups.group_id.suppressions.search.post

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.

sendgrid.asm.groups.group_id.suppressions.search.post({
  "group_id": ""
}, context)

Input

• input object
  • on-behalf-of string
  • body object
    • recipient_emails required array: The list of email address that you want to search the suppression group for.
      • items string
  • group_id required string: The ID of the suppression group that you would like to search.

Output

• output object
  • recipient_emails required array: The email address from your search that do exist in the suppression group.
    • items string

asm.groups.group_id.suppressions.email.delete

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. 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.

sendgrid.asm.groups.group_id.suppressions.email.delete({
  "group_id": "",
  "email": ""
}, context)

Input

• input object
  • on-behalf-of string
  • group_id required string: The id of the suppression group that you are removing an email address from.
  • email required string: The email address that you want to remove from the suppression group.

Output

Output schema unknown

asm.suppressions.get

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.

sendgrid.asm.suppressions.get({}, context)

Input

• input object
  • on-behalf-of string

Output

• output array
  • items object
    • created_at required integer: A UNIX timestamp indicating when the suppression was created.
    • email required string: The email address that was suppressed.
    • group_id required integer: The id of the suppression group that this email address belongs to.
    • group_name required string: The name of the suppression group that this email address belongs to.

asm.suppressions.global.post

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.

sendgrid.asm.suppressions.global.post({}, context)

Input

• input object
  • on-behalf-of string
  • body object
    • recipient_emails array: The email address, or addresses, that you want to add to the global suppressions group.
      • items string

Output

• output object
  • recipient_emails required array: The email addresses that are globally suppressed
    • items string

asm.suppressions.global.email.delete

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.

sendgrid.asm.suppressions.global.email.delete({
  "email": ""
}, context)

Input

• input object
  • on-behalf-of string
  • email required string: The email address of the global suppression you want to retrieve. Or, if you want to check if an email address is on the global suppressions list, enter that email address here.

Output

• output object

asm.suppressions.global.email.get

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.

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.

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.

sendgrid.asm.suppressions.global.email.get({
  "email": ""
}, context)

Input

• input object
  • on-behalf-of string
  • email required string: The email address of the global suppression you want to retrieve. Or, if you want to check if an email address is on the global suppressions list, enter that email address here.

Output

• output object
  • recipient_email required string: The email address that is globally suppressed. This will be an empty object if the email address you included in your call is not globally suppressed.

asm.suppressions.email.get

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.

sendgrid.asm.suppressions.email.get({
  "email": ""
}, context)

Input

• input object
  • on-behalf-of string
  • email required string: The email address that you want to search suppression groups for.

Output

• output object
  • suppressions required array: The array of suppression groups.
    • items object
      • description required string: The description of the suppression group.
      • id required integer: The id of the suppression group.
      • is_default required boolean: Indicates if the suppression group is set as the default.
      • name required string: The name of the suppression group.
      • suppressed required boolean: Indicates if the given email address is suppressed for this group.

browsers.stats.get

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.

sendgrid.browsers.stats.get({
  "start_date": ""
}, context)

Input

• input object
  • start_date required string: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.
  • end_date string: The end date of the statistics to retrieve. Defaults to today.
  • limit string: The number of results to include on each page.
  • offset string: The number of results to exclude.
  • aggregated_by string (values: day, week, month): How to group the stats. Must be either "day", "week", or "month".
  • browsers string: The browsers to get statistics for. You can include up to 10 different browsers by including this parameter multiple times.
  • on-behalf-of string

Output

• output array
  • items advanced_stats_clicks

GET_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

sendgrid.GET_campaigns({}, context)

Input

• input object
  • limit integer: The number of results you would like to receive at a time.
  • offset integer: The index of the first campaign to return, where 0 is the first campaign.

Output

• output object
  • result array
    • items object
      • categories array
        • items string
      • custom_unsubscribe_url string
      • html_content string
      • id integer
      • ip_pool string
      • list_ids array
        • items integer
      • plain_content string
      • segment_ids array
        • items integer
      • sender_id integer
      • status string
      • subject string
      • suppression_group_id integer
      • title string

POST_campaigns

This endpoint allows you to create a campaign.

Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.

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.

For more information:

• User Guide > Marketing Campaigns

sendgrid.POST_campaigns({}, context)

Input

• input object
  • body campaign_request

Output

• output campaign_response

campaigns.campaign_id.delete

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

sendgrid.campaigns.campaign_id.delete({
  "campaign_id": 0
}, context)

Input

• input object
  • campaign_id required integer: The id of the campaign you would like to retrieve.

Output

Output schema unknown

campaigns.campaign_id.get

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

sendgrid.campaigns.campaign_id.get({
  "campaign_id": 0
}, context)

Input

• input object
  • campaign_id required integer: The id of the campaign you would like to retrieve.

Output

• output object
  • categories array
    • items string
  • custom_unsubscribe_url string
  • html_content string
  • id integer
  • ip_pool string
  • list_ids array
    • items integer
  • plain_content string
  • segment_ids array
    • items integer
  • sender_id integer
  • status string
  • subject string
  • suppression_group_id integer
  • title string

campaigns.campaign_id.patch

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

sendgrid.campaigns.campaign_id.patch({
  "campaign_id": 0
}, context)

Input

• input object
  • body object
    • categories required array: The categories you want to tag on this campaign.
      • items string
    • html_content required string: The HTML content of this campaign.
    • plain_content required string: The plain content of this campaign.
    • subject required string: The subject line for your campaign.
    • title required string: The title of the campaign.
  • campaign_id required integer: The id of the campaign you would like to retrieve.

Output

• output campaign_response

campaigns.campaign_id.schedules.delete

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

sendgrid.campaigns.campaign_id.schedules.delete({
  "campaign_id": 0
}, context)

Input

• input object
  • campaign_id required integer

Output

Output schema unknown

campaigns.campaign_id.schedules.get

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

sendgrid.campaigns.campaign_id.schedules.get({
  "campaign_id": 0
}, context)

Input

• input object
  • campaign_id required integer

Output

• output object
  • send_at required integer

campaigns.campaign_id.schedules.patch

This endpoint allows to you change the scheduled time and date for a campaign to be sent.

For more information:

• User Guide > Marketing Campaigns

sendgrid.campaigns.campaign_id.schedules.patch({
  "campaign_id": 0
}, context)

Input

• input object
  • body object
    • send_at required integer
  • campaign_id required integer

Output

• output object
  • id required integer: The campaign ID
  • send_at required integer: The unix timestamp to send the campaign.
  • status required string: The status of the schedule.

campaigns.campaign_id.schedules.post

This endpoint allows you to schedule a specific date and time for your campaign to be sent.

For more information:

• User Guide > Marketing Campaigns

sendgrid.campaigns.campaign_id.schedules.post({
  "campaign_id": 0
}, context)

Input

• input object
  • body object
    • send_at required integer: The unix timestamp for the date and time you would like your campaign to be sent out.
  • campaign_id required integer

Output

• output object
  • id required integer: The campaign ID.
  • send_at required integer: The date time you scheduled your campaign to be sent.
  • status required string (values: Scheduled): The status of your campaign.

campaigns.campaign_id.schedules.now.post

This endpoint allows you to immediately send a campaign at the time you make the API call.

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.

For more information:

• User Guide > Marketing Campaigns

sendgrid.campaigns.campaign_id.schedules.now.post({
  "campaign_id": 0
}, context)

Input

• input object
  • campaign_id required integer

Output

• output object
  • id required integer
  • status required string

campaigns.campaign_id.schedules.test.post

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

sendgrid.campaigns.campaign_id.schedules.test.post({
  "campaign_id": 0
}, context)

Input

• input object
  • body object
    • to required string: The email address that should receive the test campaign.
  • campaign_id required integer

Output

• output object
  • to required string

GET_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 own custom categories. For more information, please see our User Guide.

sendgrid.GET_categories({}, context)

Input

• input object
  • limit integer: The number of categories to display per page.
  • category string: Allows you to perform a prefix search on this particular category.
  • offset integer: The point in the list that you would like to begin displaying results.
  • on-behalf-of string

Output

• output array
  • items object
    • category required string: A category used to group emails by broad topic.

categories.stats.get

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 together according to broad topics that you define. For more information, please see our User Guide.

sendgrid.categories.stats.get({
  "start_date": "",
  "categories": ""
}, context)

Input

• input object
  • start_date required string: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD
  • end_date string: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.
  • categories required string: The individual categories that you want to retrieve statistics for. You may include up to 10 different categories.
  • limit integer: The number of results to include.
  • offset integer: The number of results to skip.
  • aggregated_by string (values: day, week, month): How to group the statistics. Must be either "day", "week", or "month".
  • on-behalf-of string

Output

• output array
  • items category_stats

categories.stats.sums.get

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 together according to broad topics that you define. For more information, please see our User Guide.

sendgrid.categories.stats.sums.get({
  "start_date": ""
}, context)

Input

• input object
  • sort_by_metric string: The metric that you want to sort by. Must be a single metric.
  • sort_by_direction string (values: desc, asc): The direction you want to sort.
  • start_date required string: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.
  • end_date string: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.
  • limit integer: Limits the number of results returned.
  • offset integer: The point in the list to begin retrieving results.
  • aggregated_by string (values: day, week, month): How to group the statistics. Must be either "day", "week", or "month".
  • on-behalf-of string

Output

• output category_stats

clients.stats.get

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.

sendgrid.clients.stats.get({
  "start_date": ""
}, context)

Input

• input object
  • start_date required string: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.
  • end_date string: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.
  • aggregated_by string (values: day, week, month): How to group the statistics. Must be either "day", "week", or "month".
  • on-behalf-of string

Output

• output array
  • items advanced_stats_opens

clients.client_type.stats.get

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.

sendgrid.clients.client_type.stats.get({
  "start_date": "",
  "client_type": ""
}, context)

Input

• input object
  • start_date required string: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.
  • end_date string: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.
  • aggregated_by string (values: day, week, month): How to group the statistics. Must be either "day", "week", or "month".
  • on-behalf-of string
  • client_type required string (values: phone, tablet, webmail, desktop): Specifies the type of client to retrieve stats for. Must be either "phone", "tablet", "webmail", or "desktop".

Output

• output array
  • items advanced_stats_opens

contactdb.custom_fields.get

This endpoint allows you to retrieve all custom fields.

The contactdb is a database of your contacts for SendGrid Marketing Campaigns.

sendgrid.contactdb.custom_fields.get({}, context)

Input

• input object
  • on-behalf-of string

Output

• output object
  • custom_fields required array
    • items contactdb_custom_field_with_id

contactdb.custom_fields.post

This endpoint allows you to create a custom field.

The contactdb is a database of your contacts for SendGrid Marketing Campaigns.

sendgrid.contactdb.custom_fields.post({}, context)

Input

• input object
  • on-behalf-of string
  • body object
    • name string
    • type string

Output

• output object
  • id integer
  • name string
  • type string

contactdb.custom_fields.custom_field_id.delete

This endpoint allows you to delete a custom field by ID.

The contactdb is a database of your contacts for SendGrid Marketing Campaigns.

sendgrid.contactdb.custom_fields.custom_field_id.delete({
  "custom_field_id": 0
}, context)

Input

• input object
  • on-behalf-of string
  • custom_field_id required integer: The ID of the custom field that you want to retrieve.

Output

• output global_ErrorResponse

contactdb.custom_fields.custom_field_id.get

This endpoint allows you to retrieve a custom field by ID.

The contactdb is a database of your contacts for SendGrid Marketing Campaigns.

sendgrid.contactdb.custom_fields.custom_field_id.get({
  "custom_field_id": 0
}, context)

Input

• input object
  • on-behalf-of string
  • custom_field_id required integer: The ID of the custom field that you want to retrieve.

Output

• output contactdb_custom_field_with_id

contactdb.lists.delete

This endpoint allows you to delete multiple recipient lists.

The Contacts API helps you manage your Marketing Campaigns recipients.

sendgrid.contactdb.lists.delete({}, context)

Input

• input object
  • on-behalf-of string
  • body array
    • items integer

Output

Output schema unknown

contactdb.lists.get

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 recipients.

sendgrid.contactdb.lists.get({}, context)

Input

• input object
  • on-behalf-of string

Output

• output object
  • lists required array
    • items contactdb_list

contactdb.lists.post

This endpoint allows you to create a list for your recipients.

The Contacts API helps you manage your Marketing Campaigns recipients.

sendgrid.contactdb.lists.post({}, context)

Input

• input object
  • on-behalf-of string
  • body object
    • name required string

Output

• output contactdb_list

contactdb.lists.list_id.delete

This endpoint allows you to delete a specific recipient list with the given ID.

The Contacts API helps you manage your Marketing Campaigns recipients.

sendgrid.contactdb.lists.list_id.delete({
  "list_id": ""
}, context)

Input

• input object
  • delete_contacts boolean (values: true, false): Adds the ability to delete all contacts on the list in addition to deleting the list.
  • on-behalf-of string
  • list_id required string

Output

Output schema unknown

contactdb.lists.list_id.get

This endpoint allows you to retrieve a single recipient list.

The Contacts API helps you manage your Marketing Campaigns recipients.

sendgrid.contactdb.lists.list_id.get({
  "list_id": ""
}, context)

Input

• input object
  • list_id_query integer: The ID of the list to retrieve.
  • on-behalf-of string
  • list_id required string

Output

• output contactdb_list

contactdb.lists.list_id.patch

This endpoint allows you to update the name of one of your recipient lists.

The Contacts API helps you manage your Marketing Campaigns recipients.

sendgrid.contactdb.lists.list_id.patch({
  "list_id": 0,
  "list_id_path": ""
}, context)

Input

• input object
  • list_id required integer: The ID of the list you are updating.
  • on-behalf-of string
  • body object
    • name required string: The new name for your list.
  • list_id_path required string

Output

• output object
  • id integer: The ID of the list
  • name string: The new name for the list
  • recipient_count integer: The number of recipients on the list

contactdb.lists.list_id.recipients.get

This endpoint allows you to retrieve all recipients on the list with the given ID.

The Contacts API helps you manage your Marketing Campaigns recipients.

sendgrid.contactdb.lists.list_id.recipients.get({
  "list_id": 0,
  "list_id_path": 0
}, context)

Input

• input object
  • page integer: Page index of first recipient to return (must be a positive integer)
  • page_size integer: Number of recipients to return at a time (must be a positive integer between 1 and 1000)
  • list_id required integer: The ID of the list whose recipients you are requesting.
  • on-behalf-of string
  • list_id_path required integer: The id of the list of recipients you want to retrieve.

Output

• output object
  • recipients array
    • items contactdb_recipient

contactdb.lists.list_id.recipients.post

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 recipients.

sendgrid.contactdb.lists.list_id.recipients.post({
  "list_id": 0
}, context)

Input

• input object
  • on-behalf-of string
  • body array
    • items string
  • list_id required integer: The id of the list of recipients you want to retrieve.

Output

Output schema unknown

contactdb.lists.list_id.recipients.recipient_id.delete

This endpoint allows you to delete a single recipient from a list.

The Contacts API helps you manage your Marketing Campaigns recipients.

sendgrid.contactdb.lists.list_id.recipients.recipient_id.delete({
  "list_id": 0,
  "recipient_id": 0,
  "list_id_path": 0,
  "recipient_id_path": ""
}, context)

Input

• input object
  • list_id required integer: The ID of the list you are taking this recipient away from.
  • recipient_id required integer: The ID of the recipient to take off the list.
  • on-behalf-of string
  • list_id_path required integer: The ID of the list that you want to add the recipient to.
  • recipient_id_path required string: The ID of the recipient you are adding to the list.

Output

Output schema unknown

contactdb.lists.list_id.recipients.recipient_id.post

This endpoint allows you to add a single recipient to a list.

The Contacts API helps you manage your Marketing Campaigns recipients.

sendgrid.contactdb.lists.list_id.recipients.recipient_id.post({
  "list_id": 0,
  "recipient_id": ""
}, context)

Input

• input object
  • on-behalf-of string
  • list_id required integer: The ID of the list that you want to add the recipient to.
  • recipient_id required string: The ID of the recipient you are adding to the list.

Output

Output schema unknown

contactdb.recipients.delete

This endpoint allows you to deletes one or more recipients.

The body of an API call to this endpoint must include an array of recipient IDs of the recipients you want to delete.

The contactdb is a database of your contacts for SendGrid Marketing Campaigns.

sendgrid.contactdb.recipients.delete({}, context)

Input

• input object
  • on-behalf-of string
  • body array
    • items string

Output

• output object

contactdb.recipients.get

This endpoint allows you to retrieve all of your Marketing Campaigns recipients.

Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved.

The Contacts API helps you manage your Marketing Campaigns recipients.

sendgrid.contactdb.recipients.get({}, context)

Input

• input object
  • page integer: Page index of first recipients to return (must be a positive integer)
  • page_size integer: Number of recipients to return at a time (must be a positive integer between 1 and 1000)
  • on-behalf-of string

Output

• output object
  • recipients required array
    • items object

contactdb.recipients.patch

This endpoint allows you to update one or more recipients.

The body of an API call to this endpoint must include an array of one or more recipient objects.

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.

The contactdb is a database of your contacts for SendGrid Marketing Campaigns.

sendgrid.contactdb.recipients.patch({}, context)

Input

• input object
  • on-behalf-of string
  • body array
    • items object
      • email required string
      • first_name string: The first name of the recipient. This is one of the default custom fields.
      • last_name string: The last name of the recipient. This is one of the default custom fields.

Output

• output contactdb_recipient_response

contactdb.recipients.post

This endpoint allows you to add a Marketing Campaigns recipient.

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.

The Contacts API helps you manage your Marketing Campaigns recipients.

sendgrid.contactdb.recipients.post({}, context)

Input

• input object
  • on-behalf-of string
  • body array
    • items object
      • age integer
      • email required string: The email address of the recipient.
      • first_name string: The first name of the recipient.
      • last_name string: The last name of the recipient.

Output

• output contactdb_recipient_response

contactdb.recipients.billable_count.get

This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.

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.

The Contacts API helps you manage your Marketing Campaigns recipients.

sendgrid.contactdb.recipients.billable_count.get({}, context)

Input

• input object
  • on-behalf-of string

Output

• output contactdb_recipient_count

contactdb.recipients.count.get

This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.

The contactdb is a database of your contacts for SendGrid Marketing Campaigns.

sendgrid.contactdb.recipients.count.get({}, context)

Input

• input object
  • on-behalf-of string

Output

• output contactdb_recipient_count

contactdb.recipients.search.get

This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.

field_name:

• is a variable that is substituted for your actual custom field name from your recipient.
• Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200)
• If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through Mon, 02 Feb 2015 23:59:59 GMT.

The contactdb is a database of your contacts for SendGrid Marketing Campaigns.

sendgrid.contactdb.recipients.search.get({}, context)

Input

• input object
  • {field_name} string
  • on-behalf-of string

Output

• output object
  • recipients array
    • items contactdb_recipient

contactdb.recipients.recipient_id.delete

This endpoint allows you to delete a single recipient with the given ID from your contact database.

The Conta