REST API v1

Базовый URL: https://api.nntr.ru/api/v1. Аутентификация: Authorization: Bearer <API-ключ>. Формат — JSON.

POST /messages — отправка

* Либо raw-тело, либо template_id — что-то одно обязательно.

Другие эндпоинты

• POST /messages-batch — до 50 писем, индивидуальные переменные
• GET /messages?status=&to=&tag=&limit= — список с фильтрами
• GET /messages/{id} — статус + события
• POST /domains · GET /domains · POST /domains/{id}/verify
• GET/POST /templates · GET/PATCH/DELETE /templates/{id}
• GET /suppression · DELETE /suppression/{email}
• POST /chains/{trigger_key}/trigger — запуск цепочки
• GET /usage — лимит и потребление

Sandbox-режим

Ключ nntr_sandbox_… проходит всю валидацию (домен, лимиты, переменные шаблона), но не отправляет письмо реально — идеален для CI.

SMTP-подключение

Для сайтов без разработчиков: WordPress, Битрикс, самописные CMS. Порт 25 отключён, используйте 587 (STARTTLS) или 465 (SSL).

SMTP relay принимает письма только для верифицированных доменов проекта. Лимиты учитываются вместе с REST API (единый счётчик).

Готовые конфиги: PHP/PHPMailer, Symfony Mailer

$mail->isSMTP();
$mail->Host = 'smtp.nntr.ru';
$mail->SMTPAuth = true;
$mail->Username = 'smtp-xxxx';
$mail->Password = 'ваш-пароль';
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->Port = 587;

Node.js / Nodemailer

const t = nodemailer.createTransport({
  host: 'smtp.nntr.ru', port: 587, secure: false,
  auth: { user: 'smtp-xxxx', pass: 'пароль' },
});
await t.sendMail({ from: '"Сайт" <no-reply@домен.ru>', to: 'client@example.com', subject: 'Заказ', html: '<b>Готово</b>' });

Python / smtplib, Django

# smtplib
with smtplib.SMTP('smtp.nntr.ru', 587) as s:
    s.starttls(); s.login('smtp-xxxx', 'пароль'); s.send_message(msg)

# Django settings.py
EMAIL_HOST = 'smtp.nntr.ru'; EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = 'smtp-xxxx'; EMAIL_HOST_PASSWORD = 'пароль'

Laravel

// config/mail.php → mailers.smtp
'host' => 'smtp.nntr.ru', 'port' => 587,
'encryption' => 'tls',
'username' => 'smtp-xxxx', 'password' => 'пароль',

WordPress (WP Mail SMTP / FluentSMTP)

Host: smtp.nntr.ru / Port: 587 / Encryption: TLS
Auth: ON / Username: smtp-xxxx / Password: пароль
From Email: no-reply@вашдомен.ru

1С-Битрикс

Настройки → Почта → SMTP: smtp.nntr.ru:587 (TLS), логин/пароль из кабинета nntr

DNS: SPF, DKIM, DMARC

Для чайников

Это три TXT-записи у вашего DNS-провайдера (где куплен домен). SPF говорит «через какие сервера можно слать письма от моего имени», DKIM ставит цифровую подпись на каждое письмо (её проверяет получатель), DMARC говорит провайдеру, что делать с подделками. Без них письма улетят в спам.

Для экспертов

# SPF (TXT на корень домена; если SPF уже есть — добавьте include в существующую)
v=spf1 include:spf.nntr.ru ~all

# DKIM (TXT на <selector>._domainkey.вашдомен.ru — значение генерируется per-domain)
nntr123._domainkey  TXT  "v=DKIM1; k=rsa; p=MIIBIjANBgkq..."

# DMARC (TXT на _dmarc.вашдомен.ru) — рекомендовано
"v=DMARC1; p=none; rua=mailto:dmarc@nntr.ru"

# Return-Path выравнивание (CNAME)
rp-xxxx.вашдомен.ru  CNAME  rp.nntr.ru

Режимы DMARC: p=none — только отчёты (начните с него); p=quarantine — подозрительные письма в спам; p=reject — отклонять. Переходите к строгим режимам после 2–4 недель чистых отчётов. Сервис не требует DMARC, но настоятельно рекомендует.

Вебхуки

15 событий: message.queued/sent/delivered/bounced/complained/opened/clicked/failed, domain.verified/verification_failed, usage.threshold_reached/limit_exceeded, subscription.renewed/payment_failed, chain.step_completed.

Каждый POST содержит заголовки:

X-nntr-Event: message.delivered
X-nntr-Signature: sha256=<hex HMAC-SHA256 от raw body с вашим секретом>
X-nntr-Delivery: <id доставки для ретраев>

{"id":"01J8...","event":"message.delivered","created_at":"...","data":{"id":"...","to":"..."}}

Проверка подписи (3 языка)

# Python
import hmac, hashlib
expected = hmac.new(SECRET.encode(), raw_body, hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, sig.removeprefix('sha256='))

# Node.js
const ok = crypto.timingSafeEqual(
  Buffer.from(crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex')),
  Buffer.from(sig.replace('sha256=', '')))

# PHP
$ok = hash_equals(hash_hmac('sha256', $rawBody, $secret), str_replace('sha256=', '', $sig));

Ретраи: недоступный endpoint ретраится с экспоненциальным backoff до 24 часов. Журнал попыток (payload, HTTP-код, повтор вручную) — в кабинете: Проект → Вебхуки.

Конструктор цепочек

Типовые сценарии: welcome-серия (регистрация → приветствие → через день гайд → если открыл — тег engaged), брошенная корзина (3 часа → напоминание → день → если не кликнул — последний шанс), реактивация (нет активности 30 дней → письмо → 7 дней → проверка).

Запуск через API:

curl -X POST https://api.nntr.ru/api/v1/chains/trg_ваш_ключ/trigger \
  -H "Authorization: Bearer nntr_live_..." \
  -d '{"email":"user@example.com","context":{"name":"Иван","plan":"premium"}}'

Узлы: триггер, письмо (шаблон + переменные), задержка (минуты/часы/дни + тихие часы), условие (поле/тег/открыл/кликнул), webhook, обновление тега/поля, цель. Валидация: у условия — обе ветки, висячие узлы недопустимы, защита от бесконечных циклов (100 шагов).

⚠ Для маркетинговых цепочек юридически обязательна отписка. nntr автоматически добавляет one-click List-Unsubscribe ссылку в footer писем цепочки и ведёт suppression list отписавшихся.

Коды ошибок API

API Changelog

• 1.0.0 — стартовая версия: /messages, /messages-batch, /domains, /templates, /suppression, /chains/{key}/trigger, /usage; вебхуки 15 событий; Idempotency-Key; sandbox-ключи.

Стратегия версионирования: breaking changes — только с префиксом /v2/, текущий /v1/ стабилен. Deprecations анонсируются за 90 дней в этом changelog и заголовком Sunset.