Menu

Contacts API - Recipients

Elements that can be shared among more than one endpoint definition.

Add recipients

Add recipients

POST /contactdb/recipients

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

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required
on-behalf-of
string
default: The subuser's username. This header generates the API call as if the subuser account was making the call.

Request Body

array[object]
email
string

The email address of the recipient.

format: email
first_name
string

The first name of the recipient.

last_name
string

The last name of the recipient.

age
integer
[
  {
    "email": "example@example.com",
    "first_name": "",
    "last_name": "User",
    "age": 25
  },
  {
    "email": "example2@example.com",
    "first_name": "Example",
    "last_name": "User",
    "age": 25
  }
]

Responses

object
error_count
number

The number of errors found while adding recipients.

default: 0
required
error_indices
array[number]

The indices of the recipient(s) sent that caused the error.

default: []
new_count
number

The count of new recipients added to the contactdb.

default: 0
required
persisted_recipients
array[string]

The recipient IDs of the recipients that already existed from this request.

default: []
required
updated_count
number

The recipients who were updated from this request.

default: 0
required
errors
array[object]
message
string
error_indices
array[number]
{
  "error_count": 1,
  "error_indices": [
    2
  ],
  "new_count": 2,
  "persisted_recipients": [
    "YUBh",
    "bWlsbGVyQG1pbGxlci50ZXN0"
  ],
  "updated_count": 0,
  "errors": [
    {
      "message": "Invalid email.",
      "error_indices": [
        2
      ]
    }
  ]
}
object
errors
array[object]
message
string

the error message

field
string

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string

the error message

field
string

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.