Dokumentacja / API Reference

Przegląd API

2 min czytania

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ę

Nagłówki rate limit są dołączone do odpowiedzi:

x-ratelimit-limit: 100
x-ratelimit-remaining: 95
x-ratelimit-reset: 1705315860

Przy przekroczeniu limitu otrzymujesz 429 Too Many Requests:

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

Idempotencja

Dla żądań POST używaj kluczy idempotencji by zapobiec duplikatom:

curl -X POST https://api.mailingapi.com/v1/messages/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: unikalne-id-zadania-123" \
  -d '{...}'
  • Klucze są ważne przez 24 godziny
  • Powtórzone żądania z tym samym kluczem zwracają oryginalną odpowiedź
  • Używaj UUID lub unikalnych identyfikatorów

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:

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