Von SendGrid wechseln
Behalten Sie das SendGrid-SDK und senden Sie über OpenEmail. Ändern Sie seine Basis-URL und seinen Schlüssel, und Ihr Sendecode bleibt, wie er ist.
Was Sie ändern
Richten Sie das SDK auf https://api.openemail.uk/compat/sendgrid aus und geben Sie ihm statt des SendGrid-Schlüssels einen OpenEmail-API-Schlüssel mit der Berechtigung emails:send. Er steht im selben Header Authorization: Bearer. Ihre Aufrufe, die Mail senden, bleiben, wie sie sind, und die From-Adresse entscheidet, ob eine Nachricht hinausgehen darf, wie überall in OpenEmail.
import sgMail from '@sendgrid/mail'import client from '@sendgrid/client' client.setApiKey(process.env.OPENEMAIL_API_KEY)client.setDefaultRequest('baseUrl', 'https://api.openemail.uk/compat/sendgrid')sgMail.setClient(client) await sgMail.send({ from: '[email protected]', to: '[email protected]', subject: 'Your invoice', html: '<p>Your invoice is attached.</p>',})Setzen Sie in Node zuerst den Schlüssel auf dem Client, dann die Basis-URL, und übergeben Sie den Client danach dem Mail-Paket. Rufen Sie danach nicht mehr sgMail.setApiKey auf, denn das stellt die Basis-URL auf SendGrid zurück. Das SDK warnt, dass der Schlüssel nicht mit SG. beginnt, was harmlos ist. Geben Sie in Python, Ruby und PHP den Host ohne abschließenden Schrägstrich an.
Was worauf abgebildet wird
Bedient wird der Endpunkt POST /v3/mail/send. Jeder Eintrag in personalizations wird eine eigene OpenEmail-Nachricht mit eigener ID, daher sendet eine Anfrage höchstens 100 Nachrichten.
| SendGrid | In OpenEmail |
|---|---|
| from | Der Absender mit seinem Namen. Eine Personalisierung kann ihr eigenes from angeben. |
| personalizations | Je eine Nachricht. Ihre to, cc und bcc fassen zusammen bis zu 50 Empfänger, und ihre subject, headers, custom_args, send_at und substitutions gelten nur für diese Nachricht. |
| subject | Der Betreff, sofern eine Personalisierung keinen eigenen setzt. |
| content | text/plain wird zum Textteil und text/html zum HTML-Teil. text/x-amp-html bleibt weg, weil der HTML-Teil die Nachricht ohnehin trägt. |
| attachments | Dateien, höchstens 20 und zusammen 5 MB. Ein Inline-Bild, dessen content_id das HTML als cid: verwendet, wird an seiner Stelle eingebettet. Jede andere Inline-Datei kommt als gewöhnlicher Anhang an. |
| reply_to | Die Reply-To-Adresse. reply_to_list funktioniert ebenfalls, solange es eine einzige Adresse enthält. |
| headers | Eigene Header: X-*, List-*, Reply-To, Precedence, Auto-Submitted, Importance, Priority und Feedback-ID. Eine Personalisierung fügt ihre eigenen hinzu. |
| categories | Tags namens category, category_2 und so weiter, jeder mit einer Kategorie. |
| custom_args | Tags mit denselben Namen und Werten. Die Werte einer Personalisierung haben Vorrang. |
| send_at | Ein geplanter Versand, bis zu ein Jahr im Voraus. Ein bereits vergangener Zeitpunkt sendet sofort. |
| substitutions | Jeder Schlüssel wird im Betreff, im Textteil und im HTML-Teil dieser Nachricht durch seinen Wert ersetzt. |
| template_id | Die ID (tpl_...) oder der Slug einer OpenEmail-Vorlage, ausgefüllt aus dynamic_template_data. |
| tracking_settings | open_tracking.enable und click_tracking.enable schalten das Öffnungs- und das Klick-Tracking für die Nachricht ein oder aus. |
| mail_settings | sandbox_mode.enable prüft die Anfrage, den Absender und die Vorlage und antwortet dann mit 200, ohne etwas zu senden. |
Eine Nachricht trägt höchstens 10 Tags, Kategorien und custom_args zusammengezählt. Eine Anfrage, die mehr braucht, wird abgelehnt statt gekürzt, sodass nichts, was Sie gesendet haben, stillschweigend verloren geht.
Was abgelehnt wird, und warum
- Eine SendGrid-Vorlagen-ID in
template_id, etwad-…. Vorlagen bleiben bei SendGrid, legen Sie die Vorlage also in OpenEmail neu an und senden Sie deren ID oder Slug. contentnebentemplate_id, weil eine OpenEmail-Vorlage den gesamten Inhalt liefert.substitutionsmit einer Vorlage aus demselben Grund: Übergeben Sie die Werte indynamic_template_data.- Mehr als eine Reply-To-Adresse,
reply_toundreply_to_listzusammen sowie andere Inhaltstypen als Text und HTML. Senden Sie eine Kalendereinladung als.ics-Anhang. - Eingeschaltetes
mail_settings.footersowiesections, weil OpenEmail keinen Text in Ihre Nachricht schreibt. - Mehr als 10 Tags, ein Tag-Name aus anderen Zeichen als Buchstaben, Ziffern,
_und-, ein Header außerhalb der obigen Liste und mehr als 100 Personalisierungen in einer Anfrage.
asm, batch_id, ip_pool_name, die Bypass-Einstellungen in mail_settings, subscription_tracking, ganalytics, click_tracking.enable_text und open_tracking.substitution_tag werden angenommen und ändern nichts. Adressen auf der Sperrliste des Workspace werden immer übersprungen, ganz gleich, was eine Bypass-Einstellung sagt.
Antworten und Fehler
- Ein Versand antwortet mit 202, leerem Body und der OpenEmail-Nachrichten-ID in
X-Message-Id, der ID, dieGET /emails/{id}und Webhooks verwenden. Bei mehreren Personalisierungen enthält der Header die ID der ersten Nachricht. Ein HeaderIdempotency-Keyfunktioniert wie im Rest der API. - Fehler kommen als
errorszurück, einer Liste ausmessage,fieldundhelp: 400 für eine Anfrage, die nicht gesendet werden kann, 401 für einen fehlenden oder unbekannten Schlüssel, 403 für einen Schlüssel ohneemails:sendoder eine From-Adresse, die der Schlüssel nicht verwenden darf oder deren Domain noch nicht senden kann, 413 für einen Body über 30 MB oder Anhänge über 5 MB und 429, wenn der Workspace sein Versandkontingent aufgebraucht hat. - Scheitert eine Personalisierung, nachdem frühere angenommen wurden, nennt der Fehler die bereits gesendeten Nachrichten, damit ein erneuter Versuch sie auslassen kann.