Skip to content Skip to navigation Skip to topbar

Retrieve all recipients on a List

API Overview

(warning)

Legacy Marketing Campaigns

You are viewing the Legacy Marketing Campaigns API reference. For guidance migrating to the current version of Marketing Campaigns, see Migrating from Legacy Marketing Campaigns

(information)

Info

For the most up-to-date information on SendGrid's Contact Lists API, please visit the new Marketing Campaigns Lists API.

The Lists API allows you to manage your Marketing Campaigns contact lists. You can create, retrieve, update, and delete lists, as well as add and remove contacts from lists.

Operation overview

GET/v3/contactdb/lists/{list_id}/recipients

Base url: https://api.sendgrid.com

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

Operation details

Authentication

API Key

Headers

Property nameTypeRequiredDescription

Authorizationstringrequired

Default: Bearer <<YOUR_API_KEY_HERE>>

on-behalf-ofstringOptional

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.

Path parameters

Property nameTypeRequiredDescription

list_idintegerrequired

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

Query string

Property nameTypeRequiredDescription

pageintegerOptional

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

page_sizeintegerOptional

Number of recipients to return at a time (must be a positive integer between 1 and 1000)

list_idintegerrequired

The ID of the list whose recipients you are requesting.

Responses

200400404

SchemaExample

Property nameTypeRequiredDescriptionChild properties

recipientsarray[object]

Show child properties for recipients

Input failed validation

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[object]

Show child properties for errors

idstring

When applicable, this property value will be an error ID.

Returned if list_id does not exist

SchemaExample

Property nameTypeRequiredDescriptionChild properties

No properties defined

Retrieve all recipients on a List

Node.js

Python

Java

PHP

Ruby

curl


_22const client = require('@sendgrid/client');
_22client.setApiKey(process.env.SENDGRID_API_KEY);
_22
_22const list_id = 4900;
_22const queryParams = {
_22  "list_id": 4900
_22};
_22
_22const request = {
_22  url: `/v3/contactdb/lists/${list_id}/recipients`,
_22  method: 'GET',
_22  qs: queryParams
_22}
_22
_22client.request(request)
_22  .then(([response, body]) => {
_22    console.log(response.statusCode);
_22    console.log(response.body);
_22  })
_22  .catch(error => {
_22    console.error(error);
_22  });