Průvodce
Přechod ze SparkPostu
Přejděte ze SparkPostu (dnes Bird Email) na Emailit. Převeďte transmissions a substitution data, vyměňte nastavení SMTP_Injection a přesuňte event webhooks, blokované adresy, šablony a DNS.
Tento průvodce mapuje pojmy, volání API, webhooky, blokované adresy a šablony ze SparkPostu na jejich ekvivalenty v Emailitu. SparkPost je dnes součástí společnosti Bird a prodává se jako Bird Email, API SparkPostu na api.sparkpost.com ale dál funguje. Tento průvodce popisuje toto API. Celkové pořadí a souběžný provoz obou poskytovatelů popisuje stránka Přechod na Emailit, přečtěte si ji jako první.
Principy
| SparkPost | Emailit |
|---|---|
| Primary account a subaccounts | Účet a workspace. Každý workspace má vlastní domény, klíče, členy a kredity. |
| Účty v USA a EU na samostatných hostitelích API | Jeden hostitel API, api.emailit.com |
| API keys s grants | API klíče: Full Access, nebo Sending Only, volitelně omezený na jednu doménu |
| Sending domains | Odesílací domény |
| Bounce domains | Return path emailit.<your domain>, který má každá doména |
| Tracking domains | Subdoména pro měření, například go.acme.com |
| Transmissions | E-maily, jeden požadavek na zprávu |
| Stored recipient lists | Seznamy kontaktů a kampaně |
| Templates a snippets | Šablony s aliasem a verzemi. Snippets neexistují. |
| Event webhooks | Webhooky |
| Inbound domains a relay webhooks | Příchozí e-maily |
| Suppression list | Blokované adresy |
metadata, tags, campaign_id |
meta |
options.sandbox |
Testovací režim neexistuje. Nové workspace jsou v režimu sandbox a doručují jen členům workspace. |
| IP pools | Dedikované IP adresy na vyžádání |
Upravte volání API
Z POST /api/v1/transmissions ve SparkPostu se stane POST /v2/emails. Obsah se přesune na nejvyšší úroveň a z příjemců se stanou to, cc a bcc:
curl https://api.sparkpost.com/api/v1/transmissions \
-H "Authorization: $SPARKPOST_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"recipients": [{ "address": { "email": "ada@example.com" } }],
"content": {
"from": { "email": "hello@acme.com", "name": "Acme" },
"subject": "Your receipt",
"text": "Thanks for your order.",
"html": "<p>Thanks for your order.</p>"
}
}'curl https://api.emailit.com/v2/emails \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "Acme <hello@acme.com>",
"to": "ada@example.com",
"subject": "Your receipt",
"text": "Thanks for your order.",
"html": "<p>Thanks for your order.</p>"
}'| SparkPost | Emailit |
|---|---|
Authorization: <API key> bez Bearer |
Authorization: Bearer secret_… |
content.from, řetězec nebo { email, name } |
from: "Name <email>" |
recipients[].address |
to, řetězec nebo pole až 50 adres |
Kopie a skrytá kopie jako další příjemci s header_to a hlavičkou CC |
cc a bcc |
content.reply_to |
reply_to |
content.subject, content.text, content.html |
subject, text, html |
content.headers |
headers |
content.attachments[] s name, type, data |
attachments[] s filename, content_type, content |
content.inline_images[] |
attachments[] s content_id, na které se v HTML odkazujete přes cid: |
content.template_id |
template: alias odešle publikovanou verzi a ID tem_ odešle přesně tuto verzi, i když je to koncept |
substitution_data |
variables |
metadata, recipients[].tags, campaign_id |
meta, objekt s řetězcovými hodnotami, který se vrací v událostech webhooků |
options.open_tracking, options.click_tracking |
tracking: { "loads": true, "clicks": true } |
options.start_time (nejvýše 3 dny dopředu) |
scheduled_at (ISO 8601 nebo běžná angličtina) |
options.transactional |
Není potřeba. E-maily z API nikdy nedostanou hlavičky List-Unsubscribe, pokud je nepřidáte. |
content.email_rfc822 |
Odešlete zprávu MIME přes SMTP relay |
recipients: { "list_id": "…" } |
Kampaň pro seznam kontaktů |
Hlavička Idempotency-Key |
Hlavička Idempotency-Key, uchovává se 24 hodin |
Odpověď s id transmission a počty příjemců |
200 s id (em_…), status: "accepted" a u více příjemců ids s jedním ID pro každého |
SparkPost posílá každému příjemci transmission samostatnou zprávu a nikdo nevidí ostatní adresy. V Emailitu se všichni v to a cc objeví v hlavičkách každé kopie. Pokud chcete příjemce oddělit, nebo každému dát vlastní substitution_data, odešlete pro každého příjemce samostatný požadavek. ID e-mailů dostanete hned a nemusíte hledat ID zpráv v pozdějších událostech. Viz Odeslání e-mailu.
Změňte nastavení SMTP
| Nastavení | SparkPost | Emailit |
|---|---|---|
| Server | smtp.sparkpostmail.com nebo smtp.eu.sparkpostmail.com |
smtp.emailit.com |
| Port | 587 nebo 2525 (STARTTLS) |
587, 2587, 2525 nebo 25 (STARTTLS), 465 (TLS) |
| Uživatelské jméno | SMTP_Injection |
emailit |
| Heslo | API klíč s oprávněním Send via SMTP | Váš API klíč Emailitu |
Emailit nečte hlavičku X-MSYS-API. Odstraňte ji. Adresy pro kopii a skrytou kopii uveďte ve zprávě jako běžné příjemce, měření nastavte na doméně, a když potřebujete metadata, použijte API. Viz Nastavení SMTP.
Namapujte události webhooků
| Událost SparkPostu | Událost Emailitu |
|---|---|
injection |
email.accepted (jen API) |
delivery |
email.delivered |
delay |
email.attempted |
bounce, out_of_band |
email.bounced |
policy_rejection |
email.suppressed, když má adresa blokaci typu recipient |
generation_failure, generation_rejection |
Žádná událost. Problémy, například neznámá šablona, jsou chyby v odpovědi API. |
spam_complaint |
email.complained |
open, initial_open |
email.loaded |
click |
email.clicked |
list_unsubscribe, link_unsubscribe |
email.unsubscribed, jen u e-mailů z kampaní |
| Relay webhook | email.received, pak načtěte obsah přes GET /emails/{id} |
Mění se formát požadavku:
- Oba posílají pole JSON s událostmi. SparkPost každou událost obaluje do
msysa třídy, napříkladmessage_event. Emailit dává název dotypea e-mail dodata.object, s až 100 událostmi na požadavek. - Místo
message_idatransmission_idpoužívejtedata.object.id, IDem_z odpovědi na odeslání, a místorcpt_topoužívejtedata.object.to. Vaše hodnotymeta, které nahrazujírcpt_metaarcpt_tags, jsou vdata.object.meta. - U událostí
email.loadedaemail.clickedje vdata.objectnačtení nebo proklik. Jako ID e-mailu používejtedata.object.email_ida pro příjemce a vaše hodnotymetapoužívejtedata.object.email.rcpt_toadata.object.email.meta. - SparkPost chrání webhooky základní autentizací nebo OAuth 2.0, bez podpisu. Emailit podepisuje každý požadavek: ověřujte
X-Emailit-SignaturevůčiX-Emailit-Timestampa vašemu tajnému klíčiwhsec_. Viz Podpis požadavku.
for (const event of req.body) {
const email = event.data.object;
if (event.type === 'email.bounced') markBounced(email.to, email.id);
if (event.type === 'email.complained') unsubscribe(email.to);
}Přesuňte blokované adresy
-
Vyexportujte suppression list přes
GET /api/v1/suppression-list?per_page=10000&cursor=initiala pokračujte podle kurzoru, dokud nebudete mít všechny stránky. Obsahuje i záznamy vašich subaccounts, každý se svýmsubaccount_id. -
Sestavte jedno CSV se sloupci
email,type,reason:Záznam ve SparkPostu Typ v Emailitu transactionalnebo oba typyrecipient, který blokuje odeslání přes API, SMTP i kampaněJen non_transactionalunsubscribe, který zastaví kampaně, ale transakční e-maily propustíopen_trackingVynechte ho. Odesílání neblokuje. email,type,reason old-address@example.com,recipient,sparkpost bounce rule left@example.com,unsubscribe,sparkpost unsubscribe link -
V Email APISuppressions vyberte Import a nahrajte soubor. Každý soubor může mít až 10 000 řádků a nejvýše 8 MB. Duplicity se přeskočí.
Pokud jste používali subaccounts, rozdělte soubor podle subaccounts a každou část naimportujte do odpovídajícího workspace. Viz Správa blokovaných adres.
Přesuňte šablony
Každou publikovanou šablonu načtěte přes GET /api/v1/templates/{id}?draft=false, které vrací content.html, content.text a content.subject. Naimportujte ji v Email MarketingTemplates, nebo ji vytvořte přes API pro šablony. Jako alias použijte ID šablony ze SparkPostu, pokud odpovídá formátu aliasu: malá písmena, číslice, - a _.
Převeďte šablonovací jazyk SparkPostu na Temple:
| SparkPost | Emailit (Temple) |
|---|---|
{{name}}, {{order.total}} |
Stejně |
{{address.name}}, {{address.email}} (příjemce) |
Předejte je ve variables, například jako name a email |
{{{html_block}}} |
{{html_block}}. Temple nikdy neescapuje HTML, proto vstupy od uživatelů escapujte sami. |
{{name or 'Customer'}} |
{{name|"Customer"}} |
{{if plan}}…{{else}}…{{end}} |
{{#if plan}}…{{else}}…{{/if}} |
{{if plan == 'pro'}}, {{elseif}}, and, or |
Nepodporuje se. Předejte logickou hodnotu, například is_pro, a použijte {{#if is_pro}}. |
{{each items}}…{{end}} |
Nepodporuje se. Vykreslete seznam ve svém kódu a předejte ho jako jednu proměnnou. |
render_snippet(), render_dynamic_content() |
Nepodporuje se. Vložte obsah do šablony, nebo ho předejte jako proměnnou. |
substitution_data |
variables |
Viz Temple a Import a export šablon.
Změňte DNS
Přidejte doménu v Email APIDomains a publikujte záznamy Emailitu. Používají vlastní názvy (emailit._domainkey, emailit.<domain> a volitelně go a inbound), takže nejsou v konfliktu se záznamem DKIM SparkPostu (se selektorem například scph0316._domainkey), s jeho CNAME záznamem bounce domény ani s CNAME záznamem domény pro měření. Záznam DMARC ponechte. Viz DNS záznamy odesílacích domén.
Pokud doména pro měření nebo inbound doména ve SparkPostu už používá název go nebo inbound, zvolte pro Emailit jiné názvy pomocí tracking_key a inbound_key. Viz Nastavení vlastní domény pro měření a Nastavení příchozích e-mailů.
Po přepnutí provozu odstraňte záznamy DKIM, bounce a měření SparkPostu. Pokud přijímáte poštu přes relay webhooks, přesuňte ji nejdřív na příchozí subdoménu Emailitu a pak odstraňte MX záznamy rx1, rx2 a rx3 SparkPostu.
Další kroky
- Kontrolní seznam před ostrým provozem
- Nastavení webhooku
- Prioritní migrace: nechte inženýry Emailitu provést přechod s vámi