Szablony - Dokumentacja

Szablony pozwalają tworzyć wielokrotnego użytku projekty email, które możesz wysyłać z dynamiczną treścią. Zdefiniuj układ raz, potem personalizuj dla każdego odbiorcy.

Dlaczego warto używać szablonów

Bez szablonów:

Duplikujesz HTML w każdym wywołaniu API
Trudno utrzymać spójny branding
Zmiany wymagają aktualizacji wszystkich integracji
Łatwo o błędy

Z szablonami:

Definiujesz układ raz, używasz wszędzie
Aktualizujesz branding w jednym miejscu
Nietechniczne osoby mogą edytować
Podgląd i testy przed wysyłką

Tworzenie szablonu

Przez Dashboard

Przejdź do Szablony
Kliknij Utwórz szablon
Zaprojektuj email używając wizualnego edytora
Dodaj zmienne dla dynamicznej treści
Podgląd i test
Kliknij Zapisz

Przez API

curl -X POST https://api.mailingapi.com/v1/templates \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_email",
    "subject": "Witaj w {{company_name}}, {{name}}!",
    "html": "<h1>Witaj, {{name}}!</h1><p>Twoje konto jest gotowe.</p>",
    "text": "Witaj, {{name}}!\n\nTwoje konto jest gotowe."
  }'

Odpowiedź:

{
  "id": "tmpl_abc123",
  "name": "welcome_email",
  "subject": "Witaj w {{company_name}}, {{name}}!",
  "status": "active",
  "created_at": "2024-01-15T10:00:00Z"
}

Zmienne w szablonach

Używaj podwójnych nawiasów klamrowych dla dynamicznej treści:

<h1>Cześć, {{name}}!</h1>
<p>Twoje zamówienie #{{order_id}} zostało wysłane.</p>
<p>Śledź je tutaj: <a href="{{tracking_url}}">{{tracking_url}}</a></p>

Typy zmiennych

Proste wartości:

{{name}}
{{email}}
{{order_id}}

Zagnieżdżone obiekty:

{{user.first_name}}
{{order.total}}
{{company.address.city}}

Wartości domyślne:

{{name|default:"Kliencie"}}
{{company|default:"Nasz Zespół"}}

Zmienne zarezerwowane

Te są dostępne automatycznie:

Zmienna	Opis
`{{unsubscribe_url}}`	Link do wypisania jednym kliknięciem
`{{preferences_url}}`	Strona preferencji email
`{{view_in_browser}}`	Wersja webowa emaila
`{{current_year}}`	Aktualny rok (np. 2024)

Warunki

Wyświetlaj treść na podstawie warunków:

{{#if premium_user}}
  <p>Dziękujemy za bycie członkiem premium!</p>
{{else}}
  <p>Przejdź na premium po ekskluzywne korzyści.</p>
{{/if}}

Sprawdzanie wartości:

{{#if tracking_number}}
  <p>Śledź swoją paczkę: {{tracking_number}}</p>
{{/if}}

Porównywanie wartości:

{{#if order_total > 100}}
  <p>Kwalifikujesz się do darmowej wysyłki!</p>
{{/if}}

Pętle

Iteracja po tablicach:

<h2>Twoje zamówienie:</h2>
<ul>
{{#each items}}
  <li>{{this.name}} - {{this.price}} zł</li>
{{/each}}
</ul>

Z indeksem:

{{#each items}}
  <tr class="{{#if @odd}}odd{{/if}}">
    <td>{{@index}}. {{this.name}}</td>
  </tr>
{{/each}}

Części wspólne (Partials)

Wykorzystuj wspólne sekcje w wielu szablonach:

Utwórz partial

curl -X POST https://api.mailingapi.com/v1/templates/partials \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "name": "footer",
    "html": "<footer><p>© {{current_year}} {{company_name}}</p></footer>"
  }'

Użyj w szablonach

<body>
  <h1>Witamy!</h1>
  <p>Treść tutaj...</p>

  {{> footer}}
</body>

Typowe partials:

Nagłówki z logo
Stopki z tekstem prawnym
Linki do social media
Bloki adresowe

Wysyłka z szablonami

Podstawowa wysyłka

curl -X POST https://api.mailingapi.com/v1/messages/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@twojadomena.pl",
    "to": "user@example.com",
    "template_id": "tmpl_abc123",
    "variables": {
      "name": "Jan",
      "order_id": "12345",
      "company_name": "Acme Sp. z o.o."
    }
  }'

Wysyłka batch z szablonami

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",
    "template_id": "tmpl_abc123",
    "recipient_variables": {
      "alice@example.com": {"name": "Alicja", "order_id": "001"},
      "bob@example.com": {"name": "Robert", "order_id": "002"}
    }
  }'

Wersje szablonów

Śledź zmiany z wersjonowaniem:

Utwórz nową wersję

curl -X POST https://api.mailingapi.com/v1/templates/tmpl_abc123/versions \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "html": "<h1>Zaktualizowany email powitalny</h1>...",
    "changelog": "Odświeżony design na 2024"
  }'

Lista wersji

curl https://api.mailingapi.com/v1/templates/tmpl_abc123/versions \
  -H "Authorization: Bearer $API_KEY"

Przywróć wersję

curl -X POST https://api.mailingapi.com/v1/templates/tmpl_abc123/versions/2/restore \
  -H "Authorization: Bearer $API_KEY"

Podgląd i testowanie

Podgląd z danymi

curl -X POST https://api.mailingapi.com/v1/templates/tmpl_abc123/render \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "variables": {
      "name": "Testowy Użytkownik",
      "order_id": "TEST-001"
    }
  }'

Zwraca wyrenderowany HTML i tekst.

Wyślij testowy email

curl -X POST https://api.mailingapi.com/v1/templates/tmpl_abc123/test \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "to": "twoj-email@example.com",
    "variables": {
      "name": "Testowy Użytkownik"
    }
  }'

Kategorie szablonów

Organizuj szablony według typu:

curl -X POST https://api.mailingapi.com/v1/templates \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "name": "order_shipped",
    "category": "transactional",
    "tags": ["zamowienia", "wysylka"]
  }'

Typowe kategorie:

transactional — Paragony, potwierdzenia, alerty
marketing — Newslettery, promocje
notification — Aktualizacje, przypomnienia
authentication — Reset hasła, weryfikacja

Zarządzanie szablonami

Lista wszystkich szablonów

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

Pobierz pojedynczy szablon

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

Aktualizuj szablon

curl -X PATCH https://api.mailingapi.com/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"subject": "Nowy temat wiadomości"}'

Usuń szablon

curl -X DELETE https://api.mailingapi.com/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer $API_KEY"

Dobre praktyki

Używaj opisowych nazw — order_confirmation nie template1
Zawsze dołączaj wersję tekstową — Niektóre klienty nie renderują HTML
Testuj z prawdziwymi danymi — Podgląd przed wysyłką do klientów
Zachowaj prostotę — Złożona logika należy do Twojej aplikacji
Wersjonuj szablony — Śledź zmiany, umożliwiaj rollback
Używaj partials — Zasada DRY dla nagłówków/stopek
Mobile-first — Większość emaili jest czytana na mobile

Wskazówki projektowania emaili

Responsywny układ

<table width="100%" style="max-width: 600px; margin: 0 auto;">
  <tr>
    <td style="padding: 20px;">
<!-- Treść -->

    </td>
  </tr>
</table>

Bezpieczne fonty

font-family: Arial, Helvetica, sans-serif;
font-family: Georgia, Times, serif;

Style inline

Klienty email usuwają tagi <style>. Zawsze używaj inline:

<!-- Dobrze -->

<p style="color: #333; font-size: 16px;">Tekst</p>

<!-- Źle (może nie działać) -->

<p class="body-text">Tekst</p>

Następne kroki

Skonfiguruj webhooki by śledzić zaangażowanie
Skonfiguruj walidację by czyścić listy
Monitoruj dostarczalność z analityką