Dokumentacja / Przewodniki

Wysyłanie emaili

4 min czytania

Ten przewodnik obejmuje wszystko, co musisz wiedzieć o wysyłaniu emaili przez MailingAPI.

Podstawowy email

Najprostszy email wymaga czterech pól:

curl -X POST https://api.mailingapi.com/v1/messages/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "powiadomienia@twojadomena.pl",
    "to": "user@example.com",
    "subject": "Twoje zamówienie zostało wysłane",
    "html": "<h1>Zamówienie wysłane</h1><p>Twoja paczka jest w drodze!</p>",
    "text": "Zamówienie wysłane\n\nTwoja paczka jest w drodze!"
  }'

Wymagane pola:

  • from — Adres nadawcy (musi pasować do zweryfikowanej domeny)
  • to — Adres odbiorcy
  • subject — Temat wiadomości
  • html lub text — Treść emaila (wymagane przynajmniej jedno)

Dane nadawcy

Adres from

Pole from może być samym adresem lub zawierać nazwę:

{
  "from": "hello@twojadomena.pl"
}
{
  "from": "Twoja Firma <hello@twojadomena.pl>"
}

Adres Reply-To

Ustaw inny adres do odpowiedzi:

{
  "from": "powiadomienia@twojadomena.pl",
  "reply_to": "support@twojadomena.pl"
}

Odbiorcy

Pojedynczy odbiorca

{
  "to": "user@example.com"
}

Z nazwą:

{
  "to": "Jan Kowalski <jan@example.com>"
}

Wielu odbiorców

Dla tego samego emaila do wielu osób (widzą się nawzajem):

{
  "to": ["alice@example.com", "bob@example.com"]
}

CC i BCC

{
  "to": "primary@example.com",
  "cc": ["manager@example.com"],
  "bcc": ["archive@twojadomena.pl"]
}

Uwaga: Dla spersonalizowanych emaili do wielu odbiorców użyj wysyłki batch.

Treść emaila

HTML i plain text

Zawsze podawaj oba dla maksymalnej dostarczalności:

{
  "html": "<h1>Witaj!</h1><p>Dziękujemy za rejestrację.</p>",
  "text": "Witaj!\n\nDziękujemy za rejestrację."
}

Jeśli podasz tylko HTML, automatycznie wygenerujemy wersję tekstową.

Zmienne dynamiczne

Użyj zmiennych szablonu do personalizacji:

{
  "to": "jan@example.com",
  "subject": "Witaj, {{name}}!",
  "html": "<p>Cześć {{name}}, Twoje konto jest gotowe.</p>",
  "variables": {
    "name": "Jan"
  }
}

Wspierana składnia:

  • Mustache: {{zmienna}}
  • Styl Mailgun: %recipient.zmienna%

Załączniki

Dodaj pliki do emaila (max 10 plików, 10 MB każdy):

{
  "attachments": [
    {
      "filename": "faktura.pdf",
      "content": "base64-encoded-content-here",
      "content_type": "application/pdf"
    }
  ]
}

Dla obrazów inline (wyświetlanych w HTML):

{
  "attachments": [
    {
      "filename": "logo.png",
      "content": "base64-encoded-content",
      "content_type": "image/png",
      "content_id": "logo"
    }
  ],
  "html": "<img src=\"cid:logo\" alt=\"Logo\">"
}

Własne nagłówki

Dodaj własne nagłówki email:

{
  "headers": {
    "X-Campaign-ID": "welcome-series-2024",
    "X-Customer-ID": "cust_123"
  }
}

Zarezerwowane nagłówki (ustawiane automatycznie):

  • From, To, Subject, Date
  • Message-ID, MIME-Version
  • DKIM-Signature

Śledzenie

Kontroluj śledzenie otwarć i kliknięć per wiadomość:

{
  "tracking": {
    "opens": true,
    "clicks": true
  }
}

Domyślnie: oba włączone (dziedziczone z ustawień domeny).

Emaile transakcyjne vs marketingowe

Gdy oba opens i clicks są wyłączone, email jest traktowany jako transakcyjny:

  • Brak pixela śledzącego (śledzenie otwarć)
  • Brak przepisywania linków (śledzenie kliknięć)
  • Brak nagłówka List-Unsubscribe — ten nagłówek sygnalizuje Gmailowi że email jest promocyjny/bulk, co obniża dostarczalność wiadomości transakcyjnych

Wyłącz śledzenie dla:

  • Resetów haseł i alertów bezpieczeństwa
  • Potwierdzeń zamówień i paragonów
  • Powiadomień systemowych (nowe logowanie, zmiany na koncie)
  • Automatycznych powiadomień 1:1

Zostaw śledzenie włączone dla:

  • Kampanii marketingowych i newsletterów
  • Ofert promocyjnych
  • Aktualizacji produktu i ogłoszeń

Przykład — powiadomienie transakcyjne bez śledzenia:

{
  "from": "alerty@twojadomena.pl",
  "to": "user@example.com",
  "subject": "Zamówienie #12345 zostało wysłane",
  "html": "<p>Twoja paczka jest w drodze!</p>",
  "tracking": {
    "opens": false,
    "clicks": false
  }
}

Zaplanowana wysyłka

Wyślij email o określonej godzinie:

{
  "scheduled_at": "2024-12-25T09:00:00Z"
}
  • Użyj formatu ISO 8601 ze strefą czasową
  • Maksymalnie 7 dni wprzód
  • Anuluj przez DELETE /v1/messages/{id}/schedule

Lista zaplanowanych wiadomości:

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

Wysyłka batch

Wyślij spersonalizowane emaile do wielu odbiorców efektywnie:

curl -X POST https://api.mailingapi.com/v1/messages/batch \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@twojadomena.pl",
    "subject": "Witaj, {{name}}!",
    "html": "<p>Cześć {{name}}, Twój kod to {{code}}.</p>",
    "recipient_variables": {
      "alice@example.com": {"name": "Alicja", "code": "ABC123"},
      "bob@example.com": {"name": "Robert", "code": "XYZ789"}
    }
  }'

Lub wyślij całkowicie różne wiadomości:

{
  "messages": [
    {
      "from": "hello@twojadomena.pl",
      "to": "alice@example.com",
      "subject": "Twoja faktura",
      "html": "<p>Faktura #001 w załączniku.</p>"
    },
    {
      "from": "hello@twojadomena.pl",
      "to": "bob@example.com",
      "subject": "Twój paragon",
      "html": "<p>Paragon #002 w załączniku.</p>"
    }
  ]
}

Limity:

  • Maksymalnie 1000 wiadomości na żądanie
  • Każda wiadomość przetwarzana niezależnie
  • Częściowe błędy nie blokują innych

Używanie szablonów

Wyślij używając wcześniej zdefiniowanego szablonu:

{
  "from": "hello@twojadomena.pl",
  "to": "user@example.com",
  "template_id": "tmpl_welcome_email",
  "variables": {
    "name": "Jan",
    "activation_link": "https://example.com/activate/abc123"
  }
}

Zobacz przewodnik Szablony po tworzenie i zarządzanie szablonami.

Tagi i metadata

Dodaj tagi do filtrowania w analityce:

{
  "tags": ["welcome", "onboarding", "2024"]
}

Dodaj metadata do własnego śledzenia:

{
  "metadata": {
    "user_id": "usr_123",
    "campaign": "black-friday"
  }
}

Metadata są zwracane w webhookach i szczegółach wiadomości.

Odpowiedź

Udana wysyłka zwraca:

{
  "id": "msg_1234567890abcdef",
  "status": "queued",
  "message": "Email queued for delivery"
}

Wysyłka batch zwraca:

{
  "results": [
    {"id": "msg_abc", "status": "queued", "to": "alice@example.com"},
    {"id": "msg_xyz", "status": "queued", "to": "bob@example.com"}
  ],
  "queued": 2,
  "failed": 0
}

Walidacja przed wysyłką

Sprawdź email przed wysłaniem:

curl -X POST https://api.mailingapi.com/v1/messages/analyze \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@twojadomena.pl",
    "to": "user@example.com",
    "subject": "Test",
    "html": "<p>Treść tutaj</p>"
  }'

Zwraca spam score, potencjalne problemy i rekomendacje.

Dobre praktyki

  1. Zawsze dołączaj wersję tekstową — Niektóre klienty nie renderują HTML
  2. Używaj szablonów dla spójności — Unikaj inline HTML gdy to możliwe
  3. Ustaw reply-to odpowiednio — Nie używaj no-reply@ jeśli chcesz odpowiedzi
  4. Śledź przez metadata — Połącz emaile z wewnętrznymi systemami
  5. Testuj przed produkcją — Użyj najpierw endpointu /analyze
  6. Obsługuj bouncy — Monitoruj webhooki i czyść listy

Następne kroki