API Tallker Send
Отправляйте письма из серверного приложения. Ключ относится к одному проекту и действует только в пределах выбранных прав.
Скачать OpenAPIПервый запрос
- Подтвердите домен и добавьте отправителя.
- Создайте API-ключ с правом messages:send.
- Сохраните ключ в переменной окружения сервера.
- Отправьте письмо и сохраните его ID для проверки состояния.
cURL
curl https://send.tallker.com/api/v1/messages \
-H "Authorization: Bearer $TALLKER_SEND_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-confirmation" \
--data '{"from":"orders@your-domain.ru","to":"customer@example.com","subject":"Ваш заказ принят","text":"Спасибо за заказ 1042. Мы сообщим, когда он будет готов.","kind":"transactional"}'JavaScript
const response = await fetch('https://send.tallker.com/api/v1/messages', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.TALLKER_SEND_KEY,
'Content-Type': 'application/json',
'Idempotency-Key': 'order-1042-confirmation'
},
body: JSON.stringify({from:'orders@your-domain.ru',to:'customer@example.com',subject:'Ваш заказ принят',text:'Спасибо за заказ 1042.',kind:'transactional'})
});
const result = await response.json();
if (!response.ok) throw new Error(result.error.message);
console.log(result.data.id);Python
import os, json, urllib.request
payload = dict(from_='orders@your-domain.ru', to='customer@example.com', subject='Ваш заказ принят', text='Спасибо за заказ 1042.', kind='transactional')
payload['from'] = payload.pop('from_')
request = urllib.request.Request('https://send.tallker.com/api/v1/messages', data=json.dumps(payload).encode(), headers={'Authorization':'Bearer '+os.environ['TALLKER_SEND_KEY'],'Content-Type':'application/json','Idempotency-Key':'order-1042-confirmation'}, method='POST')
with urllib.request.urlopen(request, timeout=20) as response:
print(json.load(response)['data']['id'])PHP
<?php
$body = json_encode(['from'=>'orders@your-domain.ru','to'=>'customer@example.com','subject'=>'Ваш заказ принят','text'=>'Спасибо за заказ 1042.','kind'=>'transactional']);
$request = curl_init('https://send.tallker.com/api/v1/messages');
curl_setopt_array($request, [CURLOPT_POST=>true,CURLOPT_POSTFIELDS=>$body,CURLOPT_RETURNTRANSFER=>true,CURLOPT_TIMEOUT=>20,CURLOPT_HTTPHEADER=>['Authorization: Bearer '.getenv('TALLKER_SEND_KEY'),'Content-Type: application/json','Idempotency-Key: order-1042-confirmation']]);
$result = curl_exec($request);
if ($result === false || curl_getinfo($request,CURLINFO_HTTP_CODE) >= 400) throw new RuntimeException('Не удалось отправить письмо');
echo json_decode($result,true)['data']['id'];
curl_close($request);Повторы и ошибки
Один логический запрос — один Idempotency-Key длиной от 8 до 128 знаков. При повторе используйте тот же ключ и то же содержимое. Изменённое содержимое с прежним ключом вернёт 409. Не создавайте новый ключ после сетевого тайм-аута: это может создать второе письмо.
Ответ 202 означает, что письмо принято в очередь. Состояние sent означает подтверждение SMTP-сервера получателя. Состояние delivered появляется только при получении отчёта о доставке. Не все почтовые серверы присылают такие отчёты.
400 — неверный JSON; 401 — ключ не подошёл; 403 — не хватает прав или отправка не разрешена; 404 — запись недоступна; 409 — конфликт; 422 — ошибка данных; 429 — лимит. При 429 учитывайте Retry-After. При uncertain не отправляйте письмо заново без проверки.
Файлы и расписание
attachments — массив из максимум пяти объектов filename и content (Base64), общий размер до 5 МБ. Передавайте sendAt в ISO 8601 с часовым поясом, не более чем на 90 дней вперёд. Для HTML добавьте html, сохранив обязательную текстовую версию text.
Рекламные письма
kind: marketing требует сохранённого согласия получателя. Ссылка отписки добавляется автоматически. Импорт адреса не даёт согласия на рассылку. tracking: true включает ссылки и пиксель для учёта переходов и открытий; заранее убедитесь, что такое измерение соответствует вашим условиям обработки данных. По умолчанию отслеживание отключено.
Методы
| Метод | Адрес | Назначение |
|---|---|---|
| GET | /api/v1/project | Текущий проект |
| GET | /api/v1/domains | Домены |
| POST | /api/v1/domains | Домены |
| POST | /api/v1/domains/:id/verify | Домены |
| POST | /api/v1/senders | Отправители |
| GET | /api/v1/senders | Отправители |
| POST | /api/v1/messages | Письма |
| GET | /api/v1/messages | Письма |
| GET | /api/v1/messages/:id | Письма |
| POST | /api/v1/messages/:id/cancel | Письма |
| GET | /api/v1/statistics | Статистика |
| POST | /api/v1/contacts | Контакты |
| GET | /api/v1/contacts | Контакты |
| POST | /api/v1/suppressions | Исключения |
| GET | /api/v1/suppressions | Исключения |
| POST | /api/v1/keys | API-ключи |
| POST | /api/v1/smtp-keys | SMTP-пароли |
| GET | /api/v1/keys | API-ключи |
| DELETE | /api/v1/keys/:id | API-ключи |
| GET | /api/v1/template-gallery | Галерея шаблонов |
| GET | /api/v1/templates | Шаблоны |
| GET | /api/v1/templates/:id | Шаблоны |
| POST | /api/v1/templates/preview | Шаблоны |
| POST | /api/v1/templates | Шаблоны |
| PUT | /api/v1/templates/:id | Шаблоны |
| GET | /api/v1/templates/:id/versions | Шаблоны |
| POST | /api/v1/templates/:id/test | Шаблоны |
| POST | /api/v1/contacts/import | Контакты |
| GET | /api/v1/contacts/export | Контакты |
| GET | /api/v1/contacts/search | Контакты |
| PATCH | /api/v1/contacts/:id | Контакты |
| DELETE | /api/v1/contacts/:id | Контакты |
| POST | /api/v1/contacts/:id/consent | Контакты |
| POST | /api/v1/contacts/:id/opt-in | Контакты |
| GET | /api/v1/contacts/:id/history | Контакты |
| GET | /api/v1/campaigns | Рассылки |
| POST | /api/v1/campaigns | Рассылки |
| GET | /api/v1/campaigns/:id | Рассылки |
| POST | /api/v1/campaigns/:id/start | Рассылки |
| POST | /api/v1/campaigns/:id/:action | Рассылки |
| GET | /api/v1/automations | Сценарии |
| POST | /api/v1/automations | Сценарии |
| PATCH | /api/v1/automations/:id | Сценарии |
| POST | /api/v1/triggers | Запуск сценария |
| GET | /api/v1/webhooks | Вебхуки |
| POST | /api/v1/webhooks | Вебхуки |
| PATCH | /api/v1/webhooks/:id | Вебхуки |
| DELETE | /api/v1/webhooks/:id | Вебхуки |
| POST | /api/v1/webhooks/:id/test | Вебхуки |
| GET | /api/v1/webhooks/:id/history | Вебхуки |
| GET | /api/v1/team | Команда |
| POST | /api/v1/team/invite | Команда |
| PATCH | /api/v1/team/:id | Команда |
| DELETE | /api/v1/team/:id | Команда |
| POST | /api/v1/projects | Проекты |
| GET | /api/v1/audit | Журнал |
| GET | /api/v1/tickets | Поддержка |
| POST | /api/v1/tickets | Поддержка |
| GET | /api/v1/tickets/:id | Поддержка |
| POST | /api/v1/tickets/:id/reply | Поддержка |
| GET | /api/v1/reports | Отчёты |
| GET | /api/v1/messages-search | Поиск писем |
| GET | /api/v1/billing | Оплата |
| POST | /api/v1/payers | Плательщики |
| POST | /api/v1/orders | Заказы |
| POST | /api/v1/orders/:id/refund-request | Заказы |
| GET | /api/v1/segments | Группы получателей |
| POST | /api/v1/segments | Группы получателей |
| GET | /api/v1/segments/:id | Группы получателей |
| POST | /api/v1/subscription/cancel-renewal | Подписка |
| GET | /api/v1/delivery-status | Готовность к отправке |
| GET | /api/v1/contacts/:id | Контакты |
| POST | /api/v1/contacts/:id/pause | Контакты |
| POST | /api/v1/contacts/:id/merge | Контакты |
Вебхуки
Подключите HTTPS-обработчик в кабинете. Проверяйте HMAC-подпись и время запроса. Повтор одного ID события не должен повторно менять ваши данные.
Формат подписи и повторов →SMTP
smtp.send.tallker.com:587, STARTTLS. Используйте отдельные SMTP-данные. From должен совпадать с MAIL FROM и быть подтверждён. Один SMTP-запрос принимает одного получателя. Для списка отправляйте отдельные письма: это сохраняет независимые статусы и не раскрывает адреса. Передавайте стабильный Message-ID, текстовую часть и X-Tallker-Type: marketing для рекламы.