# Retrieve all recipients on a List

## API Overview

> \[!WARNING]
>
> This covers the obsolete Legacy Marketing Campaigns API.

> \[!NOTE]
>
> For the most up-to-date information on SendGrid's Contact Lists API, please visit the [new Marketing Campaigns Lists API](/docs/sendgrid/api-reference/lists).

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

```json
{"path":"https://api.sendgrid.com/v3/contactdb/lists/{list_id}/recipients","method":"get","servers":[{"url":"https://api.sendgrid.com","description":"The Twilio SendGrid v3 API"}]}
```

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

## Operation details

### Authentication

API Key

### Headers

```json
[{"in":"header","name":"Authorization","required":true,"default":"Bearer <<YOUR_API_KEY_HERE>>","schema":{"type":"string"}},{"name":"on-behalf-of","in":"header","description":"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**](/docs/sendgrid/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.","required":false,"schema":{"type":"string"},"refName":"#/components/parameters/OnBehalfOf","modelName":"__components_parameters_OnBehalfOf"}]
```

### Path parameters

```json
[{"name":"list_id","in":"path","description":"The id of the list of recipients you want to retrieve.","required":true,"schema":{"type":"integer"}}]
```

### Query string

```json
[{"name":"page","in":"query","description":"Page index of first recipient to return (must be a positive integer)","required":false,"schema":{"type":"integer"}},{"name":"page_size","in":"query","description":"Number of recipients to return at a time (must be a positive integer between 1 and 1000)","required":false,"schema":{"type":"integer"}}]
```

### Responses

```json
[{"responseCode":"200","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"recipients":{"type":"array","items":{"title":"ContactDB: Recipient","type":"object","refName":"ContactdbRecipient200","modelName":"ContactdbRecipient200","properties":{"recipients":{"type":"array","items":{"type":"object","required":["email"],"properties":{"id":{"type":"string","description":"The ID of this recipient."},"created_at":{"type":"number","description":"The time this record was created in your contactdb, in unixtime."},"custom_fields":{"type":"array","description":"The custom fields assigned to this recipient and their values.","items":{"title":"ContactDB Custom field schema.","type":"object","refName":"ContactdbCustomFieldIdValue","modelName":"ContactdbCustomFieldIdValue","properties":{"name":{"type":"string","description":"The name of the field"},"type":{"type":"string","description":"The type of the field.","enum":["date","text","number"],"refName":"Type","modelName":"Type"},"id":{"type":"number","description":"The ID of the custom field."},"value":{"description":"The value of this recipient's custom field","nullable":true,"type":"string"}}}},"email":{"type":"string","description":"The email address of this recipient. This is a default custom field that SendGrid provides.","format":"email"},"first_name":{"description":"The first name of this recipient. This is a default custom field that SendGrid provides.","nullable":true,"type":"string"},"last_name":{"description":"The last name of the recipient.","nullable":true,"type":"string"},"last_clicked":{"description":"The last time this recipient clicked a link from one of your campaigns, in unixtime.","nullable":true,"type":"number"},"last_emailed":{"description":"The last time this user was emailed by one of your campaigns, in unixtime.","nullable":true,"type":"number"},"last_opened":{"description":"The last time this recipient opened an email from you, in unixtime.","nullable":true,"type":"number"},"updated_at":{"type":"number","description":"The last update date for this recipient's record."}}}}}}}}},"examples":{"response":{"value":{"recipients":[{"created_at":1433348344,"custom_fields":[{"id":6234,"name":"age","type":"number","value":null},{"id":6233,"name":"country","type":"text","value":null},{"id":6235,"name":"fname","type":"text","value":"Example"},{"id":6239,"name":"lname","type":"text","value":"User"},{"id":6240,"name":"lname","type":"text","value":null}],"email":"example@example.com","first_name":"Example","id":"ZGVWfyZWsuYmFpbmVzQHNlbmRmCmLkLmNv==","last_clicked":1438616117,"last_emailed":1438613272,"last_name":"User","last_opened":1438616109,"updated_at":1438616119}]}}}}}}},{"responseCode":"400","schema":{"description":"Input failed validation","content":{"application/json":{"schema":{"type":"object","example":{"errors":[{"field":"field_name","message":"error message"}]},"refName":"ErrorResponse","modelName":"ErrorResponse","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","description":"An error message."},"field":{"description":"When applicable, this property value will be the field that generated the error.","nullable":true,"type":"string"},"help":{"type":"object","description":"When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error."}}}},"id":{"type":"string","description":"When applicable, this property value will be an error ID."}}},"examples":{"response":{"value":{"errors":[{"field":"list_id","message":"Returned if list_id is not a valid integer"},{"field":"page","message":"Returned if page is not a valid integer"},{"field":"page","message":"Returned if page is less than 1"},{"field":"page_size","message":"Returned if page_size is not a valid integer"},{"field":"page_size","message":"Returned if page_size is less than 1 or greater than 1000"}]}}}}}}},{"responseCode":"404","schema":{"description":"Returned if `list_id` does not exist","content":{"application/json":{"schema":{"type":"object"},"examples":{"response":{"value":{"errors":[{"field":"list_id","message":"Returned if list_id is invalid"}]}}}}}}}]
```

Retrieve all recipients on a List

```js
const client = require("@sendgrid/client");
client.setApiKey(process.env.SENDGRID_API_KEY);

const list_id = 42;

const request = {
  url: `/v3/contactdb/lists/${list_id}/recipients`,
  method: "GET",
};

client
  .request(request)
  .then(([response, body]) => {
    console.log(response.statusCode);
    console.log(response.body);
  })
  .catch((error) => {
    console.error(error);
  });
```

```python
import os
from sendgrid import SendGridAPIClient


sg = SendGridAPIClient(os.environ.get("SENDGRID_API_KEY"))

list_id = 42

response = sg.client.contactdb.lists._(list_id).recipients.get()

print(response.status_code)
print(response.body)
print(response.headers)
```

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SendGrid;

public class Program {
    public static async Task Main() {
        string apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY");
        var client = new SendGridClient(apiKey);

        var listId = 42;

        var response = await client.RequestAsync(
            method: SendGridClient.Method.GET, urlPath: $"contactdb/lists/{listId}/recipients");

        Console.WriteLine(response.StatusCode);
        Console.WriteLine(response.Body.ReadAsStringAsync().Result);
        Console.WriteLine(response.Headers.ToString());
    }
}
```

```java
import com.sendgrid.*;
import java.io.IOException;

public class Example {
    public static void main(String[] args) throws IOException {
        try {
            SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
            Request request = new Request();
            request.setMethod(Method.GET);
            request.setEndpoint("/contactdb/lists/42/recipients");
            Response response = sg.api(request);
            System.out.println(response.getStatusCode());
            System.out.println(response.getBody());
            System.out.println(response.getHeaders());
        } catch (IOException ex) {
            throw ex;
        }
    }
}
```

```go
package main

import (
	"fmt"
	"github.com/sendgrid/sendgrid-go"
	"os"
)

func main() {
	apiKey := os.Getenv("SENDGRID_API_KEY")
	host := "https://api.sendgrid.com"
	request := sendgrid.GetRequest(apiKey, "/v3/contactdb/lists/42/recipients", host)
	request.Method = "GET"
	response, err := sendgrid.API(request)
	if err != nil {
		fmt.Println(err.Error())
		os.Exit(1)
	} else {
		fmt.Println(response.StatusCode)
		fmt.Println(response.Body)
		fmt.Println(response.Headers)
	}
}
```

```php
<?php
// Uncomment the next line if you're using a dependency loader (such as Composer) (recommended)
// require 'vendor/autoload.php';

// Uncomment next line if you're not using a dependency loader (such as Composer)
// require_once '<PATH TO>/sendgrid-php.php';

$apiKey = getenv("SENDGRID_API_KEY");
$sg = new \SendGrid($apiKey);
$list_id = 42;

try {
    $response = $sg->client
        ->contactdb()
        ->lists()
        ->_($list_id)
        ->recipients()
        ->get();
    print $response->statusCode() . "\n";
    print_r($response->headers());
    print $response->body() . "\n";
} catch (Exception $ex) {
    echo "Caught exception: " . $ex->getMessage();
}
```

```ruby
require 'sendgrid-ruby'
include SendGrid

sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
list_id = 42

response = sg.client.contactdb.lists._(list_id).recipients.get()
puts response.status_code
puts response.headers
puts response.body
```

```bash
curl -X GET "https://api.sendgrid.com/v3/contactdb/lists/42/recipients" \
--header "Authorization: Bearer $SENDGRID_API_KEY"
```