This is the entirety of the documented v3 endpoints. We have updated all the descriptions, parameters, requests, and responses.
Every endpoint requires Authentication in the form of an Authorization Header:
Authorization: Bearer API_KEY
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.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
object |
scopes
|
array [string] |
The list of scopes for which this user has access. |
application/json
[
{
"scopes": [
"mail.send",
"alerts.create",
"alerts.read"
]
}
]
Name | Data Type | Description |
---|---|---|
body
|
object |
errors
|
array [object] |
This 401 response indicates that the user making the call doesn't have the authorization to view the list of scopes. |
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
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 Parameter | Type | Required? | Description |
---|---|---|---|
api_key_id | string | required | The ID of the API Key you are deleting. |
Name | Data Type | Description |
---|---|---|
api_key_id
|
string |
The ID of the API Key for which you are requesting information. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
api_key_id
|
string |
The ID of the API Key for which you are requesting information. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
object |
result
|
array [api_key_name_id_scopes] | |||||||||||||||||||||||
Properties
Extends
API Key Name and ID
Properties
Examples
Examples
|
application/json
[
{
"result": [
{
"name": "API Key Name",
"api_key_id": "some-apikey-id"
},
{
"name": "API Key Name 2",
"api_key_id": "another-apikey-id"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
body
|
object |
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 Parameter | Type | Required? | Description |
---|---|---|---|
api_key_id | string | required | The ID of the API Key you are updating. |
Name | Data Type | Description |
---|---|---|
api_key_id
|
string |
The ID of the API Key for which you are requesting information. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
object |
name
|
string |
The new name of the API Key. |
{
"name": "A New Hope"
}
Name | Data Type | Description |
---|---|---|
API Key Name and ID
|
object |
name
|
string |
The name of your API Key. |
api_key_id
|
string |
The ID of your API Key. |
{
"api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA",
"name": "A New Hope"
}
application/json
[
{
"name": "A New Hope",
"api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA"
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
api_key_id
|
string |
The ID of the API Key for which you are requesting information. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
object |
scopes
|
array [string] | |
name
|
string |
{
"name": "A New Hope",
"scopes": [
"user.profile.read",
"user.profile.update"
]
}
Name | Data Type | Description |
---|---|---|
API Key Name, ID, and Scopes
|
object |
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. |
Name | Data Type | Description |
---|---|---|
name
|
string |
The name of your API Key. |
api_key_id
|
string |
The ID of your API Key. |
{
"api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA",
"name": "A New Hope"
}
{
"api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA",
"name": "A New Hope",
"scopes": [
"user.profile.read",
"user.profile.update"
]
}
application/json
[
{
"name": "A New Hope",
"scopes": [
"user.profile.read",
"user.profile.update"
],
"api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA"
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "expected JSON request body with 'name' property"
}
]
}
]
Name | Data Type | Description |
---|---|---|
body
|
object |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
limit
|
integer |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
object |
result
|
array [api_key_name_id] | |||||||||||
Properties
Examples
|
application/json
[
{
"result": [
{
"name": "API Key Name",
"api_key_id": "some-apikey-id"
},
{
"name": "API Key Name 2",
"api_key_id": "another-apikey-id"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
object |
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. |
{
"name": "My API Key",
"sample": "data",
"scopes": [
"mail.send",
"alerts.create",
"alerts.read"
]
}
Name | Data Type | Description |
---|---|---|
body
|
object |
scopes
|
array [string] | |
name
|
string | |
api_key_id
|
string | |
api_key
|
string |
application/json
[
{
"name": "My API Key",
"scopes": [
"mail.send",
"alerts.create",
"alerts.read"
],
"api_key": "SG.xxxxxxxx.yyyyyyyy",
"api_key_id": "xxxxxxxx"
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"field": "name",
"message": "missing required argument"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "Cannot create more than 100 API Keys"
}
]
}
]
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.
For more information about alerts, please see our User Guide.
Name | Data Type | Description |
---|---|---|
alert_id
|
integer |
The ID of the alert you would like to retrieve. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
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.
For more information about alerts, please see our User Guide.
Name | Data Type | Description |
---|---|---|
alert_id
|
integer |
The ID of the alert you would like to retrieve. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
|
Authorization
|
string |
Name | Data Type | Description |
---|---|---|
body
|
object |
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. |
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.
For more information about alerts, please see our User Guide.
Name | Data Type | Description |
---|---|---|
alert_id
|
integer |
The ID of the alert you would like to retrieve. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
object |
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 |
{
"email_to": "example@example.com"
}
Name | Data Type | Description |
---|---|---|
body
|
object |
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. |
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.
For more information about alerts, please see our User Guide.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
|
Authorization
|
string |
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
body
|
array [object] |
The list of alerts. |
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_limit
allows you to set the threshold at which an alert will be sent.stats_notification
allows you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".For more information about alerts, please see our User Guide.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string | |
Authorization
|
string |
Name | Data Type | Description |
---|---|---|
body
|
object |
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 |
{
"email_to": "example@example.com",
"frequency": "daily",
"type": "stats_notification"
}
Name | Data Type | Description |
---|---|---|
body
|
object |
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. |
application/json
[
{
"id": 48,
"type": "stats_notification",
"email_to": "test@example.com",
"frequency": "daily",
"created_at": 1451520930,
"updated_at": 1451520930
}
]
Name | Data Type | Description |
---|---|---|
body
|
object |
message
|
string | |
field
|
string |
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.
Name | Data Type | Description |
---|---|---|
email
|
string |
The email address of the specific block. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
|
Authorization
|
string Default value: Bearer <
|
Name | Data Type | Description |
---|---|---|
body
|
null |
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.
Name | Data Type | Description |
---|---|---|
email
|
string |
The email address of the specific block. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
array [object] |
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:
delete_all
to true 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.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
object |
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. |
{
"delete_all": false,
"emails": [
"example1@example.com",
"example2@example.com"
]
}
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.
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). |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
array [object] |
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 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:
Name | Data Type | Description |
---|---|---|
email
|
string |
Name | Data Type | Description |
---|---|---|
email_address
|
The email address you would like to remove from the bounce list. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
body
|
object |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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:
Name | Data Type | Description |
---|---|---|
email
|
string |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
array [object] |
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:
Note: the delete_all
and emails
parameters should be used independently of each other as they have different purposes.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
object |
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. |
{
"delete_all": true,
"emails": [
"example@example.com",
"example2@example.com"
]
}
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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:
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). |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
|
Accept
|
string Default value: application/json
|
Name | Data Type | Description |
---|---|---|
body
|
array [object] |
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
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
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:
Name | Data Type | Description |
---|---|---|
campaign_id
|
integer |
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
Send a Campaign response
|
object |
status
|
string | |
id
|
long |
application/json
[
{
"id": 1234,
"status": "Scheduled"
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "You may only send a campaign when it is in draft mode."
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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:
Name | Data Type | Description |
---|---|---|
campaign_id
|
integer |
Name | Data Type | Description |
---|---|---|
body
|
object |
to
|
The email address that should receive the test campaign. |
{
"to": "your.email@example.com"
}
Name | Data Type | Description |
---|---|---|
Send a Test Campaign request
|
object |
to
|
string |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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:
Name | Data Type | Description |
---|---|---|
campaign_id
|
integer |
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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."
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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:
Name | Data Type | Description |
---|---|---|
campaign_id
|
integer |
Name | Data Type | Description |
---|---|---|
View Scheduled Time of a Campaign response
|
object |
send_at
|
long |
application/json
[
{
"send_at": 1490778528
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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:
Name | Data Type | Description |
---|---|---|
campaign_id
|
integer |
Name | Data Type | Description |
---|---|---|
Update a Scheduled Campaign request
|
object |
send_at
|
long |
{
"send_at": 1489451436
}
Name | Data Type | Description |
---|---|---|
Update a Scheduled Campaign response
|
object |
status
|
string |
The status of the schedule. |
send_at
|
integer |
The unix timestamp to send the campaign. |
id
|
integer |
The campaign ID |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"field": "send_at",
"message": "You cannot update the send_at value of non-scheduled campaign."
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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:
Name | Data Type | Description |
---|---|---|
campaign_id
|
integer |
Name | Data Type | Description |
---|---|---|
Schedule a Campaign request
|
object |
send_at
|
integer |
The unix timestamp for the date and time you would like your campaign to be sent out. |
{
"send_at": 1489771528
}
Name | Data Type | Description |
---|---|---|
Schedule a Campaign response
|
object |
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. |
application/json
[
{
"id": 1234,
"status": "Scheduled",
"send_at": 1489771528
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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."
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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:
Name | Data Type | Description |
---|---|---|
campaign_id
|
integer |
The id of the campaign you would like to retrieve. |
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
body
|
object |
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
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:
Name | Data Type | Description |
---|---|---|
campaign_id
|
integer |
The id of the campaign you would like to retrieve. |
Name | Data Type | Description |
---|---|---|
body
|
object |
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] |
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": ""
}
]
Name | Data Type | Description |
---|---|---|
body
|
object |
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
body
|
object |
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:
Name | Data Type | Description |
---|---|---|
campaign_id
|
integer |
The id of the campaign you would like to retrieve. |
Name | Data Type | Description |
---|---|---|
Update a Campaign request
|
object |
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. |
{
"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"
}
Name | Data Type | Description |
---|---|---|
Campaigns Response
|
object |
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. |
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. |
{
"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"
}
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": ""
}
]
Name | Data Type | Description |
---|---|---|
body
|
object |
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."
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
body
|
object |
application/json
[
{
"errors": [
{
"message": "You may only update a campaign when it is in draft mode."
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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:
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. |
Name | Data Type | Description |
---|---|---|
body
|
object |
result
|
array [object] |
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:
Name | Data Type | Description |
---|---|---|
Campaigns Request
|
object |
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. |
{
"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"
}
Name | Data Type | Description |
---|---|---|
Campaigns Response
|
object |
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. |
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. |
{
"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"
}
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": ""
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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."
}
]
}
]
Name | Data Type | Description |
---|---|---|
body
|
object |
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:
Name | Data Type | Description |
---|---|---|
batch_id
|
string |
Name | Data Type | Description |
---|---|---|
Mail: Batch ID
|
object |
batch_id
|
string Pattern: ^[a-zA-Z0-9\-\_]
|
{
"batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi"
}
application/json
[
{
"batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi"
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "invalid batch id"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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:
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
Mail: Batch ID
|
object |
batch_id
|
string Pattern: ^[a-zA-Z0-9\-\_]
|
{
"batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi"
}
application/json
[
{
"batch_id": "YOUR_BATCH_ID"
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
batch_id
|
string |
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
batch_id
|
string |
Name | Data Type | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Retrieve scheduled send response
|
array [user_scheduled_send_status] | |||||||||||||||||
Properties
Extends
Mail: Batch ID
Properties
Examples
|
application/json
[
{
"status": "cancel",
"batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi"
},
{
"status": "pause",
"batch_id": "IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg"
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
batch_id
|
string |
Name | Data Type | Description |
---|---|---|
body
|
object |
status
|
string Allowed values: - cancel - pause |
The status you would like the scheduled send to have. |
{
"status": "pause"
}
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"field": "status",
"message": "status must be either cancel or pause"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
body
|
array [user_scheduled_send_status] | |||||||||||||||||
Properties
Extends
Mail: Batch ID
Properties
Examples
|
application/json
[
{
"status": "cancel",
"batch_id": "YzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYg"
},
{
"status": "cancel",
"batch_id": "UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYgYzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2"
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
Cancel or pause a scheduled send request
|
object |
status
|
string Default value: pause Allowed 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. |
{
"batch_id": "YOUR_BATCH_ID",
"status": "pause"
}
Name | Data Type | Description |
---|---|---|
User: Scheduled Send status
|
object |
The status of the scheduled send. |
status
|
string Allowed values: - cancel - pause |
The status of the scheduled send. |
batch_id
|
string Pattern: ^[a-zA-Z0-9\-\_]
|
Name | Data Type | Description |
---|---|---|
batch_id
|
string Pattern: ^[a-zA-Z0-9\-\_]
|
{
"batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi"
}
Name | Data Type | Description |
---|---|---|
body
|
object |
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"
}
]
}
]
Name | Data Type | Description |
---|---|---|
body
|
object |
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
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.
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: desc Allowed 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. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
Stats: Category Stats
|
object |
stats
|
array [object] | |
date
|
string |
The date the statistics were gathered. |
{
"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"
}
]
}
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.
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: 500 Maximum: 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 |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
body
|
array [category_stats] | |||||||||||
Properties
Examples
|
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.
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. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
array [object] |
application/json
[
{
"category": "category 1"
},
{
"category": "category 2"
}
]
Name | Data Type | Description |
---|---|---|
body
|
object |
errors
|
array [object] |
The error returned. |
application/json
[
{
"errors": [
{
"field": "sort_by",
"message": "invalid sort value"
}
]
}
]
This endpoint allows you to delete a custom field by ID.
The contactdb is a database of your contacts for SendGrid Marketing Campaigns.
Name | Data Type | Description |
---|---|---|
custom_field_id
|
integer |
The ID of the custom field that you want to retrieve. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"message": "Custom Field delete is processing."
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "Custom field in use by one or more segment conditions"
},
{
"message": "Custom field ID does not exist"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
custom_field_id
|
integer |
The ID of the custom field that you want to retrieve. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
ContactDB Custom field schema with ID.
|
object |
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 |
Name | Data Type | Description |
---|---|---|
type
|
string Allowed values: - date - text - number |
The type of the field. |
name
|
string |
The name of the field |
{
"name": "first_name",
"type": "text"
}
application/json
[
{
"id": 1,
"name": "pet",
"type": "text"
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "invalid id"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
List All Custom Fields response
|
object |
custom_fields
|
array [contactdb_custom_field_with_id] | |||||||||||||||||||||||
Properties
Extends
ContactDB Custom field schema.
Properties
Examples
|
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"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
object |
type
|
string | |
name
|
string |
{
"name": "pet",
"type": "text"
}
Name | Data Type | Description |
---|---|---|
body
|
object |
type
|
string | |
name
|
string | |
id
|
integer |
application/json
[
{
"id": 1,
"name": "pet",
"type": "text"
}
]
Name | Data Type | Description |
---|---|---|
Error Schema
|
object |
errors
|
array [object] |
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.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
List fields that are reserved and can't be used for custom field names. response
|
object |
reserved_fields
|
array [contactdb_custom_field] |
The reserved fields that are already set up within custom fields. |
||||||||||
Properties
Examples
|
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"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
This endpoint allows you to delete a single recipient from a list.
The Contacts API helps you manage your Marketing Campaigns recipients.
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. |
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. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"field": "list_id",
"message": "Returned if list_id is invalid"
},
{
"field": "recipient_id",
"message": "no valid recipients were provided"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
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. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"field": "list_id",
"message": "Returned if list_id is invalid"
},
{
"field": "recipient_id",
"message": "Returned if recipient_id is invalid"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
list_id
|
integer |
The id of the list of recipients you want to retrieve. |
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) |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
object |
recipients
|
array [contactdb_recipient] | ||||||||
Properties
|
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"
}
]
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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"
}
]
}
]
Name | Data Type | Description |
---|---|---|
body
|
object |
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.
Name | Data Type | Description |
---|---|---|
list_id
|
integer |
The id of the list of recipients you want to retrieve. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
array [string] |
[
"recipient_id1",
"recipient_id2"
]
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
list_id
|
string |
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. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"field": "delete_contacts",
"message": "delete_contacts not a bool"
},
{
"field": "list_id",
"message": "Returned if list_id is not valid"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
list_id
|
string |
Name | Data Type | Description |
---|---|---|
list_id
|
integer |
The ID of the list to retrieve. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
ContactDB lists
|
object |
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. |
{
"id": 1,
"name": "listname",
"recipient_count": 0
}
application/json
[
{
"id": 1,
"name": "listname",
"recipient_count": 0
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "invalid id"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
list_id
|
string |
Name | Data Type | Description |
---|---|---|
list_id
|
integer |
The ID of the list you are updating. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
Update a List request
|
object |
name
|
string |
The new name for your list. |
{
"name": "newlistname"
}
Name | Data Type | Description |
---|---|---|
body
|
object |
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 |
application/json
[
{
"id": 1234,
"name": "2016 iPhone Users",
"recipient_count": 0
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "invalid id"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
array [integer] |
[
1,
2,
3,
4
]
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "list id was invalid"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
List All Lists response
|
object |
lists
|
array [contactdb_list] | ||||||||||||||
Properties
Examples
|
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.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
Create a List request
|
object |
name
|
string |
{
"name": "your list name"
}
Name | Data Type | Description |
---|---|---|
ContactDB lists
|
object |
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. |
{
"id": 1,
"name": "listname",
"recipient_count": 0
}
application/json
[
{
"id": 1,
"name": "your list name",
"recipient_count": 0
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
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.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
ContactDB: Recipient Count
|
object |
recipient_count
|
double |
The count of recipients. |
{
"recipient_count": 1234
}
application/json
[
{
"recipient_count": 1234
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
ContactDB: Recipient Count
|
object |
recipient_count
|
double |
The count of recipients. |
{
"recipient_count": 1234
}
application/json
[
{
"recipient_count": 1234
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.
field_name:
The contactdb is a database of your contacts for SendGrid Marketing Campaigns.
Name | Data Type | Description |
---|---|---|
{field_name}
|
string |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
object |
recipients
|
array [contactdb_recipient] | ||||||||
Properties
|
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"
}
]
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "The following parameters are not custom fields or reserved fields: [{field_name}]"
},
{
"message": "No search params are specified"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
recipient_id
|
string |
The ID of the recipient for whom you are retrieving lists. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
object |
lists
|
array [contactdb_list] | ||||||||||||||
Properties
Examples
|
application/json
[
{
"lists": [
{
"id": 1234,
"name": "Example list",
"recipient_count": 42
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "recipient ID is invalid"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
recipient_id
|
string |
The ID of the recipient that you want to retrieve. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
body
|
object |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "recipient not found"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
recipient_id
|
string |
The ID of the recipient that you want to retrieve. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
ContactDB: Recipient
|
object |
recipients
|
array [object] |
Name | Data Type | Description |
---|---|---|
body
|
object |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
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.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
array [string] |
[
"recipient_id1",
"recipient_id2"
]
Name | Data Type | Description |
---|---|---|
body
|
object |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "No recipient ids provided"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
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) |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
List Recipients response
|
object |
recipients
|
array [object] |
Name | Data Type | Description |
---|---|---|
body
|
object |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
array [object] |
{
"email": "jones@example.com",
"first_name": "Guy",
"last_name": "Jones"
}
Name | Data Type | Description |
---|---|---|
ContactDB: Recipient response
|
object |
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. |
{
"error_count": 1,
"error_indices": [
2
],
"errors": [
{
"error_indices": [
2
],
"message": "Invalid email."
}
],
"new_count": 2,
"persisted_recipients": [
"YUBh",
"bWlsbGVyQG1pbGxlci50ZXN0"
],
"updated_count": 0
}
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "Request body is not valid json"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
array [object] |
{
"age": 25,
"email": "example@example.com",
"first_name": "",
"last_name": "User"
}
{
"age": 25,
"email": "example2@example.com",
"first_name": "Example",
"last_name": "User"
}
Name | Data Type | Description |
---|---|---|
ContactDB: Recipient response
|
object |
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. |
{
"error_count": 1,
"error_indices": [
2
],
"errors": [
{
"error_indices": [
2
],
"message": "Invalid email."
}
],
"new_count": 2,
"persisted_recipients": [
"YUBh",
"bWlsbGVyQG1pbGxlci50ZXN0"
],
"updated_count": 0
}
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"
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "Request body is not valid json"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
|
Authorization
|
string Default value: Bearer <
|
Name | Data Type | Description |
---|---|---|
body
|
object |
status
|
array [object] |
application/json
[
{
"status": [
{
"id": "worker_delay",
"value": "delayed"
},
{
"id": "worker_delay_seconds",
"value": "75.0"
}
]
}
]
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.
Name | Data Type | Description |
---|---|---|
segment_id
|
integer |
The ID of the segment from which you want to retrieve recipients. |
Name | Data Type | Description |
---|---|---|
page_size
|
integer | |
page
|
integer |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
List Recipients On a Segment response
|
object |
recipients
|
array [contactdb_recipient] | ||||||||
Properties
|
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"
}
]
}
]
}
]
Name | Data Type | Description |
---|---|---|
body
|
object |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
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.
Name | Data Type | Description |
---|---|---|
segment_id
|
string |
Name | Data Type | Description |
---|---|---|
delete_contacts
|
boolean |
True to delete all contacts matching the segment in addition to deleting the segment |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
body
|
null |
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
segment_id
|
string |
Name | Data Type | Description |
---|---|---|
segment_id
|
integer |
The ID of the segment you want to request. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
Create a Segment request
|
object |
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
|
{
"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
}
application/json
[
{
"id": 1,
"name": "Last Name Miller",
"list_id": 4,
"conditions": [
{
"field": "last_name",
"value": "Miller",
"and_or": "",
"operator": "eq"
}
],
"recipient_count": 1
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "if segment_id is not valid"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
application/json
[
{
"errors": [
{
"message": "authorization required"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
segment_id
|
string |
Name | Data Type | Description |
---|---|---|
segment_id
|
string |
The ID of the segment you are updating. |
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
body
|
object |
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
|
{
"conditions": [
{
"and_or": "",
"field": "last_name",
"operator": "eq",
"value": "Miller"
}
],
"list_id": 5,
"name": "The Millers"
}
Name | Data Type | Description |
---|---|---|
Create a Segment request
|
object |
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
|
{
"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
}
application/json
[
{
"id": 5,
"name": "The Millers",
"list_id": 5,
"conditions": [
{
"field": "last_name",
"value": "Miller",
"and_or": "",
"operator": "eq"
}
],
"recipient_count": 1
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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"
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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.
Name | Data Type | Description |
---|---|---|
on-behalf-of
|
string Default value: subuser_
|
Name | Data Type | Description |
---|---|---|
List All Segments response
|
object |
segments
|
array [contactdb_segments] | ||||||||||||||||||||||||||||||||||||
Properties
Examples
|
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
}
]
}
]
Name | Data Type | Description |
---|---|---|
Global: Error Response
|
object |
errors
|
array [object] |
{
"errors": [
{
"field": "field_name",
"message": "Some message here"
}
]
}
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:
Valid operators for create and update depend on the type of the field you are segmenting:
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.