Rendszer email küldése

Hogy lehet kiküldeni egy rendszer email-t.

2022.11.02 — Posted by Webb & Flow

Tartalomjegyzék

Előfeltételek
Email küldés
Csatolmányok küldése
Titkos másolatok (BCC levelek) küldése
Egyedi válaszcím (REPLYTO) megadása

Előfeltételek

Létre kell hozni az API kapcsolathoz egy Service account-ot
- Service account kezelés
Létre kell hozni azt az email template-et, amit az API-n keresztül küldeni akarunk
- ennek System típusúnak kell lennie, mivel EDM típusú leveleket az email listákon keresztül lehet kiküldeni
- Email kezelés

Email küldés

Az email küldő API végpont a POST https://app.forwardhub.com/send végponton található.

Az email küldéséhez a következő példa kódot felhasználva lehet meghívni az API-t:

$curl = curl_init();
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_ENCODING, "gzip, deflate");
curl_setopt($curl, CURLOPT_HEADER, 1);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $apiKey.':'.$apiPassword);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($curl, CURLOPT_TIMEOUT, 5);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_MAXREDIRS, 10);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt(
    $curl,
    CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'TEMPLATE' => $templateName,
            'TARGET' => $emailOfTarget,
            // a paraméterek értékei
        )
    )
);
curl_setopt($curl, CURLOPT_URL, 'https://app.forwardhub.com/send');

curl_exec($curl);

$curlResult = curl_exec($curl);
$headerSize = curl_getinfo($curl, CURLINFO_HEADER_SIZE);

$result = array(
    'responseHeaders' => substr($curlResult, 0, $headerSize),
    'status' => curl_getinfo($curl, CURLINFO_HTTP_CODE),
    'errorCode' => curl_errno($curl),
    'response' => json_decode(substr($curlResult, $headerSize), 1),
);
curl_close($curl);

A $apiKey illetve $apiPassword változó értéke a service account login, illetve password értéke. A $templateName a template neve úgy, ahogy a template listában és a name mezőben is megjelenik. A $emailOfTarget az az email cím, ahova a levelet küldeni akarjuk.

Az email template paramétereit a ‘CURLOPT_POSTFIELDS’ hívásnál található tömbben lehet felsorolni. A paraméterek nevei lehetnek kis és nagybetűsek is, az API mentéskor midegyiket nagybetűssé konvertálja. A paraméterek értékei minden változtatás nélkül fognak mentődni.

Két kötelező paraméter van:

TEMPLATE
- annak a template-nek a neve vagy az azonosítója, amit ki akarunk küldeni
- amennyiben a küldött értéket a rendszer ismeri, mint template id, azonosítóként fogja kezelni, ellenkező esetben template névként
TARGET
- a címzett email címe

Opcionális paraméter:

LANG
- amennyiben több nyelvű template lett felépítve, itt lehet elküldeni a megfelelő nyelv kódját (ha nincs megadva, akkor a projektben beállított default nyelv lesz használva)

A TARGET paraméter csak olyan email címeket fogad el, amiknél a tld (az utolsó . utáni szöveg a domain névben) minimum 2, de maximum 4 karakter hosszú.

Ezek mellett minden olyan paramétert el kell küldeni, amire a template-ben változóval hivatkozunk, és fel van sorolva a template parameters listájában. Minden paraméter értéke kizárólag skaláris értéket vehetnek fel (string, egész, illetve valós szám). Amennyiben dátumot akarunk beküldeni, azt unix timestamp-ként, egész számként kell küldeni, és a template formázási lehetőségeit kihasználva megjeleníteni a levélben (másik lehetőségként lehet egyből a megfelelő formátumban, string-ként küldeni, ekkor nem kell külön a template-ben formázni, viszont így az API híváskor kell megoldani a nyelv specifikus dátum formázást). Például, ha küldeni akarok egy levelet, amiben a címzett nevét is ismerem, és azt is el akarom küldeni az API-n keresztül, hogy azon tudjam megszólítani, akkor a következőképp fog kinézni a paraméter tömb:

array(
    'TEMPLATE' => 'teszt email template',
    'TARGET' => 'gipsz@jakab.hu',
    'NAME' => 'Gipsz Jakab',
)

Csatolmányok küldése

A csatolmányokat a speciális ‘ATTACHMENTS’ paraméterben kell beküldeni. Ez a csatolmányok listáját tartalmazza (akkor is listát kell küldeni, ha csak 1 csatolmányt akarunk küldeni). Egy csatolmánynak 3 kötelező mezeje van:

name
- a fájl neve
type
- a tartalom mime-type típusa
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types
content
- a fájl tartalma base64 encode-olt string formában

Korlátozások: A csatolmányok száma nincs korlátozva, azonban az összes csatolmány teljes eredeti mérete nem haladhatja meg a 12MB-ot (azaz base64 encode-olt stringként a 16MB-ot).

Példa kód:

$curl = curl_init();
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_ENCODING, "gzip, deflate");
curl_setopt($curl, CURLOPT_HEADER, 1);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $apiKey.':'.$apiPassword);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($curl, CURLOPT_TIMEOUT, 5);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_MAXREDIRS, 10);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt(
    $curl,
    CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'TEMPLATE' => $templateName,
            'TARGET' => $emailOfTarget,
            'ATTACHMENTS' => [
                [
                    'name' => 'file1.txt',
                    'type' => 'text/plain',
                    'content' => base64_encode('content of file1'),
                ],
                [
                    'name' => 'file2.txt',
                    'type' => 'text/plain',
                    'content' => base64_encode('content of file2'),
                ],
                [
                    'name' => 'sheet.pdf',
                    'type' => 'application/pdf',
                    'content' => base64_encode(file_get_contents('path_of_my_pdf_file')),
                ],
            ],
            // a további paraméterek értékei
        )
    )
);
curl_setopt($curl, CURLOPT_URL, 'https://app.forwardhub.com/send');

curl_exec($curl);

$curlResult = curl_exec($curl);
$headerSize = curl_getinfo($curl, CURLINFO_HEADER_SIZE);

$result = array(
    'responseHeaders' => substr($curlResult, 0, $headerSize),
    'status' => curl_getinfo($curl, CURLINFO_HTTP_CODE),
    'errorCode' => curl_errno($curl),
    'response' => json_decode(substr($curlResult, $headerSize), 1),
);
curl_close($curl);

Ez a kód elküld egy levelet 3 csatolmánnyal:

file1.txt
- php oldalon generált txt fájl
file2.txt
- php oldalon generált txt fájl
sheet.pdf
- egy előre generált pdf fájl, ami a ‘path_of_my_pdf_file’ elérési útvonalon található

Titkos másolatok (BCC levelek) küldése

A BCC címzetteket a ‘BCC’ paraméterben kell beküldeni, egy email címeket tartalmazó tömbként.

A BCC levelek önálló levélként lesznek kezelve, de csak attól a pillanattól, hogy az eredeti levél ki lett küldve.

Példa kód:

$curl = curl_init();
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_ENCODING, "gzip, deflate");
curl_setopt($curl, CURLOPT_HEADER, 1);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $apiKey.':'.$apiPassword);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($curl, CURLOPT_TIMEOUT, 5);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_MAXREDIRS, 10);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt(
    $curl,
    CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'TEMPLATE' => $templateName,
            'TARGET' => $emailOfTarget,
            'BCC' => [
                'bcctarget1@example.com',
                'bcctarget2@example.com',
                'bcctarget3@example.com'
            ],
            // a további paraméterek értékei
        )
    )
);
curl_setopt($curl, CURLOPT_URL, 'https://app.forwardhub.com/send');

curl_exec($curl);

$curlResult = curl_exec($curl);
$headerSize = curl_getinfo($curl, CURLINFO_HEADER_SIZE);

$result = array(
    'responseHeaders' => substr($curlResult, 0, $headerSize),
    'status' => curl_getinfo($curl, CURLINFO_HTTP_CODE),
    'errorCode' => curl_errno($curl),
    'response' => json_decode(substr($curlResult, $headerSize), 1),
);
curl_close($curl);

Ez a kód elküld egy levelet a $emailOfTarget email címre, és 3 titkos másolatot a következő címekre:

bcctarget1@example.com
bcctarget2@example.com
bcctarget3@example.com

Egyedi válaszcím (REPLYTO) megadása

Amennyiben a levél küldésekor teljesen egyedi válaszcímet akarunk megadni, és nem azt használni, amit a levél template-je, vagy a projekt alap beállítása ad, a címet a ‘REPLYTO’ mezőben kell küldeni.

Példa kód:

$curl = curl_init();
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_ENCODING, "gzip, deflate");
curl_setopt($curl, CURLOPT_HEADER, 1);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $apiKey.':'.$apiPassword);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($curl, CURLOPT_TIMEOUT, 5);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_MAXREDIRS, 10);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt(
    $curl,
    CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'TEMPLATE' => $templateName,
            'TARGET' => $emailOfTarget,
            'REPLYTO' => 'replyto@example.com',,
            // a további paraméterek értékei
        )
    )
);
curl_setopt($curl, CURLOPT_URL, 'https://app.forwardhub.com/send');

curl_exec($curl);

$curlResult = curl_exec($curl);
$headerSize = curl_getinfo($curl, CURLINFO_HEADER_SIZE);

$result = array(
    'responseHeaders' => substr($curlResult, 0, $headerSize),
    'status' => curl_getinfo($curl, CURLINFO_HTTP_CODE),
    'errorCode' => curl_errno($curl),
    'response' => json_decode(substr($curlResult, $headerSize), 1),
);
curl_close($curl);

Ez a kód elküld egy levelet, aminek a ReplyTo mezejének az értéke a replyto@example.com cím lesz.