Dokumentacja / API Reference

Messages API

4 min czytania

API Messages pozwala wysyłać emaile transakcyjne, śledzić status dostarczenia i zarządzać zaplanowanymi wiadomościami.

Wyślij email

Wyślij pojedynczą wiadomość email.

POST /v1/messages/send

Body żądania

Pole Typ Wymagane Opis
from string Tak Adres nadawcy (musi pasować do zweryfikowanej domeny)
to string/array Tak Adres(y) odbiorcy
subject string Tak Temat wiadomości
html string * Body HTML (* wymagane przynajmniej jedno z html/text)
text string * Body tekstowe
cc array Nie Odbiorcy CC
bcc array Nie Odbiorcy BCC
reply_to string Nie Adres reply-to
headers object Nie Własne nagłówki email
attachments array Nie Załączniki
template_id string Nie ID szablonu do użycia
variables object Nie Zmienne szablonu
tags array Nie Tagi dla analityki
metadata object Nie Własne metadata
tracking object Nie Ustawienia śledzenia
scheduled_at string Nie Data/czas ISO 8601 dla zaplanowanej wysyłki

Przykładowe żądanie

curl -X POST https://api.mailingapi.com/v1/messages/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Twoja Firma <hello@twojadomena.pl>",
    "to": "Jan Kowalski <jan@example.com>",
    "subject": "Twoje zamówienie zostało wysłane",
    "html": "<h1>Zamówienie wysłane</h1><p>Cześć {{name}}, Twoje zamówienie #{{order_id}} jest w drodze!</p>",
    "text": "Zamówienie wysłane\n\nCześć {{name}}, Twoje zamówienie #{{order_id}} jest w drodze!",
    "variables": {
      "name": "Jan",
      "order_id": "12345"
    },
    "tags": ["transactional", "shipping"],
    "metadata": {
      "user_id": "usr_123",
      "order_id": "ord_456"
    }
  }'

Odpowiedź

{
  "id": "msg_1a2b3c4d5e6f",
  "status": "queued",
  "message": "Email queued for delivery"
}

Załączniki

{
  "attachments": [
    {
      "filename": "faktura.pdf",
      "content": "base64-encoded-content",
      "content_type": "application/pdf"
    },
    {
      "filename": "logo.png",
      "content": "base64-encoded-content",
      "content_type": "image/png",
      "content_id": "logo"
    }
  ]
}

Użyj content_id dla obrazów inline, potem odwołuj się przez <img src="cid:logo">.

Opcje śledzenia

Kontroluj śledzenie otwarć i kliknięć per wiadomość:

{
  "tracking": {
    "opens": true,
    "clicks": true
  }
}
Pole Typ Domyślnie Opis
opens boolean true Śledź otwarcia emaili (wstawia pixel śledzący)
clicks boolean true Śledź kliknięcia linków (przepisuje URL-e przez domenę śledzenia)

Gdy oba opens i clicks są ustawione na false, email jest traktowany jako transakcyjny:

  • Pixel śledzący nie jest wstawiany
  • Linki nie są przepisywane
  • Nagłówek List-Unsubscribe nie jest dodawany (zapobiega klasyfikacji emaila jako promocyjny/bulk przez Gmail)

Dobra praktyka: Wyłącz śledzenie dla powiadomień transakcyjnych (resety haseł, potwierdzenia zamówień, alerty systemowe) aby poprawić dostarczalność do inbox. Śledzenie pozostaw włączone dla emaili marketingowych i newsletterów.

{
  "from": "alerty@twojadomena.pl",
  "to": "user@example.com",
  "subject": "Wykryto nowe logowanie",
  "html": "<p>Wykryto nowe logowanie na Twoim koncie.</p>",
  "tracking": {
    "opens": false,
    "clicks": false
  }
}

Wysyłka batch

Wyślij wiele spersonalizowanych emaili w jednym żądaniu.

POST /v1/messages/batch

Używając zmiennych odbiorcy

curl -X POST https://api.mailingapi.com/v1/messages/batch \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@twojadomena.pl",
    "subject": "Witaj, {{name}}!",
    "html": "<p>Cześć {{name}}, Twój kod to {{code}}.</p>",
    "recipient_variables": {
      "alice@example.com": {"name": "Alicja", "code": "ABC123"},
      "bob@example.com": {"name": "Robert", "code": "XYZ789"}
    }
  }'

Używając tablicy wiadomości

curl -X POST https://api.mailingapi.com/v1/messages/batch \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "from": "hello@twojadomena.pl",
        "to": "alice@example.com",
        "subject": "Twoja faktura",
        "html": "<p>Faktura #001 w załączniku.</p>"
      },
      {
        "from": "hello@twojadomena.pl",
        "to": "bob@example.com",
        "subject": "Twój paragon",
        "html": "<p>Paragon #002 w załączniku.</p>"
      }
    ]
  }'

Odpowiedź

{
  "results": [
    {"id": "msg_abc123", "status": "queued", "to": "alice@example.com"},
    {"id": "msg_def456", "status": "queued", "to": "bob@example.com"}
  ],
  "queued": 2,
  "failed": 0
}

Limity

  • Maksymalnie 1000 wiadomości na żądanie
  • Każda wiadomość przetwarzana niezależnie
  • Częściowe błędy nie blokują innych

Pobierz wiadomość

Pobierz szczegóły wysłanej wiadomości.

GET /v1/messages/{message_id}

Przykładowe żądanie

curl https://api.mailingapi.com/v1/messages/msg_1a2b3c4d5e6f \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź

{
  "id": "msg_1a2b3c4d5e6f",
  "from": "hello@twojadomena.pl",
  "to": "jan@example.com",
  "subject": "Twoje zamówienie zostało wysłane",
  "status": "delivered",
  "created_at": "2024-01-15T10:30:00Z",
  "delivered_at": "2024-01-15T10:30:05Z",
  "tags": ["transactional", "shipping"],
  "metadata": {
    "user_id": "usr_123",
    "order_id": "ord_456"
  },
  "events": [
    {"type": "queued", "timestamp": "2024-01-15T10:30:00Z"},
    {"type": "sent", "timestamp": "2024-01-15T10:30:02Z"},
    {"type": "delivered", "timestamp": "2024-01-15T10:30:05Z"},
    {"type": "opened", "timestamp": "2024-01-15T11:45:00Z"}
  ]
}

Statusy wiadomości

Status Opis
queued Wiadomość zaakceptowana, czeka na wysyłkę
sending Wiadomość jest wysyłana
sent Wiadomość wysłana do serwera odbiorcy
delivered Wiadomość zaakceptowana przez serwer odbiorcy
bounced Wiadomość odrzucona przez serwer odbiorcy
deferred Tymczasowy błąd, ponowimy próbę
failed Permanentny błąd

Lista wiadomości

Pobierz listę wysłanych wiadomości.

GET /v1/messages

Parametry zapytania

Parametr Typ Opis
page integer Numer strony (domyślnie: 1)
per_page integer Elementów na stronę (domyślnie: 25, max: 100)
from string Data początkowa (ISO 8601)
to string Data końcowa (ISO 8601)
status string Filtruj po statusie
tag string Filtruj po tagu
recipient string Filtruj po emailu odbiorcy

Przykładowe żądanie

curl "https://api.mailingapi.com/v1/messages?status=delivered&from=2024-01-01&per_page=50" \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź

{
  "data": [
    {
      "id": "msg_1a2b3c4d5e6f",
      "from": "hello@twojadomena.pl",
      "to": "jan@example.com",
      "subject": "Twoje zamówienie zostało wysłane",
      "status": "delivered",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 1250,
    "page": 1,
    "per_page": 50,
    "total_pages": 25
  }
}

Analizuj wiadomość

Zwaliduj email przed wysłaniem. Zwraca spam score i potencjalne problemy.

POST /v1/messages/analyze

Przykładowe żądanie

curl -X POST https://api.mailingapi.com/v1/messages/analyze \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@twojadomena.pl",
    "to": "user@example.com",
    "subject": "Testowy email",
    "html": "<p>Treść tutaj</p>"
  }'

Odpowiedź

{
  "valid": true,
  "spam_score": 1.2,
  "issues": [],
  "recommendations": [
    "Rozważ dodanie wersji tekstowej dla lepszej dostarczalności"
  ],
  "preview": {
    "html": "<wyrenderowany html>",
    "text": "<wygenerowany tekst>"
  }
}

Zaplanuj wiadomość

Zaplanuj email na przyszłą dostawę. Użyj scheduled_at w żądaniu wysyłki:

curl -X POST https://api.mailingapi.com/v1/messages/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@twojadomena.pl",
    "to": "user@example.com",
    "subject": "Świąteczne życzenia",
    "html": "<p>Wesołych Świąt!</p>",
    "scheduled_at": "2024-12-25T09:00:00Z"
  }'

Lista zaplanowanych wiadomości

GET /v1/messages/scheduled

Odpowiedź

{
  "data": [
    {
      "id": "msg_abc123",
      "to": "user@example.com",
      "subject": "Świąteczne życzenia",
      "scheduled_at": "2024-12-25T09:00:00Z",
      "status": "scheduled"
    }
  ]
}

Anuluj zaplanowaną wiadomość

DELETE /v1/messages/{message_id}/schedule

Przykładowe żądanie

curl -X DELETE https://api.mailingapi.com/v1/messages/msg_abc123/schedule \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź

{
  "id": "msg_abc123",
  "status": "cancelled",
  "message": "Scheduled message cancelled"
}

Kody błędów

Kod Opis
invalid_from_address Adres from nieprawidłowy lub nie z zweryfikowanej domeny
invalid_to_address Adres to jest nieprawidłowy
missing_subject Temat wymagany
missing_body Body HTML lub tekst wymagane
attachment_too_large Załącznik przekracza 10 MB
too_many_attachments Maksymalnie 10 załączników
invalid_template Szablon nie znaleziony lub nieaktywny
domain_not_verified Domena wysyłkowa nie zweryfikowana
rate_limit_exceeded Za dużo żądań