Email Lists

Manage email lists (also known as audiences) to organize your contacts into groups for targeted campaigns.

List All Email Lists

Get all email lists for your account.

GET /api/email-lists

Response

[
  {
    "id": "list_123",
    "name": "Newsletter Subscribers",
    "description": "Main newsletter audience",
    "contact_count": 1250,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-20T14:30:00Z"
  }
]

Get Email List Statistics

Get aggregate statistics for all your email lists.

GET /api/email-lists/stats

Response

{
  "total_lists": 5,
  "total_contacts": 3420,
  "total_subscribed": 3100,
  "total_unsubscribed": 320,
  "lists": [
    {
      "id": "list_123",
      "name": "Newsletter Subscribers",
      "contact_count": 1250,
      "subscribed_count": 1200,
      "unsubscribed_count": 50
    }
  ]
}

Get Specific Email List

Get details for a single email list.

GET /api/email-lists/:id

Response

{
  "id": "list_123",
  "name": "Newsletter Subscribers",
  "description": "Main newsletter audience",
  "contact_count": 1250,
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-20T14:30:00Z"
}

Get Contacts in List

Get all contacts in a specific email list (paginated).

GET /api/email-lists/:id/contacts?page=1&limit=50&search=john

Query Parameters

Response

{
  "contacts": [
    {
      "id": "contact_123",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "status": "subscribed",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1250,
    "pages": 25
  }
}

Get Segments for List

Get all segments associated with a specific email list.

GET /api/email-lists/:id/segments

Response

{
  "segments": [
    {
      "id": "segment_123",
      "name": "Engaged Users",
      "description": "Users who opened in last 30 days",
      "rules": [...],
      "member_count": 450,
      "email_list_id": "list_123"
    }
  ]
}

Get Available Contacts

Get contacts that are not yet in this list.

GET /api/email-lists/:id/available-contacts

Response

[
  {
    "id": "contact_456",
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Smith",
    "status": "subscribed"
  }
]

Create Email List

Create a new email list.

POST /api/email-lists

Request Body

{
  "name": "Product Updates",
  "description": "Subscribers interested in product news"
}

Response

{
  "id": "list_789",
  "name": "Product Updates",
  "description": "Subscribers interested in product news",
  "contact_count": 0,
  "created_at": "2024-01-22T09:00:00Z",
  "updated_at": "2024-01-22T09:00:00Z"
}

Validation

• name is required, max 255 characters
• description is optional
• List names must be unique per account

Update Email List

Update an existing email list.

PUT /api/email-lists/:id

Request Body

{
  "name": "Weekly Newsletter",
  "description": "Updated description"
}

Response

{
  "id": "list_123",
  "name": "Weekly Newsletter",
  "description": "Updated description",
  "contact_count": 1250,
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-22T11:30:00Z"
}

Delete Email List

Delete an email list. This does not delete the contacts themselves, only their association with this list.

DELETE /api/email-lists/:id

Response

{
  "success": true,
  "message": "Email list deleted successfully"
}

Add Contacts to List

Add one or more contacts to an email list.

POST /api/email-lists/:id/contacts

Request Body

{
  "contact_ids": ["contact_123", "contact_456", "contact_789"],
  "source": "manual"
}

Parameters

Response

{
  "success": true,
  "added": 3,
  "skipped": 0,
  "message": "3 contacts added to list"
}

Remove Contact from List

Remove a specific contact from an email list.

DELETE /api/email-lists/:id/contacts/:contactId

Response

{
  "success": true,
  "message": "Contact removed from list"
}

Code Examples

Create and Populate a List

// Create a new list
const createResponse = await fetch('https://api.postbeagle.com/api/email-lists', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Product Launch',
    description: 'Early access subscribers'
  })
});

const list = await createResponse.json();

// Add contacts to the list
await fetch(`https://api.postbeagle.com/api/email-lists/${list.id}/contacts`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    contact_ids: ['contact_1', 'contact_2', 'contact_3'],
    source: 'manual'
  })
});

Get List with Pagination

import requests

api_key = 'your_api_key'
list_id = 'list_123'
base_url = 'https://api.postbeagle.com/api'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

# Get first page of contacts
response = requests.get(
    f'{base_url}/email-lists/{list_id}/contacts',
    headers=headers,
    params={'page': 1, 'limit': 100}
)

data = response.json()
contacts = data['contacts']
total_pages = data['pagination']['pages']

# Get remaining pages
for page in range(2, total_pages + 1):
    response = requests.get(
        f'{base_url}/email-lists/{list_id}/contacts',
        headers=headers,
        params={'page': page, 'limit': 100}
    )
    contacts.extend(response.json()['contacts'])

Best Practices

1. Organization: Create lists based on how subscribers sign up or their interests
2. Naming: Use clear, descriptive names that indicate the list's purpose
3. Cleanup: Regularly remove inactive subscribers to maintain list health
4. Segmentation: Use segments to target subsets of lists without creating duplicates
5. Imports: When adding many contacts, use bulk operations rather than individual requests

Error Codes

Related Endpoints

• Contacts - Manage individual contacts
• Segments - Create dynamic subsets of lists
• Campaigns - Send campaigns to lists