Pagination & Filtering

Master list operations with pagination, filtering, sorting, and search to efficiently work with large datasets.

Overview

Most Cakemail CLI list commands support:

Pagination - Retrieve results in manageable chunks
Filtering - Narrow results based on criteria
Sorting - Order results by specific fields
Search - Find specific items by keyword

These features help you work efficiently with large lists of campaigns, contacts, templates, and other resources.

Pagination

What is Pagination?

Pagination splits large result sets into smaller "pages" of results. Instead of retrieving 10,000 campaigns at once, you retrieve 50 at a time.

Why Use Pagination?

Performance: Faster response times
Memory: Lower memory usage
Usability: Easier to read and process results
API limits: Respects rate limits

Pagination Options

`--limit` (or `-l`)

Specify how many results per page (default varies by resource, typically 50-100).

# Get 10 campaigns
cakemail campaigns list --limit 10

# Get 100 contacts
cakemail contacts list 123 --limit 100

# Get 25 templates
cakemail templates list --limit 25

`--page` (or `-p`)

Specify which page of results to retrieve (1-indexed).

# Get first page (default)
cakemail campaigns list --page 1

# Get second page
cakemail campaigns list --page 2

# Get third page with custom limit
cakemail campaigns list --limit 25 --page 3

Pagination Metadata

List responses include pagination information:

{
  "data": [...],
  "count": 25,        // Number of items in this response
  "total": 247,       // Total items available
  "page": 1,          // Current page
  "per_page": 25      // Items per page
}

Calculate total pages:

# total_pages = ceiling(total / per_page)
# 247 total / 25 per_page = 10 pages

Pagination Examples

Example 1: Browse Pages Interactively

# Page 1
cakemail -f table campaigns list --limit 20 --page 1

# Page 2
cakemail -f table campaigns list --limit 20 --page 2

# Page 3
cakemail -f table campaigns list --limit 20 --page 3

Example 2: Retrieve All Results (Scripting)

#!/bin/bash
# Get all campaigns across all pages

PAGE=1
LIMIT=100

while true; do
  RESPONSE=$(cakemail -f json campaigns list --limit $LIMIT --page $PAGE)

  # Extract data
  DATA=$(echo "$RESPONSE" | jq '.data')

  # Break if no more data
  if [ "$(echo "$DATA" | jq 'length')" -eq 0 ]; then
    break
  fi

  # Process data
  echo "$DATA" | jq -r '.[] | "\(.id) - \(.name)"'

  # Next page
  PAGE=$((PAGE + 1))
done

Example 3: Get Total Count

# Just get the count without retrieving all data
cakemail -f json campaigns list --limit 1 | jq '.total'

Filtering

What is Filtering?

Filtering allows you to retrieve only items that match specific criteria, like campaigns with status "delivered" or contacts subscribed after a certain date.

Filter Syntax

Filters use a simple query language:

field==value           # Equals
field!=value           # Not equals
field>value            # Greater than
field<value            # Less than
field>=value           # Greater than or equal
field<=value           # Less than or equal

Multiple filters are separated by ; (AND logic):

field1==value1;field2==value2

Filter Examples

Example 1: Filter Campaigns by Status

# Only delivered campaigns
cakemail campaigns list --filter "status==delivered"

# Only scheduled campaigns
cakemail campaigns list --filter "status==scheduled"

# Only draft campaigns
cakemail campaigns list --filter "status==draft"

Example 2: Filter Contacts by Status

# Only active contacts
cakemail contacts list 123 --filter "status==active"

# Only unsubscribed contacts
cakemail contacts list 123 --filter "status==unsubscribed"

Example 3: Filter by Name

# Campaigns with "Newsletter" in name
cakemail campaigns list --filter "name==Newsletter"

# Lists with specific name
cakemail lists list --filter "name==Subscribers"

Example 4: Multiple Filters (AND)

# Delivered campaigns named "Newsletter"
cakemail campaigns list --filter "status==delivered;name==Newsletter"

# Active confirmed senders
cakemail senders list --filter "confirmed==true"

Example 5: Filter by Date

# Campaigns created after a date
cakemail campaigns list --filter "created_on>=2024-01-01"

# Contacts subscribed before a date
cakemail contacts list 123 --filter "subscribed_on<2024-06-01"

Filterable Fields by Resource

Campaigns:

status - draft, scheduled, sending, delivered, suspended, cancelled
name - Campaign name
created_on - Creation date
scheduled_for - Scheduled date

Contacts:

status - active, unsubscribed, bounced
email - Email address
subscribed_on - Subscription date

Lists:

status - active, archived
name - List name
created_on - Creation date

Templates:

name - Template name
created_on - Creation date

Senders:

confirmed - true/false
email - Email address
name - Sender name

Sorting

What is Sorting?

Sorting allows you to order results by a specific field in ascending or descending order.

Sort Syntax

+field    # Ascending order
-field    # Descending order

Sort Examples

Example 1: Sort Campaigns

# Sort by name (A-Z)
cakemail campaigns list --sort "+name"

# Sort by name (Z-A)
cakemail campaigns list --sort "-name"

# Sort by creation date (oldest first)
cakemail campaigns list --sort "+created_on"

# Sort by creation date (newest first)
cakemail campaigns list --sort "-created_on"

# Sort by scheduled date (soonest first)
cakemail campaigns list --sort "+scheduled_for"

Example 2: Sort Contacts

# Sort by email (A-Z)
cakemail contacts list 123 --sort "+email"

# Sort by subscription date (newest first)
cakemail contacts list 123 --sort "-subscribed_on"

# Sort by status
cakemail contacts list 123 --sort "+status"

Example 3: Sort Lists

# Sort by name (A-Z)
cakemail lists list --sort "+name"

# Sort by creation date (newest first)
cakemail lists list --sort "-created_on"

Example 4: Sort Senders

# Sort by email (A-Z)
cakemail senders list --sort "+email"

# Sort by name
cakemail senders list --sort "+name"

# Sort by confirmation status
cakemail senders list --sort "-confirmed"

Sortable Fields by Resource

Campaigns:

name - Campaign name
created_on - Creation date
scheduled_for - Scheduled date
status - Status

Contacts:

email - Email address
subscribed_on - Subscription date
status - Status

Lists:

name - List name
created_on - Creation date

Templates:

name - Template name
created_on - Creation date

Senders:

name - Sender name
email - Email address
confirmed - Confirmation status

Search

What is Search?

Some list commands support keyword search using the --query (or -q) option. This searches across multiple fields.

Search Examples

Example 1: Search Contacts

# Search contacts by email or name
cakemail contacts list 123 --query "john"

# Will match:
# - john@example.com
# - John Doe
# - johnny@example.com

Example 2: Paginated Search

# Search with pagination
cakemail contacts list 123 --query "example.com" --limit 50 --page 1

Searchable Resources

Currently, these resources support --query:

Contacts - Searches email, first name, last name

Note: Most other resources use --filter for specific field matching instead of full-text search.

Combining Options