Dokumentacja / API Reference

Inbound Email

4 min czytania

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. Każda reguła należy dokładnie do jednej zweryfikowanej domeny. Reguły inbound scope’owane tylko do organizacji nie są już wspierane.

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",
      "domain_id": "8d8f2a26-46e0-4c7c-a9ff-a9af12c4d8a1",
      "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 Tak Zakres domeny dla reguły. Domena musi należeć do Twojej organizacji
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

| regex | Wyrażenie regularne | ^(help|support)@.* | | catchall | Dopasowuje wszystkie emaile | (wzorzec nie wymagany) |

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",
    "domain_id": "8d8f2a26-46e0-4c7c-a9ff-a9af12c4d8a1",
    "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",
  "domain_id": "8d8f2a26-46e0-4c7c-a9ff-a9af12c4d8a1",
  "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.

PATCH /v1/inbound/routes/{route_id}

Body żądania

Dowolne pola z tworzenia oprócz domain_id. Po utworzeniu reguły nie można przenieść jej do innej domeny.

Przykładowe żądanie

curl -X PATCH 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