Menu

Contacts API - Lists

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

Retrieve all recipients on a List

GET /contactdb/lists/{list_id}/recipients

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

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.

Path Parameters

list_id
integer

The id of the list of recipients you want to retrieve.

default: None
required

Query String

page
integer

Page index of first recipient to return (must be a positive integer)

default: None
page_size
integer

number of results to return

default: 100
list_id
integer

The ID of the list whose recipients you are requesting.

default: None
required

Responses

object
recipients
array[object]
recipients
array[object]
id
string

The ID of this recipient.

created_at
number

The time this record was created in your contactdb, in unixtime.

custom_fields
array[object]

The custom fields assigned to this recipient and their values.

value
string or null

The value of this recipient's custom field

email
string

The email address of this recipient. This is a default custom field that SendGrid provides.

format: email
first_name
string or null

The first name of this recipient. This is a default custom field that SendGrid provides.

last_name
string or null

The last name of the recipient.

last_clicked
number or null

The last time this recipient clicked a link from one of your campaigns, in unixtime.

last_emailed
number or null

The last time this user was emailed by one of your campaigns, in unixtime.

last_opened
number or null

The last time this recipient opened an email from you, in unixtime.

updated_at
number

The last update date for this recipient's record.

object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
Rate this page:

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.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more