# Pabbly Email Marketing > **Per-section URLs available** — append `.md` to any docs URL for markdown: > - Endpoint: `/pabbly/email-marketing/{tagSlug}/{endpointSlug}.md` > - Resource object: `/pabbly/email-marketing/{tagSlug}/object.md` > - Guide page: `/pabbly/email-marketing/guides/{docSlug}.md` > > Or send `Accept: text/markdown` on the canonical URL. > REST API for Pabbly Email Marketing - Base URL: `https://emails.pabbly.com/api/v2` - Authentication: Bearer token via `Authorization` header - Version: v2 --- ## Guides ### 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* ```bash 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* ```text 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* ```json { "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* ```json { "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* ```http 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* ```bash curl https://emails.pabbly.com/api/v2/subscribers \ -H "Authorization: Bearer {{YOUR_API_KEY}}" ``` *Node.js* ```javascript const response = await fetch( 'https://emails.pabbly.com/api/v2/subscribers', { headers: { 'Authorization': 'Bearer {{YOUR_API_KEY}}' } } ); const data = await response.json(); ``` *Python* ```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. --- ## API Reference ### Subscribers #### POST /subscribers — Create Subscriber 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:** | Name | Type | Required | Description | |------|------|----------|-------------| | email | string | Yes | Valid email address of the subscriber. | | firstName | string | No | First name of the subscriber. | | lastName | string | No | Last name of the subscriber. | | mobile | string | No | Phone number with country code (e.g., +1234567890). | | leadScore | integer | No | Lead score value between 0-100. | | status | string | No | Subscription status. Valid values: subscribed, unsubscribed, bounced, complaint. Default: subscribed. | | country | string | No | Country name of the subscriber. | | city | string | No | City name of the subscriber. | | tags | array | No | Array of tag names to assign to the subscriber. Tags must exist in Settings. | | customFields | object | No | Custom field key-value pairs. Custom fields must exist in Settings. | | ↳ company | string | No | | | ↳ position | string | No | | | lists | array | No | Array of list names to assign to the subscriber. | | dateOfBirth | string | No | Date of birth in YYYY-MM-DD format. | | source | string | No | Source of the subscriber (e.g., "api", "form", "csv"). | **Example Response (201):** ```json { "success": true, "status": "success", "message": "Subscriber created successfully", "data": { "userId": "682db2da6ef7e93a3eceb126", "businessId": "695b6aabf58d3822ac852e28", "email": "jocghn.doe@example.com", "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 /subscribers — Get All Subscribers 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:** | Name | Type | Required | Description | |------|------|----------|-------------| | page | integer | No | Page number for pagination. Default: 1. | | limit | integer | No | Number of items per page. Default: 10. Maximum: 100. | | search | string | No | Search term to filter by email, firstName, or lastName. | | status | string | No | Filter by subscription status. Valid values: subscribed, unsubscribed, bounced, complaint. | | tags | string | No | Filter by tag names. Can be comma-separated string or array. | | segments | string | No | Filter by segment names. Can be comma-separated string or array. | | lists | string | No | Filter by list names. Can be comma-separated string or array. | | leadScoreMin | string | No | Minimum lead score for filtering. | | leadScoreMax | string | No | Maximum lead score for filtering. | **Example Response (200):** ```json { "success": true, "status": "success", "message": "Subscribers retrieved successfully", "data": { "subscribers": [ { "_id": "69525f392011e7f242b57684", "userId": "682db2da6ef7e93a3eceb126", "businessId": "69398c24e90b87748e209d9b", "email": "john.doe@example.com", "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 /subscribers/stats — Get Subscriber Statistics Retrieves subscriber statistics for your business, including total subscriber count and status-wise breakdown (subscribed, unsubscribed, bounced, complaint). **Example Response (200):** ```json { "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 /subscribers/{subscriber ID} — Get Subscriber by ID Retrieves complete details of a specific subscriber by their unique ID. Returns all subscriber information including custom fields, tags, segments, lists, and timestamps. **Example Response (200):** ```json { "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": "john.doe@example.com", "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" } } ``` #### PUT /subscribers/{ subscriber Id} — Update Subscriber by 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:** | Name | Type | Required | Description | |------|------|----------|-------------| | firstName | string | No | Update subscriber's first name. | | lastName | string | No | Update subscriber's last name. | | leadScore | integer | No | Update lead score value (0-100). | | status | string | No | Update subscription status. Valid values: subscribed, unsubscribed, bounced, complaint. | | tagsToAdd | array | No | 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. | | tagsToRemove | array | No | 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. | | customFields | object | No | Update custom fields. Custom fields must exist in Settings. | | ↳ company | string | No | | | ↳ position | string | No | | | mobile | string | No | Update subscriber's phone number. | | country | string | No | Update subscriber's country. | | city | string | No | Update subscriber's city. | | tags | string | No | Update tags. Note: This replaces all existing tags. Tags must exist in Settings. | | lists | string | No | Update lists. Note: This replaces all existing lists. | **Example Response (200):** ```json { "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": "s001gourav@gmail.com", "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 /subscribers — Delete Subscriber 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:** | Name | Type | Required | Description | |------|------|----------|-------------| | ids | array | Yes | Array of subscriber IDs to delete. Must contain at least one ID. | **Example Response (200):** ```json { "success": true, "status": "success", "message": " subscriber deleted successfully", "data": { "shouldRefreshStats": true, "deletedCount": 1 } } ``` #### PUT /subscribers/{{email}} — Update Subscriber by 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:** | Name | Type | Required | Description | |------|------|----------|-------------| | email | string | Yes | | **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | firstName | string | No | | | lastName | string | No | | | leadScore | integer | No | | | status | string | No | | | tagsToAdd | array | No | | | tagsToRemove | array | No | | | customFields | object | No | | | ↳ company | string | No | | | ↳ position | string | No | | **Example Response (200):** ```json { "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": "s001gourav@gmail.com", "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 /subscribers/{{email}} — Get Subscriber by 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:** | Name | Type | Required | Description | |------|------|----------|-------------| | email | string | Yes | | **Example Response (200):** ```json { "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": "john.doe@example.com", "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 /custom-fields — Get All 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. **Example Response (200):** ```json { "success": true, "status": "success", "message": "Custom fields retrieved successfully", "data": { "businessId": "695b6aabf58d3822ac852e28", "customFields": [ { "name": "NewLead", "personalizationTag": "{newlead}" } ], "total": 1 } } ``` ### Campaigns #### POST /campaigns — Create Campaign 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:** | Name | Type | Required | Description | |------|------|----------|-------------| | campaignDetails | object | No | | | ↳ campaignName | string | No | | | ↳ senderName | string | No | | | ↳ subject | string | No | | | ↳ preheaderText | string | No | | | builderType | string | No | | | content | string | No | | **Example Response (201):** ```json { "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 /campaigns — Get All Campaigns 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:** | Name | Type | Required | Description | |------|------|----------|-------------| | page | integer | No | | | limit | integer | No | | | campaignType | string | No | | **Example Response (200):** ```json { "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": "\n\n
\n \n \nStay updated with our latest news and offers
\nThank you for subscribing to our newsletter. We're excited to share amazing content with you.
\n \n Get Started\n \nStay updated with our latest news and offers
\nThank you for subscribing to our newsletter. We're excited to share amazing content with you.
\n \n Get Started\n \n