Перейти к основному содержимому
Опубликовано: 

Шаблоны популярных API-запросов

С помощью API вы можете управлять рассылками, обновлять базу, получать аналитику и выполнять другие операции, недоступные в веб-интерфейсе.

В этой статье собраны шаблоны популярных API-запросов, которые помогут вам быстро настроить интеграцию и автоматизировать ключевые процессы:

Запросы можно отправлять через API-консоль или через сторонние сервисы, например, через Postman. Используйте эти примеры как готовые решения или адаптируйте их под свои задачи.

Важно

Шаблоны запросов заполнены тестовыми данными. Перед отправкой запроса укажите настоящие данные.

Авторизация, саблогины и права​

Авторизоваться в системе​

Рекомендуем работать с API, используя API-ключ. Чтобы получить ключ потребуется параметр session, который придёт в ответ на запрос:

{
 "action" : "login",
 "login"  : "ваш логин в sendsay",
 "passwd" : "ваш пароль в sendsay"
}

Аутентификация

Получить API-ключ для саблогина​

{
 "action" : "sys.user.apikey.create",
 "login" : "логин саблогина" ,
 "session": "значение полученного ранее параметра session (login)"
}

API-ключи пользователей

Создать саблогин​

{
 "action" : "sys.user.create",
 "id" : "логин",
 "password" : " пароль",
 "email" : "email-адрес, на который придет пароль",
 "session": "значение полученного ранее параметра session (login)"
}

Создание пользователя

Задать права для саблогина​

Созданному саблогину нужно добавить права:

{
    "action": "sys.user.rights.set",
    "session": "значение полученного ранее параметра session (login)",
    "id": "логин саблогина",
    "list": {
        "api.member.get": "1",
        "api.member.set": "1",
        "api.member.list": "1",
        "api.member.import": "1",
        "api.member.find": "1"
    }
}

Права дополнительных пользователей

Импорт​

Узнать подробнее о процессе импорта данных через API можно в документации.

Массово загрузить контакты из файла​

{
    "action": "member.import",
    "addr_type": "email",
    "charset": "utf-8",
    "users.url": "rfs://upload/filelgcity.csv",
    "separator": ";",
    "if_exists": "overwrite",
    "auto_group": {
        "id":
    },
    "sequence.event": 0,
    "newbie.confirm": 0,
    "caption": [{
            "anketa": "member",
            "quest": "email"
        },
        {
            "anketa": "base",
            "quest": "firstName"
        }
    ]
}

Массово загрузить контакты из файла с указанием в запросе данных в формате АВО (анкетных данных)​

{
    "action": "member.import",
    "addr_type": "email",
    "charset": "utf-8",
    "users.url": "rfs://upload/filelgcity.csv",
    "separator": ";",
    "if_exists": "overwrite",
    "format": "",
    "auto_group": {
        "id":
    },
    "sequence.event": 0,
    "caption": [{
            "anketa": "base",
            "quest": "birthDate"
        },
        {
            "anketa": "base",
            "quest": "city"
        },
        {
            "anketa": "base",
            "quest": "gender"
        },
        {
            "anketa": "base",
            "quest": "firstName"
        },
        {
            "anketa": "base",
            "quest": "lastName"
        },
        {
            "anketa": "member",
            "quest": "email"
        }
    ]
}

Массово загрузить контакты с указанием в запросе данных в формате КД (ключи данных)​

{
    "action": "member.import",
    "addr_type": "email",
    "auto_group": {
        "id": "p4527"
    },
    "users.list": {
        "caption": [{
                "datakey": "member.email",
                "mode": "set"
            },
            {
                "datakey": "custom.contractData",
                "mode": "merge"
            }
        ],
        "rows": [
            [
                "example1@sendsay.ru",
                {
                    "557800": {
                        "dogovor": "557800",
                        "date": "2016-10-21",
                        "domane": "slava.ru",
                        "summ": "423"
                    }
                }
            ],
            [
                "example2@sendsay.ru",
                {
                    "557799": {
                        "dogovor": "557799",
                        "date": "2016-10-24",
                        "domane": "slava.ru",
                        "summ": "206"
                    }
                }
            ]
        ]
    }
}

Массово загрузить контакты с добавлением анкетных данных​

{
    "action": "member.import",
    "apikey": "ваш API-ключ",
    "addr_type": "email",
    "newbie.confirm": "1",
    "auto_group": {
        "id": "testgroup",
        "name": "Test"
    },
    "users.list": {
        "caption": [{
                "anketa": "member",
                "quest": "email"
            },
            {
                "anketa": "base",
                "quest": "lastName"
            },
            {
                "anketa": "base",
                "quest": "firstName"
            },
            {
                "anketa": "base",
                "quest": "birthDate"
            }
        ],
        "rows": [
            [
  "example1@gmail.com",
                "Иванов",
                "Петр",
                "2000-04-01"
            ],
            [
                "example2@gmail.com",
                "Криворуков",
                "Арсений",
                "1995-08-26"
            ],
            [
                "example3@gmail.com",
                "Понедельникова",
                "Марфа",
                "1990-09-27"
            ],
            [
                "example4@gmail.com",
                "Ошибкин",
                "Константин",
                "1000-07-12"
            ],
            [
                "example5@gmail.com",
                "",
                "Прасковья",
                "1987-08-28"
            ]
        ]
    }
}

Добавить один контакт с данными в формате КД (ключи данных) и добавлением в список​

{
    "action": "member.set",
    "apikey": "ваш API-ключ",
    "email": "example@sendsay.ru",
    "addr_type": "email",
    "datakey": [
        [
            "auto",
            "set",
            {
                "brand": "Opel",
                "model": "Mokka",
                "old_price": "790 000р.",
                "new_price": "705 000р.",
                "description": "Mokka, 2014 г.в., 140 623 км,<br>Внедорожник 5 дв., АКПП, Бензин <br>140 лс",
                "image": "https://image.sendsay.ru/image/demo/mokka.jpg",
                "link": "https://sendsay.ru/api/api.html"
            }
        ],
        [
            "-group.pl21586",
            "set",
            1
        ]
    ]
}

Импортировать один контакт с добавлением анкетного значения​

{
    "action": "member.set",
    "email": "example@test.ru",
    "obj": {
        "base": {
            "tz": "UTC+13:45"
        }
    }
}

Импортировать контакт с добавлением ключей данных​

{
    "action": "member.set",
    "email": "example@test.ru",
    "datakey": [
        [
            "custom.first_name",
            "set",
            "Vladimir"
        ]
    ]
}

Импортировать контакт с добавлением ключей данных и добавлением в список​

{
    "action": "member.set",
    "email": "example@test.ru",
    "datakey": [
        [
            "base.firstName",
            "set",
            "Vladimir"
        ],
        [
            "-group.pl42816",
            "set",
            1
        ]
    ]
}

Удалить подписчика из списка​

{
    "action": "member.set",
    "addr_type": "email",
    "email": "example@test.ru",
    "obj": {
        "-group": {
            "p32": "0"
        }
    }
}

Получение данных​

Получить ключи данных, указанные в запросе​

{
    "action": "member.get",
    "email": "example@mail.ru",
    "addr_type": "email",
    "datakey": [
        "member.email",
        "member.anketa.name"
    ]
}

Изменить данные​

{
    "action": "member.set",
    "email": "email-адрес подписчика",
    "addr_type": "email",
    "datakey": [
        [
            "city_name",
            "set",
            "MSK"
        ]
    ]
}

Отправка писем (issue.send)​

Узнать подробнее об отправке выпуска через API можно в документации.

Отправить транзакционное письмо для восстановления пароля​

{
    "action": "issue.send",
    "sendwhen": "now",
    "group": "personal",
    "email": "example@sendsay.ru",
    "relink": "1",
    "letter": {
        "subject": "восстановление пароля",
        "from.name": "имя отправителя",
        "from.email": "email-адрес отправителя",
        "message": {
            "html": "html-code here [% password %]"
        }
    },
    "extra": {
        "password": "qwerty"
    }
}

Отправить рассылку по списку получателей​

{
    "action": "issue.send",
    "name": "название черновика",
    "sendwhen": "now",
    "group": "masssending",
    "relink": 1,
    "relink.param": {
        "link": 1,
        "test": 0
    },
    "letter": {
        "draft.id": "1491"
    },
    "users.list": [{
            "member": {
                "email": "anna@sendsay.ru"
            },
            "personal": {
                "fio": "Иван Иванович",
                "product": "ОСАГО",
                "serialNumber": "ХХХ 0284975921",
                "endDate": "17 октября 2018",
                "makeModel": "ВАЗ/Lada 1119/Kalina",
                "carNumber": "2423 423443",
                "carType": "002"
            }
        },
        {
            "member": {
                "email": "anna@sendsay.ru"
            },
            "personal": {
                "fio": "Петр Иванович",
                "product": "Каско",
                "serialNumber": "ХХХ 0284975921",
                "endDate": "17 октября 2018",
                "makeModel": "ВАЗ/Lada 1119/Kalina",
                "carNumber": "2423 423443",
                "carType": "002"
            }
        }
    ]
}

Отправить рассылку по списку получателей, с передачей списка и содержимого письма внутри запроса​

{
    "action": "issue.send",
    "name": "название черновика",
    "sendwhen": "now",
    "group": "masssending",
    "relink": 1,
    "relink.param": {
        "link": 1,
        "test": 0
    },
    "letter": {
        "subject": "тема письма",
        "from.name": "имя отправителя",
        "from.email": "email-адрес отправителя",
        "message": {
            "html": "текст письма в html [% anketa.personal.product %]"
        }
    },
    "users.list": [{
            "member": {
                "email": "example@sendsay.ru"
            },
            "personal": {
                "fio": "Иван Иванович",
                "product": "ОСАГО",
                "serialNumber": "ХХХ 0284975921",
                "endDate": "17 октября 2018",
                "makeModel": "ВАЗ/Lada 1119/Kalina",
                "carNumber": "2423 423443",
                "carType": "002"
            }
        },
        {
            "member": {
                "email": "example1@sendsay.ru"
            },
            "personal": {
                "fio": "Петр Иванович",
                "product": "Каско",
                "serialNumber": "ХХХ 0284975921",
                "endDate": "17 октября 2018",
                "makeModel": "ВАЗ/Lada 1119/Kalina",
                "carNumber": "2423 423443",
                "carType": "002"
            }
        }
    ]
}

Отправить письмо с контактами и данными персонализации в запросе​

В запросе указывается id шаблона письма. В самом шаблоне используйте команды подстановки для персонализации:

  • [% anketa.base.name %] — имени.
  • [% anketa.main.promocode %] — промокода.

Можно использовать любые другие переменные для персонализации, но важно, чтобы они совпадали в шаблоне и в запросе.

{
    "action": "issue.send",
    "letter": {
        "draft.id": id шаблона письма
    },
    "group": "masssending",
    "users.list": {
        "caption": [{
                "anketa": "member",
                "quest": "email"
            },
            {
                "anketa": "base",
                "quest": "name"
            },
            {
                "anketa": "main",
                "quest": "promocode"
            },
            {
                "anketa": "custom",
                "quest": "phone"
            }
        ],
        "rows": [
            [
                "example1@sendsay.ru",
                "Андрей",
                "51079-458",
                "89519441111"
            ],
            [
                "example2@sendsay.ru",
                "Соня",
                "51080-141",
                "89619252222"
            ],
            [
                "example3@sendsay.ru",
                "Алиса",
                "49288-050",
                "89289253333"
            ],

            ...........
        ]
    },
    "sendwhen": "now"
}

Статистика​

Узнать подробнее об универсальной статистике можно в API-документации, а также в статье Базовые представления о получении статистики через stat.uni

Получить список email-адресов и архив письма по номеру выпуска​

{
    "action": "stat.uni",
    "select": [
        "deliv.member.email",
        "deliv.letter.archive"
    ],
    "filter": [{
        "a": "deliv.issue.id",
        "op": "==",
        "v": "номер вашего выпуска"
    }],
    "result": [{
        "type": "save",
        "to": "test",
        "format": "xlsx"
    }]
}

Получить статистику доставки, открытия и переходов по конкретному email​

{
    "action": "stat.uni",
    "groupby": "1",
    "join": [{
            "select": [
                "count(deliv.member.email)"
            ],
            "filter": [{
                "a": "deliv.member.email",
                "op": "==",
                "v": "email, по которому получаем статистику"
            }]
        },
        {
            "select": [
                "count(read.member.email)"
            ],
            "filter": [{
                "a": "read.member.email",
                "op": "==",
                "v": "email, по которому получаем статистику"
            }]
        },
        {
            "select": [
                "count(click.member.email)"
            ],
            "filter": [{
                "a": "click.member.email",
                "op": "==",
                "v": "email, по которому получаем статистику"
            }]
        }
    ]
}

Посмотреть статистику по письмам за период​

{
    "action": "stat.uni",
    "select": [
        "deliv.member.email",
        "deliv.letter.id",
        "deliv.result",
        "deliv.status",
        "deliv.dt"
    ],
    "filter": [
        {
            "a": "deliv.letter.dt:YD",
            "op": ">=",
            "v": "2025-01-01"
        },
        {
            "a": "deliv.letter.dt:YD",
            "op": "<=",
            "v": "2025-01-31"
        }
    ]
}

Посмотреть статистику по письму (letter.id)​

При отправке на группу personal, в ответе возвращается параметр letter. Это id конкретного транзакционного письма, по которому его можно отследить с помощью запроса к универсальной статистике.

{
    "action": "stat.uni",
    "select": [
        "deliv.member.email",
        "deliv.letter.id",
        "deliv.result",
        "deliv.status"
    ],
    "filter": [{
        "a": "deliv.letter.id",
        "op": "==",
        "v": "id вашего письма"
    }]
}

Посмотреть причины отписки за последние 7 дней​

{
    "action": "stat.uni",
    "result": [{
        "type": "save",
        "to": "report",
        "format": "xlsx"
    }],
    "caption": [
        "email",
        "причина",
        "id выпуска",
        "дата отписки"
    ],
    "select": [
        "unsub.member.email",
        "unsub.why",
        "unsub.issue.id",
        "unsub.dt",
        "unsub.reason",
    ],
    "filter": [{
        "a": "unsub.dt:YD",
        "op": ">=",
        "v": "current -7 day"
    }]
}

Посмотреть статистику заполнения и подтверждения формы​

{
  "action": "stat.uni",
  "select": [
    "form.member.email",
    "form.member.dt_fill",
    "form.member.dt_confirm"
  ],
  "filter": [
    {
      "a": "form.id",
      "op": "==",
      "v": "id формы"
    }
  ]
}

Посмотреть статистику транзакционных выпусков по черновику за всё время​

{
    "action": "stat.uni",
    "result": [{
        "type": "save",
        "to": "report",
        "format": "xlsx"
    }],
    "select": [
        "member.email",
        "issue.dt",
        "issue.group.name",
        "issue.members",
        "issue.deliv_ok",
        "issue.deliv_bad",
        "issue.readed",
        "issue.u_readed",
        "issue.clicked",
        "issue.u_clicked",
        "issue.unsubed",
        "issue.group.gid"
    ],
    "filter": [{
            "a": "issue.draft.id",
            "op": "==",
            "v": "51"
        },
        {
            "a": "issue.group.gid",
            "op": "==",
            "v": "personal"
        }
    ]
}