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": "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"
    }
}
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
contents Lista obiektów Tak Lista treści
contents[].type String Tak Typ treści
contents[].body String Tak Treść
headers Obiekt Nie Niestandardowe nagłówki

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 treści.

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

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.

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)