Ta część dokumentacji dotyczy obsługi e-maili transakcyjnych.

POST /messaging/emails

Ten endpoint służy do rejestracji e-maili zleconych do wysyłki.

[POST] /v3/messaging/emails

Note

Endpoint przyjmuje zapytania w trybie asynchronicznym - tzn rejestrowane wiadomości walidowane są pod kątem poprawności i następnie umieszczane w kolejce do wysyłki.

Przykładowe zapytanie

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
    "recipients": [
        {
            "email": "recipient@example.com",
            "name": "Example Recipient",
            "personalization": {
                "key1": "value1",
                "key2": "value2"
            },
             "headers": {
                 "x-custom-header-1": "Custom message header"
             }
        }
    ],
    "from": {
        "name" : "John Sender",
        "email": "sender@example.com"
    },
    "subject": "Message subject",
    "contents": [
        {
            "type": "text/html",
            "body": "<p>sample HTML</p>"
        },
        {
            "type": "text/plain",
            "body": "same text"
        }
    ],
    "headers": {
        "x-custom-header-1": "Custom message header",
        "x-custom-header-2": "Custom message header"
    }
}
Parametr Typ Wymagany Opis
recipients Lista obiektów Tak Lista odbiorców
recipients[].email String Tak Adres email odbiorcy
recipients[].name String Nie Nazwa odbiorcy
recipients[].personalization Obiekt Nie Dane personalizacyjne
recipients[].headers Obiekt Nie Niestandardowe nagłówki dla odbiorcy
from Obiekt Tak Szczegóły nadawcy
from.name String Tak Nazwa nadawcy
from.email String Tak Adres email nadawcy
subject String Tak Temat wiadomości
templateHash String Zależy * Hash szablonu zapisanego w aplikacji FreshMail
contents Lista obiektów Zależy * Lista treści
contents[].type String Tak Typ treści
contents[].body String Tak Treść
headers Obiekt Nie Niestandardowe nagłówki
attachments Lista obiektów Nie Lista załączników
attachments[].name String Tak Nazwa załącznika
attachments[].content String Tak Treść załącznika (Base64)

Note

Jedna i tylko jedna z wartości templateHash i contents MUSI być zawarta w zapytaniu.

Recipients

Parametr recipients musi zawierać minimalnie 1 i maksymalnie 100 elementów.
W praktyce oznacza to, że jednym zapytaniem można wysłać wiadomość maksymalnie do 100 odbiorców.

Recipients > Personalization

Parametr personalization służy do przesyłania spersonalizowanych wartości użytych w treści wiadomości. Kluczem obiektu jest nazwa wartości użytej w przesłanej treści.

Aby użyć spersonalizowanej treści w szablonie - musimy umieścić w jego treści znacznik odpowiadający nazwie klucza który należy przesłać w tablicy personalization przy każdym z odbiorców.

Przykład:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{ 
    "recipients": [
       {
           "email": "recipient1@example.com",
           "name": "Adam Recipient",
           "personalization": {
               "name": "Adam",
               "custom_key": "value1"
           }
       },
       {
           "email": "recipient2@example.com",
           "name": "John Recipient",
           "personalization": {
               "name": "John",
               "custom_key": "value2"
           }
       }
   ],
   "from": {
       "name" : "John Sender",
       "email": "sender@example.com"
   },
   "subject": "Message subject",
   "contents": [
       {
           "type": "text/html",
           "body": "<h1>Hello $$name$$</h1><p>Here your key: $$custom_key$$</p>"
       }
   ],
   "attachments": [
       {
           "name": "invoice.pdf",
           "content": "VGhpcyBpcyBqdXN0IHNvbWUgZW5jb2RlZCBjb250ZW50IGV4YW1wbGUg..."
       }
   ]
}

Powyższy przykład zapytania odpowiada za wysyłkę spersonalizowanej wiadomości do dwóch różnych odbiorców wypełniając szablon unikalnymi wartościami przypisanymi do każdego z nich.

Więcej na temat szablonów i personalizacji można przeczytać w dokumentacji tutaj. Przesłane treści są walidowane pod kątem poprawności kodu względem wybranego silnika. Niepoprawne treści powodują odrzucenie wiadomości.

TemplateHash

Parametr templateHash określa szablon stworzony w aplikacji FreshMail powiązany z kontem z którego wysyłane sa maile transakcyjne. Jego użycie powoduje wykorzystanie do wysyłki treści zapisanych w szablonie - odpowiednio w formacie tekstowym jak i HTML.

Korzystając z szablonów tworzonych w aplikacji - również można używać personalizacji, dokładnie tak jak w treści przesyłanej bezpośrednio w zapytaniu.

Więcej na temat szablonów i personalizacji można przeczytać w dokumentacji tutaj. Przesłane treści są walidowane pod kątem poprawności kodu względem wybranego silnika. Niepoprawne treści powodują odrzucenie wiadomości.

Note

Określenie templateHash blokuje możliwość przesłania treści przez parametr contents, a jego użycie skutkuje odrzuceniem zapytania zwracając błąd walidacji.

Contents

Parametr contents musi zawierać przynajmniej jeden ze zdefiniowanych typów treści:

Typ treść Opis
text/html Treść w formacie HTML
text/plain Treść tekstowa

W treści HTML również można korzystać z personalizacji. Wspieramy 2 typy znaczników - nasz oryginalny FreshMailowy oraz Twig w okrojonej formie (dopuszczamy użycie zmiennych, warunków oraz prostych modifikatorów jak default, czy date)

Headers

Niestandardowe nagłówki wiadomości, gdzie kluczem obiektu jest nazwa nagłówka jaki ma zostać dodany do wiadomości.

Note

Nazwy niestandardowych nagłówków muszą zaczynać się od prefiksa X-.

Note

Nagłówki zdefiniowane w parametrze recipients nadpisują te zdefiniowane w głównym obiekcie zapytania.

Attachments

Parametr attachments zawiera listę obiektów jakie mają zostać dołączone do wiadomości e-mail jako załączniki. Aby obiekt mógł zostać skonwertowany jako załącznik musi zawierać pola :

  • name - które jest nazwą pliku wraz z rozszerzeniem
  • content - treść pliku zakodowana w formacie Base64

Maksymalnie możesz dodać 10 załączników o łącznej wadze nie przekraczającej 10Mb.

Kody odpowiedzi

201

Wiadomości zostały poprawnie zarejestrowane w systemie.

1
2
3
4
5
6
[
    {
        "email": "string",
        "id": "string"
    }
]

1
2
3
4
5
6
[
    {
        "email": "recipient@example.com",
        "id": "b39ef689-4177-4a0e-b5c3-f894900adbae"
    }
]

400

Błędy walidacji zapytania.

  • Niepoprawny format
  • Brak wymaganych pól
  • Niepoprawne wartości parametrów
1
2
3
4
5
{
    "errors": [
        "string"
    ]
}

1
2
3
4
5
6
{
    "errors": [
        "Recipients[1].email": "This value is not a valid email address.",
        "Recipients[2].email": "This value is not a valid email address."
    ]
}

Przykłady zapytań

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
curl -X POST \
  https://api.freshmail.com/v3/messaging/emails \
  -H 'Authorization: Bearer [token]' \
  -H 'Content-Type: application/json' \
  -d '{ 
         "recipients": [
             {
                 "email": "recipient@example.com",
                 "name": "Adam Recipient",
                 "personalization": {
                     "key1": "value1",
                     "key2": "value2"
                 },
                  "headers": {
                      "x-custom-header-1": "Custom message header"
                  }
             }
         ],
         "from": {
             "name" : "John Sender",
             "email": "sender@example.com"
         },
         "subject": "Message subject",
         "contents": [
             {
                 "type": "text/html",
                 "body": "<p>sample HTML</p>"
             },
             {
                 "type": "text/plain",
                 "body": "same text"
             }
         ],
         "headers": {
             "x-custom-header-1": "Custom message header",
             "x-custom-header-2": "Custom message header"
         }
      }'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
<?php

$request = new HttpRequest();
$request->setUrl('https://api.freshmail.com/v3/messaging/emails');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders([
  'Authorization' => 'Bearer [token]',
  'Content-Type' => 'application/json'
)];

$request->setBody('{ 
    "recipients": [
       {
           "email": "recipient@example.com",
           "name": "Adam Recipient",
           "personalization": {
               "key1": "value1",
               "key2": "value2"
           },
            "headers": {
                "x-custom-header-1": "Custom message header"
            }
       }
   ],
   "from": {
       "name" : "John Sender",
       "email": "sender@example.com"
   },
   "subject": "Message subject",
   "contents": [
       {
           "type": "text/html",
           "body": "<p>sample HTML</p>"
       },
       {
           "type": "text/plain",
           "body": "same text"
       }
   ],
   "headers": {
       "x-custom-header-1": "Custom message header",
       "x-custom-header-2": "Custom message header"
   }
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
String body = "{\"recipients\": [{\"email\": \"recipient@example.com\"," + 
  "\"name\": \"Adam Recipient\",\"personalization\": {\"key1\": " + 
  "\"value1\",\"key2\": \"value2\"},\"headers\": {\"x-custom-header-1\": " + 
  "\"Custom message header\"}}],\"from\": {\"name\" : \"John Sender\"," + 
  "\"email\": \"sender@example.com\"},\"subject\": \"Message subject\"," + 
  "\"contents\": [{\"type\": \"text/html\",\"body\": \"<p>sample HTML</p>\"}" + 
  ",{\"type\": \"text/plain\",\"body\": \"same text\"}],\"headers\": " + 
  "{\"x-custom-header-1\": \"Custom message header\",\"x-custom-header-2\": " + 
  "\"Custom message header\"}}";

RequestBody body = RequestBody.create(mediaType, body);
Request request = new Request.Builder()
  .url("https://api.freshmail.com/v3/messaging/emails/")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer [token]")
  .build();

Response response = client.newCall(request).execute();

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import requests

url = "https://api.freshmail.com/v3/messaging/emails/"

payload = "{\"recipients\": [{\"email\": \"recipient@example.com\"," \ 
"\"name\": \"Adam Recipient\",\"personalization\": {\"key1\": " \ 
"\"value1\",\"key2\": \"value2\"},\"headers\": {\"x-custom-header-1\": " \ 
"\"Custom message header\"}}],\"from\": {\"name\" : \"John Sender\"," \ 
"\"email\": \"sender@example.com\"},\"subject\": \"Message subject\"," \ 
"\"contents\": [{\"type\": \"text/html\",\"body\": \"<p>sample HTML</p>\"}" \ 
",{\"type\": \"text/plain\",\"body\": \"same text\"}],\"headers\": " \ 
"{\"x-custom-header-1\": \"Custom message header\",\"x-custom-header-2\": " \ 
"\"Custom message header\"}}"
headers = {
    'Content-Type': "application/json",
    'Authorization': "Bearer [token]"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)