Dokumentacja / Szybki start

Autentykacja

3 min czytania

Wszystkie żądania API wymagają uwierzytelnienia kluczem API. Ta strona wyjaśnia jak tworzyć, używać i zarządzać kluczami API.

Format klucza API

Klucze API Outboxa wyglądają tak:

ob_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
ob_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Prefiks Typ Działanie
ob_live_ Produkcyjny Emaile są wysyłane naprawdę
ob_test_ Testowy (sandbox) Nic nie jest wysyłane — do testowania integracji

Klucze testowe (sandbox)

Klucz testowy przechodzi dokładnie tę samą ścieżkę API co produkcyjny — uwierzytelnianie, walidację, limity pól, idempotencję, rate limiting, kształt odpowiedzi i webhooki — ale żaden email nie opuszcza naszych serwerów.

Utworzysz go w panelu (Klucze API → Nowy klucz → Testowy) albo przez API:

curl -X POST https://api.mailingapi.com/v1/api-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Testy integracji", "domain_id": "...", "permissions": ["send", "read"], "mode": "test"}'

Czym różnią się klucze testowe:

  • Wiadomości mają "sandbox": true w każdej odpowiedzi i w payloadzie webhooka.
  • Symulowany wynik zależy od odbiorcy:
Odbiorca Wynik Webhook
bounce@simulator.mailingapi.com bounced (hard bounce, error_code: "hard_bounce") message.bounced
adres z Twojej suppression list rejected —
każdy inny adres delivered z smtp_response: "250 sandbox: not sent" message.delivered
  • Domena nadawcy nie musi być jeszcze zweryfikowana, ale adres from nadal musi być z domeny klucza.
  • Wiadomości sandbox nie liczą się do miesięcznego ani dziennego limitu planu, dziennego limitu domeny, limitu per odbiorca, statystyk ani reputacji. Rate limity API (na sekundę / minutę) obowiązują.
  • Klucze testowe nie liczą się do limitu kluczy API w planie.
  • Klucz testowy widzi w GET /v1/messages tylko wiadomości sandbox, a produkcyjny — tylko produkcyjne.
  • Wiadomości sandbox są usuwane po 7 dniach.

Używanie klucza API

Dołącz klucz API w nagłówku Authorization ze schematem Bearer:

curl -X POST https://api.mailingapi.com/v1/messages/send \
  -H "Authorization: Bearer ob_live_twój_klucz" \
  -H "Content-Type: application/json" \
  -d '{"from": "...", "to": "...", "subject": "...", "html": "..."}'

Python

import requests

headers = {
    "Authorization": "Bearer ob_live_twój_klucz",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.mailingapi.com/v1/messages/send",
    headers=headers,
    json={...}
)

JavaScript

const response = await fetch('https://api.mailingapi.com/v1/messages/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ob_live_twój_klucz',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({...})
});

Uprawnienia kluczy API

Każdy klucz API ma poziom uprawnień kontrolujący dostępne operacje:

Uprawnienie Może wykonać
send Wysyłać emaile, analizować treść
read Odczytywać wiadomości, zdarzenia, statystyki
manage Zarządzać domenami, szablonami, webhookami, kluczami API
admin Pełny dostęp włącznie z billingiem

Tworząc klucz API, wybierz minimalne wymagane uprawnienia. Jeśli Twój backend tylko wysyła emaile, użyj klucza z uprawnieniem send.

Powiązanie z domeną

Każdy klucz API jest powiązany z konkretną domeną. Adres from w emailach musi odpowiadać domenie klucza:

Domena klucza: notifications.example.com
✓ from: "alerts@notifications.example.com"
✓ from: "no-reply@notifications.example.com"
✗ from: "hello@inna-domena.com" — błąd

To zapobiega nieautoryzowanej wysyłce z domen, których nie kontrolujesz.

Tworzenie kluczy API

Przez Dashboard

  1. Przejdź do Ustawienia → Klucze API
  2. Kliknij Utwórz nowy klucz
  3. Wybierz domenę i uprawnienia
  4. Skopiuj i bezpiecznie przechowaj klucz

Pełny klucz jest pokazywany tylko raz. Przechowuj go w menedżerze sekretów lub zmiennych środowiskowych.

Przez API

curl -X POST https://api.mailingapi.com/v1/api-keys \
  -H "Authorization: Bearer ob_live_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Production",
    "domain_id": "dom_123abc",
    "permissions": ["send", "read"]
  }'

Rotacja kluczy

Aby rotować klucz bez przestoju:

  1. Utwórz nowy klucz z tymi samymi uprawnieniami
  2. Zaktualizuj aplikację, by używała nowego klucza
  3. Usuń lub unieważnij stary klucz

Lub użyj wbudowanej rotacji z okresem karencji:

curl -X POST https://api.mailingapi.com/v1/api-keys/key_123/rotate \
  -H "Authorization: Bearer ob_live_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"grace_period_minutes": 60}'

Oba klucze działają w okresie karencji, dając czas na wdrożenie aktualizacji.

Dobre praktyki bezpieczeństwa

Rób

  • Przechowuj klucze w zmiennych środowiskowych lub menedżerze sekretów
  • Używaj osobnych kluczy dla różnych środowisk (staging, produkcja)
  • Używaj minimalnych wymaganych uprawnień
  • Rotuj klucze regularnie (zalecane co 90 dni)
  • Monitoruj użycie kluczy w dashboardzie

Nie rób

  • Nie commituj kluczy do kontroli wersji
  • Nie dziel kluczy między aplikacjami
  • Nie używaj kluczy admin gdy wystarczy send
  • Nie loguj kluczy API w aplikacji

Obsługa błędów autentykacji

Jeśli autentykacja się nie powiedzie, otrzymasz odpowiedź 401 Unauthorized:

{"error": {"message": "Invalid or missing API key"}}

Częste przyczyny:

  • Brak nagłówka Authorization
  • Nieprawidłowy format klucza (nie zaczyna się od ob_)
  • Unieważniony lub usunięty klucz
  • Klucz nie ma wymaganych uprawnień
  • Adres from nie pasuje do domeny klucza

Rate limiting

Żądania API są limitowane per klucz. Udane odpowiedzi zawierają nagłówki X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset (Unix epoch w sekundach). Gdy przekroczysz limit, otrzymasz 429 Too Many Requests:

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

Każda odpowiedź 429 zawiera standardowy nagłówek Retry-After (liczba całkowita sekund) oraz tę samą wartość jako retry_after w body. Poczekaj tyle sekund przed ponowną próbą; zalecamy czytanie nagłówka Retry-After. Wszystkie nagłówki opisuje Przegląd API → Rate limiting.

Limity per akcja klucza API:

Akcja Domyślny limit
Wysyłka emaila 100/minutę
Endpointy odczytu 1000/minutę
Zarządzanie 100/minutę

Następne kroki

Teraz, gdy rozumiesz autentykację, naucz się obsługiwać błędy.

Obsługa błędów →