Inbound Email - Dokumentacja

API Inbound Email pozwala konfigurować reguły routingu przychodzących emaili i uzyskiwać dostęp do przechowywanych wiadomości.

Reguły routingu

Reguły definiują jak przetwarzać przychodzące emaile na podstawie adresu odbiorcy.

Lista reguł

Pobierz wszystkie reguły routingu dla Twojej organizacji.

GET /v1/inbound/routes

Przykładowe żądanie

curl https://api.mailingapi.com/v1/inbound/routes \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź

{
  "data": [
    {
      "id": "ir_abc123",
      "name": "Skrzynka support",
      "match_type": "prefix",
      "pattern": "support@",
      "action": "store",
      "priority": 100,
      "status": "active",
      "matched_count": 1520,
      "last_matched_at": "2024-01-20T15:30:00Z",
      "created_at": "2024-01-10T10:00:00Z"
    }
  ]
}

Utwórz regułę

Utwórz nową regułę routingu.

POST /v1/inbound/routes

Body żądania

Pole	Typ	Wymagane	Opis
`name`	string	Tak	Nazwa reguły (1-100 znaków)
`match_type`	string	Tak	Typ dopasowania (patrz niżej)
`pattern`	string	*	Wzorzec (* wymagany oprócz `catchall`)
`action`	string	Tak	Akcja do wykonania (patrz niżej)
`action_config`	object	Zależy	Konfiguracja specyficzna dla akcji
`priority`	integer	Nie	Priorytet 1-1000 (domyślnie: 100, niższy = wyższy priorytet)
`domain_id`	string	Nie	Ogranicz do konkretnej domeny
`description`	string	Nie	Czytelny opis
`filters`	object	Nie	Dodatkowe filtry
`active`	boolean	Nie	Czy reguła aktywna (domyślnie: true)

Typy dopasowania

Typ	Opis	Przykład wzorca
`exact`	Dokładne dopasowanie emaila	`support@example.com`
`prefix`	Dopasowanie początku adresu	`support@`
`suffix`	Dopasowanie końca adresu	`@support.example.com`

Akcje

Akcja	Opis	Wymagana konfiguracja
`webhook`	POST z danymi wiadomości na URL	`action_config.url`
`forward`	Przekaż na inny adres email	`action_config.to`
`store`	Przechowaj do pobrania przez API	(opcjonalna konfiguracja retencji)
`drop`	Odrzuć wiadomość	(brak)

Przykłady konfiguracji akcji

Webhook:

{
  "action_config": {
    "url": "https://twojaapka.pl/inbound-webhook",
    "secret": "opcjonalny-sekret-hmac",
    "include_attachments": true
  }
}

Forward:

{
  "action_config": {
    "to": ["odbiorca@example.com"],
    "preserve_attachments": true
  }
}

Store:

{
  "action_config": {
    "retention_days": 7,
    "notify_url": "https://twojaapka.pl/powiadomienie",
    "notify_include_body": false
  }
}

Przykładowe żądanie

curl -X POST https://api.mailingapi.com/v1/inbound/routes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support webhook",
    "match_type": "prefix",
    "pattern": "support@",
    "action": "webhook",
    "action_config": {
      "url": "https://twojaapka.pl/inbound",
      "include_attachments": true
    },
    "priority": 10
  }'

Odpowiedź

{
  "id": "ir_new456",
  "name": "Support webhook",
  "match_type": "prefix",
  "pattern": "support@",
  "action": "webhook",
  "action_config": {
    "url": "https://twojaapka.pl/inbound",
    "include_attachments": true
  },
  "priority": 10,
  "status": "active",
  "created_at": "2024-01-20T16:00:00Z"
}

Pobierz regułę

Pobierz szczegóły konkretnej reguły.

GET /v1/inbound/routes/{route_id}

Przykładowe żądanie

curl https://api.mailingapi.com/v1/inbound/routes/ir_abc123 \
  -H "Authorization: Bearer $API_KEY"

Aktualizuj regułę

Zaktualizuj istniejącą regułę routingu.

PUT /v1/inbound/routes/{route_id}

Body żądania

Dowolne pola z tworzenia (oprócz organization_id).

Przykładowe żądanie

curl -X PUT https://api.mailingapi.com/v1/inbound/routes/ir_abc123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": 5,
    "status": "paused"
  }'

Usuń regułę

Usuń regułę routingu.

DELETE /v1/inbound/routes/{route_id}

Przykładowe żądanie

curl -X DELETE https://api.mailingapi.com/v1/inbound/routes/ir_abc123 \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź

204 No Content

Wiadomości przychodzące

Dostęp do przechowywanych wiadomości przychodzących (dla reguł z akcją store).

Lista wiadomości

Pobierz przechowywane wiadomości z filtrowaniem i paginacją.

GET /v1/inbound/messages

Parametry zapytania

Parametr	Typ	Opis
`limit`	integer	Wyników na stronę (domyślnie: 50, max: 100)
`offset`	integer	Ile wyników pominąć
`from`	string	Filtruj po adresie nadawcy (dokładne dopasowanie)
`to`	string	Filtruj po adresie odbiorcy (dokładne dopasowanie)
`since`	string	Wiadomości od tej daty (ISO 8601)
`until`	string	Wiadomości do tej daty (ISO 8601)
`domain_id`	string	Filtruj po ID domeny
`is_spam`	boolean	Filtruj po oznaczeniu spam

Przykładowe żądanie

curl "https://api.mailingapi.com/v1/inbound/messages?limit=25&since=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź

{
  "data": [
    {
      "id": "im_abc123",
      "from": "nadawca@example.com",
      "to": ["support@twojadomena.pl"],
      "subject": "Pomoc z zamówieniem",
      "received_at": "2024-01-20T15:30:00Z",
      "spam_score": 1.2,
      "is_spam": false,
      "has_attachments": true
    }
  ],
  "meta": {
    "total": 150,
    "limit": 25,
    "offset": 0
  }
}

Pobierz wiadomość

Pobierz pełne szczegóły przechowanej wiadomości.

GET /v1/inbound/messages/{message_id}

Przykładowe żądanie

curl https://api.mailingapi.com/v1/inbound/messages/im_abc123 \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź

{
  "id": "im_abc123",
  "from": "nadawca@example.com",
  "to": ["support@twojadomena.pl"],
  "subject": "Pomoc z zamówieniem",
  "html": "<p>Potrzebuję pomocy z zamówieniem #12345...</p>",
  "text": "Potrzebuję pomocy z zamówieniem #12345...",
  "headers": {
    "message-id": "<abc@example.com>",
    "date": "Mon, 20 Jan 2024 15:30:00 +0000"
  },
  "attachments": [
    {
      "filename": "zrzut.png",
      "content_type": "image/png",
      "size": 45230
    }
  ],
  "authentication": {
    "spf": "pass",
    "dkim": "pass",
    "dmarc": "pass"
  },
  "spam_score": 1.2,
  "is_spam": false,
  "thread_id": "thread_xyz",
  "received_at": "2024-01-20T15:30:00Z"
}

Pobierz wątek

Pobierz wszystkie wiadomości należące do tego samego wątku konwersacji.

GET /v1/inbound/messages/thread/{thread_id}

Przykładowe żądanie

curl https://api.mailingapi.com/v1/inbound/messages/thread/thread_xyz \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź

{
  "data": [
    {
      "id": "im_abc123",
      "from": "nadawca@example.com",
      "subject": "Pomoc z zamówieniem",
      "received_at": "2024-01-20T15:30:00Z"
    },
    {
      "id": "im_def456",
      "from": "nadawca@example.com",
      "subject": "Re: Pomoc z zamówieniem",
      "received_at": "2024-01-20T16:45:00Z"
    }
  ]
}

Pobierz załącznik

Pobierz presigned URL do pobrania załącznika. URL jest ważny przez 1 godzinę.

GET /v1/inbound/messages/{message_id}/attachments/{filename}

Przykładowe żądanie

curl https://api.mailingapi.com/v1/inbound/messages/im_abc123/attachments/zrzut.png \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź

{
  "url": "https://storage.example.com/attachments/...",
  "filename": "zrzut.png",
  "content_type": "image/png",
  "expires_at": "2024-01-20T16:30:00Z"
}

Usuń wiadomość

Usuń przechowaną wiadomość wraz z załącznikami. Operacja jest nieodwracalna.

DELETE /v1/inbound/messages/{message_id}

Przykładowe żądanie

curl -X DELETE https://api.mailingapi.com/v1/inbound/messages/im_abc123 \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź

204 No Content

Kody błędów

Kod	Opis
`route_not_found`	ID reguły nie znalezione
`message_not_found`	ID wiadomości nie znalezione
`attachment_not_found`	Załącznik nie znaleziony
`invalid_action`	Nieprawidłowy typ akcji
`invalid_match_type`	Nieprawidłowy typ dopasowania
`missing_action_config`	Wymagana konfiguracja akcji nie dostarczona
`invalid_pattern`	Nieprawidłowy wzorzec regex