Skip to content

Subscribers

Unsubscribe a Subscriber

POST /api.php

This API call allows you to unsubscribe a subscriber from a mailing list.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandSubscriber.UnsubscribeYes
ListIDThe unique identifier for the mailing listYes
IPAddressThe IP address of the user making the requestYes
EmailAddressThe email address of the subscriber to unsubscribe (if known)No
SubscriberIDThe unique identifier for the subscriber to unsubscribe (if known)No
CampaignIDThe unique identifier for the campaign associated with the unsubscriptionNo
AutoResponderIDThe unique identifier for the autoresponder associated with the unsubscriptionNo
EmailIDThe unique identifier for the email associated with the unsubscriptionNo
ChannelThe channel through which the unsubscription is madeNo
PreviewA flag to indicate if the unsubscription should be simulated (1) or not (0)No
AddToGlobalSuppressionA flag to indicate if the email should be added to the global suppression listNo
RulesJSONA JSON string containing the rules for bulk unsubscriptionNo
RulesOperatorThe operator to be used with the rules ('and' or 'or')No
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=example-session-id' \
  -d 'APIKey=example-api-key' \
  -d 'Command=Subscriber.Unsubscribe' \
  -d 'ListID=123' \
  -d 'IPAddress=192.168.1.1' \
  -d 'EmailAddress=john.doe@example.com'
json
{
  "Success": true,
  "ErrorCode": 0,
  "RedirectURL": "https://example.com/unsubscribed.html"
}
json
{
  "Success": false,
  "ErrorCode": 1,
  "ErrorText": "List ID is required."
}
txt
1: List ID is required.
2: IP address is required.
3: Either email address or subscriber ID must be provided.
4: Invalid list ID or list does not exist.
5: User information could not be retrieved.
6: Invalid email address format.
7: Subscriber does not exist or does not belong to the list.
8: Invalid campaign ID or autoresponder ID.
9: Subscriber is already unsubscribed.
10: Invalid email ID.
11: Invalid query builder response.

Retrieve Subscriber Information

POST /api.php

This API call retrieves detailed information about a specific subscriber, including tags, segments, and journeys associated with them.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandSubscriber.GetYes
EmailAddressThe email address of the subscriber to retrieveYes
ListIDThe ID of the list the subscriber belongs toYes
bash
curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{"SessionID": "your-session-id", "APIKey": "your-api-key", "Command": "Subscriber.Get", "EmailAddress": "subscriber@example.com", "ListID": "123"}'
json
{
  "Success": true,
  "ErrorCode": 0,
  "SubscriberInformation": {
    "SubscriberID": "456",
    "EmailAddress": "subscriber@example.com",
    "Suppressed": false
    // Additional subscriber details...
  },
  "SubscriberTags": [
    // List of tags associated with the subscriber...
  ],
  "SubscriberSegments": [
    // List of segments the subscriber is part of...
  ],
  "SubscriberJourneys": {
    "Completed": [
      {
        "JourneyID": "5",
        "RelUserID": "1",
        "JourneyName": "Test remove",
        "Trigger": "Manual",
        "TriggerParameters": "[]",
        "Status": "Disabled",
        "Notes": null,
        "CreatedAt": "2023-12-18 14:10:12",
        "UpdatedAt": "2023-12-18 14:10:12"
      },
      {
        "JourneyID": "3",
        "RelUserID": "1",
        "JourneyName": "Test Journey Three",
        "Trigger": "Manual",
        "TriggerParameters": "[]",
        "Status": "Enabled",
        "Notes": "This is a note for a journey",
        "CreatedAt": "2023-12-18 09:54:38",
        "UpdatedAt": "2023-12-18 12:46:41"
      }
    ]
  },
  "SubscriberActivity": [
    {
      "ActivityDate": "2024-04-10 15:05:21",
      "UserID": "1",
      "ListID": "1",
      "SubscriberID": "16",
      "ActivityType": "journey start",
      "Parameters": {
        "journey_id": "3",
        "action_id": "55"
      }
    },
    {
      "ActivityDate": "2024-04-10 15:05:21",
      "UserID": "1",
      "ListID": "1",
      "SubscriberID": "16",
      "ActivityType": "tagged",
      "Parameters": {
        "TagID": "2"
      }
    },
    {
      "ActivityDate": "2024-04-10 15:05:21",
      "UserID": "1",
      "ListID": "1",
      "SubscriberID": "16",
      "ActivityType": "journey end",
      "Parameters": {
        "journey_id": "3",
        "action_id": "55"
      }
    }
  ],
  "SubscriberWebsiteEvents": [
    {
      "05fca7e4-3f07-4d62-9bfb-a6494897ad17": [
        {
          "website_tracker_uuid": "05fca7e4-3f07-4d62-9bfb-a6494897ad17",
          "event": "conversion",
          "email": "",
          "parameters.keys": [
            "$browser",
            "$browser_language",
            "$browser_version",
            "$current_url",
            "$device",
            "$device_type",
            "$dsn",
            "$host",
            "$lib",
            "$lib_version",
            "$list_id",
            "$os",
            "$pageTitle",
            "$pathname",
            "$referrer",
            "$referring_domain",
            "$screen_height",
            "$screen_width",
            "$sent_at",
            "$server",
            "$uuid",
            "$viewport_height",
            "$viewport_width",
            "conversionId",
            "conversionName",
            "conversionValue"
          ],
          "parameters.values": [
            "Google Chrome",
            "en-US",
            "123.0.0.0",
            "http://localhost:8080/test2.html",
            "Desktop",
            "Desktop",
            "1oRkpQJ0dNOLeLOvE2Mw",
            "localhost",
            "web",
            "0.1.0",
            "RO37N1aM8AeWmpny",
            "MacIntel",
            "",
            "/test2.html",
            "$direct",
            "$direct",
            "2160",
            "3840",
            "2024-04-10T19:25:40.951000+00:00",
            "https://staging-console.lindrisapi.com",
            "05fca7e4-3f07-4d62-9bfb-a6494897ad17",
            "954",
            "1920",
            "order1",
            "convName",
            "2000"
          ],
          "event_created_at": "2024-04-10 19:25:40"
        },
        {
          "website_tracker_uuid": "05fca7e4-3f07-4d62-9bfb-a6494897ad17",
          "event": "customEvent",
          "email": "",
          "parameters.keys": [
            "$browser",
            "$browser_language",
            "$browser_version",
            "$current_url",
            "$device",
            "$device_type",
            "$dsn",
            "$host",
            "$lib",
            "$lib_version",
            "$list_id",
            "$os",
            "$pageTitle",
            "$pathname",
            "$referrer",
            "$referring_domain",
            "$screen_height",
            "$screen_width",
            "$sent_at",
            "$server",
            "$uuid",
            "$viewport_height",
            "$viewport_width",
            "eventName",
            "key1"
          ],
          "parameters.values": [
            "Google Chrome",
            "en-US",
            "123.0.0.0",
            "http://localhost:8080/test2.html",
            "Desktop",
            "Desktop",
            "1oRkpQJ0dNOLeLOvE2Mw",
            "localhost",
            "web",
            "0.1.0",
            "RO37N1aM8AeWmpny",
            "MacIntel",
            "",
            "/test2.html",
            "$direct",
            "$direct",
            "2160",
            "3840",
            "2024-04-10T19:25:40.951000+00:00",
            "https://staging-console.lindrisapi.com",
            "05fca7e4-3f07-4d62-9bfb-a6494897ad17",
            "954",
            "1920",
            "event1",
            "val1"
          ],
          "event_created_at": "2024-04-10 19:25:40"
        },
        {
          "website_tracker_uuid": "05fca7e4-3f07-4d62-9bfb-a6494897ad17",
          "event": "identify",
          "email": "test@test.com",
          "parameters.keys": [
            "$browser",
            "$browser_language",
            "$browser_version",
            "$current_url",
            "$device",
            "$device_type",
            "$dsn",
            "$host",
            "$lib",
            "$lib_version",
            "$list_id",
            "$os",
            "$pageTitle",
            "$pathname",
            "$referrer",
            "$referring_domain",
            "$screen_height",
            "$screen_width",
            "$sent_at",
            "$server",
            "$uuid",
            "$viewport_height",
            "$viewport_width",
            "emailAddress"
          ],
          "parameters.values": [
            "Google Chrome",
            "en-US",
            "123.0.0.0",
            "http://localhost:8080/test2.html",
            "Desktop",
            "Desktop",
            "1oRkpQJ0dNOLeLOvE2Mw",
            "localhost",
            "web",
            "0.1.0",
            "RO37N1aM8AeWmpny",
            "MacIntel",
            "",
            "/test2.html",
            "$direct",
            "$direct",
            "2160",
            "3840",
            "2024-04-10T19:25:40.951000+00:00",
            "https://staging-console.lindrisapi.com",
            "05fca7e4-3f07-4d62-9bfb-a6494897ad17",
            "954",
            "1920",
            "cem.hurturk@gmail.com"
          ],
          "event_created_at": "2024-04-10 19:25:40"
        },
        {
          "website_tracker_uuid": "05fca7e4-3f07-4d62-9bfb-a6494897ad17",
          "event": "pageView",
          "email": "",
          "parameters.keys": [
            "$browser",
            "$browser_language",
            "$browser_version",
            "$current_url",
            "$device",
            "$device_type",
            "$dsn",
            "$host",
            "$lib",
            "$lib_version",
            "$list_id",
            "$os",
            "$pageTitle",
            "$pathname",
            "$referrer",
            "$referring_domain",
            "$screen_height",
            "$screen_width",
            "$sent_at",
            "$server",
            "$uuid",
            "$viewport_height",
            "$viewport_width",
            "url"
          ],
          "parameters.values": [
            "Google Chrome",
            "en-US",
            "123.0.0.0",
            "http://localhost:8080/test2.html",
            "Desktop",
            "Desktop",
            "1oRkpQJ0dNOLeLOvE2Mw",
            "localhost",
            "web",
            "0.1.0",
            "RO37N1aM8AeWmpny",
            "MacIntel",
            "",
            "/test2.html",
            "$direct",
            "$direct",
            "2160",
            "3840",
            "2024-04-10T19:25:40.951000+00:00",
            "https://staging-console.lindrisapi.com",
            "05fca7e4-3f07-4d62-9bfb-a6494897ad17",
            "954",
            "1920",
            "http://localhost:8080/test2.html"
          ],
          "event_created_at": "2024-04-10 19:25:40"
        }
      ],
      "25432a5c-9c80-44a9-a026-6db95e57fa7a": [
        {
          "website_tracker_uuid": "25432a5c-9c80-44a9-a026-6db95e57fa7a",
          "event": "conversion",
          "email": "",
          "parameters.keys": [
            "$browser",
            "$browser_language",
            "$browser_version",
            "$current_url",
            "$device",
            "$device_type",
            "$dsn",
            "$host",
            "$lib",
            "$lib_version",
            "$list_id",
            "$os",
            "$pageTitle",
            "$pathname",
            "$referrer",
            "$referring_domain",
            "$screen_height",
            "$screen_width",
            "$sent_at",
            "$server",
            "$uuid",
            "$viewport_height",
            "$viewport_width",
            "conversionId",
            "conversionName",
            "conversionValue"
          ],
          "parameters.values": [
            "Google Chrome",
            "en-US",
            "123.0.0.0",
            "http://localhost:8080/test2.html",
            "Desktop",
            "Desktop",
            "1oRkpQJ0dNOLeLOvE2Mw",
            "localhost",
            "web",
            "0.1.0",
            "RO37N1aM8AeWmpny",
            "MacIntel",
            "",
            "/test2.html",
            "$direct",
            "$direct",
            "2160",
            "3840",
            "2024-04-10T19:27:34.535000+00:00",
            "https://staging-console.lindrisapi.com",
            "25432a5c-9c80-44a9-a026-6db95e57fa7a",
            "1480",
            "1920",
            "order1",
            "convName",
            "2000"
          ],
          "event_created_at": "2024-04-10 19:27:34"
        }
      ]
    }
  ]
}
json
{
  "Success": false,
  "ErrorCode": [
    1
  ]
}
txt
1: Email address is required.
2: List ID is required.
3: Subscriber not found.
4: List not found.

NOTICE

  • Available SubscriptionStatus values are Opt-In Pending, Subscribed, Opt-Out Pending, Unsubscribed
  • SubscriberActivity parameter returns subscriber activities for the last 10 days only. For a detailed subscriber activity list, use Subscriber.Get.Activity API end-point.

Retrieve Subscriber Activities

POST /api.php

This endpoint returns the list of subscriber activities.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandSubscriber.Get.ActivityYes
SubscriberIDThe unique identifier of the subscriberYes
SubscriberListIDThe unique identifier of the subscriber listYes
FilterJsonThe filtering criteria in JSON syntax. Ex: ["tagged", "subscription"]. Criteria can be combination of subscription, unsubscription, email campaign delivery, transactional email delivery, auto responder delivery, email open, email link click, hard bounce, journey start, journey end, journey exit, tagged, untaggedYes
OperatorCurrently only OR operator is available. This filters the subscriber activity history based on crtieria set in FilterJson with "any of" filtering.Yes
RecordsPerRequestNumber of records to return in each API request.Yes
RecordsFromPagination start record number.Yes
bash
curl -X POST https://example.com/api.php \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "SessionID=exampleSessionId" \
  -d "Command=Subscriber.Get.Activity" \
  -d "SubscriberID=3" \
  -d "ListID=1" \
  -d "filterjson=[\"tagged\",\"subscription\"]" \
  -d "operator=OR" \
  -d "RecordsPerRequest=3" \
  -d "RecordsFrom=0"
json
{
  "Success": true,
  "ErrorCode": 0,
  "SubscriberActivity": [
    {
      "ActivityDate": "2024-04-09 13:39:14",
      "UserID": "1",
      "ListID": "1",
      "SubscriberID": "3",
      "ActivityType": "subscription",
      "Parameters": []
    },
    {
      "ActivityDate": "2024-04-09 12:46:08",
      "UserID": "1",
      "ListID": "1",
      "SubscriberID": "3",
      "ActivityType": "subscription",
      "Parameters": []
    },
    {
      "ActivityDate": "2024-04-09 08:23:27",
      "UserID": "1",
      "ListID": "1",
      "SubscriberID": "3",
      "ActivityType": "tagged",
      "Parameters": {
        "TagID": "2"
      }
    }
  ],
  "TotalSubscriberActivity": "17"
}
json
{
  "Success": false,
  "ErrorCode": [
    2
  ],
  "ErrorText": [
    "Missing subscriber id"
  ]
}
txt
1: Missing subscriber list id parameter
2: Missing subscriber id parameter
3: Invalid or missing FilterJson parameter
4: Invalid FilterJson criteria
5: Invalid criteria operator
6: Invalid subscriber list
7: Invalid subscriber

Event Response Examples

tagged:

json
{
  "ActivityDate": "2024-04-10 15:05:21",
  "UserID": "1",
  "ListID": "1",
  "SubscriberID": "16",
  "ActivityType": "tagged",
  {
    "TagID": "2",
    "TagName": "TEST-TAG-TWO",
    "RulesJSON": "\"[[{\\\"type\\\":\\\"fields\\\",\\\"field_id\\\":\\\"SubscriptionStatus\\\",\\\"operator\\\":\\\"contains\\\",\\\"value\\\":\\\"Subscribed\\\"}],[{\\\"type\\\":\\\"suppressions\\\",\\\"operator\\\":\\\"not exist\\\"}]]\"",
    "RulesOperator": "or"
  }
}

untagged:

json
{
  "ActivityDate": "2024-04-10 15:05:21",
  "UserID": "1",
  "ListID": "1",
  "SubscriberID": "16",
  "ActivityType": "untagged",
  "Parameters": {
    "TagID": "2",
    "TagName": "TEST-TAG-TWO"
  }
}

hard bounce:

json
{
  "ActivityDate": "2024-04-10 15:05:21",
  "UserID": "1",
  "ListID": "1",
  "SubscriberID": "16",
  "ActivityType": "hard bounce",
  "Parameters": {
    "campaignid": "2"
  }
}

email link click:

json
{
  "ActivityDate": "2024-04-10 15:05:21",
  "UserID": "1",
  "ListID": "1",
  "SubscriberID": "16",
  "ActivityType": "email link click",
  "Parameters": {
    "campaign_id": "2",
    "autoresponder_id": "0",
    "email_id": "2",
    "link_url": "index.html",
    "link_title": "index"
  }
}

email open:

json
{
  "ActivityDate": "2024-04-10 15:05:21",
  "UserID": "1",
  "ListID": "1",
  "SubscriberID": "16",
  "ActivityType": "email open",
  "Parameters": {
    "campaign_id": "2",
    "autoresponder_id": "0",
    "email_id": "2",
    "ip_address": "192.168.0.8"
  }
}

transactional email delivery:

json
{
  "ActivityDate": "2024-04-10 15:05:21",
  "UserID": "1",
  "ListID": "1",
  "SubscriberID": "16",
  "ActivityType": "transactional email delivery",
  "Parameters": {
    "QueueID": "2",
    "UserID": "1",
    "DomainID": "2",
    "APIKeyID": "",
    "SMTPID": ""
    // and other parameters
  }
}

journey exit:

json
{
  "ActivityDate": "2024-04-10 15:05:21",
  "UserID": "1",
  "ListID": "1",
  "SubscriberID": "16",
  "ActivityType": "journey exit",
  "Parameters": {
    "journey_id": "3",
    "action_id": "57"
  }
}

Delete Subscribers

POST /api.php

This endpoint allows you to delete subscribers from a list. You can either specify individual subscriber IDs or use a JSON rule set to define a group of subscribers to be deleted.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandSubscribers.DeleteYes
SubscriberListIDThe unique identifier of the subscriber listYes
SubscribersA comma-separated list of subscriber IDs to deleteNo
RulesJSONA JSON string defining the rules to select subscribers to deleteConditional
RulesOperatorOperator to be used with rules ('and'/'or'). Defaults to 'or' if not valid.No
SuppressedA boolean to indicate if subscribers should be removed from suppression listNo
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=exampleSessionId' \
  -d 'APIKey=exampleApiKey' \
  -d 'Command=Subscribers.Delete' \
  -d 'SubscriberListID=123' \
  -d 'Subscribers=456,789' \
  -d 'Suppressed=true'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": ""
}
json
{
  "Success": false,
  "ErrorCode": [
    2
  ],
  "ErrorText": [
    "Missing subscriber list id"
  ]
}
txt
1: Missing subscribers parameter
2: Missing subscriber list id
3: Missing RulesJSON parameter
4: Missing RulesOperator parameter
5: Invalid list id
6: Invalid query builder response
7: Missing rules operator when RulesJSON is provided

NOTICE

  • Please note that if you do not provide the Subscribers parameter, you must provide both RulesJSON and RulesOperator.
  • If RulesOperator is not provided or is invalid, it will default to 'or'.
  • If Suppressed is set to true, the specified subscribers will be removed from the suppression list instead of being deleted.

Retrieve Subscribers of a List

POST /api.php

This endpoint retrieves subscriber information based on various segments and criteria from a specified subscriber list.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandSubscribers.GetYes
SubscriberListIDThe unique identifier for the subscriber listYes
SubscriberSegmentThe segment of subscribers to retrieve (e.g., 'Active', 'Unsubscribed')Yes
RecordsPerRequestThe number of records to return per requestNo
RecordsFromThe starting point from which to return recordsNo
SearchFieldThe field to search within (e.g., 'Email', 'Name')No
SearchKeywordThe keyword to search for within the specified fieldNo
OrderFieldThe field to order the results by (e.g., 'DateAdded', 'Email')No
OrderTypeThe type of ordering to apply (e.g., 'ASC', 'DESC')No
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=example-session-id' \
  -d 'APIKey=example-api-key' \
  -d 'Command=Subscribers.Get' \
  -d 'SubscriberListID=123' \
  -d 'SubscriberSegment=Active' \
  -d 'RecordsPerRequest=25' \
  -d 'RecordsFrom=0'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "Subscribers": [
    {
      "SubscriberID": "1",
      "EmailAddress": "subscriber@example.com"
      // More subscriber fields...
    }
    // More subscribers...
  ],
  "TotalSubscribers": 100
}
json
{
  "Success": false,
  "ErrorCode": 1,
  "ErrorText": "SubscriberListID is a required field."
}
txt
1: SubscriberListID is a required field.
2: SubscriberSegment is a required field.
3: The list does not belong to the authenticated user.

Retrieve Subscribers

POST /api.php

This endpoint retrieves a list of subscribers based on various criteria such as list ID, segment, and search parameters.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandSubscribers.SearchYes
ListIDThe unique identifier for the subscriber listYes
OperatorThe operator to apply on the search (e.g., AND, OR)Yes
RecordsPerRequestThe number of records to return per requestNo
RecordsFromThe starting record number from which to return resultsNo
OrderFieldThe field by which to order the resultsNo
OrderTypeThe order type (e.g., ASC, DESC)No
RulesThe search rules in JSON formatNo
RulesJsonThe search rules in a JSON stringNo
DebugQueryBuilderA flag to return the prepared SQL query for debugging purposesNo
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=exampleSessionId' \
  -d 'APIKey=exampleApiKey' \
  -d 'Command=Subscribers.Search' \
  -d 'ListID=123' \
  -d 'Operator=AND' \
  -d 'RecordsPerRequest=25' \
  -d 'RecordsFrom=0' \
  -d 'OrderField=EmailAddress' \
  -d 'OrderType=ASC'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "Subscribers": [
    {
      "SubscriberID": 1,
      "EmailAddress": "example@example.com",
      "Suppressed": false
      // More subscriber fields...
    }
    // More subscribers...
  ],
  "TotalSubscribers": 150
}
json
{
  "Success": false,
  "ErrorCode": 1,
  "ErrorText": "ListID is a required field."
}
txt
1: "ListID is a required field."
2: "Operator is a required field."
3: "The list does not belong to the authenticated user."

Request Subscriber Data Export

POST /api/v1/subscriber.export

This API end-point allows for the export of subscriber data based on specified criteria. It supports filtering and exporting in different formats.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
ListIDThe unique identifier for the list to export fromYes
RulesJSONJSON string containing the rules for filtering subscribersYes
RulesOperatorOperator to apply between rules ("and" or "or")Yes
ExportFormatThe format for the export file ("csv" or "json")Yes
FieldsToExportArray of field names to include in the exportYes
TargetThe target subscribers to export ("", "Active", "Suppressed", etc. or ID)No
bash
curl -X POST 'https://example.com/api/v1/subscriber.export' \
-H 'Authorization: Bearer {User API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "SessionID": "your-session-id",
    "APIKey": "your-api-key",
    "ListID": "123",
    "RulesJSON": "{\"field\":\"value\"}",
    "RulesOperator": "and",
    "ExportFormat": "csv",
    "FieldsToExport": ["EmailAddress", "Name"],
    "Target": "Active"
}'
json
{
  "ExportID": 456
}
json
{
  "Errors": [
    {
      "Code": 1,
      "Message": "Missing ListID parameter"
    },
    {
      "Code": 2,
      "Message": "Missing RulesJSON parameter"
    }
    // Additional errors based on the validation
  ]
}
txt
1: Missing ListID parameter
2: Missing RulesJSON parameter
3: Missing RulesOperator parameter
4: Missing ExportFormat parameter
5: Missing FieldsToExport parameter
6: Invalid ListID parameter
7: Invalid RulesJSON syntax. It must be a properly formatted JSON payload
8: RulesOperator must be either "and" or "or"
9: ExportFormat must be either "csv" or "json"
10: List not found
11: Target must be "", "Active", "Suppressed", "Unsubscribed", "Soft bounced", "Hard bounced" or segment ID
12: Segment not found

Export Subscriber Data

GET /api/v1/subscriber.export

This API end-point allows you to export subscriber data from a specified list. You can also retrieve the status of an export job or download the exported data if the job is completed.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
ListIDThe unique identifier for the list to export fromYes
ExportIDThe unique identifier for a specific export jobNo
DownloadA flag to indicate if the exported data should be downloaded (set to true to download)No
bash
curl -X GET 'https://api.example.com/api/v1/subscriber.export' \
-H 'Authorization: Bearer {User API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "SessionID": "example-session-id",
    "APIKey": "example-api-key",
    "ListID": "123",
    "ExportID": "456",
    "Download": true
}'
json
{
  "ExportJob": {
    "ExportID": "456",
    "Status": "Completed",
    "SubmittedAt": "2023-01-01T00:00:00Z",
    "ExportOptions": {
      ...
    },
    "DownloadSize": 1024
  }
}
json
{
  "Errors": [
    {
      "Code": 1,
      "Message": "Missing ListID parameter"
    },
    {
      "Code": 2,
      "Message": "Invalid ListID parameter"
    },
    {
      "Code": 3,
      "Message": "Invalid ExportID parameter"
    },
    {
      "Code": 4,
      "Message": "List not found"
    },
    {
      "Code": 5,
      "Message": "Invalid ExportID parameter"
    },
    {
      "Code": 6,
      "Message": "Export job not found"
    }
  ]
}
txt
1: Missing ListID parameter
2: Invalid ListID parameter
3: Invalid ExportID parameter
4: List not found
5: Invalid ExportID parameter
6: Export job not found

NOTICE

  • Please note that the ExportID parameter is optional.
  • If provided, the API will return the status of the specified export job or allow you to download the exported data if the job is completed and the Download parameter is set to true.
  • If ExportID is not provided, the API will return a list of all export jobs for the user.

Import Subscribers

POST /api/v1/subscriber.import

This API end-point allows for importing subscribers into a specified list. It supports importing from CSV data, Mailchimp, or ActiveCampaign. The import process can be customized with various options such as updating duplicates, triggering actions, and adding to suppression lists.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
ListIDThe unique identifier for the list to import subscribers intoYes
AddToGlobalSuppressionListWhether to add the imported subscribers to the global suppression listYes
AddToSuppressionListWhether to add the imported subscribers to the list's suppression listYes
UpdateDuplicatesWhether to update existing subscribers if duplicates are foundYes
TriggerActionsWhether to trigger actions for the imported subscribersYes
TagsAn array of tags to assign to the imported subscribersYes
ImportFrom.CSV.URLThe URL to fetch CSV data from (optional if CSV data is provided)No
ImportFrom.CSV.DataThe CSV data to import (optional if a URL is provided)No
ImportFrom.CSV.FieldTerminatorThe character used to terminate fields in the CSV dataNo
ImportFrom.CSV.FieldEncloserThe character used to enclose fields in the CSV dataNo
ImportFrom.CSV.EscapedByThe character used to escape special characters in the CSV dataNo
ImportFrom.CSV.MappedFieldsAn array mapping CSV fields to subscriber attributesYes
ImportFrom.Mailchimp.APIKeyThe Mailchimp API key for importing subscribersNo
ImportFrom.Mailchimp.ServerThe Mailchimp server prefix for importing subscribersNo
ImportFrom.Mailchimp.MailchimpListIDThe Mailchimp list ID to import subscribers fromNo
ImportFrom.ActiveCampaign.APIKeyThe ActiveCampaign API key for importing subscribersNo
ImportFrom.ActiveCampaign.AccountNameThe ActiveCampaign account name for importing subscribersNo
ImportFrom.ActiveCampaign.ActiveCampaignListIDThe ActiveCampaign list ID to import subscribers fromNo
ImportStatusUpdateWebhookURLA webhook URL to receive updates about the import statusNo
bash
curl -X POST "https://example.com/api/v1/subscriber.import" \
     -H "Authorization: Bearer {User API Key}" \
     -H "Content-Type: application/json" \
     -d '{
           "SessionID": "example-session-id",
           "APIKey": "example-api-key",
           "ListID": "123",
           "AddToGlobalSuppressionList": false,
           "AddToSuppressionList": false,
           "UpdateDuplicates": true,
           "TriggerActions": true,
           "Tags": ["NewSubscriber", "Imported"],
           "ImportFrom": {
             "CSV": {
               "Data": "email,name\nexample@example.com,John Doe",
               "FieldTerminator": ",",
               "FieldEncloser": "\"",
               "EscapedBy": "\\",
               "MappedFields": {
                 "email": "Email",
                 "name": "FullName"
               }
             }
           }
         }'
json
{
  "ImportID": 456
}
json
{
  "Errors": [
    {
      "Code": 1,
      "Message": "Missing ListID parameter"
    },
    {
      "Code": 4,
      "Message": "Missing AddToGlobalSuppressionList parameter"
    }
    // Additional errors may be included
  ]
}
txt
1: Missing ListID parameter
4: Missing AddToGlobalSuppressionList parameter
5: Missing AddToSuppressionList parameter
6: Missing UpdateDuplicates parameter
7: Missing TriggerActions parameter
8: Missing MappedFields parameter
9: Invalid AddToGlobalSuppressionList parameter
10: Invalid AddToSuppressionList parameter
11: Invalid UpdateDuplicates parameter
12: Invalid TriggerActions parameter
13: Invalid MappedFields parameter
14: ImportFrom.CSV.URL, ImportFrom.CSV.Data, ImportFrom.Mailchimp.APIKey or ImportFrom.ActiveCampaign.APIKey must be provided
15: Fields are not mapped in MappedFields parameter
16: Missing EscapedBy parameter
17: Field mapping is invalid
18: ImportFrom.CSV.URL remote data fetch failure
19: List not found
20: Failed to create import record
21: Missing Tags parameter
22: Mailchimp API key is missing
23: Mailchimp server is missing
24: Mailchimp Error: {error status} - {error title}: {error detail}
25: ActiveCampaign API key is missing
26: ActiveCampaign account name is missing
27: ActiveCampaign Error: {error status} - {error title}: {error detail}
28: ActiveCampaign Error: {error status} - {error title}: {error detail}

Retrieve Import Job Details

GET /api/v1/subscriber.import

This API end-point is used to retrieve details of a specific import job for a subscriber list. It requires an admin-level authorization and provides comprehensive information about the import process, including status and statistics.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
ListIDThe unique identifier for the subscriber listYes
ImportIDThe unique identifier for the import jobYes
bash
curl -X GET "https://example.com/api/v1/subscriber.import" \
-H "Authorization: Bearer {Admin API Key}" \
-d "SessionID=exampleSessionId" \
-d "APIKey=exampleApiKey" \
-d "ListID=123" \
-d "ImportID=456"
json
{
  "ImportJob": {
    "ImportID": "456",
    "ImportDate": "2023-01-01T00:00:00Z",
    "FinishedAt": "2023-01-01T01:00:00Z",
    "ImportStatus": "Completed",
    "FailedData": [],
    "TotalSubscribers": 1000,
    "TotalImported": 950,
    "TotalDuplicates": 30,
    "TotalFailed": 20
  }
}
json
{
  "Errors": [
    {
      "Code": 5,
      "Message": "List not found"
    }
  ]
}
txt
1: Missing ListID parameter
2: Missing ImportID parameter
3: Invalid ListID parameter
4: Invalid ImportID parameter
5: List not found
6: Invalid ImportID parameter
7: Import job not found

Create a New Subscriber

POST api/v1/subscriber.create

This endpoint is used to create a new subscriber in the system. It requires an admin API key for authorization and accepts various subscriber details.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
ListIDThe unique identifier for the mailing listYes
EmailAddressThe email address of the new subscriberYes
StatusThe subscription status ('Opt-In Pending', 'Subscribed', 'Opt-Out Pending', 'Unsubscribed')No
OptInDateThe date the user opted inConditional
SubscriptionDateThe date the user subscribedConditional
SubscriptionIPThe IP address from which the subscription was madeConditional
UnsubscriptionDateThe date the user unsubscribedConditional
UnsubscriptionIPThe IP address from which the unsubscription was madeConditional
BounceTypeThe type of email bounce (e.g., 'Not Bounced', 'Hard', 'Soft')No
CustomFieldsAn array of custom field IDs and their valuesNo
UpdateIfDuplicateFlag to update subscriber if email address is duplicateNo
UpdateIfUnsubscribedFlag to update subscriber if previously unsubscribedNo
ApplyBehaviorsFlag to apply behaviors associated with the subscriptionNo
SendConfirmationEmailFlag to send a confirmation email to the subscriberNo
UpdateStatisticsFlag to update statistics upon subscriptionNo
TriggerWebServicesFlag to trigger web services upon subscriptionNo
TriggerAutoRespondersFlag to trigger autoresponders upon subscriptionNo
bash
curl -X POST 'https://example.com/api/v1/subscriber.create' \
-H 'Authorization: Bearer {AdminApiKey}' \
-H 'Content-Type: application/json' \
-d '{
  "SessionID": "session_id_here",
  "APIKey": "api_key_here",
  "ListID": "list_id_here",
  "EmailAddress": "email@example.com",
  "Status": "Subscribed",
  "OptInDate": "2023-01-01",
  "SubscriptionDate": "2023-01-01",
  "SubscriptionIP": "192.168.1.1",
  "CustomFields": {
    "100":"First Name Value",
    "103":"Last Name Value"
  }
}'
json
{
  "ErrorCode": 0,
  "SubscriberInformation": {
    "SubscriberID": "subscriber_id_here",
    "EmailAddress": "email@example.com",
    "Status": "Subscribed"
    // Additional subscriber details...
  },
  "SubscriberTags": [],
  "SubscriberSegments": [],
  "SubscriberJourneys": [],
  "SubscriberWebsiteEvents": []
}
json
{
  "Errors": [
    {
      "Code": 2,
      "Message": "Missing EmailAddress parameter"
    }
    // Additional errors...
  ]
}
text
1: Missing ListID parameter
2: Missing EmailAddress parameter
3: Invalid EmailAddress. Make sure email address is valid.
4: Invalid ListID.
5: Invalid BounceType value.
6: Invalid Status value.
7: Invalid SubscriptionDate value.
8: Missing SubscriptionDate parameter
9: Missing SubscriptionIP parameter
10: Invalid SubscriptionIP value. It must be an IP address.
11: Missing UnsubscriptionDate parameter
12: Missing UnsubscriptionIP parameter
13: Invalid UnsubscriptionDate value.
14: Invalid UnsubscriptionIP value. It must be an IP address.
15: Missing OptInDate parameter
16: Invalid OptInDate value.
17: Invalid Custom Field value.
18: Subscriber create limit is exceeded
19: Invalid EmailAddress
20: Duplicate EmailAddress
21: Previously unsubscribed EmailAddress
22: Invalid user information
23: Invalid list information

HTTP Response and Error Codes:

HTTP CodeError CodeDescription
2000Success
4221-23Various errors related to input validation

Update Subscriber Information

POST /api.php

This endpoint is used to update the information of a subscriber in a mailing list. It allows for updating various subscriber details, including email address, subscription status, bounce type, and custom fields.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandThe API command to execute: Subscriber.UpdateYes
SubscriberIDThe unique identifier of the subscriberYes
SubscriberListIDThe unique identifier of the subscriber listYes
EmailAddressThe new email address of the subscriber (if applicable)No
SubscriptionStatusThe new subscription status of the subscriber (Opt-In Pending, Subscribed, Opt-Out Pending, Unsubscribed)No
BounceTypeThe new bounce type of the subscriber (Not Bounced, Soft, Hard)No
FieldsAn array of custom field values to updateNo
AuthenticationTypeThe type of authentication usedNo
IgnoreAllOtherCustomFieldsExceptGivenOnesFlag to ignore unspecified custom fieldsNo
bash
curl --location 'https://example.com/api.php' \
--form 'ResponseFormat="JSON"' \
--form 'Command="Subscriber.Update"' \
--form 'SessionID="exampleSessionId"' \
--form 'SubscriberListID="26"' \
--form 'SubscriberID="1008"' \
--form 'EmailAddress="test@gmail.com"' \
--form 'AuthenticationType="user"' \
--form 'IgnoreAllOtherCustomFieldsExceptGivenOnes="true"' \
--form 'Fields[CustomField59]="100"' \
--form 'SubscriptionStatus="Subscribed"' \
--form 'BounceType="Not Bounced"' \
--form 'Fields[CustomField59]="102"'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": ""
}
json
{
  "Success": false,
  "ErrorCode": 1,
  "ErrorText": "Required field 'subscriberid' is missing."
}
text
1: Required field 'subscriberid' is missing.
2: Required field 'subscriberlistid' is missing.
3: Email address is empty.
4: Email address is invalid.
5: Subscriber list does not exist or does not belong to the user.
6: Subscriber does not exist.
7: Email address is a duplicate.
8: Required custom field is missing.
9: Custom field value is not unique.
10: Custom field value failed validation.

HTTP Response and Error Codes:

HTTP CodeError CodeDescription
2000Success
4001Missing required 'subscriberid' parameter
4002Missing required 'subscriberlistid' parameter
4003Email address is empty
4004Email address is invalid
4005Subscriber list does not exist or not owned
4006Subscriber does not exist
4007Email address is a duplicate
4008Required custom field is missing
4009Custom field value is not unique
40010Custom field value failed validation

Search Subscribers

POST /api.php

This endpoint retrieves a list of subscribers based on the provided criteria, such as list ID and operator. It supports pagination and ordering of the subscriber list.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandSubscribers.SearchYes
ListIDUnique identifier for the listYes
OperatorOperator to apply on the list retrieval (and, or)Yes
RecordsPerRequestNumber of records to retrieve per requestNo
RecordsFromStarting point for record retrievalNo
OrderFieldField to order the records byNo
OrderTypeType of ordering to apply (ASC or DESC)No
RulesFiltering rules for the queryNo
RulesJsonJSON representation of the filtering rulesNo
DebugQueryBuilderIf set to true, returns the prepared SQL queryNo

NOTICE

Please refer to this help article for RulesJSON parameter syntax.

bash
curl --location 'https://example/api.php' \
--form 'ResponseFormat="JSON"' \
--form 'Command="Subscribers.Search"' \
--form 'SessionID="{SessionID}"' \
--form 'ListID="26"' \
--form 'Operator="and"' \
--form 'RulesJSON="[[{\"type\":\"fields\",\"field_id\":\"EmailAddress\",\"operator\":\"contains\",\"value\":\"cem\"}]]"' \
--form 'RecordsFrom="0"' \
--form 'RecordsPerRequest="3"' \
--form 'OrderField="EmailAddress"' \
--form 'OrderType="ASC"'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "Subscribers": [
    {
      "EmailAddress": "example@example.com",
      "SubscriberID": "123",
      "SubscriberTags": [
        "Tag1",
        "Tag2"
      ]
    }
  ],
  "TotalSubscribers": 100
}
json
{
  "Success": false,
  "ErrorCode": 1,
  "ErrorText": "List ID is required."
}
text
1: List ID is required.
2: Operator is required.
3: Unauthorized access to the list.

:::

HTTP Response and Error Codes:

HTTP CodeError CodeDescription
2000Success
4001List ID is required.
4002Operator is required.
4033Unauthorized access to the list.

Any questions? Contact us.