Menu

Lists

Lists are static collections of Marketing Campaigns contacts. This API allows you to interact with the list objects themselves. To add contacts to a list, you must use the Contacts API.

You can also manage your lists using the Contacts menu in the Marketing Campaigns UI. For more information about lists and best practices for building them, see "Building your Contact List".

Get a List by ID

Get a List by ID

GET /marketing/lists/{id}

This endpoint returns data about a specific list.

Setting the optional parameter contact_sample=true returns the contact_sample in the response body. Up to fifty of the most recent contacts uploaded or attached to a list will be returned, sorted alphabetically, by email address.

The full contact count is also returned.

Authentication

  • API Key

Headers

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required

Path Parameters

id
string
default: None
required

Query String

contact_sample
boolean

Setting this parameter to the true will cause the contact_sample to be returned

default: False

Responses

object
id
string

The generated ID for your list.

maxLength: 36minLength: 36
name
string

The name you gave your list.

contact_count
integer

The number of contacts currently stored on the list.

_metadata
object
self
string

A link to this object.

contact_sample
object
id
string
format: uuidmaxLength: 36minLength: 36
required
first_name
string
last_name
string
unique_name
string
email
string
format: email
alternate_emails
array[string] or null
address_line_1
string
address_line_2
string
city
string
state_province_region
string
country
string
postal_code
string
phone_number
string
whatsapp
string
line
string
facebook
string
list_ids
array[string]
required
segment_ids
array[string]
custom_fields
object
created_at
string
format: date-time
required
updated_at
string
format: date-time
required
_metadata
object
self
string

A link to this object.

array[object]
message
string
field
string
error_id
string
parameter
string
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