Tallker Send
← Все инструкции

API Tallker Send

Отправляйте письма из серверного приложения. Ключ относится к одному проекту и действует только в пределах выбранных прав.

Скачать OpenAPI

Первый запрос

  1. Подтвердите домен и добавьте отправителя.
  2. Создайте API-ключ с правом messages:send.
  3. Сохраните ключ в переменной окружения сервера.
  4. Отправьте письмо и сохраните его 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/keysAPI-ключи
POST/api/v1/smtp-keysSMTP-пароли
GET/api/v1/keysAPI-ключи
DELETE/api/v1/keys/:idAPI-ключи
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 для рекламы.