Unsubscribe Lead From Campaign

Unsubscribes a lead from a specific Lemlist campaign. The lead will no longer receive emails from this campaign but can be re-added to the campaign later if needed.

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.
Campaign Id - The unique identifier of the campaign from which to unsubscribe the lead. You can obtain this from the List Campaigns node.
Email Address - The email address of the lead to unsubscribe from the campaign.

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.

How It Works

The Unsubscribe Lead From Campaign node removes a lead from an active campaign while preserving the lead's data. When executed, the node:

Validates authentication (either via Client ID or direct credentials)
Validates that both Campaign ID and Email Address are provided
Constructs a DELETE request to /api/campaigns/{campaignId}/leads/{email}
Sends the authenticated request to the Lemlist API
The lead is unsubscribed and will no longer receive emails from this campaign
Completes without returning any output (successful execution means the operation succeeded)

Key Difference from Remove Lead:

Unsubscribe: Lead is soft-deleted and can be re-added to the campaign later. The lead's history and data are preserved.
Remove: Lead is permanently deleted from the campaign with all associated data.

Requirements

A valid Lemlist account with at least one active campaign
Either a Client ID from the Connect node OR API credentials
Valid Campaign ID (can be retrieved using List Campaigns node)
Valid email address of a lead that exists in the specified campaign
Appropriate API permissions to modify campaign leads

Error Handling

The node will return specific errors in the following cases:

ErrInvalidArg:
- Neither Client ID nor valid credentials were provided
- Campaign ID is empty or missing
- Email Address is empty or missing
ErrInternal: Network errors or failed HTTP requests
HTTP Status Errors:
- 401 Unauthorized: Invalid API credentials
- 404 Not Found: Campaign or lead doesn't exist
- 403 Forbidden: Insufficient permissions
- 429 Too Many Requests: API rate limit exceeded

Usage Examples

Example 1: Unsubscribe Single Lead

Basic unsubscribe operation:

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

2. Unsubscribe Lead From Campaign
   └─> Input: client_id = "abc123"
   └─> Campaign Id: "camp_xyz789"
   └─> Email Address: "user@example.com"
   └─> Success: Lead unsubscribed

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

Example 2: Bulk Unsubscribe from CSV

Unsubscribe multiple leads from a campaign:

1. Connect to Lemlist
   └─> client_id = "abc123"

2. Read CSV file
   └─> unsubscribe_list = [
         {email: "user1@example.com", campaign: "camp_123"},
         {email: "user2@example.com", campaign: "camp_123"},
         {email: "user3@example.com", campaign: "camp_456"}
       ]

3. For each entry in unsubscribe_list:
   └─> Unsubscribe Lead From Campaign
       └─> Campaign Id: entry.campaign
       └─> Email Address: entry.email

4. Log results
   └─> "Unsubscribed X leads successfully"

5. Disconnect from Lemlist

Example 3: Conditional Unsubscribe Based on Response

Unsubscribe leads who opted out:

1. Connect to Lemlist
   └─> client_id = "abc123"

2. Read email responses from inbox
   └─> Filter for "unsubscribe" or "opt-out" keywords

3. Extract email addresses
   └─> opt_out_emails = [...]

4. List Campaigns
   └─> Get all active campaign IDs

5. For each campaign:
   └─> For each opt_out_email:
       └─> Unsubscribe Lead From Campaign
           └─> Campaign Id: campaign._id
           └─> Email Address: opt_out_email

6. Disconnect from Lemlist

Practical Automation Scenarios

Handle unsubscribe requests automatically:

Trigger: New row in "Unsubscribe Requests" spreadsheet

1. Get unsubscribe request details
   └─> email = row.email_address

2. List all campaigns
   └─> campaign_ids = campaigns.map(c => c._id)

3. For each campaign_id:
   Try:
     └─> Unsubscribe Lead From Campaign
         └─> Campaign Id: campaign_id
         └─> Email Address: email
   Catch:
     └─> Log: "Lead not in campaign (expected)"

4. Update spreadsheet
   └─> Mark request as "Processed"

5. Send confirmation email
   └─> "You've been unsubscribed from all campaigns"

Scenario 2: Bounce Management

Automatically unsubscribe bounced emails:

Trigger: Daily at 9 AM

1. Connect to email provider
   └─> Get bounce notifications from last 24 hours

2. Extract bounced email addresses
   └─> bounced_emails = [...]

3. Connect to Lemlist
   └─> client_id = "abc123"

4. List Campaigns
   └─> active_campaigns = campaigns.filter(c => c.status === 'active')

5. For each bounced_email:
   └─> For each active campaign:
       └─> Unsubscribe Lead From Campaign
           └─> Email: bounced_email
           └─> Campaign: campaign._id

6. Log to monitoring system
   └─> "Unsubscribed X bounced emails"

7. Disconnect from Lemlist

Scenario 3: Engagement-Based Cleanup

Unsubscribe unengaged leads after 30 days:

Trigger: Weekly on Sunday

1. Connect to Lemlist

2. List Campaigns
   └─> Get all campaigns

3. For each campaign:
   a. Get campaign leads with statistics

   b. Identify unengaged leads:
      └─> Filter leads where:
          - Days in campaign > 30
          - Opens = 0
          - Clicks = 0
          - No replies

   c. For each unengaged_lead:
      └─> Unsubscribe Lead From Campaign
          └─> Email: unengaged_lead.email
          └─> Campaign: campaign._id

      └─> Add to "Re-engagement List" for future campaigns

4. Generate report
   └─> Summary of cleanup actions

5. Disconnect from Lemlist

Scenario 4: Cross-Platform Integration

Sync unsubscribes with CRM:

Trigger: Contact marked "Do Not Email" in CRM

1. Get contact details from CRM
   └─> email = contact.email

2. Connect to Lemlist
   └─> client_id = "abc123"

3. List Campaigns
   └─> Get all campaigns

4. For each campaign:
   └─> Unsubscribe Lead From Campaign
       └─> Campaign Id: campaign._id
       └─> Email Address: email

5. Log to CRM activity feed
   └─> "Unsubscribed from all Lemlist campaigns"

6. Disconnect from Lemlist

Unsubscribe vs Remove: When to Use Which

Use Unsubscribe When:

Temporary Opt-Out: Lead asked to be removed but might be re-engaged later
Compliance: GDPR or CAN-SPAM unsubscribe requests (preserves history)
Bounce Management: Soft bounces that might be temporary
Campaign Switch: Moving lead from one campaign to another
Re-engagement Strategy: Planning to add lead back after a cooling-off period

Use Remove When:

Hard Bounces: Invalid email addresses that will never work
Data Cleanup: Permanently removing test/invalid data
Complete Deletion: Lead should never be contacted again
Privacy Requests: "Right to be forgotten" requests requiring complete data removal
Duplicate Cleanup: Removing duplicate entries permanently

Usage Notes

This operation does not return any data - success is indicated by no error
The lead can be re-added to the campaign in the future if needed
Unsubscribing a lead does not affect their presence in other campaigns
The lead's history and statistics in the campaign are preserved
If the lead doesn't exist in the campaign, the API may return a 404 error
Some Lemlist plans may have limits on API operations - monitor your usage

Best Practices

Batch Operations: When unsubscribing multiple leads, add delays between requests to avoid rate limiting
Error Handling: Use try-catch blocks when unsubscribing from multiple campaigns - a lead may not exist in all campaigns
Logging: Always log unsubscribe operations for audit and compliance purposes
Verification: Before bulk unsubscribes, verify email addresses are valid
Notification: Send confirmation emails to users who requested unsubscription
Database Sync: Keep your CRM/database in sync with Lemlist unsubscribe status
Re-engagement: Maintain a separate list of unsubscribed leads for potential re-engagement campaigns

Common Errors and Solutions

Error: "Campaign ID cannot be empty"

Cause: No Campaign ID was provided
Solution: Ensure you're passing a valid Campaign ID from List Campaigns or your records

Error: "Email Address cannot be empty"

Cause: No email address was provided
Solution: Verify the email address variable is populated correctly

Error: "Response Status: 404 Not Found"

Cause: The campaign doesn't exist, or the lead is not in the campaign
Solution: Verify the campaign ID is correct and the lead exists in that campaign. This may be expected when bulk processing.

Error: "Response Status: 429 Too Many Requests"

Cause: API rate limit exceeded
Solution: Add delays between requests (e.g., 1-2 seconds), or batch operations in smaller groups

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

Tips for Effective Use

Idempotent Operations: Unsubscribe operations are idempotent - running them multiple times has the same effect
Compliance Tracking: Create a database table to track all unsubscribe events with timestamps
Multi-Campaign Cleanup: When a user unsubscribes, consider unsubscribing them from ALL campaigns
Validation First: Check if a lead exists in a campaign before attempting to unsubscribe
Rate Limiting: Implement delays (500ms-1s) between consecutive unsubscribe operations
Error Recovery: For bulk operations, continue processing even if some unsubscribes fail
Audit Trail: Log every unsubscribe with timestamp, campaign ID, and reason

Performance Optimization

Parallel Processing: For unsubscribing from multiple campaigns, process campaigns in parallel when possible
Batch Delays: Group unsubscribe operations and add delays between batches
Async Operations: Use asynchronous flows for bulk unsubscribe operations
Queue Management: For large volumes, use a queue system to process unsubscribes gradually
Caching Campaign IDs: Cache campaign IDs to avoid repeated List Campaigns calls

Compliance and Legal Considerations

Response Time: Process unsubscribe requests within 24-48 hours for compliance
Confirmation: Send confirmation emails after unsubscribing users
Documentation: Maintain records of all unsubscribe requests and actions
Global Unsubscribe: Consider implementing a global unsubscribe that removes leads from all campaigns
Re-subscription: Implement a clear re-subscription process if users change their minds
Privacy Laws: Ensure your unsubscribe process complies with GDPR, CAN-SPAM, and other regulations

Common Properties​

Inputs​

Options​

How It Works​

Requirements​

Error Handling​

Usage Examples​

Example 1: Unsubscribe Single Lead​

Example 2: Bulk Unsubscribe from CSV​

Example 3: Conditional Unsubscribe Based on Response​

Practical Automation Scenarios​

Scenario 1: GDPR Compliance - Automated Unsubscribe​

Scenario 2: Bounce Management​

Scenario 3: Engagement-Based Cleanup​

Scenario 4: Cross-Platform Integration​

Unsubscribe vs Remove: When to Use Which​

Use Unsubscribe When:​

Use Remove When:​

Usage Notes​

Best Practices​

Common Errors and Solutions​

Tips for Effective Use​

Performance Optimization​

Compliance and Legal Considerations​