Wprowadzenie

Przegląd

API Mailist jest zorganizowane według zasad REST. Nasze API posiada przewidywalne, zorientowane na zasoby adresy URL, przyjmuje żądania zakodowane w JSON, zwraca odpowiedzi w formacie JSON oraz wykorzystuje standardowe kody odpowiedzi HTTP, autentykację i metody HTTP. Za pomocą API Mailist możesz programowo zarządzać kontaktami, listami, kampaniami oraz śledzić wydajność wiadomości email.

Bazowy URL

https://api.mailist.com/api/v1

Autentykacja

API Mailist wykorzystuje klucze API do uwierzytelniania żądań. Możesz przeglądać i zarządzać swoimi kluczami API w Panelu Mailist. Twoje klucze API posiadają wiele uprawnień, dlatego upewnij się, że są bezpieczne! Nie udostępniaj swoich tajnych kluczy API w publicznie dostępnych miejscach takich jak GitHub, kod po stronie klienta, itp. Uwierzytelnianie w API odbywa się poprzez nagłówek HTTP. Podaj swój klucz API jako wartość nagłówka X-API-Key:

X-API-Key: TWOJ_KLUCZ_API

Wszystkie żądania API muszą być wykonywane przez HTTPS. Wywołania przez zwykły HTTP zakończą się niepowodzeniem. Żądania API bez uwierzytelnienia również zakończą się niepowodzeniem.

Uprawnienia

Każdy klucz API może być skonfigurowany ze szczegółowymi uprawnieniami:

contacts.read - Odczyt informacji o kontaktach
contacts.write - Tworzenie i aktualizacja kontaktów
lists.read - Odczyt informacji o listach
lists.write - Tworzenie, aktualizacja i zarządzanie listami
campaigns.read - Odczyt informacji o kampaniach i statystykach

Odpowiedzi

API Mailist wykorzystuje konwencjonalne kody odpowiedzi HTTP, aby wskazać sukces lub niepowodzenie żądania API. Ogólnie: Kody z zakresu 2xx oznaczają sukces. Kody z zakresu 4xx oznaczają błąd wynikający z podanych informacji (np. pominięto wymagany parametr, zasób nie został znaleziony, itp.). Kody z zakresu 5xx oznaczają błąd po stronie serwerów Mailist.

Kody statusu HTTP

Kod statusu	Opis
`200 OK`	Wszystko przebiegło zgodnie z oczekiwaniami
`201 Created`	Zasób został pomyślnie utworzony
`400 Bad Request`	Żądanie było niedopuszczalne, często z powodu braku wymaganego parametru
`401 Unauthorized`	Nie podano prawidłowego klucza API
`403 Forbidden`	Klucz API nie ma uprawnień do wykonania żądania
`404 Not Found`	Żądany zasób nie istnieje
`429 Too Many Requests`	Zbyt wiele żądań wysłanych zbyt szybko
`500 Internal Server Error`	Coś poszło nie tak po stronie Mailist

Struktura odpowiedzi

Wszystkie odpowiedzi API mają spójną strukturę z wartością logiczną success oraz obiektem data lub error.

Odpowiedź sukcesu

{
  "success": true,
  "data": {
    "id": 123,
    "email": "user@example.com"
  },
  "message": "Kontakt utworzony pomyślnie"
}

Odpowiedź błędu

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Adres email jest wymagany"
  }
}

Kody błędów

Kod błędu	Opis
`INVALID_REQUEST`	Żądanie zawierało nieprawidłowe parametry
`CONTACT_NOT_FOUND`	Określony kontakt nie istnieje
`LIST_NOT_FOUND`	Określona lista nie istnieje
`CAMPAIGN_NOT_FOUND`	Określona kampania nie istnieje
`PERMISSION_DENIED`	Klucz API nie posiada wymaganych uprawnień
`INTERNAL_ERROR`	Wystąpił błąd na serwerze

Paginacja

Endpointy listujące, które zwracają wiele elementów, są paginowane. Paginacja wykorzystuje następujące parametry:

page - Numer strony (indeksowany od 0, domyślnie: 0)
size - Liczba elementów na stronę (domyślnie: 20)

Odpowiedzi paginowane zawierają:

{
  "success": true,
  "data": {
    "items": [...],
    "page": 0,
    "size": 20,
    "totalElements": 150,
    "totalPages": 8
  }
}

Limity częstotliwości

API posiada limity częstotliwości, aby zapobiec nadużyciom, które mogłyby pogorszyć naszą zdolność do utrzymania stałej wydajności API dla wszystkich użytkowników. Domyślnie każdy klucz API jest ograniczony do 1000 żądań na godzinę. Gdy przekroczysz limit częstotliwości, API zwróci kod statusu 429 Too Many Requests.

Kontakty

Listy kontaktów

Kampanie

Wprowadzenie

Przegląd

Bazowy URL

Autentykacja

Uprawnienia

Odpowiedzi

Kody statusu HTTP

Struktura odpowiedzi

Odpowiedź sukcesu

Odpowiedź błędu

Kody błędów

Paginacja

Limity częstotliwości

​Przegląd

​Bazowy URL

​Autentykacja

​Uprawnienia

​Odpowiedzi

​Kody statusu HTTP

​Struktura odpowiedzi

​Odpowiedź sukcesu

​Odpowiedź błędu

​Kody błędów

​Paginacja

​Limity częstotliwości

Przegląd

Bazowy URL

Autentykacja

Uprawnienia

Odpowiedzi

Kody statusu HTTP

Struktura odpowiedzi

Odpowiedź sukcesu

Odpowiedź błędu

Kody błędów

Paginacja

Limity częstotliwości