Skip to main content

List Campaigns

Retrieves a list of all email campaigns in your Lemlist account with pagination support for managing large campaign datasets.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs​

  • Client Id - (Optional) The client identifier returned from the Connect node. If not provided, you must provide Credentials instead.

Options​

  • Credentials - (Optional) The Lemlist API key credential. Provide this if you're not using the Connect/Disconnect pattern. If both Client Id and Credentials are provided, Credentials takes priority.
  • Offset - (Optional) Number of campaigns to skip for pagination. Default is 0. Use this to retrieve campaigns beyond the first page.
  • Limit - (Optional) Maximum number of campaigns to return per request. Default is 100. Valid range: 1-100.

Output​

  • Campaigns - An array of campaign objects containing detailed information about each email campaign, including campaign ID, name, status, statistics, and settings.

How It Works​

The List Campaigns node retrieves your email campaigns from Lemlist. When executed, the node:

  1. Validates authentication (either via Client ID or direct credentials)
  2. Constructs a GET request to the Lemlist /api/campaigns endpoint
  3. Applies pagination parameters (offset and limit) if specified
  4. Sends the authenticated request to the Lemlist API
  5. Processes the response and returns the campaigns array
  6. Outputs the campaign data as a structured array of objects

This node is essential for:

  • Monitoring active email campaigns
  • Analyzing campaign performance metrics
  • Automating campaign management workflows
  • Building campaign dashboards
  • Retrieving campaign IDs for lead management operations

Requirements​

  • A valid Lemlist account with at least one campaign
  • Either a Client ID from the Connect node OR API credentials
  • Appropriate API permissions to access campaign information

Error Handling​

The node will return specific errors in the following cases:

  • ErrInvalidArg:
    • Neither Client ID nor valid credentials were provided
    • Limit is set to 0 (must be between 1-100)
  • ErrInternal: Network errors or failed HTTP requests
  • HTTP Status Errors: If the API returns a non-2xx status code (e.g., 401 Unauthorized, 403 Forbidden)

Usage Examples​

Example 1: List All Campaigns (Basic)​

Retrieve first 100 campaigns:

1. Connect Node
   └─> Output: client_id = "abc123"

2. List Campaigns Node
   └─> Input: client_id = "abc123"
   └─> Options: (defaults - Limit: 100, Offset: 0)
   └─> Output: campaigns = [
         {
           "_id": "camp123",
           "name": "Product Launch 2024",
           "status": "active",
           "stats": {...}
         },
         {
           "_id": "camp456",
           "name": "Follow-up Sequence",
           "status": "paused",
           "stats": {...}
         }
       ]

3. Disconnect Node
   └─> Input: client_id = "abc123"

Example 2: Paginated Campaign Retrieval​

Get campaigns in batches:

Set: page_size = 50, current_offset = 0, all_campaigns = []

Loop (while has_more_campaigns):
  1. List Campaigns
     └─> Offset: current_offset
     └─> Limit: page_size
     └─> Output: campaigns_batch

  2. Append to all_campaigns
     └─> all_campaigns.push(...campaigns_batch)

  3. Update offset
     └─> current_offset = current_offset + page_size
     └─> has_more_campaigns = campaigns_batch.length == page_size

Example 3: Direct Credentials (Quick Lookup)​

Single API call without Connect:

List Campaigns Node
└─> Credentials: [Lemlist API Key]
└─> Limit: 25
└─> Output: campaigns (first 25 campaigns)

Practical Automation Scenarios​

Scenario 1: Active Campaign Monitor​

Monitor and report on active campaigns:

1. List Campaigns
   └─> Get all campaigns

2. Filter active campaigns
   └─> campaigns.filter(c => c.status === 'active')

3. For each active campaign:
   └─> Extract performance metrics
   └─> Calculate response rates
   └─> Identify underperforming campaigns

4. Generate report
   └─> Email dashboard to marketing team

Scenario 2: Automated Campaign Cleanup​

Pause inactive campaigns:

1. List Campaigns
   └─> Retrieve all campaigns

2. Identify stale campaigns
   └─> Filter campaigns with:
       - Last activity > 30 days ago
       - Response rate < 5%

3. For each stale campaign:
   └─> Update status to "paused"
   └─> Notify campaign owner
   └─> Log to audit database

Scenario 3: Campaign ID Extraction for Lead Management​

Get campaign IDs for bulk lead operations:

1. List Campaigns
   └─> Output: campaigns

2. Extract campaign IDs
   └─> campaign_ids = campaigns.map(c => c._id)

3. Read CSV of bounced emails
   └─> bounced_list = ["user1@example.com", ...]

4. For each campaign_id:
   └─> For each bounced_email:
       └─> Unsubscribe Lead from Campaign

Scenario 4: Multi-Account Campaign Aggregation​

Aggregate campaigns across multiple Lemlist accounts:

Set: all_accounts_campaigns = []

For each account in lemlist_accounts:
  1. List Campaigns
     └─> Using account credentials
     └─> Output: account_campaigns

  2. Add account identifier
     └─> campaigns.forEach(c => c.account_name = account.name)

  3. Append to master list
     └─> all_accounts_campaigns.push(...account_campaigns)

4. Create unified dashboard
   └─> Display all campaigns with filtering

Campaign Object Structure​

Each campaign in the output array typically includes:

{
  "_id": "camp_abc123xyz",
  "name": "Summer Sale 2024",
  "status": "active",
  "isDeleted": false,
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-20T14:30:00Z",
  "stats": {
    "contacted": 250,
    "replied": 45,
    "interested": 20,
    "notInterested": 15,
    "bounced": 5,
    "unsubscribed": 3
  },
  "schedule": {
    "timezone": "America/New_York",
    "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
    "startTime": "09:00",
    "endTime": "17:00"
  },
  "settings": {...}
}

Note: The exact structure may vary based on Lemlist API version and your account settings.

Pagination Strategy​

Understanding Pagination​

  • Default Limit: 100 campaigns per request
  • Offset: Number of campaigns to skip
  • Maximum Limit: 100 (enforced by Lemlist API)

Retrieving All Campaigns​

To get all campaigns when you have more than 100:

1. First request: Offset=0, Limit=100 → Returns campaigns 1-100
2. Second request: Offset=100, Limit=100 → Returns campaigns 101-200
3. Third request: Offset=200, Limit=100 → Returns campaigns 201-300
... continue until response length < limit

Example Pagination Logic​

let allCampaigns = [];
let offset = 0;
const limit = 100;
let hasMore = true;

while (hasMore) {
  // List Campaigns with current offset
  const batch = await listCampaigns({ offset, limit });

  allCampaigns = allCampaigns.concat(batch);

  // Check if there are more campaigns
  hasMore = batch.length === limit;
  offset += limit;
}

Usage Notes​

  • This is a read-only operation - it does not modify any campaigns
  • The response includes both active and paused campaigns by default
  • Deleted campaigns are not included in the results
  • Campaign statistics are included in real-time
  • No filtering options are available directly in this node - filter results after retrieval
  • For large numbers of campaigns, use pagination to avoid timeouts
  • The limit cannot exceed 100 (Lemlist API restriction)

Best Practices​

  • Use Pagination: For accounts with many campaigns, always implement pagination to ensure you retrieve all data
  • Cache Campaign Data: If you need to reference campaign information multiple times, cache the results
  • Filter After Retrieval: Apply your own filtering logic to the campaigns array based on status, dates, or metrics
  • Rate Limiting: Add delays between paginated requests to avoid hitting API rate limits
  • Error Recovery: Implement retry logic for network errors during pagination
  • Index by ID: Create a map of campaign IDs to campaign objects for quick lookups
  • Monitor Performance: Track which campaigns are performing well to optimize your outreach strategy

Common Errors and Solutions​

Error: "Limit cannot be empty"

  • Cause: The limit parameter was explicitly set to 0
  • Solution: Use a limit between 1-100, or leave it unset to use the default (100)

Error: "Response Status: 401 Unauthorized"

  • Cause: Invalid or expired API key
  • Solution: Verify your API key in Lemlist settings and update the credential

Error: "Either API Key credentials or Client ID must be provided"

  • Cause: Neither Client ID nor Credentials were provided
  • Solution: Provide either a Client ID from Connect node or direct API credentials

Empty Response Array

  • Cause: No campaigns exist in your account, or all campaigns are deleted
  • Solution: Create campaigns in Lemlist, or check that you're using the correct account credentials

Tips for Effective Use​

  1. Campaign Monitoring: Set up scheduled flows to monitor campaign performance daily
  2. Dashboard Integration: Use this node to populate campaign dashboards with live data
  3. Conditional Logic: Filter campaigns by status or metrics to trigger specific actions
  4. Lead Management: Extract campaign IDs to use with Unsubscribe/Remove Lead nodes
  5. Audit Trail: Log campaign changes over time to track modifications
  6. Performance Analysis: Calculate aggregate metrics across all campaigns for reporting
  7. Smart Pagination: Only paginate when necessary - most accounts have fewer than 100 campaigns

Performance Optimization​

  • Limit Results: If you only need a few campaigns, set a smaller limit (e.g., 10-20)
  • Implement Caching: Cache campaign lists for a few minutes to reduce API calls
  • Parallel Processing: When working with multiple campaigns, process them in parallel when possible
  • Selective Retrieval: If you only need specific campaigns, filter immediately after retrieval
  • Batch Operations: Group similar operations across campaigns to minimize node executions

Security Considerations​

  • Campaign data may contain sensitive business information
  • Restrict access to flows that retrieve campaign lists
  • Don't expose campaign statistics publicly without authorization
  • Use secure storage for any cached campaign data
  • Monitor API usage to detect unauthorized access
  • Be cautious when sharing campaign IDs as they can be used to manage leads