> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailist.pl/llms.txt
> Use this file to discover all available pages before exploring further.

# Wprowadzenie

> Dokumentacja REST API platformy email marketingowej Mailist

## 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`:

```bash theme={null}
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

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

#### Odpowiedź błędu

```json theme={null}
{
  "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ą:

```json theme={null}
{
  "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`.