API полей подписчика: свои поля и их ключи

Ресурс fields. У подписчика есть обычные поля (имя, фамилия, город и другие) и свои поля, которые вы заводите в кабинете: «Номер в CRM», «День рождения», «Компания». У каждого поля есть ключ. Значение передаётся по ключу рядом с адресом: при добавлении, правке и импорте подписчиков. Через API приходит список всех полей с ключами.

Свои поля заводятся и удаляются в кабинете: «Подписчики» › «Список» › кнопка «Дополнительные поля». Там же виден ключ.

Ключ поля

Строчные латинские буквы, цифры и _, начинается с буквы, от 2 до 32 знаков.
Кабинет предлагает ключ из названия латиницей («Номер в CRM» → nomer_v_crm), его можно поправить до создания.
После создания ключ не меняется, название менять можно.
Регистр не важен: CRM_ID и crm_id считаются одним ключом.

Обычные поля

Поле	Ключ	Тип	Прежнее имя, тоже работает
Email	`email`	email
Имя	`name`	text
Фамилия	`last_name`	text
Телефон	`phone`	text
Город	`city`	text
Телеграм	`telegram`	text	`skype`
IP	`ip`	ip
Дата подписки	`subscribe_date`	date	`date`
Страница подписки	`subscribe_url`	url	`subscribe_link`

В ответе поле приходит тем именем, которым вы его спросили: fields=["telegram"] вернёт telegram, fields=["skype"] вернёт skype.

Значения своих полей

Тип	Принимается	Хранится
`text`	Строка до 1000 знаков; пробелы по краям и управляющие знаки убираются.	Как передали.
`number`	`42`, `-3`, `12.5`, `12,5`	С точкой: `12.5`.
`date`	`ГГГГ-ММ-ДД`, настоящая дата.	`1990-05-17`
`url`	Адрес с `http://` или `https://`, до 1000 знаков.	Как передали.
`email`	Адрес почты.	Строчными буквами.

Дата своего поля передаётся и приходит строкой ГГГГ-ММ-ДД, а не числом unix: у дня рождения нет часового пояса.
Массив или объект вместо значения даёт ошибку значения.
Если значения нет, в ответе null.

Неизвестный ключ

Ключ, которого нет среди ваших полей, даёт ошибку с номером, и ничего не записывается: опечатка в ключе не теряет данные молча. Имена параметров API и служебные имена (id, email, status, date, list_id и другие) по-прежнему можно передавать: метод их пропускает. Поэтому объект подписчика из GET можно отправить обратно в PUT.

GET`/mailer/fields.json`

Все поля подписчика

Сначала обычные поля (standard: true), затем ваши (standard: false, с номером id).

На POST, PUT и DELETE для /mailer/fields ответ 405: поля заводятся и удаляются в кабинете.

curl https://v1.estismail.com/mailer/fields.json \
  -H "X-Estis-Auth: ВАШ_КЛЮЧ"

<?php
$ch = curl_init('https://v1.estismail.com/mailer/fields.json');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['X-Estis-Auth: ВАШ_КЛЮЧ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$fields = json_decode(curl_exec($ch), true)['fields'];
curl_close($ch);

import requests

r = requests.get('https://v1.estismail.com/mailer/fields.json',
                 headers={'X-Estis-Auth': 'ВАШ_КЛЮЧ'})
fields = r.json()['fields']

const r = await fetch('https://v1.estismail.com/mailer/fields.json', {
  headers: { 'X-Estis-Auth': 'ВАШ_КЛЮЧ' }
});
const { fields } = await r.json();

Ответ 200

{
  "fields": [
    {
      "key": "email",
      "title": "Email",
      "type": "email",
      "standard": true
    },
    {
      "key": "name",
      "title": "Имя",
      "type": "text",
      "standard": true
    },
    {
      "key": "last_name",
      "title": "Фамилия",
      "type": "text",
      "standard": true
    },
    {
      "key": "phone",
      "title": "Телефон",
      "type": "text",
      "standard": true
    },
    {
      "key": "city",
      "title": "Город",
      "type": "text",
      "standard": true
    },
    {
      "key": "telegram",
      "title": "Телеграм",
      "type": "text",
      "standard": true
    },
    {
      "key": "ip",
      "title": "IP",
      "type": "ip",
      "standard": true
    },
    {
      "key": "subscribe_date",
      "title": "Дата подписки",
      "type": "date",
      "standard": true
    },
    {
      "key": "subscribe_url",
      "title": "Страница подписки",
      "type": "url",
      "standard": true
    },
    {
      "id": 105,
      "key": "crm_id",
      "title": "Номер в CRM",
      "type": "text",
      "standard": false
    },
    {
      "id": 106,
      "key": "birthday",
      "title": "День рождения",
      "type": "date",
      "standard": false
    }
  ]
}

GET`/mailer/fields/{id}.json`

Одно своё поле

Если поля с таким номером у вас нет, ответ 404.

curl https://v1.estismail.com/mailer/fields/105.json \
  -H "X-Estis-Auth: ВАШ_КЛЮЧ"

<?php
$ch = curl_init('https://v1.estismail.com/mailer/fields/105.json');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['X-Estis-Auth: ВАШ_КЛЮЧ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n", $response;

import requests

r = requests.get(
    "https://v1.estismail.com/mailer/fields/105.json",
    headers={"X-Estis-Auth": "ВАШ_КЛЮЧ"},
)
print(r.status_code, r.text)

const res = await fetch("https://v1.estismail.com/mailer/fields/105.json", {
  headers: { "X-Estis-Auth": "ВАШ_КЛЮЧ" },
});
console.log(res.status, await res.text());

Ответ 200

{
  "id": 105,
  "key": "crm_id",
  "title": "Номер в CRM",
  "type": "text",
  "standard": false
}

Вопросы по API: support@estismail.com

Поля подписчика