Как отправить письмо через API: PHP, Node, Python, Go

Как отправить письмо через API

Чтобы отправить письмо через API YourTrend, сделайте POST-запрос на https://yourtrend.online/api/v1/messages с заголовком Authorization: Bearer YOUR_API_KEY и JSON-телом с полями from, to, subject и html. Сервер отвечает 202 Accepted, ставит письмо в очередь и подписывает его DKIM. Ниже — рабочие примеры на curl и четырёх SDK.

Получите API-ключ и подтвердите домен

Ключ создаётся в панели в разделе «API-ключи» — у него есть скоупы (например messages:send). Отправлять можно только с адреса на проверенном домене: добавьте домен, опубликуйте записи SPF, DKIM и DMARC и дождитесь статуса verified. Подробности — в документации, а бесплатная проверка домена есть в лаборатории доставляемости.

Быстрый старт: curl

curl -X POST https://yourtrend.online/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "to": "user@example.com",
    "subject": "Добро пожаловать!",
    "html": "<h1>Привет!</h1><p>Спасибо за регистрацию.</p>",
    "stream": "transactional"
  }'

Успешный ответ — HTTP 202:

{
  "data": {
    "id": "9b1c7e2a-1f3d-4b8a-9c11-4a2f6e8d0c33",
    "status": "queued",
    "stream": "transactional",
    "from": "noreply@yourdomain.com",
    "to": "user@example.com",
    "subject": "Добро пожаловать!"
  }
}

PHP

Скачайте однофайловый SDK по адресу /sdk/yourtrend.php — зависимостей нет, нужен только модуль cURL.

<?php
require 'yourtrend.php';

$yt  = new YourTrend('YOUR_API_KEY');
$res = $yt->sendEmail(
    'noreply@yourdomain.com',
    'user@example.com',
    'Добро пожаловать!',
    '<h1>Привет!</h1>'
);

if ($res['status'] === 202) {
    echo 'В очереди: ' . $res['data']['data']['id'];
} else {
    echo 'Ошибка: ' . ($res['data']['error']['message'] ?? 'unknown');
}

Node.js

SDK /sdk/yourtrend.js использует встроенный fetch (Node 18+), внешних пакетов не требует.

const YourTrend = require('./yourtrend');
const yt = new YourTrend('YOUR_API_KEY');

const { status, data } = await yt.sendEmail(
  'noreply@yourdomain.com',
  'user@example.com',
  'Добро пожаловать!',
  '<h1>Привет!</h1>'
);

if (status === 202) console.log('В очереди:', data.data.id);
else console.error('Ошибка:', data.error?.message);

Python

SDK /sdk/yourtrend.py написан на чистой стандартной библиотеке (urllib), ставить ничего не нужно.

from yourtrend import YourTrend

yt = YourTrend('YOUR_API_KEY')
res = yt.send_email(
    'noreply@yourdomain.com',
    'user@example.com',
    'Добро пожаловать!',
    '<h1>Привет!</h1>',
)

if res['status'] == 202:
    print('В очереди:', res['data']['data']['id'])
else:
    print('Ошибка:', res['data']['error']['message'])

Go

package main

import (
    "fmt"
    "log"
    "yourtrend"
)

func main() {
    c := yourtrend.New("YOUR_API_KEY")
    resp, err := c.SendEmail(
        "noreply@yourdomain.com",
        "user@example.com",
        "Добро пожаловать!",
        "<h1>Привет!</h1>",
    )
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    fmt.Println("HTTP", resp.StatusCode) // 202 = принято
}

Дополнительные поля

Тело запроса принимает больше, чем базовые четыре поля:

• text — текстовая версия письма (рекомендуется вместе с html).
• cc, bcc, reply_to — списки адресов или строка через запятую.
• stream — transactional или bulk: разделение потоков бережёт репутацию IP.
• attachments — массив объектов {filename, content, content_type}, где content закодирован в base64.
• template_id + variables — отправка по готовому шаблону с подстановками.
• send_at — ISO-8601 время для отложенной отправки.

Идемпотентность и тест-режим

Добавьте заголовок Idempotency-Key: <uuid> — при повторе того же запроса (например, после таймаута) YourTrend вернёт первый ответ и не отправит дубликат. Заголовок X-Test-Mode: true прогоняет запрос без реальной доставки и без списания квоты — удобно для CI.

Обработка ошибок

Все ошибки API приходят в едином конверте:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Daily sending limit reached.",
    "request_id": "0f9d…"
  }
}

Проверяйте HTTP-код, а не только тело. Частые коды: 401 — неверный ключ; 422 — ошибка валидации (поле errors со списком проблем по каждому полю); 429 — превышен лимит запросов, повторите с экспоненциальной задержкой; 402/quota_exceeded — исчерпана квота тарифа. Для массовых рассылок используйте POST /api/v1/messages/batch (до 1000 писем, ответ 207 с индивидуальным статусом каждого).

Хотите обёртку под свой стек? SDK YourTrend для PHP, Node, Python и Go — это по одному файлу без зависимостей: их можно просто скопировать в проект. Полный список эндпоинтов и полей смотрите в документации API, а тарифы на объёмы — на странице цен.

Проверка статуса и вебхуки

После постановки в очередь статус письма можно узнать запросом GET /api/v1/messages/{id} — в ответе поля status (queued, sent, delivered, bounced, complained) и счётчики открытий и жалоб. Опрашивать API на каждое письмо неэффективно, поэтому для событий доставки настройте вебхуки: YourTrend присылает POST на ваш URL при событиях delivered, opened, clicked, bounced и complained. Каждый вызов подписан HMAC в заголовке — проверяйте подпись, чтобы отсеять подделки, и отвечайте 2xx за несколько секунд; при ошибке доставка вебхука повторяется с возрастающей задержкой (очередь повторов). Так строится надёжная обработка отказов: жёсткие возвраты уходят в стоп-лист, на жалобы вы реагируете сразу, а собственная аналитика собирается без ручного опроса. Полный список типов событий и формат полезной нагрузки — в документации, а тарифы на объёмы отправки — на странице цен.