# List contacts

> GET /contacts — list every contact on a sending domain.

`GET /contacts`

List all contacts on one of your **sending domains**, newest first. `?domain=` is required. Returns a list object whose `data` array holds the contacts.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | Yes | The sending domain whose contacts to list (one of your domains, e.g. `yourdomain.com`). |
| `segment_id` | string | No | Optional. Only return contacts that belong to this [segment](https://www.mailblastr.com/docs/segments/overview). |

**Node.js**

```js
import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.contacts.list({ domain: 'yourdomain.com' });
console.log({ data, error });
```

**Ruby**

```ruby
require "mailblastr"

Mailblastr.api_key = "mb_xxxxxxxxx"

Mailblastr::Contacts.list({
  "domain": "yourdomain.com"
})
```

**PHP**

```php
$mailblastr = Mailblastr::client('mb_xxxxxxxxx');

$mailblastr->contacts->list([
  'domain' => "yourdomain.com"
]);
```

**Python**

```python
import mailblastr

mailblastr.api_key = "mb_xxxxxxxxx"

mailblastr.Contacts.list({
  "domain": "yourdomain.com"
})
```

**Go**

```go
client := mailblastr.NewClient("mb_xxxxxxxxx")
contacts, err := client.Contacts.List(&mailblastr.ListContactsRequest{Domain: "yourdomain.com"})
```

**Rust**

```rust
let mb = Mailblastr::new("mb_xxxxxxxxx");
let _contacts = mb.contacts.list(ListContactsParams::for_domain("yourdomain.com")).await?;
```

**Java**

```java
Mailblastr mailblastr = new Mailblastr("mb_xxxxxxxxx");
mailblastr.contacts().list("yourdomain.com");
```

**.NET**

```csharp
IMailblastr mailblastr = MailblastrClient.Create("mb_xxxxxxxxx");
var resp = await mailblastr.ContactListAsync(new ContactListOptions { Domain = "yourdomain.com" });
```

**cURL**

```bash
curl -X GET 'https://api.mailblastr.com/contacts?domain=yourdomain.com' \
  -H 'Authorization: Bearer mb_xxxxxxxxx'
```

**CLI**

```bash
mailblastr contacts list \
  --domain yourdomain.com
```

**Response (200)**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact",
      "id": "479e3145-dd0e-4f64-bf48-1d4b6d4cd8f6",
      "email": "steve@example.com",
      "first_name": "Steve",
      "last_name": "Wozniak",
      "unsubscribed": false,
      "properties": {
        "company_name": "Acme Corp"
      },
      "created_at": "2026-06-23T17:30:11.000Z"
    }
  ]
}
```

Each contact includes `object: "contact"` and a `properties` map (merged with registered fallback values). A domain that is not yours returns `404 not_found`. See [Errors](https://www.mailblastr.com/docs/api/errors).

## Audience-scoped variant

The nested route `GET /audiences/:audience_id/contacts` still works and lists the contacts of one audience (no `domain` query needed):

**Node.js**

```js
import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.contacts.list({ audienceId: 'AUDIENCE_ID' });
console.log({ data, error });
```

**Ruby**

```ruby
require 'net/http'
require 'uri'

uri = URI('https://api.mailblastr.com/audiences/AUDIENCE_ID/contacts')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer mb_xxxxxxxxx'
res = http.request(req)
puts res.body
```

**PHP**

```php
<?php
$ch = curl_init('https://api.mailblastr.com/audiences/AUDIENCE_ID/contacts');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer mb_xxxxxxxxx',
    ],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```

**Python**

```python
import requests

res = requests.get(
    "https://api.mailblastr.com/audiences/AUDIENCE_ID/contacts",
    headers={"Authorization": "Bearer mb_xxxxxxxxx"},
)
print(res.json())
```

**Go**

```go
package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.mailblastr.com/audiences/AUDIENCE_ID/contacts", nil)
    req.Header.Set("Authorization", "Bearer mb_xxxxxxxxx")
    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    out, _ := io.ReadAll(res.Body)
    fmt.Println(string(out))
}
```

**Rust**

```rust
use reqwest::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let res = Client::new()
        .get("https://api.mailblastr.com/audiences/AUDIENCE_ID/contacts")
        .header("Authorization", "Bearer mb_xxxxxxxxx")
        .send()
        .await?;
    println!("{}", res.text().await?);
    Ok(())
}
```

**Java**

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mailblastr.com/audiences/AUDIENCE_ID/contacts"))
    .header("Authorization", "Bearer mb_xxxxxxxxx")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

**.NET**

```csharp
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.mailblastr.com/audiences/AUDIENCE_ID/contacts");
request.Headers.Add("Authorization", "Bearer mb_xxxxxxxxx");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

**cURL**

```bash
curl -X GET 'https://api.mailblastr.com/audiences/AUDIENCE_ID/contacts' \
  -H 'Authorization: Bearer mb_xxxxxxxxx'
```