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
Resources
API Key Permissions
This endpoint returns a list of all scopes that this user has access to.
API Keys can be used to authenticate the use of SendGrid’s v3 Web API, or the Mail API Endpoint. API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. For a more detailed explanation of how you can use API Key permissios, please visit our User Guide or Classroom.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
scopes
|
array [string] |
The list of scopes for which this user has access. |
Examples
Example application/json
[
{
"scopes": [
"mail.send",
"alerts.create",
"alerts.read"
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
errors
|
array [object] |
This 401 response indicates that the user making the call doesn't have the authorization to view the list of scopes. |
Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]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 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. |
Request
Path
| Name | Data Type | Description |
|---|---|---|
api_key_id
|
string |
The ID of the API Key for which you are requesting information. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "unable to find 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.
Request
Path
| Name | Data Type | Description |
|---|---|---|
api_key_id
|
string |
The ID of the API Key for which you are requesting information. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
result
|
array [api_key_name_id_scopes] | |||||||||||||||||||||||
Properties
Extends
API Key Name and ID
Properties
ExamplesExamples |
||||||||||||||||||||||||
Examples
Example application/json
[
{
"result": [
{
"name": "API Key Name",
"api_key_id": "some-apikey-id"
},
{
"name": "API Key Name 2",
"api_key_id": "another-apikey-id"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Examples
Example application/json
[
{
"errors": [
{
"message": "unable to find API Key"
}
]
}
]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. |
Request
Path
| Name | Data Type | Description |
|---|---|---|
api_key_id
|
string |
The ID of the API Key for which you are requesting information. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
name
|
string |
The new name of the API Key. |
Examples
{
"name": "A New Hope"
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
API Key Name and ID
|
object |
Properties
name
|
string |
The name of your API Key. |
api_key_id
|
string |
The ID of your API Key. |
Examples
{
"api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA",
"name": "A New Hope"
}Examples
Example application/json
[
{
"name": "A New Hope",
"api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA"
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]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.
Request
Path
| Name | Data Type | Description |
|---|---|---|
api_key_id
|
string |
The ID of the API Key for which you are requesting information. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
scopes
|
array [string] | |
name
|
string |
Examples
{
"name": "A New Hope",
"scopes": [
"user.profile.read",
"user.profile.update"
]
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
API Key Name, ID, and Scopes
|
object |
Properties
name
|
string |
The name of your API Key. |
api_key_id
|
string |
The ID of your API Key. |
scopes
|
array [string] |
The permissions this API Key has access to. |
Extends
Properties
| Name | Data Type | Description |
|---|---|---|
name
|
string |
The name of your API Key. |
api_key_id
|
string |
The ID of your API Key. |
Examples
{
"api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA",
"name": "A New Hope"
}Examples
{
"api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA",
"name": "A New Hope",
"scopes": [
"user.profile.read",
"user.profile.update"
]
}Examples
Example application/json
[
{
"name": "A New Hope",
"scopes": [
"user.profile.read",
"user.profile.update"
],
"api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA"
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "expected JSON request body with 'name' property"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "unable to find API Key to update"
}
]
}
]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.
Request
Query
| Name | Data Type | Description |
|---|---|---|
limit
|
integer |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
result
|
array [api_key_name_id] | |||||||||||
Properties
Examples |
||||||||||||
Examples
Example application/json
[
{
"result": [
{
"name": "API Key Name",
"api_key_id": "some-apikey-id"
},
{
"name": "API Key Name 2",
"api_key_id": "another-apikey-id"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]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.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
scopes
|
array [string] |
The individual permissions that you are giving to this API Key. |
sample
|
string | |
name
|
string |
The name you will use to describe this API Key. |
Examples
{
"name": "My API Key",
"sample": "data",
"scopes": [
"mail.send",
"alerts.create",
"alerts.read"
]
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
scopes
|
array [string] | |
name
|
string | |
api_key_id
|
string | |
api_key
|
string |
Examples
Example application/json
[
{
"name": "My API Key",
"scopes": [
"mail.send",
"alerts.create",
"alerts.read"
],
"api_key": "SG.xxxxxxxx.yyyyyyyy",
"api_key_id": "xxxxxxxx"
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "name",
"message": "missing required argument"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "Cannot create more than 100 API Keys"
}
]
}
]Alerts
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.
Request
Path
| Name | Data Type | Description |
|---|---|---|
alert_id
|
integer |
The ID of the alert you would like to retrieve. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
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.
Request
Path
| Name | Data Type | Description |
|---|---|---|
alert_id
|
integer |
The ID of the alert you would like to retrieve. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
|
Authorization
|
string |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
updated_at
|
integer |
A Unix timestamp indicating when the alert was last modified. |
type
|
string Allowed values: - usage_alert- stats_notification |
The type of 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. |
id
|
integer |
The ID of the alert. |
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". |
email_to
|
string |
The email address that the alert will be sent to. |
created_at
|
integer |
A Unix timestamp indicating when the alert was created. |
Examples
Example application/json
[
{
"id": 48,
"type": "stats_notification",
"email_to": "example@example.com",
"frequency": "daily",
"created_at": 1451520930,
"updated_at": 1451520930
}
]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.
Request
Path
| Name | Data Type | Description |
|---|---|---|
alert_id
|
integer |
The ID of the alert you would like to retrieve. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
percentage
|
integer |
The new percentage threshold at which the usage_limit alert will be sent. Example: 90 |
frequency
|
string |
The new frequency at which to send the stats_notification alert. Example: monthly |
email_to
|
string |
The new email address you want your alert to be sent to. Example: test@example.com |
Examples
{
"email_to": "example@example.com"
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
updated_at
|
integer |
A Unix timestamp indicating when the alert was last modified. |
type
|
string Allowed values: - usage_alert- stats_notification |
The type of 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. |
id
|
integer |
The ID of the alert. |
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". |
email_to
|
string |
The email address that the alert will be sent to. |
created_at
|
integer |
A Unix timestamp indicating when the alert was created. |
Examples
Example application/json
[
{
"id": 48,
"type": "stats_notification",
"email_to": "example@example.com",
"frequency": "daily",
"created_at": 1451520930,
"updated_at": 1451522691
}
]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.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
|
Authorization
|
string |
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
array [object] |
The list of alerts. |
Examples
Example application/json
[
{
"id": 46,
"type": "usage_limit",
"email_to": "example1@example.com",
"created_at": 1451498784,
"percentage": 90,
"updated_at": 1451498784
},
{
"id": 47,
"type": "stats_notification",
"email_to": "example2@example.com",
"frequency": "monthly",
"created_at": 1451498812,
"updated_at": 1451498812
},
{
"id": 48,
"type": "stats_notification",
"email_to": "example3@example.com",
"frequency": "daily",
"created_at": 1451520930,
"updated_at": 1451520930
}
]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_limitallows you to set the threshold at which an alert will be sent.stats_notificationallows 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.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string | |
Authorization
|
string |
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
type
|
string Allowed values: - stats_notification- usage_limit |
The type of alert you want to create. Can be either usage_limit or stats_notification. Example: usage_limit |
percentage
|
integer |
Required for usage_alert. When this usage threshold is reached, the alert will be sent. Example: 90 |
frequency
|
string |
Required for stats_notification. How frequently the alert will be sent. Example: daily |
email_to
|
string |
The email address the alert will be sent to. Example: test@example.com |
Examples
{
"email_to": "example@example.com",
"frequency": "daily",
"type": "stats_notification"
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
updated_at
|
integer |
A Unix timestamp indicating when the alert was last modified. |
type
|
string |
The type of 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. |
id
|
integer |
The ID of the alert. |
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". |
email_to
|
string |
The email address that the alert will be sent to. |
created_at
|
integer |
A Unix timestamp indicating when the alert was created. |
Examples
Example application/json
[
{
"id": 48,
"type": "stats_notification",
"email_to": "test@example.com",
"frequency": "daily",
"created_at": 1451520930,
"updated_at": 1451520930
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
message
|
string | |
field
|
string |
Blocks API
This endpoint allows you to delete a specific email address from your blocks list.
Blocks happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.
For more information, please see our User Guide.
Request
Path
| Name | Data Type | Description |
|---|---|---|
email
|
string |
The email address of the specific block. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
|
Authorization
|
string Default value: Bearer <
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
This endpoint allows you to retrieve a specific email address from your blocks list.
Blocks happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.
For more information, please see our User Guide.
Request
Path
| Name | Data Type | Description |
|---|---|---|
email
|
string |
The email address of the specific block. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
array [object] |
Examples
Example application/json
[
{
"email": "example@example.com",
"reason": "error dialing remote address: dial tcp 10.57.152.165:25: no route to host",
"status": "4.0.0",
"created": 1443651154
}
]This endpoint allows you to delete all email addresses on your blocks list.
There are two options for deleting blocked emails:
- You can delete all blocked emails by setting
delete_allto true in the request body. - You can delete some blocked emails by specifying the email addresses in an array in the request body.
Blocks happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.
For more information, please see our User Guide.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
emails
|
array [string] |
The specific blocked email addresses that you want to delete. |
delete_all
|
boolean |
Indicates if you want to delete all blocked email addresses. |
Examples
{
"delete_all": false,
"emails": [
"example1@example.com",
"example2@example.com"
]
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
This endpoint allows you to retrieve a list of all email addresses that are currently on your blocks list.
There are several causes for blocked emails: for example, your mail server IP address is on an ISP blacklist, or blocked by an ISP, or if the receiving server flags the message content.
For more information, please see our User Guide.
Request
Query
| Name | Data Type | Description |
|---|---|---|
offset
|
integer |
The point in the list to begin displaying results. |
limit
|
integer |
Limit the number of results to be displayed per page. |
end_time
|
integer |
Refers end of the time range in unix timestamp when a blocked email was created (inclusive). |
start_time
|
integer |
Refers start of the time range in unix timestamp when a blocked email was created (inclusive). |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
array [object] |
Examples
Example application/json
[
{
"email": "example@example.com",
"reason": "error dialing remote address: dial tcp 10.57.152.165:25: no route to host",
"status": "4.0.0",
"created": 1443651154
}
]Bounces API
This endpoint allows you to remove an email address from your bounce list.
A bounced email is when the message is undeliverable and then returned to the server that sent it. This endpoint allows you to delete a single email addresses from your bounce list.
For more information see:
- User Guide > Bounces for more information
- Glossary > Bounces
- Classroom > List Scrubbing Guide
Request
Path
| Name | Data Type | Description |
|---|---|---|
email
|
string |
Query
| Name | Data Type | Description |
|---|---|---|
email_address
|
The email address you would like to remove from the bounce list. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]This endpoint allows you to retrieve a specific bounce for a given email address.
A bounced email is when the message is undeliverable and then returned to the server that sent it.
For more information see:
- User Guide > Bounces for more information
- Glossary > Bounces
- Classroom > List Scrubbing Guide
Request
Path
| Name | Data Type | Description |
|---|---|---|
email
|
string |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
array [object] |
Examples
Example application/json
[
{
"email": "bounce1@test.com",
"reason": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https:\/\/support.google.com\/mail\/answer\/6596 o186si2389584ioe.63 - gsmtp ",
"status": "5.1.1",
"created": 1443651125
}
]This endpoint allows you to delete all of your bounces. You can also use this endpoint to remove a specific email address from your bounce list.
A bounced email is when the message is undeliverable and then returned to the server that sent it.
For more information see:
- User Guide > Bounces for more information
- Glossary > Bounces
- Classroom > List Scrubbing Guide
Note: the delete_all and emails parameters should be used independently of each other as they have different purposes.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
emails
|
array [string] |
Delete multiple emails from your bounce list at the same time. This should not be used with the delete_all parameter. |
delete_all
|
boolean |
This parameter allows you to delete every email in your bounce list. This should not be used with the emails parameter. |
Examples
{
"delete_all": true,
"emails": [
"example@example.com",
"example2@example.com"
]
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]This endpoint allows you to retrieve all of your bounces.
A bounced email is when the message is undeliverable and then returned to the server that sent it.
For more information see:
- User Guide > Bounces for more information
- Glossary > Bounces
Request
Query
| Name | Data Type | Description |
|---|---|---|
end_time
|
integer |
Refers end of the time range in unix timestamp when a bounce was created (inclusive). |
start_time
|
integer |
Refers start of the time range in unix timestamp when a bounce was created (inclusive). |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
|
Accept
|
string Default value: application/json
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
array [object] |
Examples
Example application/json
[
{
"email": "example@example.com",
"reason": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https:\/\/support.google.com\/mail\/answer\/6596 o186si2389584ioe.63 - gsmtp ",
"status": "5.1.1",
"created": 1250337600
},
{
"email": "example@example.com",
"reason": "550 5.1.1 <testemail2@testing.com>: Recipient address rejected: User unknown in virtual alias table ",
"status": "5.1.1",
"created": 1250337600
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Campaigns API
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:
Request
Path
| Name | Data Type | Description |
|---|---|---|
campaign_id
|
integer |
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
Send a Campaign response
|
object |
Properties
status
|
string | |
id
|
long |
Examples
Example application/json
[
{
"id": 1234,
"status": "Scheduled"
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "subject",
"message": "subject can't be blank"
},
{
"field": "sender_id",
"message": "sender_id can't be blank"
},
{
"field": "plain_content",
"message": "plain_content can't be blank, please provide plain text or html content"
},
{
"field": "list_id",
"message": "You must select at least 1 segment or 1 list to send to."
},
{
"field": "unsubscribe_tag",
"message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign."
},
{
"field": "suppression_group_id",
"message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign."
},
{
"message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https:\/\/app.sendgrid.com\/settings\/billing"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "You may only send a campaign when it is in draft mode."
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "not found"
}
]
}
]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:
Request
Path
| Name | Data Type | Description |
|---|---|---|
campaign_id
|
integer |
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
to
|
The email address that should receive the test campaign. |
Examples
{
"to": "your.email@example.com"
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
Send a Test Campaign request
|
object |
Properties
to
|
string |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "send_at",
"message": "Please choose a future time for sending your campaign."
},
{
"message": "The JSON you have submitted cannot be parsed."
},
{
"message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https:\/\/app.sendgrid.com\/settings\/billing"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "not found"
}
]
}
]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:
Request
Path
| Name | Data Type | Description |
|---|---|---|
campaign_id
|
integer |
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "This campaign is already In Progress."
},
{
"message": "This campaign is already Sent."
},
{
"message": "This campaign is already Paused."
},
{
"message": "This campaign is already Canceled."
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "not found"
}
]
}
]This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent.
For more information:
Request
Path
| Name | Data Type | Description |
|---|---|---|
campaign_id
|
integer |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
View Scheduled Time of a Campaign response
|
object |
Properties
send_at
|
long |
Examples
Example application/json
[
{
"send_at": 1490778528
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "not found"
}
]
}
]This endpoint allows to you change the scheduled time and date for a campaign to be sent.
For more information:
Request
Path
| Name | Data Type | Description |
|---|---|---|
campaign_id
|
integer |
Body
| Name | Data Type | Description |
|---|---|---|
Update a Scheduled Campaign request
|
object |
Properties
send_at
|
long |
Examples
{
"send_at": 1489451436
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
Update a Scheduled Campaign response
|
object |
Properties
status
|
string |
The status of the schedule. |
send_at
|
integer |
The unix timestamp to send the campaign. |
id
|
integer |
The campaign ID |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "send_at",
"message": "Please choose a future time for sending your campaign."
},
{
"message": "The JSON you have submitted cannot be parsed."
},
{
"message": "You do not have enough credits to send this campaign. Upgrade your plan to send https:\/\/app.sendgrid.com\/settings\/billing"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "send_at",
"message": "You cannot update the send_at value of non-scheduled campaign."
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "not found"
}
]
}
]This endpoint allows you to schedule a specific date and time for your campaign to be sent.
For more information:
Request
Path
| Name | Data Type | Description |
|---|---|---|
campaign_id
|
integer |
Body
| Name | Data Type | Description |
|---|---|---|
Schedule a Campaign request
|
object |
Properties
send_at
|
integer |
The unix timestamp for the date and time you would like your campaign to be sent out. |
Examples
{
"send_at": 1489771528
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
Schedule a Campaign response
|
object |
Properties
status
|
string Allowed values: - Scheduled |
The status of your campaign. |
send_at
|
integer |
The date time you scheduled your campaign to be sent. |
id
|
integer |
The campaign ID. |
Examples
Example application/json
[
{
"id": 1234,
"status": "Scheduled",
"send_at": 1489771528
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "subject",
"message": "subject can't be blank"
},
{
"field": "sender_id",
"message": "sender_id can't be blank"
},
{
"field": "plain_content",
"message": "plain_content can't be blank, please provide plain text or html content"
},
{
"field": "list_id",
"message": "You must select at least 1 segment or 1 list to send to."
},
{
"field": "unsubscribe_tag",
"message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign."
},
{
"field": "suppression_group_id",
"message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign."
},
{
"message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https:\/\/app.sendgrid.com\/settings\/billing"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH."
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "not found"
}
]
}
]This endpoint allows you to delete a specific campaign.
Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.
For more information:
Request
Path
| Name | Data Type | Description |
|---|---|---|
campaign_id
|
integer |
The id of the campaign you would like to retrieve. |
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
This endpoint allows you to retrieve a specific campaign.
Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.
For more information:
Request
Path
| Name | Data Type | Description |
|---|---|---|
campaign_id
|
integer |
The id of the campaign you would like to retrieve. |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
title
|
string | |
suppression_group_id
|
integer | |
subject
|
string | |
status
|
string | |
sender_id
|
integer | |
segment_ids
|
array [integer] | |
plain_content
|
string | |
list_ids
|
array [integer] | |
ip_pool
|
string | |
id
|
integer | |
html_content
|
string | |
custom_unsubscribe_url
|
string | |
categories
|
array [string] |
Examples
Example application/json
[
{
"id": 986724,
"title": "March Newsletter",
"status": "Draft",
"ip_pool": "marketing",
"subject": "New Products for Spring!",
"list_ids": [
110
],
"sender_id": 124451,
"categories": [
"spring line"
],
"segment_ids": [
110
],
"html_content": "<html><head><title><\/title><\/head><body><p>Check out our spring line!<\/p><\/body><\/html>",
"plain_content": "Check out our spring line!",
"suppression_group_id": 42,
"custom_unsubscribe_url": ""
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Examples
Example application/json
[
{
"errors": [
{
"message": "not found"
}
]
}
]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:
Request
Path
| Name | Data Type | Description |
|---|---|---|
campaign_id
|
integer |
The id of the campaign you would like to retrieve. |
Body
| Name | Data Type | Description |
|---|---|---|
Update a Campaign request
|
object |
Properties
title
|
string |
The title of the campaign. |
subject
|
string |
The subject line for your campaign. |
plain_content
|
string |
The plain content of this campaign. |
html_content
|
string |
The HTML content of this campaign. |
categories
|
array [string] |
The categories you want to tag on this campaign. |
Examples
{
"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"
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
Campaigns Response
|
object |
Properties
status
|
string |
The status of your campaign. |
id
|
integer | |
title
|
string |
The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI. |
suppression_group_id
|
integer |
The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type. |
subject
|
string |
The subject of your campaign that your recipients will see. |
sender_id
|
integer |
The ID of the "sender" identity that you have created. Your recipients will see this as the "from" on your marketing emails. |
segment_ids
|
array [integer] |
The segment IDs that you are sending this list to. You can have both segment IDs and list IDs. |
plain_content
|
string |
The plain text content of your emails. |
list_ids
|
array [integer] |
The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs |
ip_pool
|
string |
The pool of IPs that you would like to send this email from. |
html_content
|
string |
The HTML of your marketing email. |
custom_unsubscribe_url
|
string |
This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups. |
categories
|
array [string] |
The categories you would like associated to this campaign. |
Extends
Properties
| Name | Data Type | Description |
|---|---|---|
title
|
string |
The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI. |
suppression_group_id
|
integer |
The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type. |
subject
|
string |
The subject of your campaign that your recipients will see. |
sender_id
|
integer |
The ID of the "sender" identity that you have created. Your recipients will see this as the "from" on your marketing emails. |
segment_ids
|
array [integer] |
The segment IDs that you are sending this list to. You can have both segment IDs and list IDs. |
plain_content
|
string |
The plain text content of your emails. |
list_ids
|
array [integer] |
The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs |
ip_pool
|
string |
The pool of IPs that you would like to send this email from. |
html_content
|
string |
The HTML of your marketing email. |
custom_unsubscribe_url
|
string |
This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups. |
categories
|
array [string] |
The categories you would like associated to this campaign. |
Examples
{
"categories": [
"summer line"
],
"custom_unsubscribe_url": "",
"html_content": "<html><head><title><\/title><\/head><body><p>Check out our summer line!<\/p><\/body><\/html>",
"id": 986724,
"ip_pool": "marketing",
"list_ids": [
110,
124
],
"plain_content": "Check out our summer line!",
"segment_ids": [
110
],
"sender_id": 124451,
"status": "Draft",
"subject": "New Products for Summer!",
"suppression_group_id": 42,
"title": "May Newsletter"
}Examples
Example application/json
[
{
"id": 986724,
"title": "May Newsletter",
"status": "Draft",
"ip_pool": "marketing",
"subject": "New Products for Summer!",
"list_ids": [
110,
124
],
"sender_id": 124451,
"categories": [
"summer line"
],
"segment_ids": [
110
],
"html_content": "<html><head><title><\/title><\/head><body><p>Check out our summer line!<\/p><\/body><\/html>",
"plain_content": "Check out our summer line!",
"suppression_group_id": 42,
"custom_unsubscribe_url": ""
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Examples
Example application/json
[
{
"errors": [
{
"field": "title",
"message": "title can't be blank"
},
{
"field": "title",
"message": "title is too long (maximum is 100 characters)"
},
{
"field": "categories",
"message": "categories exceeds 10 category limit"
},
{
"field": "html_content",
"message": "html_content exceeds the 1MB limit"
},
{
"field": "plain_content",
"message": "plain_content exceeds the 1MB limit"
},
{
"field": "sender_id",
"message": "sender_id does not exist"
},
{
"field": "sender_id",
"message": "sender_id is not a verified sender identity"
},
{
"field": "list_ids",
"message": "list_ids do not all exist"
},
{
"field": "segment_ids",
"message": "segment_ids do not all exist"
},
{
"field": "ip_pool",
"message": "The ip pool you provided is invalid"
},
{
"field": "suppression_group_id",
"message": "suppression_group_id does not exist"
},
{
"field": "unsubscribes",
"message": "Either suppression_group_id or custom_unsubscribe_url may be set\/used, but not both. Please remove one before setting the other."
},
{
"message": "The JSON you have submitted cannot be parsed."
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Examples
Example application/json
[
{
"errors": [
{
"message": "You may only update a campaign when it is in draft mode."
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "not found"
}
]
}
]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:
Request
Query
| Name | Data Type | Description |
|---|---|---|
offset
|
integer Default value: 0
|
The index of the first campaign to return, where 0 is the first campaign. |
limit
|
integer Default value: 10
|
The number of results you would like to receive at a time. |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
result
|
array [object] |
Examples
Example application/json
[
{
"result": [
{
"id": 986724,
"title": "March Newsletter",
"status": "Draft",
"ip_pool": "marketing",
"subject": "New Products for Spring!",
"list_ids": [
110
],
"sender_id": 124451,
"categories": [
"spring line"
],
"segment_ids": [
110
],
"html_content": "<html><head><title><\/title><\/head><body><p>Check out our spring line!<\/p><\/body><\/html>",
"plain_content": "Check out our spring line!",
"suppression_group_id": 42,
"custom_unsubscribe_url": ""
}
]
}
]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:
Request
Body
| Name | Data Type | Description |
|---|---|---|
Campaigns Request
|
object |
Properties
title
|
string |
The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI. |
suppression_group_id
|
integer |
The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type. |
subject
|
string |
The subject of your campaign that your recipients will see. |
sender_id
|
integer |
The ID of the "sender" identity that you have created. Your recipients will see this as the "from" on your marketing emails. |
segment_ids
|
array [integer] |
The segment IDs that you are sending this list to. You can have both segment IDs and list IDs. |
plain_content
|
string |
The plain text content of your emails. |
list_ids
|
array [integer] |
The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs |
ip_pool
|
string |
The pool of IPs that you would like to send this email from. |
html_content
|
string |
The HTML of your marketing email. |
custom_unsubscribe_url
|
string |
This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups. |
categories
|
array [string] |
The categories you would like associated to this campaign. |
Examples
{
"categories": [
"summer line"
],
"custom_unsubscribe_url": "",
"html_content": "<html><head><title><\/title><\/head><body><p>Check out our summer line!<\/p><\/body><\/html>",
"id": 986724,
"ip_pool": "marketing",
"list_ids": [
110,
124
],
"plain_content": "Check out our summer line!",
"segment_ids": [
110
],
"sender_id": 124451,
"status": "Draft",
"subject": "New Products for Summer!",
"suppression_group_id": 42,
"title": "May Newsletter"
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
Campaigns Response
|
object |
Properties
status
|
string |
The status of your campaign. |
id
|
integer | |
title
|
string |
The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI. |
suppression_group_id
|
integer |
The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type. |
subject
|
string |
The subject of your campaign that your recipients will see. |
sender_id
|
integer |
The ID of the "sender" identity that you have created. Your recipients will see this as the "from" on your marketing emails. |
segment_ids
|
array [integer] |
The segment IDs that you are sending this list to. You can have both segment IDs and list IDs. |
plain_content
|
string |
The plain text content of your emails. |
list_ids
|
array [integer] |
The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs |
ip_pool
|
string |
The pool of IPs that you would like to send this email from. |
html_content
|
string |
The HTML of your marketing email. |
custom_unsubscribe_url
|
string |
This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups. |
categories
|
array [string] |
The categories you would like associated to this campaign. |
Extends
Properties
| Name | Data Type | Description |
|---|---|---|
title
|
string |
The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI. |
suppression_group_id
|
integer |
The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type. |
subject
|
string |
The subject of your campaign that your recipients will see. |
sender_id
|
integer |
The ID of the "sender" identity that you have created. Your recipients will see this as the "from" on your marketing emails. |
segment_ids
|
array [integer] |
The segment IDs that you are sending this list to. You can have both segment IDs and list IDs. |
plain_content
|
string |
The plain text content of your emails. |
list_ids
|
array [integer] |
The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs |
ip_pool
|
string |
The pool of IPs that you would like to send this email from. |
html_content
|
string |
The HTML of your marketing email. |
custom_unsubscribe_url
|
string |
This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups. |
categories
|
array [string] |
The categories you would like associated to this campaign. |
Examples
{
"categories": [
"summer line"
],
"custom_unsubscribe_url": "",
"html_content": "<html><head><title><\/title><\/head><body><p>Check out our summer line!<\/p><\/body><\/html>",
"id": 986724,
"ip_pool": "marketing",
"list_ids": [
110,
124
],
"plain_content": "Check out our summer line!",
"segment_ids": [
110
],
"sender_id": 124451,
"status": "Draft",
"subject": "New Products for Summer!",
"suppression_group_id": 42,
"title": "May Newsletter"
}Examples
Example application/json
[
{
"id": 986724,
"title": "March Newsletter",
"status": "Draft",
"ip_pool": "marketing",
"subject": "New Products for Spring!",
"list_ids": [
110,
124
],
"sender_id": 124451,
"categories": [
"spring line"
],
"segment_ids": [
110
],
"html_content": "<html><head><title><\/title><\/head><body><p>Check out our spring line!<\/p><\/body><\/html>",
"plain_content": "Check out our spring line!",
"suppression_group_id": 42,
"custom_unsubscribe_url": ""
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "title",
"message": "title can't be blank"
},
{
"field": "title",
"message": "title is too long (maximum is 100 characters)"
},
{
"field": "categories",
"message": "categories exceeds 10 category limit"
},
{
"field": "html_content",
"message": "html_content exceeds the 1MB limit"
},
{
"field": "plain_content",
"message": "plain_content exceeds the 1MB limit"
},
{
"field": "sender_id",
"message": "sender_id does not exist"
},
{
"field": "sender_id",
"message": "sender_id is not a verified sender identity"
},
{
"field": "list_ids",
"message": "list_ids do not all exist"
},
{
"field": "segment_ids",
"message": "segment_ids do not all exist"
},
{
"field": "ip_pool",
"message": "The ip pool you provided is invalid"
},
{
"field": "suppression_group_id",
"message": "suppression_group_id does not exist"
},
{
"field": "unsubscribes",
"message": "Either suppression_group_id or custom_unsubscribe_url may be set\/used, but not both. Please remove one before setting the other."
},
{
"message": "The JSON you have submitted cannot be parsed."
},
{
"message": "You've reached your limit of 250 campaigns. Please delete one or more and try again."
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Cancel Scheduled Sends
This endpoint allows you to validate a batch ID.
If you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint.
More Information:
Request
Path
| Name | Data Type | Description |
|---|---|---|
batch_id
|
string |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
Mail: Batch ID
|
object |
Properties
batch_id
|
string Pattern: ^[a-zA-Z0-9\-\_]
|
Examples
{
"batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi"
}Examples
Example application/json
[
{
"batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi"
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "invalid batch id"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]This endpoint allows you to generate a new batch ID. This batch ID can be associated with scheduled sends via the mail/send endpoint.
If you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint.
More Information:
Request
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
Mail: Batch ID
|
object |
Properties
batch_id
|
string Pattern: ^[a-zA-Z0-9\-\_]
|
Examples
{
"batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi"
}Examples
Example application/json
[
{
"batch_id": "YOUR_BATCH_ID"
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]This endpoint allows you to delete the cancellation/pause of a scheduled send.
The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header. Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.
Request
Path
| Name | Data Type | Description |
|---|---|---|
batch_id
|
string |
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "batch id not found"
}
]
}
]This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific batch_id.
The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header. Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.
Request
Path
| Name | Data Type | Description |
|---|---|---|
batch_id
|
string |
Responses
Body
| Name | Data Type | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Retrieve scheduled send response
|
array [user_scheduled_send_status] | |||||||||||||||||
Properties
Extends
Mail: Batch ID
Properties
Examples |
||||||||||||||||||
Examples
Example application/json
[
{
"status": "cancel",
"batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi"
},
{
"status": "pause",
"batch_id": "IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg"
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]This endpoint allows you to update the status of a scheduled send for the given batch_id.
The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header. Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.
Request
Path
| Name | Data Type | Description |
|---|---|---|
batch_id
|
string |
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
status
|
string Allowed values: - cancel- pause |
The status you would like the scheduled send to have. |
Examples
{
"status": "pause"
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "status",
"message": "status must be either cancel or pause"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "batch id not found"
}
]
}
]This endpoint allows you to retrieve all cancel/paused scheduled send information.
The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header. Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.
Responses
Body
| Name | Data Type | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
body
|
array [user_scheduled_send_status] | |||||||||||||||||
Properties
Extends
Mail: Batch ID
Properties
Examples |
||||||||||||||||||
Examples
Example application/json
[
{
"status": "cancel",
"batch_id": "YzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYg"
},
{
"status": "cancel",
"batch_id": "UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYgYzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2"
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]This endpoint allows you to cancel or pause an email that has been scheduled to be sent.
If the maximum number of cancellations/pauses are added, HTTP 400 will be returned.
The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header. Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.
Request
Body
| Name | Data Type | Description |
|---|---|---|
Cancel or pause a scheduled send request
|
object |
Properties
status
|
string Default value: pauseAllowed values: - pause- cancel |
The status of the send you would like to implement. This can be pause or cancel. To delete a pause or cancel status see DELETE /v3/user/scheduled_sends/{batch_id} |
batch_id
|
string Pattern: ^[a-zA-Z0-9]
|
The batch ID is the identifier that your scheduled mail sends share. |
Examples
{
"batch_id": "YOUR_BATCH_ID",
"status": "pause"
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
User: Scheduled Send status
|
object |
The status of the scheduled send. |
Properties
status
|
string Allowed values: - cancel- pause |
The status of the scheduled send. |
batch_id
|
string Pattern: ^[a-zA-Z0-9\-\_]
|
Extends
Properties
| Name | Data Type | Description |
|---|---|---|
batch_id
|
string Pattern: ^[a-zA-Z0-9\-\_]
|
Examples
{
"batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi"
}Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Examples
Example application/json
[
{
"errors": [
{
"message": "max limit reached"
},
{
"field": "batch_id",
"message": "invalid batch id"
},
{
"field": "batch_id",
"message": "a status for this batch id exists, try PATCH to update the status"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Categories
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.
Request
Query
| Name | Data Type | Description |
|---|---|---|
aggregated_by
|
string Allowed values: - day- week- month |
How to group the statistics. Must be either "day", "week", or "month". |
offset
|
integer Default value: 0
|
The point in the list to begin retrieving results. |
limit
|
integer Default value: 5
|
Limits the number of results returned. |
end_date
|
string |
The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. |
start_date
|
string |
The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. |
sort_by_direction
|
string Default value: descAllowed values: - desc- asc |
The direction you want to sort. |
sort_by_metric
|
string Default value: delivered
|
The metric that you want to sort by. Must be a single metric. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
Stats: Category Stats
|
object |
Properties
stats
|
array [object] | |
date
|
string |
The date the statistics were gathered. |
Examples
{
"date": "2015-01-01",
"stats": [
{
"metrics": {
"blocks": 0,
"bounce_drops": 0,
"bounces": 0,
"clicks": 0,
"deferred": 0,
"delivered": 0,
"invalid_emails": 0,
"opens": 0,
"processed": 0,
"requests": 0,
"spam_report_drops": 0,
"spam_reports": 0,
"unique_clicks": 0,
"unique_opens": 0,
"unsubscribe_drops": 0,
"unsubscribes": 0
},
"name": "cat1",
"type": "category"
},
{
"metrics": {
"blocks": 0,
"bounce_drops": 0,
"bounces": 0,
"clicks": 0,
"deferred": 0,
"delivered": 0,
"invalid_emails": 0,
"opens": 0,
"processed": 0,
"requests": 0,
"spam_report_drops": 0,
"spam_reports": 0,
"unique_clicks": 0,
"unique_opens": 0,
"unsubscribe_drops": 0,
"unsubscribes": 0
},
"name": "cat2",
"type": "category"
}
]
}Examples
Example application/json
[
{
"date": "2015-01-01",
"stats": [
{
"name": "cat1",
"type": "category",
"metrics": {
"opens": 20,
"blocks": 0,
"clicks": 20,
"bounces": 0,
"deferred": 0,
"requests": 20,
"delivered": 20,
"processed": 0,
"bounce_drops": 0,
"spam_reports": 0,
"unique_opens": 20,
"unsubscribes": 20,
"unique_clicks": 20,
"invalid_emails": 0,
"spam_report_drops": 0,
"unsubscribe_drops": 0
}
},
{
"name": "cat2",
"type": "category",
"metrics": {
"opens": 19,
"blocks": 1,
"clicks": 19,
"bounces": 0,
"deferred": 0,
"requests": 20,
"delivered": 19,
"processed": 0,
"bounce_drops": 0,
"spam_reports": 0,
"unique_opens": 19,
"unsubscribes": 19,
"unique_clicks": 19,
"invalid_emails": 0,
"spam_report_drops": 0,
"unsubscribe_drops": 0
}
},
{
"name": "cat3",
"type": "category",
"metrics": {
"opens": 5,
"blocks": 0,
"clicks": 5,
"bounces": 0,
"deferred": 0,
"requests": 5,
"delivered": 5,
"processed": 0,
"bounce_drops": 0,
"spam_reports": 0,
"unique_opens": 5,
"unsubscribes": 5,
"unique_clicks": 5,
"invalid_emails": 0,
"spam_report_drops": 0,
"unsubscribe_drops": 0
}
},
{
"name": "cat4",
"type": "category",
"metrics": {
"opens": 6,
"blocks": 0,
"clicks": 6,
"bounces": 0,
"deferred": 0,
"requests": 5,
"delivered": 5,
"processed": 0,
"bounce_drops": 0,
"spam_reports": 0,
"unique_opens": 5,
"unsubscribes": 6,
"unique_clicks": 5,
"invalid_emails": 0,
"spam_report_drops": 0,
"unsubscribe_drops": 0
}
},
{
"name": "cat5",
"type": "category",
"metrics": {
"opens": 0,
"blocks": 10,
"clicks": 0,
"bounces": 0,
"deferred": 0,
"requests": 10,
"delivered": 0,
"processed": 0,
"bounce_drops": 0,
"spam_reports": 0,
"unique_opens": 0,
"unsubscribes": 0,
"unique_clicks": 0,
"invalid_emails": 0,
"spam_report_drops": 0,
"unsubscribe_drops": 0
}
}
]
}
]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.
Request
Query
| Name | Data Type | Description |
|---|---|---|
aggregated_by
|
string Allowed values: - day- week- month |
How to group the statistics. Must be either "day", "week", or "month". |
offset
|
integer |
The number of results to skip. |
limit
|
integer Default value: 500Maximum: 500 |
The number of results to include. |
categories
|
string |
The individual categories that you want to retrieve statistics for. You may include up to 10 different categories. |
end_date
|
string |
The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. |
start_date
|
string |
The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
body
|
array [category_stats] | |||||||||||
Properties
Examples |
||||||||||||
Examples
Example application/json
[
{
"date": "2015-10-01",
"stats": [
{
"name": "docs",
"type": "category",
"metrics": {
"opens": 0,
"blocks": 0,
"clicks": 0,
"bounces": 0,
"deferred": 0,
"requests": 0,
"delivered": 0,
"processed": 0,
"bounce_drops": 0,
"spam_reports": 0,
"unique_opens": 0,
"unsubscribes": 0,
"unique_clicks": 0,
"invalid_emails": 0,
"spam_report_drops": 0,
"unsubscribe_drops": 0
}
},
{
"name": "mattscategory",
"type": "category",
"metrics": {
"opens": 0,
"blocks": 0,
"clicks": 0,
"bounces": 0,
"deferred": 0,
"requests": 0,
"delivered": 0,
"processed": 0,
"bounce_drops": 0,
"spam_reports": 0,
"unique_opens": 0,
"unsubscribes": 0,
"unique_clicks": 0,
"invalid_emails": 0,
"spam_report_drops": 0,
"unsubscribe_drops": 0
}
}
]
},
{
"date": "2015-11-01",
"stats": [
{
"name": "docs",
"type": "category",
"metrics": {
"opens": 0,
"blocks": 0,
"clicks": 0,
"bounces": 0,
"deferred": 0,
"requests": 0,
"delivered": 0,
"processed": 0,
"bounce_drops": 0,
"spam_reports": 0,
"unique_opens": 0,
"unsubscribes": 0,
"unique_clicks": 0,
"invalid_emails": 0,
"spam_report_drops": 0,
"unsubscribe_drops": 0
}
},
{
"name": "mattscategory",
"type": "category",
"metrics": {
"opens": 0,
"blocks": 0,
"clicks": 0,
"bounces": 0,
"deferred": 0,
"requests": 0,
"delivered": 0,
"processed": 0,
"bounce_drops": 0,
"spam_reports": 0,
"unique_opens": 0,
"unsubscribes": 0,
"unique_clicks": 0,
"invalid_emails": 0,
"spam_report_drops": 0,
"unsubscribe_drops": 0
}
}
]
}
]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.
Request
Query
| Name | Data Type | Description |
|---|---|---|
offset
|
integer Default value: 0
|
The point in the list that you would like to begin displaying results. |
category
|
string |
Allows you to perform a prefix search on this particular category. |
limit
|
integer Default value: 50
|
The number of categories to display per page. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
array [object] |
Examples
Example application/json
[
{
"category": "category 1"
},
{
"category": "category 2"
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
errors
|
array [object] |
The error returned. |
Examples
Example application/json
[
{
"errors": [
{
"field": "sort_by",
"message": "invalid sort value"
}
]
}
]Contacts API - Custom Fields
This endpoint allows you to delete a custom field by ID.
The contactdb is a database of your contacts for SendGrid Marketing Campaigns.
Request
Path
| Name | Data Type | Description |
|---|---|---|
custom_field_id
|
integer |
The ID of the custom field that you want to retrieve. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"message": "Custom Field delete is processing."
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "Custom field in use by one or more segment conditions"
},
{
"message": "Custom field ID does not exist"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "Custom field ID does not exist"
}
]
}
]This endpoint allows you to retrieve a custom field by ID.
The contactdb is a database of your contacts for SendGrid Marketing Campaigns.
Request
Path
| Name | Data Type | Description |
|---|---|---|
custom_field_id
|
integer |
The ID of the custom field that you want to retrieve. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
ContactDB Custom field schema with ID.
|
object |
Properties
id
|
double |
The ID of the custom field. |
type
|
string Allowed values: - date- text- number |
The type of the field. |
name
|
string |
The name of the field |
Extends
Properties
| Name | Data Type | Description |
|---|---|---|
type
|
string Allowed values: - date- text- number |
The type of the field. |
name
|
string |
The name of the field |
Examples
{
"name": "first_name",
"type": "text"
}Examples
Example application/json
[
{
"id": 1,
"name": "pet",
"type": "text"
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "invalid id"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "Custom field ID does not exist"
}
]
}
]This endpoint allows you to retrieve all custom fields.
The contactdb is a database of your contacts for SendGrid Marketing Campaigns.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
List All Custom Fields response
|
object |
Properties
custom_fields
|
array [contactdb_custom_field_with_id] | |||||||||||||||||||||||
Properties
Extends
ContactDB Custom field schema.
Properties
Examples |
||||||||||||||||||||||||
Examples
Example application/json
[
{
"custom_fields": [
{
"id": 6234,
"name": "age",
"type": "number"
},
{
"id": 6233,
"name": "country",
"type": "text"
},
{
"id": 6235,
"name": "favorite_color",
"type": "text"
},
{
"id": 6239,
"name": "fname",
"type": "text"
},
{
"id": 6240,
"name": "lname",
"type": "text"
},
{
"id": 49439,
"name": "pet",
"type": "text"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]This endpoint allows you to create a custom field.
The contactdb is a database of your contacts for SendGrid Marketing Campaigns.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
type
|
string | |
name
|
string |
Examples
{
"name": "pet",
"type": "text"
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
type
|
string | |
name
|
string | |
id
|
integer |
Examples
Example application/json
[
{
"id": 1,
"name": "pet",
"type": "text"
}
]Body
| Name | Data Type | Description |
|---|---|---|
Error Schema
|
object |
Properties
errors
|
array [object] |
Examples
Example application/json
[
{
"errors": [
{
"message": "Returned if request body is invalid JSON"
},
{
"field": "type",
"message": "Returned if custom field type is invalid or not provided"
},
{
"field": "name",
"message": "Returned if custom field name is not provided"
}
]
}
]This endpoint allows you to list all fields that are reserved and can't be used for custom field names.
The contactdb is a database of your contacts for SendGrid Marketing Campaigns.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
List fields that are reserved and can't be used for custom field names. response
|
object |
Properties
reserved_fields
|
array [contactdb_custom_field] |
The reserved fields that are already set up within custom fields. |
||||||||||
Properties
Examples |
||||||||||||
Examples
Example application/json
[
{
"reserved_fields": [
{
"name": "first_name",
"type": "text"
},
{
"name": "last_name",
"type": "text"
},
{
"name": "email",
"type": "text"
},
{
"name": "created_at",
"type": "date"
},
{
"name": "updated_at",
"type": "date"
},
{
"name": "last_emailed",
"type": "date"
},
{
"name": "last_clicked",
"type": "date"
},
{
"name": "last_opened",
"type": "date"
},
{
"name": "my_custom_field",
"type": "text"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Contacts API - Lists
This endpoint allows you to delete a single recipient from a list.
The Contacts API helps you manage your Marketing Campaigns recipients.
Request
Path
| Name | Data Type | Description |
|---|---|---|
recipient_id
|
string |
The ID of the recipient you are adding to the list. |
list_id
|
integer |
The ID of the list that you want to add the recipient to. |
Query
| Name | Data Type | Description |
|---|---|---|
recipient_id
|
integer |
The ID of the recipient to take off the list. |
list_id
|
integer |
The ID of the list you are taking this recipient away from. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "list_id",
"message": "Returned if list_id is invalid"
},
{
"field": "recipient_id",
"message": "no valid recipients were provided"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "list_id",
"message": "Returned if list_id does not exist"
},
{
"field": "recipient_id",
"message": "Returned if recipient_id does not exist"
}
]
}
]This endpoint allows you to add a single recipient to a list.
The Contacts API helps you manage your Marketing Campaigns recipients.
Request
Path
| Name | Data Type | Description |
|---|---|---|
recipient_id
|
string |
The ID of the recipient you are adding to the list. |
list_id
|
integer |
The ID of the list that you want to add the recipient to. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "list_id",
"message": "Returned if list_id is invalid"
},
{
"field": "recipient_id",
"message": "Returned if recipient_id is invalid"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "list_id",
"message": "Returned if list_id does not exist"
},
{
"field": "recipient_id",
"message": "Returned if recipient_id does not exist"
}
]
}
]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.
Request
Path
| Name | Data Type | Description |
|---|---|---|
list_id
|
integer |
The id of the list of recipients you want to retrieve. |
Query
| Name | Data Type | Description |
|---|---|---|
list_id
|
integer |
The ID of the list whose recipients you are requesting. |
page_size
|
integer |
Number of recipients to return at a time (must be a positive integer between 1 and 1000) |
page
|
integer |
Page index of first recipient to return (must be a positive integer) |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
recipients
|
array [contactdb_recipient] | ||||||||
Properties
|
|||||||||
Examples
Example application/json
[
{
"recipients": [
{
"id": "ZGVWfyZWsuYmFpbmVzQHNlbmRmCmLkLmNv==",
"email": "example@example.com",
"last_name": "User",
"created_at": 1433348344,
"first_name": "Example",
"updated_at": 1438616119,
"last_opened": 1438616109,
"last_clicked": 1438616117,
"last_emailed": 1438613272,
"custom_fields": [
{
"id": 6234,
"name": "age",
"type": "number"
},
{
"id": 6233,
"name": "country",
"type": "text"
},
{
"id": 6235,
"name": "fname",
"type": "text",
"value": "Example"
},
{
"id": 6239,
"name": "lname",
"type": "text",
"value": "User"
},
{
"id": 6240,
"name": "lname",
"type": "text"
}
]
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "list_id",
"message": "Returned if list_id is not a valid integer"
},
{
"field": "page",
"message": "Returned if page is not a valid integer"
},
{
"field": "page",
"message": "Returned if page is less than 1"
},
{
"field": "page_size",
"message": "Returned if page_size is not a valid integer"
},
{
"field": "page_size",
"message": "Returned if page_size is less than 1 or greater than 1000"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Examples
Example application/json
[
{
"errors": [
{
"field": "list_id",
"message": "Returned if list_id is invalid"
}
]
}
]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.
Request
Path
| Name | Data Type | Description |
|---|---|---|
list_id
|
integer |
The id of the list of recipients you want to retrieve. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
array [string] |
Examples
[
"recipient_id1",
"recipient_id2"
]Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "list_id",
"message": "list_id is invalid"
},
{
"field": "recipient_id",
"message": "no valid recipients were provided"
},
{
"message": "no recipients were added"
},
{
"message": "request body is invalid JSON"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "list_id",
"message": "list_id does not exist"
},
{
"field": "recipient_id",
"message": "recipient_id does not exist"
}
]
}
]This endpoint allows you to delete a specific recipient list with the given ID.
The Contacts API helps you manage your Marketing Campaigns recipients.
Request
Path
| Name | Data Type | Description |
|---|---|---|
list_id
|
string |
Query
| Name | Data Type | Description |
|---|---|---|
delete_contacts
|
boolean Allowed values: - 1- |
Adds the ability to delete all contacts on the list in addition to deleting the list. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "delete_contacts",
"message": "delete_contacts not a bool"
},
{
"field": "list_id",
"message": "Returned if list_id is not valid"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "List not found: 5"
}
]
}
]This endpoint allows you to retrieve a single recipient list.
The Contacts API helps you manage your Marketing Campaigns recipients.
Request
Path
| Name | Data Type | Description |
|---|---|---|
list_id
|
string |
Query
| Name | Data Type | Description |
|---|---|---|
list_id
|
integer |
The ID of the list to retrieve. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
ContactDB lists
|
object |
Properties
recipient_count
|
integer |
The count of recipients currently in the list. |
name
|
string |
The name of your list. |
id
|
integer |
The reference ID of your list. |
Examples
{
"id": 1,
"name": "listname",
"recipient_count": 0
}Examples
Example application/json
[
{
"id": 1,
"name": "listname",
"recipient_count": 0
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "invalid id"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "List ID does not exist"
}
]
}
]This endpoint allows you to update the name of one of your recipient lists.
The Contacts API helps you manage your Marketing Campaigns recipients.
Request
Path
| Name | Data Type | Description |
|---|---|---|
list_id
|
string |
Query
| Name | Data Type | Description |
|---|---|---|
list_id
|
integer |
The ID of the list you are updating. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
Update a List request
|
object |
Properties
name
|
string |
The new name for your list. |
Examples
{
"name": "newlistname"
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
recipient_count
|
integer |
The number of recipients on the list |
name
|
string |
The new name for the list |
id
|
integer |
The ID of the list |
Examples
Example application/json
[
{
"id": 1234,
"name": "2016 iPhone Users",
"recipient_count": 0
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "invalid id"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "List ID does not exist"
}
]
}
]This endpoint allows you to delete multiple recipient lists.
The Contacts API helps you manage your Marketing Campaigns recipients.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
array [integer] |
Examples
[
1,
2,
3,
4
]Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "list id was invalid"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]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.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
List All Lists response
|
object |
Properties
lists
|
array [contactdb_list] | ||||||||||||||
Properties
Examples |
|||||||||||||||
Examples
Example application/json
[
{
"lists": [
{
"id": 1,
"name": "the jones",
"recipient_count": 1
}
]
}
]This endpoint allows you to create a list for your recipients.
The Contacts API helps you manage your Marketing Campaigns recipients.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
Create a List request
|
object |
Properties
name
|
string |
Examples
{
"name": "your list name"
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
ContactDB lists
|
object |
Properties
recipient_count
|
integer |
The count of recipients currently in the list. |
name
|
string |
The name of your list. |
id
|
integer |
The reference ID of your list. |
Examples
{
"id": 1,
"name": "listname",
"recipient_count": 0
}Examples
Example application/json
[
{
"id": 1,
"name": "your list name",
"recipient_count": 0
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "Returned if request body is invalid JSON"
},
{
"field": "name",
"message": "Returned if list name is not a string"
},
{
"field": "name",
"message": "Returned if list name is a duplicate of an existing list or segment"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Contacts API - Recipients
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.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
ContactDB: Recipient Count
|
object |
Properties
recipient_count
|
double |
The count of recipients. |
Examples
{
"recipient_count": 1234
}Examples
Example application/json
[
{
"recipient_count": 1234
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]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.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
ContactDB: Recipient Count
|
object |
Properties
recipient_count
|
double |
The count of recipients. |
Examples
{
"recipient_count": 1234
}Examples
Example application/json
[
{
"recipient_count": 1234
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]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.
Request
Query
| Name | Data Type | Description |
|---|---|---|
{field_name}
|
string |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
recipients
|
array [contactdb_recipient] | ||||||||
Properties
|
|||||||||
Examples
Example application/json
[
{
"recipients": [
{
"id": "YUBh",
"email": "jones@example.com",
"last_name": "Jones",
"created_at": 1422313607,
"updated_at": 1422313790,
"custom_fields": [
{
"id": 23,
"name": "pet",
"type": "text",
"value": "Fluffy"
}
]
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "The following parameters are not custom fields or reserved fields: [{field_name}]"
},
{
"message": "No search params are specified"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]This endpoint allows you to retrieve the lists that a given recipient belongs to.
Each recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to.
The Contacts API helps you manage your Marketing Campaigns recipients.
Request
Path
| Name | Data Type | Description |
|---|---|---|
recipient_id
|
string |
The ID of the recipient for whom you are retrieving lists. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
lists
|
array [contactdb_list] | ||||||||||||||
Properties
Examples |
|||||||||||||||
Examples
Example application/json
[
{
"lists": [
{
"id": 1234,
"name": "Example list",
"recipient_count": 42
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "recipient ID is invalid"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "recipient id not found"
}
]
}
]This endpoint allows you to delete a single recipient with the given ID from your contact database.
The Contacts API helps you manage your Marketing Campaigns recipients.
Request
Path
| Name | Data Type | Description |
|---|---|---|
recipient_id
|
string |
The ID of the recipient that you want to retrieve. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "recipient not found"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "recipient_id is not valid"
}
]
}
]This endpoint allows you to retrieve a single recipient by ID from your contact database.
The Contacts API helps you manage your Marketing Campaigns recipients.
Request
Path
| Name | Data Type | Description |
|---|---|---|
recipient_id
|
string |
The ID of the recipient that you want to retrieve. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
ContactDB: Recipient
|
object |
Properties
recipients
|
array [object] |
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
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.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
array [string] |
Examples
[
"recipient_id1",
"recipient_id2"
]Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "No recipient ids provided"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]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.
Request
Query
| Name | Data Type | Description |
|---|---|---|
page_size
|
integer |
Number of recipients to return at a time (must be a positive integer between 1 and 1000) |
page
|
integer |
Page index of first recipients to return (must be a positive integer) |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
List Recipients response
|
object |
Properties
recipients
|
array [object] |
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]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.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
array [object] |
Examples
{
"email": "jones@example.com",
"first_name": "Guy",
"last_name": "Jones"
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
ContactDB: Recipient response
|
object |
Properties
updated_count
|
double Default value: 0
|
The recipients who were updated from this request. |
persisted_recipients
|
array [string] |
The recipient IDs of the recipients that already existed from this request. |
new_count
|
double Default value: 0
|
The count of new recipients added to the contactdb. |
errors
|
array [object] | |
error_indices
|
array [double] |
The indices of the recipient(s) sent that caused the error. |
error_count
|
double Default value: 0
|
The number of errors found while adding recipients. |
Examples
{
"error_count": 1,
"error_indices": [
2
],
"errors": [
{
"error_indices": [
2
],
"message": "Invalid email."
}
],
"new_count": 2,
"persisted_recipients": [
"YUBh",
"bWlsbGVyQG1pbGxlci50ZXN0"
],
"updated_count": 0
}Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "Request body is not valid json"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]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.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
array [object] |
Examples
{
"age": 25,
"email": "example@example.com",
"first_name": "",
"last_name": "User"
}{
"age": 25,
"email": "example2@example.com",
"first_name": "Example",
"last_name": "User"
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
ContactDB: Recipient response
|
object |
Properties
updated_count
|
double Default value: 0
|
The recipients who were updated from this request. |
persisted_recipients
|
array [string] |
The recipient IDs of the recipients that already existed from this request. |
new_count
|
double Default value: 0
|
The count of new recipients added to the contactdb. |
errors
|
array [object] | |
error_indices
|
array [double] |
The indices of the recipient(s) sent that caused the error. |
error_count
|
double Default value: 0
|
The number of errors found while adding recipients. |
Examples
{
"error_count": 1,
"error_indices": [
2
],
"errors": [
{
"error_indices": [
2
],
"message": "Invalid email."
}
],
"new_count": 2,
"persisted_recipients": [
"YUBh",
"bWlsbGVyQG1pbGxlci50ZXN0"
],
"updated_count": 0
}Examples
Example application/json
[
{
"errors": [
{
"message": "Invalid email.",
"error_indices": [
2
]
}
],
"new_count": 2,
"error_count": 1,
"error_indices": [
2
],
"updated_count": 0,
"persisted_recipients": [
"YUBh",
"bWlsbGVyQG1pbGxlci50ZXN0"
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "Request body is not valid json"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
|
Authorization
|
string Default value: Bearer <
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
status
|
array [object] |
Examples
Example application/json
[
{
"status": [
{
"id": "worker_delay",
"value": "delayed"
},
{
"id": "worker_delay_seconds",
"value": "75.0"
}
]
}
]Contacts API - Segments
This endpoint allows you to retrieve all of the recipients in a segment with the given ID.
The Contacts API helps you manage your Marketing Campaigns recipients.
For more information about segments in Marketing Campaigns, please see our User Guide.
Request
Path
| Name | Data Type | Description |
|---|---|---|
segment_id
|
integer |
The ID of the segment from which you want to retrieve recipients. |
Query
| Name | Data Type | Description |
|---|---|---|
page_size
|
integer | |
page
|
integer |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
List Recipients On a Segment response
|
object |
Properties
recipients
|
array [contactdb_recipient] | ||||||||
Properties
|
|||||||||
Examples
Example application/json
[
{
"recipients": [
{
"id": "YUBh",
"email": "jones@example.com",
"last_name": "Jones",
"created_at": 1422313607,
"updated_at": 1422313790,
"custom_fields": [
{
"id": 23,
"name": "pet",
"type": "text",
"value": "Indiana"
}
]
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
This endpoint allows you to delete a segment from your recipients database.
You also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment.
The Contacts API helps you manage your Marketing Campaigns recipients.
For more information about segments in Marketing Campaigns, please see our User Guide.
Request
Path
| Name | Data Type | Description |
|---|---|---|
segment_id
|
string |
Query
| Name | Data Type | Description |
|---|---|---|
delete_contacts
|
boolean |
True to delete all contacts matching the segment in addition to deleting the segment |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Responses
Body
| Name | Data Type | Description |
|---|---|---|
body
|
null |
Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "segment_id",
"message": "Returned if segment_id is not valid"
},
{
"field": "delete_contacts",
"message": "Returned if delete_contacts is not a valid boolean"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"field": "segment_id",
"message": "segment_id does not exist"
}
]
}
]This endpoint allows you to retrieve a single segment with the given ID.
The Contacts API helps you manage your Marketing Campaigns recipients.
For more information about segments in Marketing Campaigns, please see our User Guide.
Request
Path
| Name | Data Type | Description |
|---|---|---|
segment_id
|
string |
Query
| Name | Data Type | Description |
|---|---|---|
segment_id
|
integer |
The ID of the segment you want to request. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
Create a Segment request
|
object |
Properties
recipient_count
|
double |
The count of recipients in this list. This is not included on creation of segments. |
||||||||||||||||
name
|
string |
The name of this segment. |
||||||||||||||||
list_id
|
integer |
The list id from which to make this segment. Not including this ID will mean your segment is created from the main contactdb rather than a list. |
||||||||||||||||
conditions
|
array [contactdb_segments_conditions] |
The conditions for a recipient to be included in this segment. |
||||||||||||||||
Properties
|
||||||||||||||||||
Examples
{
"conditions": [
{
"and_or": "",
"field": "last_name",
"operator": "eq",
"value": "Miller"
},
{
"and_or": "and",
"field": "last_clicked",
"operator": "gt",
"value": "01\/02\/2015"
},
{
"and_or": "or",
"field": "clicks.campaign_identifier",
"operator": "eq",
"value": "513"
}
],
"list_id": 4,
"name": "Last Name Miller",
"recipient_count": 1234
}Examples
Example application/json
[
{
"id": 1,
"name": "Last Name Miller",
"list_id": 4,
"conditions": [
{
"field": "last_name",
"value": "Miller",
"and_or": "",
"operator": "eq"
}
],
"recipient_count": 1
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "if segment_id is not valid"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "segment_id not found"
}
]
}
]This endpoint allows you to update a segment.
The Contacts API helps you manage your Marketing Campaigns recipients.
For more information about segments in Marketing Campaigns, please see our User Guide.
Request
Path
| Name | Data Type | Description |
|---|---|---|
segment_id
|
string |
Query
| Name | Data Type | Description |
|---|---|---|
segment_id
|
string |
The ID of the segment you are updating. |
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Body
| Name | Data Type | Description |
|---|---|---|
body
|
object |
Properties
name
|
string | |||||||||||||||||
list_id
|
double |
The list ID you would like this segment to be built from. |
||||||||||||||||
conditions
|
array [contactdb_segments_conditions] |
The conditions by which this segment should be created. |
||||||||||||||||
Properties
|
||||||||||||||||||
Examples
{
"conditions": [
{
"and_or": "",
"field": "last_name",
"operator": "eq",
"value": "Miller"
}
],
"list_id": 5,
"name": "The Millers"
}Responses
Body
| Name | Data Type | Description |
|---|---|---|
Create a Segment request
|
object |
Properties
recipient_count
|
double |
The count of recipients in this list. This is not included on creation of segments. |
||||||||||||||||
name
|
string |
The name of this segment. |
||||||||||||||||
list_id
|
integer |
The list id from which to make this segment. Not including this ID will mean your segment is created from the main contactdb rather than a list. |
||||||||||||||||
conditions
|
array [contactdb_segments_conditions] |
The conditions for a recipient to be included in this segment. |
||||||||||||||||
Properties
|
||||||||||||||||||
Examples
{
"conditions": [
{
"and_or": "",
"field": "last_name",
"operator": "eq",
"value": "Miller"
},
{
"and_or": "and",
"field": "last_clicked",
"operator": "gt",
"value": "01\/02\/2015"
},
{
"and_or": "or",
"field": "clicks.campaign_identifier",
"operator": "eq",
"value": "513"
}
],
"list_id": 4,
"name": "Last Name Miller",
"recipient_count": 1234
}Examples
Example application/json
[
{
"id": 5,
"name": "The Millers",
"list_id": 5,
"conditions": [
{
"field": "last_name",
"value": "Miller",
"and_or": "",
"operator": "eq"
}
],
"recipient_count": 1
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "request body is not valid json"
},
{
"message": "invalid value is passed into one of the request body parameters"
},
{
"message": "segment id is not valid",
"segment_id": "segment_id"
},
{
"field": "field",
"message": "field and set value is not passed into the request body"
},
{
"field": "value",
"message": "value and set value is not passed into the request body"
},
{
"field": "operator",
"message": "operator and set value is not passed into the request body"
},
{
"field": "and_or",
"message": "and_or is not set on more than one condition and less than all conditions"
},
{
"field": "and_or",
"message": "and_or is set on all conditions"
},
{
"field": "and_or",
"message": "and_or is set on the only condition passed"
},
{
"field": "and_or",
"message": "and_or and set value is not passed into the request body"
},
{
"field": "list_id",
"message": "the list_id is not valid"
},
{
"field": "name",
"message": "the name is not valid"
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]This endpoint allows you to retrieve all of your segments.
The Contacts API helps you manage your Marketing Campaigns recipients.
For more information about segments in Marketing Campaigns, please see our User Guide.
Request
Header
| Name | Data Type | Description |
|---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Responses
Body
| Name | Data Type | Description |
|---|---|---|
List All Segments response
|
object |
Properties
segments
|
array [contactdb_segments] | ||||||||||||||||||||||||||||||||||||
Properties
Examples |
|||||||||||||||||||||||||||||||||||||
Examples
Example application/json
[
{
"segments": [
{
"id": 1234,
"name": "Age segments < 25",
"conditions": [
{
"field": "age",
"value": "25",
"operator": "lt"
}
],
"recipient_count": 8
},
{
"id": 2345,
"name": "email address - gmail",
"conditions": [
{
"field": "email",
"value": "@gmail.com",
"operator": "contains"
}
],
"recipient_count": 0
}
]
}
]Body
| Name | Data Type | Description |
|---|---|---|
Global: Error Response
|
object |
Properties
errors
|
array [object] |
Examples
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}Examples
Example application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]This endpoint allows you to create a segment.
All recipients in your contactdb will be added or removed automatically depending on whether they match the criteria for this segment.
List Id:
- Send this to segment from an existing list
- Don't send this in order to segment from your entire contactdb.
Valid operators for create and update depend on the type of the field you are segmenting:
- Dates: "eq", "ne", "lt" (before), "gt" (after)
- Text: "contains", "eq" (is - matches the full field), "ne" (is not - matches any field where the entire field is not the condition value)
- Numbers: "eq", "lt", "gt"
- Email Clicks and Opens: "eq" (opened), "ne" (not opened)
Segment conditions using "eq" or "ne" for email clicks and opens should provide a "field" of either clicks.campaign_identifier or opens.campaign_identifier. The condition value should be a string containing the id of a completed campaign.
Segments may contain multiple condtions, joined by an "and" or "or" in the "and_or" field. The first condition in the conditions list must have an empty "and_or", and subsequent conditions must all specify an "and_or".
The Contacts API helps you manage your Marketing Campaigns recipients.
For more information about segments in Marketing Campaigns, please see our User Guide.