Leitfaden
Von SparkPost migrieren
Wechseln Sie von SparkPost (jetzt Bird Email) zu Emailit. Transmissions und Substitution Data umwandeln, die SMTP-Einstellungen mit SMTP_Injection austauschen und Event-Webhooks, Sperrungen, Vorlagen und DNS umziehen.
Diese Anleitung ordnet Konzepte, API-Aufrufe, Webhooks, Sperrungen und Vorlagen von SparkPost ihren Entsprechungen in Emailit zu. SparkPost gehört jetzt zu Bird und wird als Bird Email verkauft, und die SparkPost-API unter api.sparkpost.com läuft weiterhin. Diese Anleitung behandelt diese API. Lesen Sie zuerst Zu Emailit migrieren für die allgemeine Reihenfolge und den parallelen Betrieb beider Anbieter.
Konzepte
| SparkPost | Emailit |
|---|---|
| Hauptkonto und Subaccounts | Konto und Workspaces. Jeder Workspace hat eigene Domains, Schlüssel, Mitglieder und Credits. |
| US- und EU-Konten auf getrennten API-Hosts | Ein API-Host, api.emailit.com |
| API-Schlüssel mit Grants | API-Schlüssel: Full Access oder Sending Only, optional auf eine Domain beschränkt |
| Versanddomains | Versanddomains |
| Bounce-Domains | Der Return-Path emailit.<your domain>, den jede Domain hat |
| Tracking-Domains | Tracking-Subdomain wie go.acme.com |
| Transmissions | E-Mails, eine Anfrage pro Nachricht |
| Gespeicherte Empfängerlisten | Kontaktlisten und Kampagnen |
| Vorlagen und Snippets | Vorlagen mit Alias und Versionen. Snippets gibt es nicht. |
| Event-Webhooks | Webhooks |
| Inbound-Domains und Relay-Webhooks | Eingehende E-Mails |
| Sperrliste | Sperrungen |
metadata, tags, campaign_id |
meta |
options.sandbox |
Kein Testmodus. Neue Workspaces sind im Sandbox-Modus und stellen nur an Mitglieder des Workspace zu. |
| IP-Pools | Dedizierte IPs auf Anfrage |
API-Aufrufe anpassen
Aus POST /api/v1/transmissions von SparkPost wird POST /v2/emails. Der Inhalt wandert auf die oberste Ebene, und aus den Empfängern werden to, cc und 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>, ohne Bearer |
Authorization: Bearer secret_… |
content.from, ein String oder { email, name } |
from: "Name <email>" |
recipients[].address |
to, ein String oder ein Array mit bis zu 50 Adressen |
Cc und Bcc als zusätzliche Empfänger mit header_to und einem Header CC |
cc und bcc |
content.reply_to |
reply_to |
content.subject, content.text, content.html |
subject, text, html |
content.headers |
headers |
content.attachments[] mit name, type, data |
attachments[] mit filename, content_type, content |
content.inline_images[] |
attachments[] mit einer content_id, im HTML als cid: referenziert |
content.template_id |
template: Ein Alias sendet die veröffentlichte Version, eine tem_-ID genau diese Version, ob Entwurf oder nicht |
substitution_data |
variables |
metadata, recipients[].tags, campaign_id |
meta, ein Objekt aus String-Werten, das in Webhook-Events zurückgegeben wird |
options.open_tracking, options.click_tracking |
tracking: { "loads": true, "clicks": true } |
options.start_time (bis zu 3 Tage im Voraus) |
scheduled_at (ISO 8601 oder englischer Klartext) |
options.transactional |
Nicht nötig. E-Mails per API erhalten nie List-Unsubscribe-Header, außer Sie fügen sie hinzu. |
content.email_rfc822 |
Senden Sie die MIME-Nachricht über das SMTP-Relay |
recipients: { "list_id": "…" } |
Eine Kampagne an eine Kontaktliste |
Header Idempotency-Key |
Header Idempotency-Key, 24 Stunden lang gespeichert |
Antwort mit der id der Transmission und Empfängerzahlen |
200 mit id (em_…), status: "accepted" und, bei mehreren Empfängern, ids mit einer ID pro Empfänger |
SparkPost sendet jedem Empfänger einer Transmission eine eigene Nachricht, und niemand sieht die anderen Adressen. In Emailit erscheinen alle Adressen aus to und cc in den Headern jeder Kopie. Um Empfänger getrennt zu halten oder jedem eigene substitution_data zu geben, senden Sie eine Anfrage pro Empfänger. Sie erhalten die E-Mail-IDs sofort, statt Message-IDs erst in späteren Events zu finden. Siehe E-Mail senden.
SMTP-Einstellungen umstellen
| Einstellung | SparkPost | Emailit |
|---|---|---|
| Host | smtp.sparkpostmail.com oder smtp.eu.sparkpostmail.com |
smtp.emailit.com |
| Port | 587 oder 2525 (STARTTLS) |
587, 2587, 2525 oder 25 (STARTTLS), 465 (TLS) |
| Benutzername | SMTP_Injection |
emailit |
| Passwort | Ein API-Schlüssel mit der Berechtigung Send via SMTP | Ihr Emailit-API-Schlüssel |
Emailit liest den Header X-MSYS-API nicht. Entfernen Sie ihn. Geben Sie Cc- und Bcc-Adressen in der Nachricht als normale Empfänger an, legen Sie das Tracking bei der Domain fest und nutzen Sie die API, wenn Sie Metadaten brauchen. Siehe SMTP-Einstellungen.
Webhook-Events zuordnen
| SparkPost-Event | Emailit-Event |
|---|---|
injection |
email.accepted (nur API) |
delivery |
email.delivered |
delay |
email.attempted |
bounce, out_of_band |
email.bounced |
policy_rejection |
email.suppressed, wenn die Adresse eine Sperrung vom Typ recipient hat |
generation_failure, generation_rejection |
Kein Event. Probleme wie eine unbekannte Vorlage sind Fehler in der API-Antwort. |
spam_complaint |
email.complained |
open, initial_open |
email.loaded |
click |
email.clicked |
list_unsubscribe, link_unsubscribe |
email.unsubscribed, nur für Kampagnen-E-Mails |
| Relay-Webhook | email.received, dann den Inhalt mit GET /emails/{id} abrufen |
Das Anfrageformat ändert sich:
- Beide senden ein JSON-Array von Events. SparkPost verpackt jedes Event in
msysund eine Klasse wiemessage_event. Emailit legt den Namen intypeund die E-Mail indata.objectab, mit bis zu 100 Events pro Anfrage. - Verwenden Sie
data.object.id, dieem_-ID aus der Antwort auf den Versand, stattmessage_idundtransmission_idunddata.object.tostattrcpt_to. Ihremeta-Werte, diercpt_metaundrcpt_tagsersetzen, stehen indata.object.meta. - Bei
email.loadedundemail.clickedistdata.objectder Ladevorgang oder der Klick. Verwenden Siedata.object.email_idfür die ID der E-Mail sowiedata.object.email.rcpt_tounddata.object.email.metafür den Empfänger und Ihremeta-Werte. - SparkPost schützt Webhooks mit Basic Authentication oder OAuth 2.0, ohne Signatur. Emailit signiert jede Anfrage: Verifizieren Sie
X-Emailit-Signatureanhand vonX-Emailit-Timestampund Ihremwhsec_-Secret. Siehe Anfragesignatur.
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);
}Sperrungen umziehen
-
Exportieren Sie die Sperrliste mit
GET /api/v1/suppression-list?per_page=10000&cursor=initialund folgen Sie dem Cursor, bis Sie alle Seiten haben. Sie enthält auch die Einträge Ihrer Subaccounts, jeweils mit ihrersubaccount_id. -
Erstellen Sie eine CSV-Datei mit den Spalten
email,type,reason:Eintrag in SparkPost Typ in Emailit transactionaloder beide Typenrecipient, der Versände per API, SMTP und Kampagne blockiertNur non_transactionalunsubscribe, der Kampagnen stoppt, transaktionale E-Mails aber weiter durchlässtopen_trackingLassen Sie den Eintrag weg. Er blockiert keinen Versand. email,type,reason old-address@example.com,recipient,sparkpost bounce rule left@example.com,unsubscribe,sparkpost unsubscribe link -
Wählen Sie unter Email APISuppressions die Option Import und laden Sie die Datei hoch. Jede Datei darf bis zu 10.000 Zeilen haben und höchstens 8 MB groß sein. Duplikate werden übersprungen.
Wenn Sie Subaccounts genutzt haben, teilen Sie die Datei nach Subaccount auf und importieren Sie jeden Teil in den passenden Workspace. Siehe Sperrungen verwalten.
Vorlagen umziehen
Holen Sie jede veröffentlichte Vorlage mit GET /api/v1/templates/{id}?draft=false ab, das content.html, content.text und content.subject zurückgibt. Importieren Sie sie unter Email MarketingTemplates oder erstellen Sie sie mit der Vorlagen-API und verwenden Sie die Vorlagen-ID aus SparkPost als Alias, sofern sie dem Alias-Format aus Kleinbuchstaben, Ziffern, - und _ entspricht.
Wandeln Sie die Vorlagensprache von SparkPost in Temple um:
| SparkPost | Emailit (Temple) |
|---|---|
{{name}}, {{order.total}} |
Identisch |
{{address.name}}, {{address.email}} (der Empfänger) |
Übergeben Sie sie in variables, zum Beispiel als name und email |
{{{html_block}}} |
{{html_block}}. Temple maskiert HTML nie, maskieren Sie Benutzereingaben also selbst. |
{{name or 'Customer'}} |
{{name|"Customer"}} |
{{if plan}}…{{else}}…{{end}} |
{{#if plan}}…{{else}}…{{/if}} |
{{if plan == 'pro'}}, {{elseif}}, and, or |
Nicht unterstützt. Übergeben Sie einen Boolean wie is_pro und verwenden Sie {{#if is_pro}}. |
{{each items}}…{{end}} |
Nicht unterstützt. Rendern Sie die Liste in Ihrem Code und übergeben Sie sie als eine Variable. |
render_snippet(), render_dynamic_content() |
Nicht unterstützt. Fügen Sie den Inhalt in die Vorlage ein oder übergeben Sie ihn als Variable. |
substitution_data |
variables |
Siehe Temple und Vorlagen importieren und exportieren.
DNS ändern
Fügen Sie Ihre Domain unter Email APIDomains hinzu und legen Sie die Einträge von Emailit an. Sie verwenden eigene Namen (emailit._domainkey, emailit.<domain> und optional go und inbound) und kollidieren daher weder mit dem DKIM-Eintrag von SparkPost (ein Selektor wie scph0316._domainkey) noch mit dessen CNAMEs für Bounce-Domain und Tracking-Domain. Behalten Sie Ihren DMARC-Eintrag. Siehe DNS-Einträge.
Wenn Ihre Tracking-Domain oder Inbound-Domain bei SparkPost bereits den Namen go oder inbound verwendet, wählen Sie mit tracking_key und inbound_key andere Namen für Emailit. Siehe Eigene Tracking-Domain einrichten und Eingehende E-Mails einrichten.
Entfernen Sie nach der Umstellung die DKIM-, Bounce- und Tracking-Einträge von SparkPost. Wenn Sie E-Mails mit Relay-Webhooks empfangen, verlagern Sie das zuerst auf eine Inbound-Subdomain von Emailit und entfernen Sie dann die MX-Einträge rx1, rx2 und rx3 von SparkPost.
Nächste Schritte
- Go-live-Checkliste
- Webhook einrichten
- Priority migration: Lassen Sie Engineers von Emailit den Umzug gemeinsam mit Ihnen erledigen