API-документация CogaSystem
Подключение API CogaSystem: получение ключа, отправка писем, управление получателями и шаблонами, статистика и webhook-уведомления.
API позволяет связать CogaSystem с сайтом, CRM или другим приложением. Приложение передаёт запросы сервису, а сервис возвращает данные о выполненной операции или описание ошибки.
Что можно делать через API
- Отправлять одиночные сообщения и управлять email-рассылками.
- Создавать группы получателей, добавлять и обновлять контакты.
- Работать с шаблонами и передавать параметры для персонализации писем.
- Получать статусы сообщений и статистику рассылок.
- Получать webhook-уведомления о доставках, открытиях, переходах, отписках и жалобах.
Ключевой принцип. API-ключ предоставляет доступ к аккаунту. Храните его на стороне сервера и не размещайте в открытом коде страницы, публичном репозитории или скриншотах.
Как подключиться к API
- Получите ключ. В личном кабинете откройте «Автоматизация» → «API и SMTP» → «Параметры подключения API и SMTP».
- Укажите базовый адрес. Используйте https://api.msndr.net/v1. Путь конкретного метода добавляется к этому адресу согласно документации.
- Добавьте авторизацию. Передавайте заголовок Authorization: Bearer YOUR_API_TOKEN, заменив YOUR_API_TOKEN своим ключом.
- Укажите формат данных. Для JSON-запросов добавляйте заголовок Content-Type: application/json. Для загрузки вложений следуйте отдельному примеру выбранного метода.
- Проверьте подключение. Начните с получения списка групп методом GET /email/lists. Такой запрос позволяет проверить авторизацию без отправки писем.
- Обрабатывайте результат. Проверяйте HTTP-статус и тело ответа. Успешное принятие сообщения в очередь ещё не означает его доставку получателю.
Что учитывать при интеграции
- Для отправки действуют ограничения и правила сервиса. Ответ 429 означает ограничение частоты или объёма запросов на отправку; учитывайте текст ошибки перед повторной попыткой.
- При получении списков проверяйте параметры постраничной выдачи, чтобы не пропустить часть данных.
- Перед запуском отправки проверьте адрес отправителя, настройки домена, содержание письма и доступные ресурсы аккаунта.
- После тестовой отправки проверяйте статус сообщения и события, а не только успешный ответ на исходный запрос.
Обратите внимание. API не отменяет требования к качеству базы, согласию получателей и обработке отписок. Не повторяйте отправку автоматически без проверки результата предыдущего запроса: это может привести к дублированию писем.
Документация и примеры запросов
В документации описаны методы, параметры, форматы ответов, ограничения и webhook-события. Доступны примеры cURL и PHP.