Contacts API - Recipients
Elements that can be shared among more than one endpoint definition.
Add recipients
POST /v3/contactdb/recipients
Base url: https://api.sendgrid.com
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 rate limit is three requests every 2 seconds. You can upload 1000 contacts per request. So the maximum upload rate is 1500 recipients per second.
Authentication
- API Key
Headers
The on-behalf-of header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header. When making a call on behalf of a customer account, the property value should be "account-id" followed by the customer account's ID (e.g., on-behalf-of: account-id <account-id>). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., on-behalf-of: <subuser-username>). See On Behalf Of for more information.
Request Body
The email address of the recipient.
format: emailThe first name of the recipient.
The last name of the recipient.
[
{
"email": "example@example.com",
"first_name": "",
"last_name": "User",
"age": 25
},
{
"email": "example2@example.com",
"first_name": "Example",
"last_name": "User",
"age": 25
}
]Responses
The number of errors found while adding recipients.
default: 0The indices of the recipient(s) sent that caused the error.
default: []The count of new recipients added to the contactdb.
default: 0The recipient IDs of the recipients that already existed from this request.
default: []The recipients who were updated from this request.
default: 0{
"error_count": 1,
"error_indices": [
2
],
"new_count": 2,
"persisted_recipients": [
"YUBh",
"bWlsbGVyQG1pbGxlci50ZXN0"
],
"updated_count": 0,
"errors": [
{
"message": "Invalid email.",
"error_indices": [
2
]
}
]
}the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}Need some help?
We all do sometimes. Get help now from the Twilio SendGrid Support Team.
Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.
