Remove Lead From Campaign

Permanently removes a lead from a specific Lemlist campaign, deleting all associated data and history. Unlike unsubscribe, this action is irreversible and the lead cannot be re-added with their previous history.

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 permanently remove the lead. You can obtain this from the List Campaigns node.
Email Address - The email address of the lead to permanently remove 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 Remove Lead From Campaign node permanently deletes a lead from a campaign along with all their 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}?action=remove
Sends the authenticated request to the Lemlist API
The lead is permanently removed with all history, statistics, and activity data
Completes without returning any output (successful execution means the operation succeeded)

Critical Difference from Unsubscribe:

Remove (this node): Permanent deletion of lead and all associated data. Lead history is lost forever.
Unsubscribe: Soft deletion that preserves lead data. Lead can be re-added to campaign later.

warning

This is a destructive operation that cannot be undone. Once a lead is removed, all their campaign history and statistics are permanently deleted.

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: Remove Single Invalid Lead

Basic remove operation:

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

2. Remove Lead From Campaign
   └─> Input: client_id = "abc123"
   └─> Campaign Id: "camp_xyz789"
   └─> Email Address: "invalid@bounced.com"
   └─> Success: Lead permanently removed

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

Example 2: Bulk Remove Hard Bounces

Remove all hard bounced emails from a campaign:

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

2. Connect to email service
   └─> Get hard bounce report from last 7 days

3. Extract bounced email addresses
   └─> hard_bounces = [
         "bounce1@invalid.com",
         "bounce2@nonexistent.net",
         "bounce3@failed.org"
       ]

4. Get campaign ID
   └─> campaign_id = "camp_123"

5. For each bounced_email in hard_bounces:
   Try:
     └─> Remove Lead From Campaign
         └─> Campaign Id: campaign_id
         └─> Email Address: bounced_email
     └─> Log: "Removed {bounced_email} from campaign"
   Catch:
     └─> Log: "Failed to remove {bounced_email}: {error}"

6. Generate cleanup report
   └─> "Removed X hard bounces from campaign"

7. Disconnect from Lemlist

Example 3: Test Data Cleanup

Remove all test leads from campaigns:

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

2. Define test email patterns
   └─> test_patterns = ["@test.com", "@example.com", "test+"]

3. List Campaigns
   └─> Get all campaigns

4. For each campaign:
   a. Get campaign leads (via API or export)

   b. Filter test leads:
      └─> test_leads = leads.filter(lead =>
            test_patterns.some(pattern => lead.email.includes(pattern))
          )

   c. For each test_lead:
      └─> Remove Lead From Campaign
          └─> Campaign Id: campaign._id
          └─> Email Address: test_lead.email

5. Log cleanup results
   └─> "Removed X test leads across Y campaigns"

6. Disconnect from Lemlist

Practical Automation Scenarios

Scenario 1: Hard Bounce Cleanup Automation

Daily cleanup of invalid email addresses:

Trigger: Daily at 2 AM

1. Connect to email service (e.g., SendGrid, Mailgun)
   └─> Get bounce report
   └─> Filter for hard bounces (permanent failures)

2. Extract email addresses
   └─> hard_bounced_emails = [...]

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

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

5. For each campaign:
   └─> For each hard_bounced_email:
       Try:
         └─> Remove Lead From Campaign
             └─> Email: hard_bounced_email
             └─> Campaign: campaign._id
       Catch:
         └─> Continue (lead may not exist in all campaigns)

6. Update database
   └─> Mark emails as "permanently_bounced"

7. Generate daily report
   └─> Email to admin with cleanup statistics

8. Disconnect from Lemlist

Complete data deletion upon user request:

Trigger: User submits "Delete My Data" request

1. Get user details
   └─> email = request.email_address

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

3. List Campaigns
   └─> Get ALL campaigns (active, paused, completed)

4. For each campaign:
   └─> Remove Lead From Campaign
       └─> Campaign Id: campaign._id
       └─> Email Address: email
       └─> Result: Permanent deletion

5. Log compliance action
   └─> Timestamp, email, campaigns affected

6. Update compliance database
   └─> Mark request as "completed"

7. Send confirmation to user
   └─> "Your data has been permanently deleted"

8. Disconnect from Lemlist

Scenario 3: Duplicate Email Cleanup

Remove duplicate entries from campaigns:

1. Connect to Lemlist

2. List Campaigns
   └─> Get all campaigns

3. For each campaign:
   a. Export campaign leads

   b. Identify duplicates:
      └─> Group by email address
      └─> Find entries with count > 1

   c. For each duplicate group:
      └─> Keep most recent entry
      └─> For older entries:
          └─> Remove Lead From Campaign
              └─> Email: duplicate.email
              └─> Note: Removes specific instance

4. Generate deduplication report

5. Disconnect from Lemlist

Scenario 4: Competitor Email Cleanup

Remove competitor emails from campaigns:

Trigger: Manual or Scheduled

1. Define competitor domains
   └─> competitor_domains = [
         "competitor1.com",
         "competitor2.com",
         "competitor3.net"
       ]

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

3. List Campaigns
   └─> Get active sales campaigns

4. For each campaign:
   a. Get campaign leads

   b. Filter competitor emails:
      └─> competitors = leads.filter(lead =>
            competitor_domains.some(domain =>
              lead.email.endsWith('@' + domain)
            )
          )

   c. For each competitor_lead:
      └─> Remove Lead From Campaign
          └─> Campaign Id: campaign._id
          └─> Email: competitor_lead.email

      └─> Add to blocklist

5. Log removed competitors

6. Disconnect from Lemlist

Remove vs Unsubscribe: Decision Guide

Use Remove (Permanent Deletion) For:

Hard Bounces
- Invalid email addresses
- Non-existent domains
- Permanent delivery failures
Data Cleanup
- Test/dummy data removal
- Duplicate entries
- Invalid or corrupted records
Privacy Compliance
- GDPR "Right to be Forgotten" requests
- Complete data deletion requirements
- Legal compliance mandates
Invalid Data
- Malformed email addresses
- Spam trap addresses
- Role-based emails you want to exclude
Business Rules
- Competitor email addresses
- Blacklisted domains
- Permanently excluded contacts

Use Unsubscribe (Soft Delete) For:

User Requests
- Opt-out requests from recipients
- "Unsubscribe" link clicks
- Temporary opt-outs
Engagement Management
- Low engagement cleanup (might re-engage later)
- Campaign switches
- Cooling-off periods
Soft Bounces
- Temporary delivery issues
- Mailbox full errors
- Temporary server issues
Re-engagement Strategies
- Planning to add leads back later
- Seasonal campaigns
- Maintaining lead history

tip

General Rule: If there's any chance you'll want to re-engage the lead or review their history, use Unsubscribe. If the data is invalid or must be permanently deleted, use Remove.

Usage Notes

This operation is irreversible - removed leads cannot be recovered with their history
The operation does not return any data - success is indicated by no error
Removing a lead from one campaign does not affect their presence in other campaigns
The lead can be added back to the campaign as a completely new lead, but previous history is lost
If the lead doesn't exist in the campaign, the API will return a 404 error
Use with caution - prefer Unsubscribe for most use cases unless permanent deletion is required

Best Practices

Double-Check Before Removing: Always verify you're removing the correct lead from the correct campaign
Backup First: Export campaign data before bulk remove operations
Use Unsubscribe by Default: Only use Remove when you're certain permanent deletion is needed
Logging: Maintain detailed logs of all remove operations for audit purposes
Rate Limiting: Add delays between requests when removing multiple leads
Error Handling: Use try-catch blocks - leads may not exist in all campaigns
Confirmation: For user-initiated deletions, implement a confirmation step
Compliance: Ensure removal operations comply with data protection regulations
Testing: Test remove operations on a test campaign before production use

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. When bulk processing, this may be expected for some leads.

Error: "Response Status: 429 Too Many Requests"

Cause: API rate limit exceeded
Solution: Implement delays between requests (1-2 seconds), or process in smaller batches

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

Audit Trail: Create a database table logging all remove operations with timestamps and reasons
Batch Processing: Group remove operations in batches with delays to avoid rate limits
Verification: Before bulk removes, export and verify the list of emails to be removed
Dry Run: Test your remove logic on a test campaign before running on production
Confirmation: For manual operations, add a confirmation dialog before removal
Recovery Plan: Maintain backups of campaign data in case you need to restore leads
Monitoring: Track removal metrics to identify patterns (e.g., specific domains with high bounce rates)
Automation Safety: Add safeguards to prevent accidental mass deletion

Performance and Safety

Performance Tips:

Add 500ms-1s delays between consecutive remove operations
Process in batches of 50-100 leads at a time
Use parallel processing for different campaigns, sequential for same campaign
Monitor API rate limits and implement exponential backoff on errors

Safety Measures:

Whitelist Important Emails: Never remove VIP or team email addresses
Limit Scope: When possible, limit bulk removes to specific campaigns
Preview First: Generate a preview list before executing bulk removes
Rollback Plan: Maintain campaign exports for potential data recovery
Access Control: Restrict who can execute remove operations in production

Compliance Considerations

Data Retention: Document your data retention and deletion policies
User Consent: Ensure you have legal grounds for data deletion
Proof of Deletion: Maintain logs proving data was deleted upon request
Response Time: Process deletion requests within regulatory timeframes (e.g., 30 days for GDPR)
Scope: Ensure deletion covers all systems (not just Lemlist)
Confirmation: Provide confirmation to users when their data is deleted
Legal Review: Have your data deletion process reviewed by legal counsel

Troubleshooting

Lead Not Found Errors

These are common in bulk operations and may not indicate a problem:

The lead was already removed
The lead was never in that specific campaign
The email address doesn't match exactly (case-sensitive)

Rate Limiting Issues

If you're hitting rate limits:

Increase delays between operations
Process in smaller batches
Implement retry logic with exponential backoff
Contact Lemlist support about API limits for your plan

Data Recovery

If you accidentally removed leads:

Check your campaign backups/exports
Re-add leads as new entries (history will be lost)
Contact Lemlist support immediately (they may be able to help within a short window)
Review and improve your safety measures to prevent recurrence

Common Properties​

Inputs​

Options​

How It Works​

Requirements​

Error Handling​

Usage Examples​

Example 1: Remove Single Invalid Lead​

Example 2: Bulk Remove Hard Bounces​

Example 3: Test Data Cleanup​

Practical Automation Scenarios​

Scenario 1: Hard Bounce Cleanup Automation​

Scenario 2: GDPR "Right to be Forgotten" Request​

Scenario 3: Duplicate Email Cleanup​

Scenario 4: Competitor Email Cleanup​

Remove vs Unsubscribe: Decision Guide​

Use Remove (Permanent Deletion) For:​

Use Unsubscribe (Soft Delete) For:​

Usage Notes​

Best Practices​

Common Errors and Solutions​

Tips for Effective Use​

Performance and Safety​

Performance Tips:​

Safety Measures:​

Compliance Considerations​

Troubleshooting​

Lead Not Found Errors​

Rate Limiting Issues​

Data Recovery​