Add Subscriber to Lists

Add Subscriber to Lists — Pabbly Email Marketing API | Pabbly

API Docs

vv2

Overview

The Pabbly Email Marketing API lets you programmatically manage subscribers, subscriber lists, campaigns, delivery servers, and custom fields. Integrate your Pabbly Email Marketing account with your own applications, automate list management, and trigger campaign sends from anywhere over standard HTTPS.

Example request

curl https://emails.pabbly.com/api/v2/subscribers \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"

Base URL

All endpoints are relative to the base URL below. Combine the base URL with the path on each endpoint to get the full request URL.

Base URL

https://emails.pabbly.com/api/v2

Requests and responses

The API accepts JSON request bodies and returns JSON responses. Send Content-Type: application/json on every request that has a body. Path parameters are interpolated into the URL; query parameters and body fields are documented per endpoint.

Success response

{
  "success": true,
  "data": { /* … */ }
}

Errors

When a request fails, the response status code reflects the error category and the body carries a human-readable message. Treat any non-2xx status as a failure.

Status	Meaning
200, 201	Success
400	Bad request — missing or malformed parameters
401	Unauthorized — missing or invalid API credentials
404	Not found — the resource does not exist
429	Too many requests
5xx	Server error — retry with backoff

Error response

{
  "success": false,
  "error": "A human-readable explanation"
}

Authentication

The Pabbly Email Marketing API uses Bearer Token authentication. Every request must include your API key in the Authorization header.

Auth header

Authorization: Bearer {{YOUR_API_KEY}}

Getting your credentials

Sign in to your Pabbly account and navigate to Settings → API & Webhooks. Copy the API key shown there — it is the only credential you need for API requests. Treat it like a password.

Making authenticated requests

Send your API key in the Authorization header on every request. The examples on the right show how to call /subscribers with proper authentication.

cURL

curl https://emails.pabbly.com/api/v2/subscribers \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"

Node.js

const response = await fetch(
  'https://emails.pabbly.com/api/v2/subscribers',
  { headers: { 'Authorization': 'Bearer {{YOUR_API_KEY}}' } }
);
const data = await response.json();

Python

import requests

response = requests.get(
    'https://emails.pabbly.com/api/v2/subscribers',
    headers={'Authorization': 'Bearer {{YOUR_API_KEY}}'},
)
data = response.json()

Keep your credentials secret

Your credentials grant full access to your account. Never embed them in browser-side code, commit them to version control, or share them in support tickets. If you suspect a credential has been exposed, rotate it from the dashboard (Settings → API & Webhooks) and update any servers that use it.

Create Subscriber

POST/subscribers

Creates a new subscriber or updates an existing subscriber (upsert operation). If the email already exists, the subscriber will be updated; otherwise, a new subscriber will be created. You can assign tags, segments, lists, and custom fields during creation

Body parameters

emailstringrequired

Valid email address of the subscriber.

e.g. [email protected]

firstNamestringoptional

First name of the subscriber.

e.g. John

lastNamestringoptional

Last name of the subscriber.

e.g. Doe

mobilestringoptional

Phone number with country code (e.g., +1234567890).

e.g. +1234567890

leadScoreintegeroptional

Lead score value between 0-100.

e.g. 85

statusstringoptional

Subscription status. Valid values: subscribed, unsubscribed, bounced, complaint. Default: subscribed.

e.g. subscribed

countrystringoptional

Country name of the subscriber.

e.g. USA

citystringoptional

City name of the subscriber.

e.g. New York

tagsarrayoptional

Array of tag names to assign to the subscriber. Tags must exist in Settings.

e.g. ["temp"]

customFieldsobjectoptional

Custom field key-value pairs. Custom fields must exist in Settings.

e.g. {"company":"Acme Corporation","position":"Software Engineer"}

listsarrayoptional

Array of list names to assign to the subscriber.

e.g. ["Temp List"]

dateOfBirthstringoptional

Date of birth in YYYY-MM-DD format.

sourcestringoptional

Source of the subscriber (e.g., "api", "form", "csv").

POST/subscribers

curl -X POST https://emails.pabbly.com/api/v2/subscribers \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "mobile": "+1234567890",
    "leadScore": 85,
    "status": "subscribed",
    "country": "USA",
    "city": "New York",
    "tags": [
      "temp"
    ],
    "customFields": {
      "company": "Acme Corporation",
      "position": "Software Engineer"
    },
    "lists": [
      "Temp List"
    ]
  }'

Create Subscriber

Response

{
  "success": true,
  "status": "success",
  "message": "Subscriber created successfully",
  "data": {
    "userId": "682db2da6ef7e93a3eceb126",
    "businessId": "695b6aabf58d3822ac852e28",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "mobile": "+1234567890",
    "leadScore": 85,
    "dateOfBirth": null,
    "status": "subscribed",
    "country": "USA",
    "city": "New York",
    "tags": [
      "temp"
    ],
    "source": "manual",
    "segments": [],
    "customFields": {},
    "activity": [],
    "automationWorkflows": [],
    "lists": [
      "Temp List"
    ],
    "totalSent": 0,
    "totalDelivered": 0,
    "totalOpens": 0,
    "totalUniqueOpens": 0,
    "totalUniqueClick": 0,
    "totalClicks": 0,
    "deleteAfter": null,
    "suppressionDetail": {
      "createdAt": "2026-01-14T06:00:57.540Z",
      "updatedAt": "2026-01-14T06:00:57.540Z"
    },
    "_id": "6967311955b46d5df8e4a7c3",
    "campaignDetails": [],
    "createdAt": "2026-01-14T06:00:57.540Z",
    "updatedAt": "2026-01-14T06:00:57.540Z"
  }
}

Get All Subscribers

GET

/subscribers?page={page}&limit={limit}&search={search}&status={status}&tags={tags}&segments={segments}&lists={lists}&leadScoreMin={leadScoreMin}&leadScoreMax={leadScoreMax}

Retrieves a paginated list of subscribers with optional filtering and search capabilities. Supports filtering by status, tags, segments, lists, and lead score range. Also supports searching by email, first name, or last name. Query Parameters:

Query parameters

pageintegeroptional

Page number for pagination. Default: 1.

e.g. 1

limitintegeroptional

Number of items per page. Default: 10. Maximum: 100.

e.g. 20

searchstringoptional

Search term to filter by email, firstName, or lastName.

statusstringoptional

Filter by subscription status. Valid values: subscribed, unsubscribed, bounced, complaint.

tagsstringoptional

Filter by tag names. Can be comma-separated string or array.

segmentsstringoptional

Filter by segment names. Can be comma-separated string or array.

listsstringoptional

Filter by list names. Can be comma-separated string or array.

leadScoreMinstringoptional

Minimum lead score for filtering.

leadScoreMaxstringoptional

Maximum lead score for filtering.

GET

/subscribers?page={page}&limit={limit}&search={search}&status={status}&tags={tags}&segments={segments}&lists={lists}&leadScoreMin={leadScoreMin}&leadScoreMax={leadScoreMax}

curl https://emails.pabbly.com/api/v2/subscribers?page={{page}}&limit={{limit}}&search={{search}}&status={{status}}&tags={{tags}}&segments={{segments}}&lists={{lists}}&leadScoreMin={{leadScoreMin}}&leadScoreMax={{leadScoreMax}} \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"

Get All Subscribers

Response

{
  "success": true,
  "status": "success",
  "message": "Subscribers retrieved successfully",
  "data": {
    "subscribers": [
      {
        "_id": "69525f392011e7f242b57684",
        "userId": "682db2da6ef7e93a3eceb126",
        "businessId": "69398c24e90b87748e209d9b",
        "email": "[email protected]",
        "firstName": "John",
        "lastName": "Doe Updated",
        "mobile": "+1234567890",
        "leadScore": 90,
        "dateOfBirth": null,
        "status": "subscribed",
        "country": "USA",
        "city": "New York",
        "tags": [
          "VIP",
          "Premium",
          "New Tag"
        ],
        "source": "manual",
        "segments": [
          "Temp Customer"
        ],
        "customFields": {
          "company": "Updated Company Name",
          "position": "Senior Software Engineer"
        },
        "activity": [],
        "automationWorkflows": [],
        "lists": [
          "Temp List"
        ],
        "totalSent": 0,
        "totalDelivered": 0,
        "totalOpens": 0,
        "totalUniqueOpens": 0,
        "totalUniqueClick": 0,
        "totalClicks": 0,
        "deleteAfter": null,
        "suppressionDetail": {
          "createdAt": "2025-12-29T11:00:09.547Z",
          "updatedAt": "2025-12-29T11:00:09.547Z"
        },
        "campaignDetails": [],
        "createdAt": "2025-12-29T11:00:09.547Z",
        "updatedAt": "2025-12-29T11:00:39.970Z"
      }
    ],
    "suppressionList": [],
    "pagination": {
      "currentPage": 1,
      "itemsPerPage": 20,
      "totalItems": 1,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPrevPage": false
    }
  }
}

Get Subscriber Statistics

GET/subscribers/stats

Retrieves subscriber statistics for your business, including total subscriber count and status-wise breakdown (subscribed, unsubscribed, bounced, complaint).

GET/subscribers/stats

curl https://emails.pabbly.com/api/v2/subscribers/stats \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"

Get Subscriber Statistics

Response

{
  "success": true,
  "status": "success",
  "message": "Subscribers record retrieved successfully",
  "data": {
    "totalSubscribersInBusiness": 1,
    "totalSubscribersAcrossAllLists": 1,
    "listWiseCounts": [
      {
        "_id": "1022247",
        "listName": "Default List",
        "count": 0,
        "totalSubscribers": 0,
        "unsubscribedCount": 0,
        "engagedCount": 0
      },
      {
        "_id": "1024200",
        "listName": "Segment_10 number",
        "count": 0,
        "totalSubscribers": 0,
        "unsubscribedCount": 0,
        "engagedCount": 0
      },
      {
        "_id": "693a5a165ed8605a12f04d10",
        "listName": "Temp List",
        "count": 1,
        "totalSubscribers": 1,
        "unsubscribedCount": 0,
        "engagedCount": 0
      }
    ],
    "leadScoreAnalytics": {
      "averageLeadScore": 90,
      "hotLeads": 1,
      "coldLeads": 0
    },
    "leadScoreConfig": {
      "emailOpen": {
        "value": 5,
        "status": "active"
      },
      "emailClick": {
        "value": 10,
        "status": "active"
      },
      "emailBounce": {
        "value": -20,
        "status": "active"
      },
      "unsubscribe": {
        "value": -50,
        "status": "active"
      },
      "createdAt": "2025-12-16T20:32:02.930Z",
      "updatedAt": "2025-12-16T20:32:02.930Z"
    },
    "statusAnalytics": {
      "subscribed": 1,
      "unsubscribed": 0,
      "bounced": 0,
      "spam": 0
    },
    "engagedSubscribers": 0,
    "isListSpecific": false,
    "selectedListName": "All Subscribers"
  }
}

Get Subscriber by ID

GET/subscribers/{subscriber ID}

Retrieves complete details of a specific subscriber by their unique ID. Returns all subscriber information including custom fields, tags, segments, lists, and timestamps.

GET/subscribers/{subscriber ID}

curl https://emails.pabbly.com/api/v2/subscribers/{subscriber ID} \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"

Get Subscriber by ID

Response

{
  "success": true,
  "status": "success",
  "message": "Subscriber retrieved successfully",
  "data": {
    "suppressionDetail": {
      "createdAt": "2025-12-26T10:52:24.301Z",
      "updatedAt": "2025-12-26T10:52:24.301Z"
    },
    "_id": "694e68e83dd13469d1326278",
    "userId": "682db2da6ef7e93a3eceb126",
    "businessId": "69398c24e90b87748e209d9b",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "mobile": "+1234567890",
    "leadScore": 85,
    "dateOfBirth": null,
    "status": "subscribed",
    "country": "USA",
    "city": "New York",
    "tags": [
      "VIP",
      "Premium",
      "New Tag",
      "temp"
    ],
    "source": "manual",
    "segments": [
      "Temp Customer"
    ],
    "customFields": {
      "company": "Acme Corporation",
      "position": "Software Engineer"
    },
    "activity": [],
    "automationWorkflows": [],
    "lists": [
      "Temp List"
    ],
    "totalSent": 0,
    "totalDelivered": 0,
    "totalOpens": 0,
    "totalUniqueOpens": 0,
    "totalUniqueClick": 0,
    "totalClicks": 0,
    "deleteAfter": null,
    "campaignDetails": [],
    "createdAt": "2025-12-26T10:52:24.301Z",
    "updatedAt": "2025-12-27T07:43:17.294Z"
  }
}

Update Subscriber by ID

PUT/subscribers/{ subscriber Id}

Updates an existing subscriber's information by their unique ID or email address. The API automatically detects whether you're using a subscriber ID or email address. All provided fields will be updated; omitted fields remain unchanged.

Body parameters

firstNamestringoptional

Update subscriber's first name.

e.g. John

lastNamestringoptional

Update subscriber's last name.

e.g. Doe Updated

leadScoreintegeroptional

Update lead score value (0-100).

e.g. 90

statusstringoptional

Update subscription status. Valid values: subscribed, unsubscribed, bounced, complaint.

e.g. subscribed

tagsToAddarrayoptional

Add tags to existing subscriber tags. Tags will be merged with existing tags (duplicates are automatically removed). Tags must exist in Settings. This field is ignored if tags field is also provided.

e.g. ["hot lead","Premium","New Tag"]

tagsToRemovearrayoptional

Remove specific tags from subscriber. Tags specified in this array will be removed from existing tags. This field is ignored if tags field is also provided.

e.g. ["cold lead"]

customFieldsobjectoptional

Update custom fields. Custom fields must exist in Settings.

e.g. {"company":"Updated Company Name","position":"Senior Software Engineer"}

mobilestringoptional

Update subscriber's phone number.

countrystringoptional

Update subscriber's country.

citystringoptional

Update subscriber's city.

tagsstringoptional

Update tags. Note: This replaces all existing tags. Tags must exist in Settings.

listsstringoptional

Update lists. Note: This replaces all existing lists.

PUT/subscribers/{ subscriber Id}

curl -X PUT https://emails.pabbly.com/api/v2/subscribers/{ subscriber Id} \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe Updated",
    "leadScore": 90,
    "status": "subscribed",
    "tagsToAdd": [
      "hot lead",
      "Premium",
      "New Tag"
    ],
    "tagsToRemove": [
      "cold lead"
    ],
    "customFields": {
      "company": "Updated Company Name",
      "position": "Senior Software Engineer"
    }
  }'

Update Subscriber by ID

Response

{
  "success": true,
  "status": "success",
  "message": "Subscriber updated successfully",
  "data": {
    "suppressionDetail": {
      "createdAt": "2026-01-06T06:19:07.546Z",
      "updatedAt": "2026-01-06T07:15:45.730Z",
      "reason": "bounced",
      "type": "bounced"
    },
    "_id": "695ca95b9a8ed4e65738d1c5",
    "userId": "682db2da6ef7e93a3eceb126",
    "businessId": "695b6aabf58d3822ac852e28",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe Updated",
    "mobile": "",
    "leadScore": 90,
    "dateOfBirth": null,
    "status": "subscribed",
    "country": "Not Specified",
    "city": "Not Specified",
    "tags": [
      "hot lead",
      "Premium",
      "New Tag"
    ],
    "source": "manual",
    "segments": [],
    "customFields": {
      "company": "Updated Company Name",
      "position": "Senior Software Engineer"
    },
    "activity": [],
    "automationWorkflows": [],
    "lists": [
      "Pabbly Email Marketing",
      "cvbcbbc"
    ],
    "totalSent": 2,
    "totalDelivered": 0,
    "totalOpens": 0,
    "totalUniqueOpens": 0,
    "totalUniqueClick": 0,
    "totalClicks": 0,
    "deleteAfter": null,
    "campaignDetails": [
      {
        "_id": "69672de955b46d5df8e456e7",
        "campaignId": "695ca9729a8ed4e65738d2d9",
        "campaignName": "gfgf"
      },
      {
        "_id": "69672de955b46d5df8e456e8",
        "campaignId": "695caafb9a8ed4e6573906ac",
        "campaignName": "pp"
      },
      {
        "_id": "69672de955b46d5df8e456e9",
        "campaignId": "695cb3d29a8ed4e6573a0430",
        "campaignName": "tr"
      },
      {
        "_id": "69672de955b46d5df8e456ea",
        "campaignId": "695cb6579a8ed4e6573a05fd",
        "campaignName": "d"
      }
    ],
    "createdAt": "2026-01-06T06:19:07.546Z",
    "updatedAt": "2026-01-14T05:47:21.327Z",
    "isSuppressed": true
  }
}

Delete Subscriber

DELETE/subscribers

Deletes one or more subscribers from your account. Supports bulk deletion by providing multiple subscriber IDs in the request body. Warning: Deleted subscribers cannot be recovered.

Body parameters

idsarrayrequired

Array of subscriber IDs to delete. Must contain at least one ID.

e.g. ["694e68e83dd13469d1326278"]

DELETE/subscribers

curl -X DELETE https://emails.pabbly.com/api/v2/subscribers \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"

Delete Subscriber

Response

{
  "success": true,
  "status": "success",
  "message": " subscriber deleted successfully",
  "data": {
    "shouldRefreshStats": true,
    "deletedCount": 1
  }
}

Update Subscriber by Email

PUT/subscribers/{{email}}

Updates an existing subscriber's information using their email address. Allows updating any subscriber field including tags, segments, lists, custom fields, lead score, and status. All provided fields will be updated; omitted fields will remain unchanged. The email address must be a valid, properly formatted email. URL Parameters:

Path parameters

emailstringrequired

Body parameters

firstNamestringoptional

e.g. John

lastNamestringoptional

e.g. Doe Updated

leadScoreintegeroptional

e.g. 90

statusstringoptional

e.g. subscribed

tagsToAddarrayoptional

e.g. ["hot lead","Premium","New Tag"]

tagsToRemovearrayoptional

e.g. ["cold lead"]

customFieldsobjectoptional

e.g. {"company":"Updated Company Name","position":"Senior Software Engineer"}

PUT/subscribers/{{email}}

curl -X PUT https://emails.pabbly.com/api/v2/subscribers/{{email}} \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe Updated",
    "leadScore": 90,
    "status": "subscribed",
    "tagsToAdd": [
      "hot lead",
      "Premium",
      "New Tag"
    ],
    "tagsToRemove": [
      "cold lead"
    ],
    "customFields": {
      "company": "Updated Company Name",
      "position": "Senior Software Engineer"
    }
  }'

Update Subscriber by Email

Response

{
  "success": true,
  "status": "success",
  "message": "Subscriber updated successfully",
  "data": {
    "suppressionDetail": {
      "createdAt": "2026-01-06T06:19:07.546Z",
      "updatedAt": "2026-01-06T07:15:45.730Z",
      "reason": "bounced",
      "type": "bounced"
    },
    "_id": "695ca95b9a8ed4e65738d1c5",
    "userId": "682db2da6ef7e93a3eceb126",
    "businessId": "695b6aabf58d3822ac852e28",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe Updated",
    "mobile": "",
    "leadScore": 90,
    "dateOfBirth": null,
    "status": "subscribed",
    "country": "Not Specified",
    "city": "Not Specified",
    "tags": [
      "hot lead",
      "Premium",
      "New Tag"
    ],
    "source": "manual",
    "segments": [],
    "customFields": {
      "company": "Updated Company Name",
      "position": "Senior Software Engineer"
    },
    "activity": [],
    "automationWorkflows": [],
    "lists": [
      "Pabbly Email Marketing",
      "cvbcbbc"
    ],
    "totalSent": 2,
    "totalDelivered": 0,
    "totalOpens": 0,
    "totalUniqueOpens": 0,
    "totalUniqueClick": 0,
    "totalClicks": 0,
    "deleteAfter": null,
    "campaignDetails": [
      {
        "_id": "69672bdf55b46d5df8e4284c",
        "campaignId": "695ca9729a8ed4e65738d2d9",
        "campaignName": "gfgf"
      },
      {
        "_id": "69672bdf55b46d5df8e4284d",
        "campaignId": "695caafb9a8ed4e6573906ac",
        "campaignName": "pp"
      },
      {
        "_id": "69672bdf55b46d5df8e4284e",
        "campaignId": "695cb3d29a8ed4e6573a0430",
        "campaignName": "tr"
      },
      {
        "_id": "69672bdf55b46d5df8e4284f",
        "campaignId": "695cb6579a8ed4e6573a05fd",
        "campaignName": "d"
      }
    ],
    "createdAt": "2026-01-06T06:19:07.546Z",
    "updatedAt": "2026-01-14T05:38:39.423Z",
    "isSuppressed": true
  }
}

Get Subscriber by Email

GET/subscribers/{{email}}

Retrieves complete details of a specific subscriber by their Email ID. Returns all subscriber information including custom fields, tags, segments, lists, and timestamps.

Path parameters

emailstringrequired

GET/subscribers/{{email}}

curl https://emails.pabbly.com/api/v2/subscribers/{{email}} \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"

Get Subscriber by Email

Response

{
  "success": true,
  "status": "success",
  "message": "Subscriber retrieved successfully",
  "data": {
    "suppressionDetail": {
      "createdAt": "2025-12-29T11:00:09.547Z",
      "updatedAt": "2025-12-29T11:00:09.547Z"
    },
    "_id": "69525f392011e7f242b57684",
    "userId": "682db2da6ef7e93a3eceb126",
    "businessId": "69398c24e90b87748e209d9b",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "mobile": "+1234567890",
    "leadScore": 85,
    "dateOfBirth": null,
    "status": "subscribed",
    "country": "USA",
    "city": "New York",
    "tags": [
      "VIP",
      "Premium",
      "New Tag",
      "temp"
    ],
    "source": "manual",
    "segments": [
      "Temp Customer"
    ],
    "customFields": {
      "company": "Acme Corporation",
      "position": "Software Engineer"
    },
    "activity": [],
    "automationWorkflows": [],
    "lists": [
      "Temp List"
    ],
    "totalSent": 0,
    "totalDelivered": 0,
    "totalOpens": 0,
    "totalUniqueOpens": 0,
    "totalUniqueClick": 0,
    "totalClicks": 0,
    "deleteAfter": null,
    "campaignDetails": [],
    "createdAt": "2025-12-29T11:00:09.547Z",
    "updatedAt": "2025-12-29T11:00:39.970Z"
  }
}

Get All Custom Fields

GET/custom-fields

Prerequites: You need a valid API token generated from your Pabbly Email Marketing account. Retrieves all custom fields defined for a specific business. Returns custom field names and personalization tags. Custom fields are sorted alphabetically by name. Use this endpoint to get valid custom field names before creating or updating subscribers.

GET/custom-fields

curl https://emails.pabbly.com/api/v2/custom-fields \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"

Get All Custom Fields

Response

{
  "success": true,
  "status": "success",
  "message": "Custom fields retrieved successfully",
  "data": {
    "businessId": "695b6aabf58d3822ac852e28",
    "customFields": [
      {
        "name": "NewLead",
        "personalizationTag": "{newlead}"
      }
    ],
    "total": 1
  }
}

Create Campaign

POST/campaigns

Only HTML builder type is supported. The campaign is automatically set to "live" status and "API / Workflow Campaign" type. You can paste HTML content directly to create the campaign.EndFragment Body Fields

Body parameters

campaignDetailsobjectoptional

e.g. {"campaignName":"Welcome Newsletddter","senderName":"John Doe","subject":"Welcome to our newsletter","preheaderText":"Check out our latest updates"}

builderTypestringoptional

e.g. HTML

contentstringoptional

e.g. <!DOCTYPE html><html><head><meta charset='UTF-8'><title>Welcome</title></head><body style='font-family: Arial, sans-serif; padding: 20px; background-color: #f4f4f4;'><div style='max-width: 600px; margin: 0 auto; background-color: #ffffff; padding: 30px; border-radius: 8px;'><h1 style='color: #333; margin-bottom: 20px;'>Welcome to Our Newsletter!</h1><p style='color: #666; line-height: 1.6;'>Thank you for subscribing. We're excited to share amazing content with you.</p><a href='#' style='display: inline-block; margin-top: 20px; padding: 12px 24px; background-color: #007bff; color: #ffffff; text-decoration: none; border-radius: 4px;'>Get Started</a></div></body></html>

POST/campaigns

curl -X POST https://emails.pabbly.com/api/v2/campaigns \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignDetails": {
      "campaignName": "Welcome Newsletddter",
      "senderName": "John Doe",
      "subject": "Welcome to our newsletter",
      "preheaderText": "Check out our latest updates"
    },
    "builderType": "HTML",
    "content": "<!DOCTYPE html><html><head><meta charset='UTF-8'><title>Welcome</title></head><body style='font-family: Arial, sans-serif; padding: 20px; background-color: #f4f4f4;'><div style='max-width: 600px; margin: 0 auto; background-color: #ffffff; padding: 30px; border-radius: 8px;'><h1 style='color: #333; margin-bottom: 20px;'>Welcome to Our Newsletter!</h1><p style='color: #666; line-height: 1.6;'>Thank you for subscribing. We're excited to share amazing content with you.</p><a href='#' style='display: inline-block; margin-top: 20px; padding: 12px 24px; background-color: #007bff; color: #ffffff; text-decoration: none; border-radius: 4px;'>Get Started</a></div></body></html>"
  }'

Create Campaign

Response

{
  "success": true,
  "status": "success",
  "message": "Campaign created successfully via public API.",
  "data": {
    "campaignDetails": {
      "campaignType": "API / Workflow Campaign",
      "campaignName": "Welcome Newsletddter",
      "senderName": "John Doe",
      "subject": "Welcome to our newsletter",
      "preheaderText": "Check out our latest updates"
    },
    "sendDetails": {
      "deliveryServerRouting": false,
      "deliveryServerRoutingConfig": []
    },
    "recipientDetails": {
      "includedList": [],
      "excludedList": [],
      "sentToIndividuals": [],
      "autoFollow": false
    },
    "totalStats": {
      "sent": 0,
      "delivered": 0,
      "failed": 0,
      "queued": 0,
      "opened": 0,
      "uniqueOpens": 0,
      "clicked": 0,
      "unsubscribed": 0,
      "bounced": 0,
      "softBounced": 0,
      "hardBounced": 0
    },
    "linksStats": {
      "clicks": 0
    },
    "batchProcessing": {
      "currentListIndex": 0,
      "currentBatchSkip": 0,
      "batchSize": 10000,
      "isInitialized": false,
      "processedSubscribers": 0,
      "allSubscribersQueued": false,
      "totalUniqueEmails": 0,
      "completionRetryCount": 0,
      "validationMismatch": false,
      "forceCompleted": false
    },
    "_id": "695264982011e7f242b9cd9c",
    "userId": "682db2da6ef7e93a3eceb126",
    "businessId": "69398c24e90b87748e209d9b",
    "campaignFolder": null,
    "status": "live",
    "templateId": "695264982011e7f242b9cd9e",
    "totalSubscribers": 0,
    "isDeleted": false,
    "deletedAt": null,
    "permanentDeleteAt": null,
    "countryStats": [],
    "deviceStats": [],
    "osStats": [],
    "createdAt": "2025-12-29T11:23:04.838Z",
    "updatedAt": "2025-12-29T11:23:04.841Z",
    "__v": 0
  }
}

Get All Campaigns

GET/campaigns?page={page}&limit={limit}&campaignType={campaignType}

Retrieves a paginated list of campaigns for your business. Supports filtering by campaign type (Regular, API / Workflow Campaign, or All). Returns campaigns with template information and pagination metadata.Filter Options: "all" (default): Returns all campaigns regardless of type - includes both Regular campaigns and API / Workflow Campaigns mixed together. Use this when you want to see all your campaigns without any type-based filtering. "Regular": Returns only Regular type campaigns. These are traditional email campaigns created through the dashboard interface using Drag-&-Drop or Rich-Text builders. Regular campaigns are manually created and managed through the UI, and they can have different statuses like draft, scheduled, or live. "API / Workflow Campaign": Returns only API / Workflow Campaign type campaigns. These are campaigns created programmatically via API or integrated with workflows. They typically use HTML builder type, are automatically set to "live" status, and are designed for programmatic use and workflow integrations. Use this filter when you want to manage only API-created campaigns separately from Regular campaigns. Pagination: Default page size is 10 campaigns per page Maximum limit is 100 campaigns per page (automatically capped if exceeded) Page numbers start from 1 Response includes pagination metadata: totalCount, totalPages, hasNextPage, hasPrevPage Response Structure: Each campaign in the response includes complete campaign details (campaignName, senderName, subject, preheaderText), status, associated template information (name, htmlContent, builderType), and timestamps (createdAt, updatedAt). The response also includes pagination object with current page, limit, total count, total pages, and navigation flags. Query Parameters:

Query parameters

pageintegeroptional

e.g. 1

limitintegeroptional

e.g. 10

campaignTypestringoptional

e.g. regular

GET/campaigns?page={page}&limit={limit}&campaignType={campaignType}

curl https://emails.pabbly.com/api/v2/campaigns?page={{page}}&limit={{limit}}&campaignType={{campaignType}} \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"

Get All Campaigns

Response

{
  "success": true,
  "status": "success",
  "message": "Campaigns retrieved successfully",
  "data": {
    "campaigns": [
      {
        "_id": "694eddfb5b445a55127ce174",
        "campaignDetails": {
          "campaignType": "Regular",
          "campaignName": "ff",
          "senderName": "fwef",
          "subject": "ef",
          "preheaderText": "dbfff"
        },
        "status": "draft",
        "templateId": {
          "_id": "694eddfb5b445a55127ce172",
          "name": "sdds Copy",
          "builderType": "HTML",
          "htmlContent": "<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"UTF-8\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n    <title>Email Template</title>\n    <style>\n        .email-container {\n            max-width: 600px;\n            margin: 0 auto;\n            font-family: Arial, sans-serif;\n            background-color: #ffffff;\n            color: #333333;\n        }\n        .header {\n            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);\n            color: white;\n            padding: 30px;\n            text-align: center;\n        }\n        .content {\n            padding: 30px;\n            line-height: 1.6;\n            background-color: #ffffff;\n            color: #333333;\n        }\n        .cta-button {\n            display: inline-block;\n            background-color: #0D68E9;\n            color: white;\n            padding: 15px 30px;\n            text-decoration: none;\n            border-radius: 5px;\n            margin: 20px 0;\n        }\n        .footer {\n            background-color: #f5f5f5;\n            padding: 20px;\n            text-align: center;\n            font-size: 12px;\n            color: #666;\n        }\n        \n        /* Dark mode support */\n        @media (prefers-color-scheme: dark) {\n            .email-container {\n                background-color: #2d2d2d;\n                color: #ffffff;\n            }\n            .content {\n                background-color: #2d2d2d;\n                color: #ffffff;\n            }\n            .footer {\n                background-color: #1a1a1a;\n                color: #cccccc;\n            }\n        }\n    </style>\n</head>\n<body>\n    <div class=\"email-container\">\n        <div class=\"header\">\n            <h1>Welcome to Our Newsletter!</h1>\n            <p>Stay updated with our latest news and offers</p>\n        </div>\n        \n        <div class=\"content\">\n            <h2>Hello there!</h2>\n            <p>Thank you for subscribing to our newsletter. We're excited to share amazing content with you.</p>\n            \n            <a href=\"#\" class=\"cta-button\">Get Started</a>\n            \n            <h3>What you can expect:</h3>\n            <ul>\n                <li>Weekly updates</li>\n                <li>Exclusive offers</li>\n                <li>Industry insights</li>\n                <li>Product announcements</li>\n            </ul>\n        </div>\n        \n        <div class=\"footer\" style=\"background-color: #f5f5f5; padding: 20px; font-size: 12px; color: #666; text-align: center;\">\n          <div style=\"text-align: center;\">\n            <p style=\"margin: 0; display: inline-block;\">This email was sent to {email}</p>\n            <span style=\"margin: 0 5px;\">|</span>\n            <div style=\"display: inline-block;\">\n              <a href=\"#unsubscribe\">Unsubscribe</a>\n              <span>|</span>\n              <a href=\"#view-in-browser\">View in Browser</a>   \n            </div>\n          </div>\n          <p style=\"text-align: center; margin-top: 10px;\">\n            You are receiving this email because you have signed up on our website or subscribed to our email list.\n          </p>\n          <div style=\"text-align: center; margin-top: 10px;\">\n            <img src=\"https://assets-emails.pabbly.com/assets/email-builder/send-with-pabbly-light.png\" alt=\"Google Logo\" width=\"150px\" height=\"20px\"/>\n          </div>\n        </div>\n    </div>\n</body>\n</html>"
        },
        "createdAt": "2025-12-26T19:11:55.131Z",
        "updatedAt": "2025-12-26T19:11:55.131Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "totalCount": 1,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPrevPage": false
    }
  }
}

Get Campaign by ID

GET/campaigns/{Campaign ID}

Retrieves complete details of a specific campaign by its unique ID. Returns campaign information including template details, campaign details, status, and timestamps. Only returns campaigns belonging to your authenticated business. URL Parameters:

GET/campaigns/{Campaign ID}

curl https://emails.pabbly.com/api/v2/campaigns/{Campaign ID} \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"

Get Campaign by ID

Response

{
  "success": true,
  "status": "success",
  "message": "Campaign fetched successfully",
  "data": {
    "_id": "694eddfb5b445a55127ce174",
    "userId": "682db2da6ef7e93a3eceb126",
    "businessId": "69398c24e90b87748e209d9b",
    "campaignDetails": {
      "campaignType": "Regular",
      "campaignName": "ff",
      "senderName": "fwef",
      "subject": "ef",
      "preheaderText": "dbfff"
    },
    "campaignFolder": "Home",
    "status": "draft",
    "templateId": {
      "_id": "694eddfb5b445a55127ce172",
      "name": "sdds Copy",
      "builderType": "HTML",
      "htmlContent": "<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"UTF-8\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n    <title>Email Template</title>\n    <style>\n        .email-container {\n            max-width: 600px;\n            margin: 0 auto;\n            font-family: Arial, sans-serif;\n            background-color: #ffffff;\n            color: #333333;\n        }\n        .header {\n            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);\n            color: white;\n            padding: 30px;\n            text-align: center;\n        }\n        .content {\n            padding: 30px;\n            line-height: 1.6;\n            background-color: #ffffff;\n            color: #333333;\n        }\n        .cta-button {\n            display: inline-block;\n            background-color: #0D68E9;\n            color: white;\n            padding: 15px 30px;\n            text-decoration: none;\n            border-radius: 5px;\n            margin: 20px 0;\n        }\n        .footer {\n            background-color: #f5f5f5;\n            padding: 20px;\n            text-align: center;\n            font-size: 12px;\n            color: #666;\n        }\n        \n        /* Dark mode support */\n        @media (prefers-color-scheme: dark) {\n            .email-container {\n                background-color: #2d2d2d;\n                color: #ffffff;\n            }\n            .content {\n                background-color: #2d2d2d;\n                color: #ffffff;\n            }\n            .footer {\n                background-color: #1a1a1a;\n                color: #cccccc;\n            }\n        }\n    </style>\n</head>\n<body>\n    <div class=\"email-container\">\n        <div class=\"header\">\n            <h1>Welcome to Our Newsletter!</h1>\n            <p>Stay updated with our latest news and offers</p>\n        </div>\n        \n        <div class=\"content\">\n            <h2>Hello there!</h2>\n            <p>Thank you for subscribing to our newsletter. We're excited to share amazing content with you.</p>\n            \n            <a href=\"#\" class=\"cta-button\">Get Started</a>\n            \n            <h3>What you can expect:</h3>\n            <ul>\n                <li>Weekly updates</li>\n                <li>Exclusive offers</li>\n                <li>Industry insights</li>\n                <li>Product announcements</li>\n            </ul>\n        </div>\n        \n        <div class=\"footer\" style=\"background-color: #f5f5f5; padding: 20px; font-size: 12px; color: #666; text-align: center;\">\n          <div style=\"text-align: center;\">\n            <p style=\"margin: 0; display: inline-block;\">This email was sent to {email}</p>\n            <span style=\"margin: 0 5px;\">|</span>\n            <div style=\"display: inline-block;\">\n              <a href=\"#unsubscribe\">Unsubscribe</a>\n              <span>|</span>\n              <a href=\"#view-in-browser\">View in Browser</a>   \n            </div>\n          </div>\n          <p style=\"text-align: center; margin-top: 10px;\">\n            You are receiving this email because you have signed up on our website or subscribed to our email list.\n          </p>\n          <div style=\"text-align: center; margin-top: 10px;\">\n            <img src=\"https://assets-emails.pabbly.com/assets/email-builder/send-with-pabbly-light.png\" alt=\"Google Logo\" width=\"150px\" height=\"20px\"/>\n          </div>\n        </div>\n    </div>\n</body>\n</html>"
    },
    "sendDetails": {
      "deliveryServerRouting": false,
      "deliveryServerRoutingConfig": []
    },
    "recipientDetails": {
      "sentToIndividuals": [],
      "autoFollow": false,
      "includedList": [],
      "excludedList": []
    },
    "totalStats": {
      "sent": 0,
      "delivered": 0,
      "failed": 0,
      "queued": 0,
      "opened": 0,
      "uniqueOpens": 0,
      "clicked": 0,
      "unsubscribed": 0,
      "bounced": 0,
      "softBounced": 0,
      "hardBounced": 0
    },
    "linksStats": {
      "clicks": 0
    },
    "totalSubscribers": 0,
    "batchProcessing": {
      "currentListIndex": 0,
      "currentBatchSkip": 0,
      "batchSize": 10000,
      "isInitialized": false,
      "processedSubscribers": 0,
      "allSubscribersQueued": false,
      "totalUniqueEmails": 0,
      "completionRetryCount": 0,
      "validationMismatch": false,
      "forceCompleted": false
    },
    "isDeleted": false,
    "deletedAt": null,
    "permanentDeleteAt": null,
    "countryStats": [],
    "deviceStats": [],
    "osStats": [],
    "createdAt": "2025-12-26T19:11:55.131Z",
    "updatedAt": "2025-12-26T19:11:55.131Z",
    "__v": 0
  }
}

Send Campaign to Individual

POST/campaigns/send-to-individual

The token must be included in the Authorization header as a Bearer token. The campaign must exist and belong to your business. Sends a campaign to one or more individual email addresses using the campaign's template. This endpoint allows you to send personalized emails to specific recipients without requiring them to be in a subscriber list. The campaign template content is used, but you can optionally override the subject line. Emails are queued for sending asynchronously. Only campaigns with status "live" can be sent. All specified email addresses must be in a valid format.

Body parameters

campaignIdstringoptional

e.g. 507f1f77bcf86cd799439011

emailsarrayoptional

e.g. ["[email protected]","[email protected]"]

deliveryServerIdstringoptional

e.g. server123

senderEmailstringoptional

e.g. [email protected]

fromNamestringoptional

e.g. John Doe

subjectstringoptional

e.g. Custom Subject Line

POST/campaigns/send-to-individual

curl -X POST https://emails.pabbly.com/api/v2/campaigns/send-to-individual \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "507f1f77bcf86cd799439011",
    "emails": [
      "[email protected]",
      "[email protected]"
    ],
    "deliveryServerId": "server123",
    "senderEmail": "[email protected]",
    "fromName": "John Doe",
    "subject": "Custom Subject Line"
  }'

Campaign Send to Individual

Response

{
  "success": true,
  "status": "success",
  "message": "All emails queued successfully",
  "data": {
    "campaignId": "693a741cb1dd9aa1a3c770eb",
    "campaignName": "Sarah Mcgowan",
    "totalEmails": 1,
    "queued": 1,
    "message": "1 email(s) queued for sending"
  }
}

Send Campaign to Lists

POST/campaigns/send-to-list

The token must be included in the Authorization header as a Bearer token. The campaign must exist, belong to your business, and have a status of "live". The specified lists/segments must exist in your account. Sends a campaign to all active subscribers in one or more subscriber lists or segments using the campaign's template. Supports advanced filtering with included lists (required) and excluded lists (optional). Subscribers must have status "subscribed", not be deleted, and not be suppressed. The endpoint processes emails asynchronously in the background and returns immediately. Emails are queued in batches to handle large lists efficiently. Supports both regular subscriber lists and segments. Duplicate email addresses across multiple lists are automatically deduplicated.

Body parameters

campaignIdstringoptional

e.g. 507f1f77bcf86cd799439011

includedListarrayoptional

e.g. [{"listName":"All Subscribers"},{"listName":"VIP Customers"}]

excludedListarrayoptional

e.g. [{"listName":"Unsubscribed"}]

deliveryServerIdstringoptional

e.g. server123

senderEmailstringoptional

e.g. [email protected]

fromNamestringoptional

e.g. John Doe

subjectstringoptional

e.g. Special Offer for You

POST/campaigns/send-to-list

curl -X POST https://emails.pabbly.com/api/v2/campaigns/send-to-list \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "507f1f77bcf86cd799439011",
    "includedList": [
      {
        "listName": "All Subscribers"
      },
      {
        "listName": "VIP Customers"
      }
    ],
    "excludedList": [
      {
        "listName": "Unsubscribed"
      }
    ],
    "deliveryServerId": "server123",
    "senderEmail": "[email protected]",
    "fromName": "John Doe",
    "subject": "Special Offer for You"
  }'

Campaign Send to Lists

Response

{
  "success": true,
  "status": "success",
  "message": "Email sending initiated successfully",
  "data": {
    "campaignId": "693a741cb1dd9aa1a3c770eb",
    "campaignName": "Sarah Mcgowan",
    "includedList": [
      "pem-dev"
    ],
    "excludedList": [],
    "totalSubscribers": 6,
    "message": "6 email(s) are being queued in the background. Processing may take a few minutes.",
    "note": "Emails are being processed asynchronously. Check campaign status for delivery updates."
  }
}

Get All Subscriber Lists

GET/lists

Retrieves all subscriber lists associated with your account. Returns list IDs, names, subscriber counts, and metadata for each list. Lists are sorted alphabetically by name.

GET/lists

curl https://emails.pabbly.com/api/v2/lists \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"

Get All Subscriber Lists

Response

{
  "success": true,
  "status": "success",
  "message": "Subscriber lists retrieved successfully",
  "data": {
    "subscriberLists": [
      {
        "id": "695ca9409a8ed4e65738c3b7",
        "name": "New User",
        "count": 1,
        "counts": {
          "totalSubscribers": 1,
          "unsubscribedCount": 0,
          "engagedCount": 0,
          "lastUpdated": "2026-01-06T09:50:35.504Z"
        },
        "createdAt": "2026-01-06T06:18:40.487Z",
        "updatedAt": "2026-01-06T06:18:40.487Z"
      },
      {
        "id": "695cdac06fa49c6ac63dca11",
        "name": "Pabbly Email Marketing ",
        "count": 0,
        "counts": {
          "totalSubscribers": 0,
          "unsubscribedCount": 0,
          "engagedCount": 0,
          "lastUpdated": "2026-01-06T09:50:35.511Z"
        },
        "createdAt": "2026-01-06T09:49:52.925Z",
        "updatedAt": "2026-01-06T09:49:52.925Z"
      }
    ],
    "total": 2
  }
}

Get Single Subscriber List by ID

GET/lists/{{listId}}

Retrieves a single subscriber list by its unique ID or name. The API automatically detects whether you're using a list ID or list name (via query parameter). Returns detailed information including subscriber counts and metadata. URL Parameters:

Path parameters

listIdstringrequired

GET/lists/{{listId}}

curl https://emails.pabbly.com/api/v2/lists/{{listId}} \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"

Get Single Subscriber List by ID

Response

{
  "success": true,
  "status": "success",
  "message": "List retrieved successfully",
  "data": {
    "list": {
      "id": "695ca9409a8ed4e65738c3b7",
      "name": "New User",
      "count": 1,
      "counts": {
        "totalSubscribers": 1,
        "unsubscribedCount": 0,
        "engagedCount": 0,
        "lastUpdated": "2026-01-06T09:50:35.504Z"
      },
      "createdAt": "2026-01-06T06:18:40.487Z",
      "updatedAt": "2026-01-06T06:18:40.487Z"
    }
  }
}

POST/lists/add-subscriber

Adds an existing subscriber to one or more subscriber lists. You can identify the subscriber by email address or subscriber ID. The subscriber will be added to all valid lists provided. If the subscriber is already in a list, that list will be skipped. List counts are automatically updated.

Body parameters

emailstringoptional

Email address of the subscriber (required if subscriberId is not provided)

e.g. [email protected]

listIdsarrayrequired

Array of list IDs to add the subscriber to (must contain at least one list ID)

e.g. ["695ca9409a8ed4e65738c3b7"]

subscriberIdstringoptional

ID of the subscriber (required if email is not provided)

POST/lists/add-subscriber

curl -X POST https://emails.pabbly.com/api/v2/lists/add-subscriber \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "listIds": [
      "695ca9409a8ed4e65738c3b7"
    ]
  }'

Add Subscriber to Lists

Response

{
  "success": true,
  "status": "success",
  "message": "Subscriber added to lists successfully",
  "data": {
    "subscriberId": "695ca95b9a8ed4e65738d1c5",
    "email": "[email protected]",
    "addedLists": [
      "New User"
    ],
    "currentLists": [
      "Pabbly Email Marketing",
      "New User"
    ]
  }
}

Remove Subscriber from Lists

POST/lists/remove-subscriber

Removes an existing subscriber from one or more subscriber lists. You can identify the subscriber by email address or subscriber ID. The subscriber will be removed from all valid lists provided. If the subscriber is not in a list, that list will be skipped. List counts are automatically updated.

Body parameters

emailstringoptional

Email address of the subscriber (required if subscriberId is not provided)

e.g. [email protected]

listIdsarrayrequired

Array of list IDs to remove the subscriber from (must contain at least one list ID)

e.g. ["695ca9409a8ed4e65738c3b7"]

subscriberIdstringoptional

ID of the subscriber (required if email is not provided)

POST/lists/remove-subscriber

curl -X POST https://emails.pabbly.com/api/v2/lists/remove-subscriber \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "listIds": [
      "695ca9409a8ed4e65738c3b7"
    ]
  }'

Remove Subscriber from Lists

Response

{
  "success": true,
  "status": "success",
  "message": "Subscriber removed from lists successfully",
  "data": {
    "subscriberId": "695ca95b9a8ed4e65738d1c5",
    "email": "[email protected]",
    "removedLists": [
      "New User"
    ],
    "currentLists": [
      "Pabbly Email Marketing"
    ]
  }
}

Create Subscriber List

POST/lists

Creates a new subscriber list in your account. The list name must be unique (case-insensitive) and cannot conflict with existing segment names. List name must be between 1 and 100 characters.

Body parameters

namestringrequired

The name of the subscriber list to create (1-100 characters)

e.g. Newsletter Subscribers

POST/lists

curl -X POST https://emails.pabbly.com/api/v2/lists \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Subscribers"
  }'

Create Subscriber List

Response

{
  "success": true,
  "status": "success",
  "message": "Subscriber list created successfully",
  "data": {
    "list": {
      "id": "695ce285efb6f84c1a193d2a",
      "name": "Newsletter Subscribers",
      "count": 0,
      "counts": {
        "totalSubscribers": 0,
        "unsubscribedCount": 0,
        "engagedCount": 0,
        "lastUpdated": "2026-01-06T10:23:01.285Z"
      },
      "createdAt": "2026-01-06T10:23:01.285Z",
      "updatedAt": "2026-01-06T10:23:01.285Z"
    }
  }
}

Get Single Subscriber List by List Name

GET/lists?listName={listName}

Retrieves a single subscriber list by its name. The list name search is case-insensitive and will match the exact name (trimmed). Returns detailed information including subscriber counts and metadata. URL Parameters:

Query parameters

listNamestringoptional

e.g. {{listName}}

GET/lists?listName={listName}

curl https://emails.pabbly.com/api/v2/lists?listName={{listName}} \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"

Get Single Subscriber List by List Name

Response

{
  "success": true,
  "status": "success",
  "message": "List retrieved successfully",
  "data": {
    "list": {
      "id": "695ca9409a8ed4e65738c3b7",
      "name": "new",
      "count": 0,
      "counts": {
        "totalSubscribers": 0,
        "unsubscribedCount": 0,
        "engagedCount": 0,
        "lastUpdated": "2026-01-06T10:37:41.525Z"
      },
      "createdAt": "2026-01-06T06:18:40.487Z",
      "updatedAt": "2026-01-06T06:18:40.487Z"
    }
  }
}

Move Subscriber Between Lists

POST/lists/move-subscriber

Moves an existing subscriber from one subscriber list to another. The subscriber will be removed from the source list and added to the target list. If the subscriber is already in the target list, they will only be removed from the source list. List counts are automatically updated for both lists.

Body parameters

emailstringoptional

Email address of the subscriber (required if subscriberId is not provided)

e.g. [email protected]

fromListIdstringrequired

ID of the source list to move subscriber from

e.g. 695ca9409a8ed4e65738c3b7

toListIdstringrequired

ID of the target list to move subscriber to

e.g. 695cf4e01b66bf088e1b4a92

subscriberIdstringoptional

ID of the subscriber (required if email is not provided)

POST/lists/move-subscriber

curl -X POST https://emails.pabbly.com/api/v2/lists/move-subscriber \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "fromListId": "695ca9409a8ed4e65738c3b7",
    "toListId": "695cf4e01b66bf088e1b4a92"
  }'

Move Subscriber Between Lists

Response

{
  "success": true,
  "status": "success",
  "message": "Subscriber moved between lists successfully",
  "data": {
    "subscriberId": "695ca95b9a8ed4e65738d1c5",
    "email": "[email protected]",
    "movedFrom": "new",
    "movedTo": "cvbcbbc",
    "alreadyInToList": false,
    "currentLists": [
      "Pabbly Email Marketing",
      "cvbcbbc"
    ]
  }
}

Get all Lists and Segments

GET/lists-and-segments

The token must be included in the Authorization header as a Bearer token. Retrieves a complete list of all subscriber lists and segments belonging to your authenticated business. Returns both lists and segments with their IDs, names, subscriber counts, and metadata. Lists and segments are sorted alphabetically by name (A-Z). This endpoint is useful for selecting target lists or segments when sending campaigns via the API. The response includes separate arrays for lists and segments, along with total counts for each type.

GET/lists-and-segments

curl https://emails.pabbly.com/api/v2/lists-and-segments \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"

Get all Lists and Segments

Response

{
  "success": true,
  "status": "success",
  "message": "Lists and segments retrieved successfully",
  "data": {
    "lists": [
      {
        "id": "1024158",
        "name": "Default list",
        "type": "list",
        "count": 9156,
        "counts": {
          "totalSubscribers": 9156,
          "unsubscribedCount": 6,
          "engagedCount": 5,
          "lastUpdated": "2026-02-02T06:47:24.447Z"
        },
        "createdAt": "2025-12-16T10:57:37.141Z",
        "updatedAt": "2025-12-16T10:57:37.141Z"
      },
      {
        "id": "1024165",
        "name": "new demo",
        "type": "list",
        "count": 0,
        "counts": {
          "totalSubscribers": 0,
          "unsubscribedCount": 0,
          "engagedCount": 0,
          "lastUpdated": "2026-02-02T06:47:24.447Z"
        },
        "createdAt": "2025-12-16T10:57:37.170Z",
        "updatedAt": "2025-12-16T10:57:37.170Z"
      },
      {
        "id": "69412881c231c8db46a01b23",
        "name": "pem-dev",
        "type": "list",
        "count": 6,
        "counts": {
          "totalSubscribers": 6,
          "unsubscribedCount": 0,
          "engagedCount": 6,
          "lastUpdated": "2026-02-02T06:47:24.447Z"
        },
        "createdAt": "2025-12-16T09:38:09.224Z",
        "updatedAt": "2025-12-16T09:38:09.224Z"
      },
      {
        "id": "6965320222f445bcaacb5ef8",
        "name": "test-1",
        "type": "list",
        "count": 0,
        "counts": {
          "totalSubscribers": 0,
          "unsubscribedCount": 0,
          "engagedCount": 0,
          "lastUpdated": "2026-02-02T06:47:24.447Z"
        },
        "createdAt": "2026-01-12T17:40:18.139Z",
        "updatedAt": "2026-01-12T17:40:18.139Z"
      }
    ],
    "segments": [
      {
        "id": "6952345b2011e7f242a11836",
        "name": "test",
        "type": "segment",
        "conditions": [
          [
            {
              "filterBy": "Custom Field",
              "customField": "firstName",
              "filterType": "Contains",
              "value": "user",
              "_id": "695234652011e7f242a11a2a"
            }
          ]
        ],
        "createdAt": "2025-12-29T07:57:15.811Z",
        "updatedAt": "2026-01-13T07:35:42.766Z"
      },
      {
        "id": "695255f52011e7f242adc8bf",
        "name": "test1",
        "type": "segment",
        "conditions": [
          [
            {
              "filterBy": "Custom Field",
              "customField": "email",
              "filterType": "Contains",
              "value": "user",
              "_id": "695256002011e7f242add121"
            }
          ]
        ],
        "createdAt": "2025-12-29T10:20:37.265Z",
        "updatedAt": "2026-01-13T07:35:42.765Z"
      }
    ],
    "totalLists": 4,
    "totalSegments": 2,
    "total": 6
  }
}

Get Delivery Servers

GET/delivery-servers

The token must be included in the Authorization header as a Bearer token. Retrieves a list of all active delivery servers belonging to your authenticated business. Only returns delivery servers with status "active". Supports search functionality to filter servers by server name, from email, or server type. Returns essential server information including server name, type, from email, verification status, and creation timestamp. Results are sorted by creation date (newest first). This endpoint is useful for selecting a delivery server when sending campaigns via the API. Query Parameters:

GET/delivery-servers

curl https://emails.pabbly.com/api/v2/delivery-servers \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"

Get Delivery Servers

Response

{
  "success": true,
  "status": "success",
  "message": "Delivery servers fetched successfully",
  "data": [
    {
      "_id": "696b3fd5b8426ea8d11c14f5",
      "serverName": "gmail",
      "serverType": "custom",
      "fromEmail": "[email protected]",
      "status": "active",
      "verified": true,
      "createdAt": "2026-01-17T07:52:53.181Z"
    },
    {
      "_id": "694fc94248ead5fec68f71bd",
      "serverName": "ethereal",
      "serverType": "custom",
      "fromEmail": "[email protected]",
      "status": "active",
      "verified": true,
      "createdAt": "2025-12-27T11:55:46.672Z"
    },
    {
      "_id": "694a3c492be0f610781f9eb0",
      "serverName": "smtp",
      "serverType": "custom",
      "fromEmail": "[email protected]",
      "status": "active",
      "verified": true,
      "createdAt": "2025-12-23T06:52:57.889Z"
    },
    {
      "_id": "6942576598c9f014dc02f062",
      "serverName": "brevo",
      "serverType": "sendinblue",
      "fromEmail": "[email protected]",
      "status": "active",
      "verified": true,
      "createdAt": "2025-12-17T07:10:29.117Z"
    },
    {
      "_id": "6939a325e90b87748e20a505",
      "serverName": "smtp-pool",
      "serverType": "custom",
      "fromEmail": "[email protected]",
      "status": "active",
      "verified": true,
      "createdAt": "2025-12-10T16:43:17.230Z"
    }
  ]
}