Mailfly
Zaloguj sięZałóż konto
Mailfly API v1

Połącz swój system.

REST JSON, klucze per workspace, jawne zakresy uprawnień i podpisane webhooki z ponawianiem dostarczeń.

Zarządzaj integracjami
Start

Autoryzacja Bearer

Utwórz klucz w Integracje → API i webhooki. Sekret zobaczysz jeden raz. Każde żądanie wyślij przez HTTPS z nagłówkiem Authorization. Limit jednego klucza wynosi 600 żądań na minutę.

curl https://mailfly.pl/api/v1/me -H "Authorization: Bearer mf_live_TWOJ_KLUCZ"

Zakresy: contacts:read, contacts:write, groups:read, groups:write, campaigns:read, analytics:read.

Endpointy

API v1

GET/api/v1/meDane workspace i klucza
GET/api/v1/contactsLista i filtrowanie kontaktów
POST/api/v1/contactsKontakt z pełnym dowodem zgody
GET/api/v1/contacts/{id}Szczegóły kontaktu
POST/api/v1/contacts/{id}/unsubscribeTrwały wypis i suppression
GET/api/v1/groupsLista grup
POST/api/v1/groupsNowa grupa
GET/api/v1/campaignsKampanie i wyniki
GET/api/v1/campaigns/{id}Szczegóły kampanii

Dodanie kontaktu

Dowód zgody jest obowiązkowy. Pole externalId daje bezpieczną idempotencję: ponowienie tego samego żądania zwróci istniejący kontakt.

{ "externalId": "crm-123", "email": "kontakt@example.pl", "consentConfirmed": true, "consentAt": "2026-08-28T12:00:00Z", "consentSource": "Formularz newslettera", "consentMethod": "website_form", "consentText": "Zgoda na komunikację marketingową e-mail", "consentProof": "form_submission:abc123", "groupIds": [] }
E-commerce headless

Next.js i React

Utwórz osobne połączenie w Integracje → Next.js / React. Otrzymasz identyfikator i sekret widoczny tylko raz oraz gotowy starter ZIP dla App Routera. Sekret umieść wyłącznie w zmiennych serwerowych bez prefiksu NEXT_PUBLIC_.

POST /api/integrations/commerce/events
X-Mailfly-Key: identyfikator
X-Mailfly-Timestamp: unix_seconds
X-Mailfly-Signature: v1=HMAC_SHA256(secret, timestamp + "." + rawBody)

Obsługiwane są produkty, rozpoznane oglądanie, zgody, koszyk, checkout, zamówienie, płatność, zakończenie, anulowanie i zwrot. Każde zdarzenie ma własny eventId. Ponowienie dokładnie tego samego identyfikatora i treści jest bezpieczne. Zdarzenia przeglądarkowe przechodzą przez własny Route Handler Next.js, nigdy bezpośrednio z sekretem w React.

Pobierz connector Next.js
E-commerce SaaS

IdoSell API Admin Webhook

Połączenie utworzysz w Integracje → IdoSell. Mailfly pokaże token autoryzacyjny i cztery adresy dla klientów, produktów, zamówień oraz zwrotów. Dane są zgodne z odpowiedziami API Admin v8.

  1. W panelu IdoSell przejdź do konfiguracji API Admin Webhook.
  2. Dodaj cztery webhooki i przypisz do każdego właściwą grupę zdarzeń.
  3. W polu Authorization Token wklej token pokazany przez Mailfly. IdoSell wyśle go jako Authentication: Bearer. Jeżeli konfigurujesz własny dodatkowy nagłówek, możesz użyć Authorization: Bearer.
  4. Wybierz JSON, API v8 i wykonaj test na prawdziwym obiekcie. Mailfly nie prosi o login, hasło ani klucz API sklepu.

Obsługiwane są zgody newsletterowe, produkty i warianty, zamówienia, płatności, zakończenia, anulowania oraz zatwierdzone zwroty. Ponowienia IdoSell są deduplikowane. Aktualne API Admin Webhook nie udostępnia zdarzeń koszyka, dlatego automatyzacja porzuconego koszyka wymaga osobnej integracji storefront po sprawdzeniu szablonu sklepu.

Dokumentacja API Admin Webhook IdoSell

Zdarzenia

Podpisane webhooki

Mailfly wysyła pełny JSON metodą POST. Nagłówki Mailfly-Event-Id, Mailfly-Event-Type, Mailfly-Timestamp i Mailfly-Signature pozwalają zweryfikować źródło i odrzucić powtórzenia.

expected = HMAC_SHA256(secret, timestamp + "." + rawBody)

Dostępne zdarzenia obejmują kontakty, kampanie, dostarczenia, opóźnienia, odbicia, skargi, odrzucenia, otwarcia i kliknięcia. Odpowiedź 2xx kończy dostarczenie. Inne odpowiedzi są ponawiane łącznie do 6 razy przez 24 godziny.

Bezpieczeństwo

Zasady wdrożenia

Nie umieszczaj klucza API ani sekretu webhooka w kodzie przeglądarki. Weryfikuj podpis na surowym body przed parsowaniem JSON. Odrzucaj timestamp starszy niż 5 minut i zapamiętuj Event-Id, aby jedno zdarzenie nie wykonało operacji drugi raz. Adres webhooka musi być publicznym HTTPS i nie może prowadzić do sieci prywatnej.