Subscribers

Manage list subscribers, update profiles, suppress contacts, or perform bulk imports.
GET /subscribers

Retrieves a paginated list of mailing subscribers. Supports searching by keyword and filtering by status or list.

Query Parameters

Parameter Type Status Description
list_uuid String (UUID) Optional Filter subscribers belonging to a specific mailing list UUID.
search String Optional Keyword search. Matches first name, last name, or email.
status String Optional Filter by subscriber status: confirmed, unconfirmed, unsubscribed, bounced.
per_page Integer Optional Number of records per page (Default: 15).
GET /subscribers/{uuid}

Retrieves complete profile details and custom field metadata for a single subscriber by their UUID or subscriber ID.

POST /subscribers

Adds a single subscriber to a specified mailing list. Verifies account subscriber limits/quotas and list custom fields dynamically.

Request Parameters

Parameter Type Status Description
list_uuid String Required The unique UUID of the target mailing list.
email String Required Email address of the subscriber. Must be unique for the list.
first_name String Optional First name.
last_name String Optional Last name.
status String Optional confirmed, unconfirmed, unsubscribed, bounced (Default: confirmed).
ip_address String Optional IP address of the subscriber registration source.
source String Optional Source description (Default: api).
profile Object Optional Mappable profile object: dob, company, website, zip, country, state, address_1, address_2, city, phone, fax.
custom_fields Object Optional Key-value custom fields mapped to lists (e.g. {"Job Title": "CEO"}).

Example Payload

{
    "list_uuid": "4c8f9db0-4fdc-4a3b-9a84-18a72b64d1f2",
    "email": "jane.smith@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "profile": {
        "company": "Acme Org",
        "city": "Boston",
        "country": "US"
    },
    "custom_fields": {
        "Age": "28"
    }
}
PUT /subscribers/{uuid}

Updates an existing subscriber's core fields, profile attributes, custom fields, or subscription status.

Request Parameters

Accepts any optional parameter defined in the POST /subscribers creation method (such as first_name, status, profile, and custom_fields).

POST /subscribers/import

Bulk imports subscribers into a mailing list. Supports two payload mechanisms:

  • JSON Batch Array: Supply an array of subscriber objects in the subscribers field.
  • CSV File Upload: Upload a file in multipart/form-data. The headers are parsed and automatically matched (e.g. mapping Email, First Name, etc.).

Request Parameters

Parameter Type Status Description
list_uuid String Required The unique UUID of the target mailing list.
subscribers Array Optional Array of subscriber objects (e.g. [{"email": "jane@abc.com", "first_name": "Jane"}]).
file File Optional CSV file upload with header rows.

Example JSON Batch Payload

{
    "list_uuid": "4c8f9db0-4fdc-4a3b-9a84-18a72b64d1f2",
    "subscribers": [
        { "email": "a@domain.com", "first_name": "A" },
        { "email": "b@domain.com", "first_name": "B" }
    ]
}

Response Example

{
    "success": true,
    "message": "Subscribers import processed.",
    "data": {
        "total_processed": 2,
        "imported": 2,
        "duplicates": 0,
        "failed": 0,
        "failed_reasons": []
    }
}
POST /suppression

Adds an email address to the suppression list. Contacts in this list will never receive campaigns.

Request Parameters

Parameter Type Status Description
email String Required The email address to suppress.
first_name String Optional First name.
last_name String Optional Last name.

Response Example

{
    "success": true,
    "message": "Email added to suppression list successfully.",
    "data": {
        "uuid": "429a8b84-ea17-7a3b-d0d3-c90a2b64d1f2",
        "email": "suppressed@example.com",
        "status": "active"
    }
}