Przegląd API

REST API MailingAPI pozwala wysyłać emaile transakcyjne, zarządzać domenami, konfigurować webhooki i programowo uzyskiwać dostęp do analityki.

Bazowy URL

Wszystkie żądania API używają tego bazowego URL:

https://api.mailingapi.com/v1

Uwierzytelnianie

Uwierzytelniaj używając tokenów Bearer w nagłówku Authorization:

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

Klucze API są przypisane do pojedynczej domeny. Pobierz swój klucz z Ustawienia → Klucze API.

Zobacz Uwierzytelnianie po szczegóły.

Format żądań

Content-Type

Wysyłaj JSON z Content-Type: application/json:

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", ...}'

Body żądania

Wszystkie żądania POST/PUT/PATCH przyjmują body JSON:

{
  "from": "hello@twojadomena.pl",
  "to": "user@example.com",
  "subject": "Cześć",
  "html": "<p>Witaj świecie</p>"
}

Format odpowiedzi

Wszystkie odpowiedzi zwracają JSON ze spójną strukturą.

Odpowiedź sukcesu

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued",
    "from": "hello@twojadomena.pl",
    "to": "user@example.com",
    "subject": "Cześć",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Odpowiedź listowa

{
  "data": [
    {"id": "550e8400-...", "status": "delivered"}
  ],
  "meta": {
    "count": 25,
    "total": 150,
    "limit": 25,
    "offset": 0,
    "has_more": true
  }
}

Odpowiedź błędu

{
  "error": {
    "message": "Invalid email address format"
  }
}

Metody HTTP

Metoda	Użycie
GET	Pobieranie zasobów
POST	Tworzenie zasobów
PATCH	Częściowa aktualizacja
PUT	Pełna zamiana
DELETE	Usuwanie zasobów

Kody statusów

Kod	Znaczenie
200	Sukces
201	Utworzono
204	Brak treści (udane usunięcie)
400	Złe żądanie (nieprawidłowe dane)
401	Nieautoryzowany (nieprawidłowy/brak klucza API)
403	Zabroniony (niewystarczające uprawnienia)
404	Nie znaleziono
422	Nieobrobialna encja (walidacja nie powiodła się)
429	Za dużo żądań (rate limited)
500	Wewnętrzny błąd serwera

Paginacja

Endpointy listowe wspierają paginację:

curl "https://api.mailingapi.com/v1/messages?limit=25&offset=50" \
  -H "Authorization: Bearer $API_KEY"

Parametry:

• limit — Liczba elementów do pobrania (domyślnie: 25, max: 100)
• offset — Przesunięcie od początku (domyślnie: 0)

Odpowiedź zawiera metadane paginacji:

{
  "data": [...],
  "meta": {
    "count": 25,
    "total": 150,
    "limit": 25,
    "offset": 50,
    "has_more": true
  }
}

Filtrowanie

Wiele endpointów wspiera filtrowanie:

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

Typowe filtry:

• since / until — Zakres dat (ISO 8601)
• status — Status zasobu
• to — Filtruj po odbiorcy

Rate limiting

Żądania API są limitowane per klucz API:

Endpoint	Limit
Wysyłka emaila	100/minutę, 10/sekundę burst
Endpointy odczytu	1000/minutę
Endpointy zarządzania	100/minutę

Udane odpowiedzi zawierają nagłówki:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705315860

X-RateLimit-Reset to znacznik Unix w sekundach. Jeśli domena ma dzienny limit wysyłki, odpowiedzi zawierają też X-Daily-Limit i X-Daily-Remaining.

Przy przekroczeniu limitu otrzymujesz 429 Too Many Requests:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "retry_after": 5
  }
}

Każda odpowiedź 429 zawsze zawiera standardowy nagłówek Retry-After (liczba całkowita sekund) oraz tę samą wartość jako retry_after w body. Zalecamy czytanie nagłówka Retry-After. 429 dla limitu na sekundę lub minutę zawiera też nagłówki X-RateLimit-*; 429 dla limitu dziennego (daily_limit_exceeded) zawiera X-Daily-Limit i X-Daily-Remaining: 0. 429 z kodem recipient_rate_limited oznacza, że ten sam odbiorca dostał od Twojej organizacji za dużo emaili (maks. 10 na godzinę, 50 na dobę). Wszystkie kody błędów opisuje Obsługa błędów.

Dokumentacja API i OpenAPI

Interaktywna dokumentacja API (Swagger UI) jest pod /api/docs i wymaga JavaScript. Specyfikacja OpenAPI 3 w formie maszynowej (JSON) jest pod /api/openapi.

Idempotencja

POST /v1/messages/send, POST /v1/messages/batch i POST /v1/messages/analyze przyjmują nagłówek Idempotency-Key. Wysyłaj ten sam klucz przy ponawianiu żądania — wtedy timeout czy błąd sieci nigdy nie skończy się zdublowanym e-mailem:

curl -X POST https://api.mailingapi.com/v1/messages/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f9c2a8e-6b1d-4c3e-9a7f-2d5e8b1c0a93" \
  -d '{...}'

• Klucz ma 1–255 znaków. Używaj UUID lub innego identyfikatora unikalnego dla danego logicznego żądania (np. ID zamówienia).
• Klucze obowiązują w obrębie klucza API i są ważne przez 24 godziny.
• Nagłówek jest opcjonalny. Bez niego każde żądanie jest przetwarzane niezależnie.
• Batch to jedna całość: ponowienie /v1/messages/batch z tym samym kluczem odtwarza odpowiedź całego batcha — żadna wiadomość z niego nie zostanie wysłana drugi raz.

Sytuacja	Odpowiedź	Ponawiać?
Pierwsze żądanie z kluczem	Przetwarzane normalnie; odpowiedź jest zapisywana	—
Ten sam klucz, to samo body	Oryginalny status i body z nagłówkiem Idempotent-Replayed: true. Nic nie jest wysyłane ponownie	—
Ten sam klucz, inne body	422 idempotency_key_reused	Nie — użyj nowego klucza
Ten sam klucz, pierwsze żądanie wciąż w toku	409 idempotency_request_in_progress, Retry-After: 1	Tak, po Retry-After sekundach
Nieprawidłowy klucz (pusty lub dłuższy niż 255 znaków)	400 invalid_idempotency_key	Nie

Zapisywane i odtwarzane są zarówno odpowiedzi udane, jak i błędy klienta (2xx, 4xx). Błędy serwera (5xx) i 429 nie są zapisywane, więc ponowienie z tym samym kluczem wykona żądanie od nowa.

Body porównywane jest po treści, nie po formatowaniu — zmiana kolejności pól JSON nie oznacza innego body.

Wersjonowanie

API jest wersjonowane przez ścieżkę URL:

https://api.mailingapi.com/v1/...

Utrzymujemy wsteczną kompatybilność wewnątrz głównych wersji. Zmiany łamiące wymagają nowej wersji.

SDK

Oficjalne SDK dostępne:

• Python SDK
• Node.js SDK
• Ruby SDK
• PHP SDK
• Go SDK
• Elixir SDK

Pełna dokumentacja SDK: SDK i biblioteki.

Zasoby API

Zasób	Opis
Messages	Wysyłka i śledzenie emaili
Domains	Zarządzanie domenami wysyłkowymi
Webhooks	Konfiguracja powiadomień o zdarzeniach
Templates	Szablony email
Validation	Walidacja adresów email