Poniższa dokumentacja jest już nieaktualna kliknij w link poniżej aby przejść do aktualnej dokumentacji.
Przejdź do dokumentacji API >>>
Identyfikatory
Czyli pola w nagłówku e-mail pozwalające zidentyfikować wiadomość e-mail, np. jej pochodzenie, datę wysłania itp. Jednak tego typu pola można tworzyć i wykorzystywać samemu do przesyłania konkretnych danych. Jednym z takich pól jest pole Message-id. W tym przykładzie pokażemy w jaki sposób wykorzystać to pole do własnych potrzeb, i zaszyć w nim np. dane jakiej transakcji w systemie rozliczeniowym dotyczyła dana wiadomość.
Czym jest pole Message-Id?
Jest to pole posiadające unikalny numer wiadomości z danego serwera <idwiadomosci@domena.com> ustalana przez serwer nadawcy. Dzięki temu możemy sprawdzać co dzieje się z naszą wiadomości na poszczególnych etapach dostarczania wiadomości do użytkownika końcowego.
Jak budować własne Message-Id?
Po pierwsze musimy zadbać o to aby identyfikator naszej wiadomości był zawsze unikalny. Oraz podobnie jak adres e-mail miał dopisaną domenę: id_wiadomości@domena.pl, dodatkowo nasz unikalny numer musimy dodać pomiędzy znacznikami <> czyli: <id_wiadomości@domena.pl>. Aby dowiedzieć się więcej przeczytaj o standardach RFC.
Trochę praktyki
Pole Message-id poza samą identyfikacją może pełnić także inne role. Zastanówmy się co chcielibyśmy przekazywać w polu Message-Id. Załóżmy że będziemy wysyłać wiadomość dla klienta sklepu internetowego, który właśnie dokonał zakupu. A podstawą dla naszego unikalnego klienta będzie: numer transakcji (oid), numer użytkownika (uid) oraz data wysłania wiadomości (time).
|
1 2 3 4 5 |
{ "oid":"1234567", "uid":"87654321", "time":1417176584 } |
Oczywiście wysłanie danych w takiej formie mija się z celem, ponieważ bardzo prawdopodobne jest to iż taki identyfikator zostanie odrzucony przez serwer. Można zakodować je przy użyciu Base64 w rezultacie uzyskami następujący ciąg znaków:
|
1 |
eyJvaWQiOiIxMjM0NTY3IiwidWlkIjoiODc2NTQzMjEiLCJ0aW1lIjoxNDE3NTA0NTEwfQ== |
Posiadając taki ciąg znaków możemy zabrać się za wysyłkę wiadomości. Napiszmy prosty skrypt do sprawdzenia naszej wysyłki z własnym numerem id wiadomości:
|
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 |
//Bibliotek PHPMailer dla uproszczenia wysyłki require_once( dirname(__FILE__).'/../protected/commands/PHPMailer/class.phpmailer.php' ); require_once( dirname(__FILE__).'/../protected/commands/PHPMailer/class.smtp.php' ); //Dane do stworznie Message-Id $data = array( 'oid' => '1234567', 'uid' => '87654321', 'date' => date('Y-m-d'), 'sent' => time(), ); //Konwertowanie tablicy do JSON $json = json_encode( $data ); //Konwertowanie JSON do Base64 $messageId = base64_encode( $json ); //Inicjalizacja biblioteki PHPMailer $mail = new PHPMailer(); //Ustawienia połączeni SMTP $mail->IsSMTP(); $mail->SMTPAuth = true; $mail->Host = 'smtp.emaillabs.net.pl'; $mail->Port = '587'; $mail->Username = 'login.do.konta.smtl'; $mail->Password = 'hasło.do.konta.smtp'; $mail->SMTPSecure = 'tls'; //Ustawienia kodowania oraz nadawcy $mail->CharSet = 'utf-8'; $mail->From = 'adres-email@nadawcy.pl'; //Ustawienia odbiorcy $mail->AddAddress('adres-email@odbiorcy.pl'); //Ustawienie Message-Id $mail->MessageID = '<'.$messageId.'@emaillabs.pl>'; //Po @ dodajemy serwer nadawcy musimy także dodać znaczniki < > tak jak w przykładzie //Ustawienie tematu wiadomości oraz treści $mail->Subject = 'Wiadomość do testowania Message-Id'; $mail->Body = 'Hej oto wiadomość do testowania message-id'; //Wysyłanie wiadomości $mail->Send(); |
Po poprawnej wysyłce sprawdzamy pocztę:
Jak widać Message-id został przyjęty przez serwer ( w tym przypadku GMail ), możemy sprawdzić czy takie Message-id istnieje już w systemie, np. przy użyciu API. Aby rozpocząć działanie z API zobacz ten artykuł. Napiszmy krótki skrypt który zrobi to za nas oraz wyświetli rezultat:
|
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 |
//Inicjalizacja biblioteki CURL $curl = curl_init(); //Ustawienie adresu z którego zostaną pobrane dane $url = "https://api.emaillabs.net.pl/api/emails"; //Ustawienie klucza App Key $appkey = 'twoj-app-key'; //Ustawienie klucza Secret Key $secret = 'twoj-secret-key'; //Tworzenie kryteriów wyszukiwania $data = array( //Tutaj szukamy wiadomości po swoim message-id 'filter' => '"message_id::eyJvaWQiOiIxMjM0NTY3IiwidWlkIjoiODc2NTQzMjEiLCJ0aW1lIjoxNDE3NTA0NTEwfQ==@emaillabs.pl"', 'offset' => 0, 'limit' => 1, 'sort' => '-created_at', ); //Przekazywania kryteriów wyszukiwania do adresu URL $url = sprintf("%s?%s", $url, http_build_query($data)); //Ustawianie typu autoryzacji curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); //Przekazywanie danych do logowania curl_setopt($curl, CURLOPT_USERPWD , "$appkey:$secret"); //Przekazywania adresu URL z akcją curl_setopt($curl, CURLOPT_URL, $url); //Ustawienia dotyczące zwrotu z serwera curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); //Pobieranie rezultatu $result = curl_exec($curl); //Przetwarzanie danych z API $json = json_decode( $result ); echo '<pre>'; print_r( $json ); |
A oto i rezultat:
|
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 |
stdClass Object ( [code] => 200 [status] => success [message] => [data] => Array ( [0] => stdClass Object ( [vps] => smtp2-03 [account] => 1.testowe.smtp [injected_time] => 2014-12-02 08:15:12 [message_id] => eyJvaWQiOiIxMjM0NTY3IiwidWlkIjoiODc2NTQzMjEiLCJ0aW1lIjoxNDE3NTA0NTEwfQ==@emaillabs.pl [ok_desc] => 250 2.0.0 OK 1417504512 kn5si33697578wjb.116 - gsmtp [ok_time] => 2014-12-02 08:15:12 [open_desc] => [open_time] => [postfix_id] => Array ( [0] => 3jsF266HBKz9f50k [1] => 3jsF2650sWz8jd4K ) [tracking] => Array ( ) [tags] => Array ( ) [to] => email_odbiorcy@gmail.com [uid] => 8ba341fe29d5dad8bd683a4cef2dc7d9 [from] => Root User [subject] => Generowane Message-Id 08:15:10 [created_at] => [updated_at] => [id] => 547d67aae1e68a470e43bbe8 ) ) ) |
Następnie niemal jedną linijką kodu można odkodować nasze Message-id do stanu pierwotnego:
|
1 |
json_decode( base64_decode( str_replace('@emaillabs.pl', '', $json->data[0]->message_id) ) ) |
W rezultacie dostaliśmy to:
|
1 2 3 4 5 6 |
stdClass Object ( [oid] => 1234567 [uid] => 87654321 [time] => 1417504510 ) |