Einen API-Schlüssel erstellen

Mit einem API-Schlüssel versendet eine Anwendung direkt über die REST-API von 2Mail, ohne SMTP-Verbindung, und bekommt je Nachricht eine Kennung zurück, um den Status zu verfolgen. Sie legen je Anwendung einen eigenen Schlüssel an, damit Sie ihn einzeln widerrufen können.

Schritt 1: den Schlüssel anlegen

1. Öffnen Sie im Dashboard von 2Mail den Bereich mit den API-Schlüsseln.
2. Legen Sie einen neuen Schlüssel an und geben Sie ihm den Namen der Anwendung, die ihn verwenden wird: den Namen Ihres Onlineshops, Ihres CRM, Ihres Rechnungsprogramms. Keinen allgemeinen Namen wie "Produktion" — in einem Jahr weiß niemand mehr, wofür der gedacht war.
3. Verknüpfen Sie den Schlüssel mit der Versanddomain oder den Versanddomains, für die er versenden darf.
4. Speichern Sie und kopieren Sie den Schlüssel sofort. Aus Sicherheitsgründen wird er nur ein einziges Mal vollständig angezeigt; danach sehen Sie nur noch den Namen und die letzten Zeichen.

Schritt 2: den Schlüssel sicher aufbewahren

Legen Sie den Schlüssel in der geheimen Konfiguration Ihrer Anwendung ab — einer Umgebungsvariable oder einer Secrets-Verwaltung — und niemals im Quellcode, in einer E-Mail oder in einer Chatnachricht. Wer den Schlüssel hat, kann im Namen Ihrer Domain versenden. Verwenden Sie für Test- und Produktionsumgebung je einen eigenen Schlüssel, dann berührt ein Test niemals Ihre echten Kunden.

Schritt 3: den Schlüssel verwenden

Ihre Anwendung sendet den Schlüssel im Autorisierungs-Header jeder Anfrage an die API mit. Die Dokumentation bei der E-Mail-API beschreibt die Endpunkte für das Versenden einer Nachricht, das Abfragen des Status und das Verwalten von Listen. Jede Anfrage, die eine Nachricht versendet, gibt eine Kennung zurück; bewahren Sie diese bei der Nachricht in Ihrem eigenen System auf, dann können Sie später Status und Bounces daran knüpfen.

Schritt 4: testen

Versenden Sie eine einzelne Nachricht an eine externe Testadresse und prüfen Sie sie im Zustellprotokoll des Dashboards. Bei der Protokollzeile steht der Name des Schlüssels, mit dem sie versendet wurde — praktisch, um zu sehen, welche Anwendung was versendet.

Einen Schlüssel widerrufen oder ersetzen

Vermuten Sie, dass ein Schlüssel geleakt ist, oder verlässt der Entwickler das Haus, der ihn kannte, legen Sie zuerst einen neuen Schlüssel an, tragen Sie ihn in die Anwendung ein und widerrufen Sie erst danach den alten. So steht die Anwendung nie still. Ein widerrufener Schlüssel funktioniert sofort nicht mehr; Anfragen damit erscheinen als abgelehnt im Protokoll.

Wo es schiefgeht

• Anfrage abgelehnt — der Schlüssel wurde falsch kopiert, ist widerrufen oder nicht mit der Domain verknüpft, für die Sie versenden.
• Schlüssel verloren — er kann nicht erneut angezeigt werden; legen Sie einen neuen an.
• Ein Schlüssel für alles — funktioniert, bis Sie damit eine einzelne Anwendung abschalten müssen. Teilen Sie sie auf.

Möchten Sie auch Zustellungen, Bounces und Öffnungen zurück in Ihre Anwendung bekommen, richten Sie einen Webhook ein.

Klappt es nicht?

Geben Sie uns über Kontakt den Namen des Schlüssels und die Uhrzeit Ihrer Anfrage durch. Niemals den Schlüssel selbst — den müssen wir nicht sehen.