Як надіслати лист через 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 за кілька секунд; при помилці доставка вебхука повторюється зі зростаючою затримкою (черга повторів). Так будується надійна обробка відмов: жорсткі повернення йдуть у стоп-лист, на скарги ви реагуєте одразу, а власна аналітика збирається без ручного опитування. Повний перелік типів подій і формат корисного навантаження — у документації, а тарифи на обсяги відправлення — на сторінці цін.