Разработчикам · API reference

Документация API

Технический справочник по HTTP API Sendarix, аутентификации и типичным паттернам интеграции. Обзор продукта: Email API.

cURL Node SMTP
# Отправить критическое письмо через routing policy
curl -sS -X POST 'https://app.sendarix.com/v1/email/send' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Idempotency-Key: otp_8842' \
  -d '{"to":"user@acme.com","template":"password_reset","routing_policy":"transactional-critical"}'
const sendarix = require("sendarix")(process.env.SENDARIX_KEY);

await sendarix.email.send({
  to: "user@acme.com",
  template: "password_reset",
  routingPolicy: "transactional-critical",
  idempotencyKey: "otp_8842"
});
# Drop-in SMTP — сохраните интеграцию и получите control plane
host:     smtp.sendarix.com
port:     587  (STARTTLS)
username: "your_sending_key"
header:   X-Sendarix-Policy: transactional-critical

Аудит возможностей (эта платформа)

Приведённые ниже числа отражают то, что приложение сегодня отдаёт интеграторам. Любой язык с HTTPS + JSON может вызывать эти endpoints; на странице шесть готовых к копированию стеков примеров.

5

Поверхности интеграции

6

Языки примеров

6

Паттерны использования

Поверхности: (1) транзакционная отправка REST, (2) приём клиентских алертов REST, (3) Deliverability Intel REST, (4) SMTP relay (протокол, не JSON), (5) исходящие engagement webhooks (вы получаете HTTPS POST от Sendarix). Session endpoints дашборда вроде GET /api/keys — браузерные/сессионные потоки, не автоматизация X-API-Key.

Поверхности интеграции

ПоверхностьМеханизмБаза / вход
Транзакционная отправкаPOST JSON, API-ключ аккаунтаPOST /v1/email/send (алиас /v1/send)
Клиентские алертыPOST JSON, тот же ключевой middleware что и для sendPOST /v1/alerts/ingest
Deliverability IntelGET/POST JSON, API-ключ workspace deliverability/api/deliverability/v1/* (7 маршрутов)
SMTP relaySMTP AUTH (хост, порт, логин, пароль из дашборда)См. SMTP Relay
Engagement webhooksВаш HTTPS endpoint принимает подписанные POSTНастройка в приложении → Webhooks

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

  • API-ключ аккаунта (send + alerts): заголовок X-API-Key: … или Authorization: Bearer …. Опциональный query ?api_key= для инструментов; рекомендуются заголовки.
  • API-ключ deliverability: заголовок X-API-Key (область workspace; для Intel / монитора доставляемости).
  • Идемпотентность (send): опциональный заголовок Idempotency-Key для безопасных повторов.

Ключи создаются и ротируются в дашборде клиента (управление API). Режимы scope описаны во внутренней политике для ограниченных ключей.

Send API

POST https://app.sendarix.com/v1/email/send

Поля JSON body (обязательны, если не указано иное):

  • from — проверенный адрес отправителя
  • to — строка или массив адресов
  • subject
  • html и/или text — ожидается хотя бы одно непустое тело (plain text может быть выведен из HTML)
Несколько получателей: API проверяет каждый адрес в to, но текущий транспорт доставляет первому получателю. Для нескольких раздельных доставок — один запрос на получателя (или SMTP для multi-RCPT).

Успешные ответы включают идентификаторы вроде message_id и sx_trace_id для связи с логами и вебхуками.

Приём клиентских алертов

POST https://app.sendarix.com/v1/alerts/ingest

Типичные поля JSON: event_type, severity (info, warning, critical), source, message, опционально entity_type, entity_id, context (object). Доставка зависит от правил алертов в дашборде.

Deliverability Intel API

База: /api/deliverability/v1/. Endpoints: workspaces, clients, domains, blacklist status, генерация отчётов. Все требуют API-ключ workspace deliverability.

GET/workspaces
GET/clients
POST/clients
GET/domains
POST/domains
GET/blacklists/status
POST/reports/generate

SMTP relay и inbound-style вебхуки

SMTP — стандартная передача с учётными данными из дашборда, для legacy и MTA. Engagement webhooks — исходящие от Sendarix на ваш URL для событий доставки и вовлечённости (payload и безопасность — на продуктовой странице).

Inbound webhooks провайдера (например Postal) — инфраструктурные endpoints, не цели интеграции клиента.

Send API — примеры (6 языков)

Замените YOUR_API_KEY и адреса. Один JSON для всех стеков.

# Bash — транзакционная отправка
curl -sS -X POST 'https://app.sendarix.com/v1/email/send' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Idempotency-Key: order-10042-reset' \
  -d '{
    "from": "noreply@example.com",
    "to": "user@example.com",
    "subject": "\u0421\u0431\u0440\u043e\u0441 \u043f\u0430\u0440\u043e\u043b\u044f",
    "text": "\u0418\u0441\u043f\u043e\u043b\u044c\u0437\u0443\u0439\u0442\u0435 \u044d\u0442\u0443 \u0441\u0441\u044b\u043b\u043a\u0443 \u0434\u043b\u044f \u0441\u0431\u0440\u043e\u0441\u0430 \u043f\u0430\u0440\u043e\u043b\u044f.",
    "html": "<p>\u0418\u0441\u043f\u043e\u043b\u044c\u0437\u0443\u0439\u0442\u0435 \u044d\u0442\u0443 \u0441\u0441\u044b\u043b\u043a\u0443 \u0434\u043b\u044f \u0441\u0431\u0440\u043e\u0441\u0430 \u043f\u0430\u0440\u043e\u043b\u044f.</p>"
}'
// Node 18+ (global fetch)
const res = await fetch('https://app.sendarix.com/v1/email/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY',
    'Idempotency-Key': 'order-10042-reset',
  },
  body: JSON.stringify({
    from: 'noreply@example.com',
    to: 'user@example.com',
    subject: "Сброс пароля",
    text: "Используйте эту ссылку для сброса пароля.",
    html: "<p>Используйте эту ссылку для сброса пароля.<\/p>",
  }),
});
console.log(await res.json());
# Python 3
import json, urllib.request

req = urllib.request.Request(
    'https://app.sendarix.com/v1/email/send',
    data=json.dumps({
        'from': 'noreply@example.com',
        'to': 'user@example.com',
        'subject': "Сброс пароля",
        'text': "Используйте эту ссылку для сброса пароля.",
        'html': "<p>Используйте эту ссылку для сброса пароля.<\/p>",
    }).encode(),
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'YOUR_API_KEY',
        'Idempotency-Key': 'order-10042-reset',
    },
    method='POST',
)
with urllib.request.urlopen(req) as r:
    print(r.read().decode())
<?php
$ch = curl_init('https://app.sendarix.com/v1/email/send');
$payload = json_encode([
    'from' => 'noreply@example.com',
    'to' => 'user@example.com',
    'subject' => 'Сброс пароля',
    'text' => 'Используйте эту ссылку для сброса пароля.',
    'html' => '<p>Используйте эту ссылку для сброса пароля.</p>',
]);\ncurl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: YOUR_API_KEY',
        'Idempotency-Key: order-10042-reset',
    ],
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
// Go
package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]any{
        "from":    "noreply@example.com",
        "to":      "user@example.com",
        "subject": "Сброс пароля",
        "text":    "Используйте эту ссылку для сброса пароля.",
        "html":    "<p>Используйте эту ссылку для сброса пароля.<\/p>",
    })
    req, _ := http.NewRequest("POST", "https://app.sendarix.com/v1/email/send", bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    req.Header.Set("Idempotency-Key", "order-10042-reset")
    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
}
# Ruby — net/http
require 'json'
require 'net/http'
uri = URI('https://app.sendarix.com/v1/email/send')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req['X-API-Key'] = 'YOUR_API_KEY'
req['Idempotency-Key'] = 'order-10042-reset'
req.body = {
  from: 'noreply@example.com',
  to: 'user@example.com',
  subject: "Сброс пароля",
  text: "Используйте эту ссылку для сброса пароля.",
  html: "<p>Используйте эту ссылку для сброса пароля.<\/p>",
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Паттерны использования (6)

  1. Одноразовая отправка — один POST на сообщение, без idempotency header.
  2. Идемпотентный retry — тот же Idempotency-Key + body при сбоях сети.
  3. Bearer auth — замените X-API-Key на Authorization: Bearer YOUR_API_KEY.
  4. HTML + text — оба для multipart-alternative там, где поддерживается.
  5. Alert fan-out — POST на /v1/alerts/ingest из мониторов; маршрутизация по политике в UI.
  6. Автоматизация deliverability — poll или изменение Intel под /api/deliverability/v1/* с workspace-ключом.

Защитите критически важную почту по всем tenants.

Перенесите самый критичный поток в Sendarix на этой неделе. Все остальное оставьте там, где оно есть.