Jak wysłać e-mail za pomocą API: PHP, Node, Python, Go

Jak wysłać e-mail za pomocą API

To send an email through the YourTrend API, make a POST request to https://yourtrend.online/api/v1/messages with an Authorization: Bearer YOUR_API_KEY header and a JSON body containing from, to, subject and html. The server responds 202 Accepted, queues the message and signs it with DKIM. Below are working examples in curl and four SDKs.

Uzyskaj klucz API i zweryfikuj swoją domenę

Utwórz klucz w panelu w sekcji "Klucze API" — każdy klucz ma zakresy takie jak messages:send. Możesz wysyłać tylko z adresu na zweryfikowanej domenie: dodaj domenę, opublikuj SPF, DKIM i DMARC, a następnie poczekaj na status verified. Zobacz dokumentację i sprawdź domenę za darmo w laboratorium dostarczalności.

Szybki start: 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": "Witamy!",
    "html": "<h1>Cześć</h1><p>Dziękujemy za rejestrację.</p>",
    "stream": "transactional"
  }'

Sukces odpowiedzi to HTTP 202:

{
  "data": {
    "id": "9b1c7e2a-1f3d-4b8a-9c11-4a2f6e8d0c33",
    "status": "queued",
    "stream": "transactional",
    "from": "noreply@yourdomain.com",
    "to": "user@example.com",
    "subject": "Witamy!"
  }
}

PHP

Pobierz SDK w jednym pliku z /sdk/yourtrend.php — bez zależności, tylko rozszerzenie cURL.

<?php
require 'yourtrend.php';

$yt  = new YourTrend('YOUR_API_KEY');
$res = $yt->sendEmail(
    'noreply@yourdomain.com',
    'user@example.com',
    'Witamy!',
    '<h1>Cześć</h1>'
);

if ($res['status'] === 202) {
    echo 'W kolejce: ' . $res['data']['data']['id'];
} else {
    echo 'Błąd: ' . ($res['data']['error']['message'] ?? 'nieznany');
}

Node.js

SDK /sdk/yourtrend.js korzysta z wbudowanego fetch (Node 18+) i nie wymaga zewnętrznych pakietów.

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

const { status, data } = await yt.sendEmail(
  'noreply@yourdomain.com',
  'user@example.com',
  'Witamy!',
  '<h1>Cześć</h1>'
);

if (status === 202) console.log('W kolejce:', data.data.id);
else console.error('Błąd:', data.error?.message);

Python

SDK /sdk/yourtrend.py jest czystą biblioteką standardową (urllib) — nic do zainstalowania.

from yourtrend import YourTrend

yt = YourTrend('YOUR_API_KEY')
res = yt.send_email(
    'noreply@yourdomain.com',
    'user@example.com',
    'Witamy!',
    '<h1>Cześć!</h1>',
)

if res['status'] == 202:
    print('W kolejce:', res['data']['data']['id'])
else:
    print('Błąd:', res['data']['error']['message'])

Idź

package main

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

func main() {
    c := yourtrend.New("YOUR_API_KEY")
    resp, err := c.SendEmail(
        "noreply@yourdomain.com",
        "user@example.com",
        "Witamy!",
        "<h1>Cześć!</h1>",
    )
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    fmt.Println("HTTP", resp.StatusCode) // 202 = zaakceptowane
}

Dodatkowe pola

Treść żądania akceptuje więcej niż cztery podstawowe:

text — alternatywa w formacie czystego tekstu (zalecana obok html).
cc, bcc, reply_to — tablice adresów lub ciąg oddzielony przecinkami.
strumień — transakcyjny lub masowy: dzielenie strumieni chroni Twoją reputację IP.
załączniki — tablica obiektów {nazwa_pliku, zawartość, typ_zawartości}, z zawartością zakodowaną w base64.
id_szablonu + zmienne — wyślij zapisany szablon z substytucjami.
wyślij_o — znacznik czasu ISO-8601 dla zaplanowanej dostawy.

Idempotencja i tryb testowy

Dodaj nagłówek Idempotency-Key: <uuid> — przy ponownym wysłaniu tej samej prośby (na przykład po upływie czasu) YourTrend zwraca pierwszą odpowiedź zamiast wysyłać duplikat. Nagłówek X-Test-Mode: true uruchamia żądanie bez rzeczywistej dostawy i bez zużywania limitu — przydatne w CI.

Obsługa błędów

Każdy błąd API przychodzi w jednej kopercie:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Osiągnięto dzienny limit wysyłania.",
    "request_id": "0f9d…"
  }
}

Sprawdź status HTTP, a nie tylko treść. Powszechne kody: 401 — zły klucz; 422 — błąd walidacji (pole błędy wymienia problem dla każdego pola); 429 — limit szybkości, spróbuj ponownie z wykładniczym opóźnieniem; 402/quota_exceeded — limit planu wyczerpany. Dla zadań masowych użyj POST /api/v1/messages/batch (do 1000 wiadomości, odpowiedź 207 z statusem dla każdej wiadomości).

Chcesz opakowanie dla swojego stosu? SDK YourTrend dla PHP, Node, Python i Go to jeden plik bez zależności — skopiuj je bezpośrednio do swojego projektu. Pełna lista punktów końcowych i pól znajduje się w dokumentacji API, a poziomy wolumenu są na stronie cennikowej.

Sprawdzanie statusu i webhooków

Po dodaniu do kolejki, możesz odczytać status wiadomości za pomocą GET /api/v1/messages/{id} — odpowiedź zawiera status (w kolejce, wysłane, dostarczone, odrzucone, skargowe) oraz liczby otwarć i skarg. Polling API dla każdej wiadomości jest nieefektywny, więc skonfiguruj webhooki dla zdarzeń dostawy: YourTrend wysyła POST do Twojego URL po dostarczeniu, otwarciu, kliknięciu, odrzuceniu i skardze. Każde wywołanie jest podpisane HMAC w nagłówku — zweryfikuj podpis, aby odrzucić fałszywki, i odpowiedz 2xx w ciągu kilku sekund; w przypadku niepowodzenia webhook jest ponawiany z rosnącym opóźnieniem (kolejka ponownych prób). Tak budujesz solidną obsługę błędów: twarde odrzucenia trafiają na listę tłumienia, skargi otrzymują natychmiastową reakcję, a Twoja własna analityka wypełnia się bez ręcznego pollingu. Pełna lista typów zdarzeń i kształt ładunku znajduje się w dokumentacji, a poziomy wysyłania są na stronie cennikowej.

Jak wysłać e-mail za pomocą API: PHP, Node, Python, Go