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. Wählen Sie, wofür der Schlüssel gilt: eine einzelne Mailbox oder eine Gruppe von Mailboxen. Die Absenderadresse Ihrer Nachrichten muss auf einer der zugelassenen Domains dieser Mailbox liegen.
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 ersten 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 Webhooks. 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 den API-Schlüsseln zeigt das Dashboard außerdem die jüngste API-Aktivität je Schlüssel — praktisch, um zu sehen, welche Anwendung was tut.

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 erhalten eine Fehlermeldung zurück.

Wo es schiefgeht

• Anfrage abgelehnt — der Schlüssel wurde falsch kopiert, ist widerrufen oder die Absenderdomain gehört nicht zur Mailbox des Schlüssels.
• 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.