Add new subscriber to list

curl -X POST https://api2.ecomailapp.cz/lists/1/subscribe \
  -H "key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber_data": {
      "name": "Jan",
      "surname": "Novak",
      "email": "jan@novak.cz",
      "gender": "male",
      "company": "Company name",
      "city": "Praha",
      "country": "CZ",
      "phone": "+420777888999",
      "birthday": "1984-01-01",
      "custom_fields": {
        "shop": "myshop.cz",
        "birthday": { "value": "2022-01-20", "type": "date" }
      },
      "tags": ["tags"],
      "groups": { "grp_5a145ee75780f": ["Category 1", "Category 2"] }
    },
    "trigger_autoresponders": false,
    "update_existing": false,
    "resubscribe": false
  }'

$listId = 1;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api2.ecomailapp.cz/lists/{$listId}/subscribe");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'key: YOUR_API_KEY',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'subscriber_data' => [
        'name' => 'Jan',
        'surname' => 'Novak',
        'email' => 'jan@novak.cz',
        'gender' => 'male',
        'company' => 'Company name',
        'city' => 'Praha',
        'country' => 'CZ',
        'phone' => '+420777888999',
        'birthday' => '1984-01-01',
        'custom_fields' => [
            'shop' => 'myshop.cz',
            'birthday' => ['value' => '2022-01-20', 'type' => 'date'],
        ],
        'tags' => ['tags'],
        'groups' => ['grp_5a145ee75780f' => ['Category 1', 'Category 2']],
    ],
    'trigger_autoresponders' => false,
    'update_existing' => false,
    'resubscribe' => false,
]));
$response = curl_exec($ch);
curl_close($ch);

{
  "id": 259471,
  "name": "Jan",
  "surname": "Novak",
  "email": "jan@novak.cz",
  "gender": null,
  "bounce_soft": 0,
  "bounced_hard": 0,
  "bounce_message": null,
  "inserted_at": "2015-01-21 10:50:04",
  "already_subscribed": true
}

{
  "success": false,
  "message": "Validation errors",
  "data": {
    "subscriber_data.custom_fields": [
      "Custom fields must be an array with unique keys (case-insensitive)",
      "Subscriber custom fields must be an array with max 5000 bytes"
    ]
  }
}

POST

lists

{list_id}

curl -X POST https://api2.ecomailapp.cz/lists/1/subscribe \
  -H "key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber_data": {
      "name": "Jan",
      "surname": "Novak",
      "email": "jan@novak.cz",
      "gender": "male",
      "company": "Company name",
      "city": "Praha",
      "country": "CZ",
      "phone": "+420777888999",
      "birthday": "1984-01-01",
      "custom_fields": {
        "shop": "myshop.cz",
        "birthday": { "value": "2022-01-20", "type": "date" }
      },
      "tags": ["tags"],
      "groups": { "grp_5a145ee75780f": ["Category 1", "Category 2"] }
    },
    "trigger_autoresponders": false,
    "update_existing": false,
    "resubscribe": false
  }'

$listId = 1;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api2.ecomailapp.cz/lists/{$listId}/subscribe");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'key: YOUR_API_KEY',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'subscriber_data' => [
        'name' => 'Jan',
        'surname' => 'Novak',
        'email' => 'jan@novak.cz',
        'gender' => 'male',
        'company' => 'Company name',
        'city' => 'Praha',
        'country' => 'CZ',
        'phone' => '+420777888999',
        'birthday' => '1984-01-01',
        'custom_fields' => [
            'shop' => 'myshop.cz',
            'birthday' => ['value' => '2022-01-20', 'type' => 'date'],
        ],
        'tags' => ['tags'],
        'groups' => ['grp_5a145ee75780f' => ['Category 1', 'Category 2']],
    ],
    'trigger_autoresponders' => false,
    'update_existing' => false,
    'resubscribe' => false,
]));
$response = curl_exec($ch);
curl_close($ch);

{
  "id": 259471,
  "name": "Jan",
  "surname": "Novak",
  "email": "jan@novak.cz",
  "gender": null,
  "bounce_soft": 0,
  "bounced_hard": 0,
  "bounce_message": null,
  "inserted_at": "2015-01-21 10:50:04",
  "already_subscribed": true
}

{
  "success": false,
  "message": "Validation errors",
  "data": {
    "subscriber_data.custom_fields": [
      "Custom fields must be an array with unique keys (case-insensitive)",
      "Subscriber custom fields must be an array with max 5000 bytes"
    ]
  }
}

list_id

integer

required

ID of the list.

subscriber_data

object

required

Information about the subscriber.

Show subscriber_data properties

subscriber_data[email]

string

required

Subscriber’s email address.

subscriber_data[name]

string

First name.

subscriber_data[surname]

string

Last name.

subscriber_data[gender]

string

Gender. Must be male or female.

subscriber_data[status]

integer

Subscriber status. 1 = subscribed, 2 = unsubscribed, 4 = hard bounce, 5 = spam complaint, 6 = unconfirmed.

subscriber_data[company]

string

Company name.

subscriber_data[city]

string

City.

subscriber_data[street]

string

Street address.

subscriber_data[zip]

string

ZIP or postal code.

subscriber_data[country]

string

Country code.

subscriber_data[phone]

string

Phone number.

subscriber_data[pretitle]

string

Pre-title (e.g. Mr., Mrs.).

subscriber_data[surtitle]

string

Post-nominal title (e.g. PhD).

subscriber_data[birthday]

string

Birthday in YYYY-MM-DD format.

subscriber_data[nameday]

string

Name day in MM-DD format.

subscriber_data[source]

string

Source of the subscriber.

subscriber_data[custom_fields]

object

Custom field values. Limited to 5000 characters total. Reserved system merge tags are ignored. If a field doesn’t exist, a new field is created. Supported types: string, date, json, int, float, url. Float precision is limited to 3 decimal places.Keys are case-insensitive — they are trimmed and lowercased on input, so SHOP, shop and Shop are treated as the same field. Two keys that differ only in case or whitespace in the same request are rejected as duplicates.

subscriber_data[tags]

array

Subscriber tags. Limited to 2000 characters total and 50 characters per tag. Content overwrites current tags. Only updates if the parameter is present and update_existing is true. To clear all tags, send an empty array.

subscriber_data[groups]

object

Group assignments. Overwrites current values. To keep existing selections, send the current values together with new ones.

trigger_autoresponders

boolean

default:"false"

Trigger automations when the subscriber is added.

trigger_notification

boolean

default:"false"

Send a notification about the new subscriber if configured in list settings.

update_existing

boolean

default:"false"

Update the subscriber if they already exist in the list.

skip_confirmation

boolean

default:"false"

Skip double opt-in confirmation. If false, the system sends a double opt-in email and the subscriber is added with status 6 (unconfirmed).

resubscribe

boolean

default:"false"

Force resubscribe if the subscriber was previously unsubscribed (status 2). If status is provided in subscriber_data, it takes precedence. For resubscribe to work, the status must be 1.

If the subscriber already exists in the list, the response includes already_subscribed: true.

The inserted_at field in the response returns the time in UTC format.

curl -X POST https://api2.ecomailapp.cz/lists/1/subscribe \
  -H "key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber_data": {
      "name": "Jan",
      "surname": "Novak",
      "email": "jan@novak.cz",
      "gender": "male",
      "company": "Company name",
      "city": "Praha",
      "country": "CZ",
      "phone": "+420777888999",
      "birthday": "1984-01-01",
      "custom_fields": {
        "shop": "myshop.cz",
        "birthday": { "value": "2022-01-20", "type": "date" }
      },
      "tags": ["tags"],
      "groups": { "grp_5a145ee75780f": ["Category 1", "Category 2"] }
    },
    "trigger_autoresponders": false,
    "update_existing": false,
    "resubscribe": false
  }'

$listId = 1;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api2.ecomailapp.cz/lists/{$listId}/subscribe");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'key: YOUR_API_KEY',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'subscriber_data' => [
        'name' => 'Jan',
        'surname' => 'Novak',
        'email' => 'jan@novak.cz',
        'gender' => 'male',
        'company' => 'Company name',
        'city' => 'Praha',
        'country' => 'CZ',
        'phone' => '+420777888999',
        'birthday' => '1984-01-01',
        'custom_fields' => [
            'shop' => 'myshop.cz',
            'birthday' => ['value' => '2022-01-20', 'type' => 'date'],
        ],
        'tags' => ['tags'],
        'groups' => ['grp_5a145ee75780f' => ['Category 1', 'Category 2']],
    ],
    'trigger_autoresponders' => false,
    'update_existing' => false,
    'resubscribe' => false,
]));
$response = curl_exec($ch);
curl_close($ch);

{
  "id": 259471,
  "name": "Jan",
  "surname": "Novak",
  "email": "jan@novak.cz",
  "gender": null,
  "bounce_soft": 0,
  "bounced_hard": 0,
  "bounce_message": null,
  "inserted_at": "2015-01-21 10:50:04",
  "already_subscribed": true
}

{
  "success": false,
  "message": "Validation errors",
  "data": {
    "subscriber_data.custom_fields": [
      "Custom fields must be an array with unique keys (case-insensitive)",
      "Subscriber custom fields must be an array with max 5000 bytes"
    ]
  }
}

Get subscriber by phone Add bulk subscribers