E-Mail-API: Kompletter Leitfaden für Entwickler (2026)

E-Mail-API-Integration: Von OAuth zu Echtzeit-Synchronisation

Eine reale E-Mail-API-Integration durchläuft vier Phasen, unabhängig davon, welchen Anbieter Sie anvisieren. Lesen Sie diesen Abschnitt als Checkliste, bevor Sie mit Ihrer Implementierung beginnen: Das Überspringen eines Schritts ist der häufigste Grund dafür, dass Integrationen in der Entwicklung funktionieren und in der Produktion fehlschlagen.

OAuth 2.0 Authentifizierung

Sowohl Gmail als auch Microsoft Graph verwenden den Standard OAuth 2.0-Autorisierungscode-Fluss. Die Mechanik ist identisch: leiten Sie den Benutzer zum Anbieter weiter, erhalten Sie einen Einmalcode an Ihrer Callback-URL, tauschen Sie ihn serverseitig gegen ein langlebiges Refresh-Token aus und verwenden Sie dann dieses Refresh-Token, um für jeden nachfolgenden API-Aufruf kurzlebige Access-Token zu generieren.

• Leiten Sie den Benutzer mit Ihrer an den Autorisierungsendpunkt des Anbieters weiter client_id, redirect_uri, und die angeforderte Umfang.
• Der Nutzer erteilt die Berechtigungen, der Anbieter leitet mit einer einmaligen zu Ihrer Callback-URL weiter Code Parameter.
• Ihr Server tauscht das aus Code für ein Zugriffstoken (1 Stunde Lebensdauer) und eine Aktualisierungsschlüssel über einen Back-Channel POST.
• Speichern Sie die Aktualisierungsschlüssel sicher serverseitig, ruhend verschlüsselt. Dies ist die langlebige Anmeldeinformation, die Sie zum automatischen Generieren neuer Zugriffstoken verwenden.

E-Mails senden & empfangen

Nach der Authentifizierung decken die nächsten beiden Operationen 80% des typischen E-Mail-API-Gebrauchs ab: Posteingang abrufen und eine Nachricht senden. Mit der einheitlichen API von Unipile funktionieren beide identisch über Gmail, Outlook und IMAP über einen einzigen Satz von Endpunkten.

# Holen Sie die neuesten 50 E-Mails aus einem verbundenen Posteingang
curl --request GET \
  --url 'https://api.unipile.com/api/v1/emails?limit=50&folder=inbox' \
  --header 'X-API-KEY: YOUR_API_KEY'

# Senden Sie eine einfache Text-E-Mail
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "account_id": "YOUR_ACCOUNT_ID",
    "subject": "Hallo von Unipile",
    "body": "Hallo, dies ist eine einfache Text-E-Mail",
    "to": [{"display_name":"John Doe","identifier":"john@example.com"}]
  }'

Unipile unterstützt auch die typischen fortgeschrittenen Versandfunktionen, die Entwickler erwarten: Anhänge (multipart/form-data mit mehreren Dateien), benutzerdefinierte Header (Übergabe von Arrays von X- vorgezogene Kopfzeilen), Antworten in diesem Thread (die ursprüngliche Nachricht verwendend provider_id), Anzeigename-Überschreibung, erlaubte Absender-Aliase und Öffnungs- / Link-Tracking mit Echtzeit-Webhook-Ereignissen. Jede dieser Zuordnungen entspricht einem einzelnen Feld im Request Body, keine Protokollverhandlung erforderlich.

# Senden mit Anhängen + benutzerdefinierten Headern + Tracking
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --form 'account_id=YOUR_ACCOUNT_ID' \
  --form 'subject=Vertragsentwurf' \
  --form 'body=Bitte finden Sie die v3 im Anhang.' \
  --form 'to=[{"identifier":"sarah@acme.com"}]' \
  --form 'attachments=@/path/to/contract.pdf' \
  --form 'attachments=@/path/to/appendix.png' \
  --form 'custom_headers=[{"name":"X-Campaign-ID","value":"q1-outreach"}]' \
  --form 'tracking_options={"opens":true,"links":true,"label":"q1-outreach"}'

Für eine vollständige Entwicklerreferenz, die alle Sendoptionen und anbieterspezifisches Verhalten abdeckt, siehe unsere E-Mail-API-Leitfaden.

E-Mail-Synchronisierung in Echtzeit

Die Synchronisation des Posteingangs ist der komplexeste Teil jeder E-Mail-Integration und wird am häufigsten missverstanden. Eine robuste E-Mail-Synchronisierung Die Implementierung hat drei verschiedene Phasen: Erstsynchronisierung, inkrementelle Synchronisierung und Echtzeit-Webhook-Benachrichtigungen. Das Auslassen einer davon führt zu einer Integration, die am ersten Tag funktioniert und bei Skalierung fehlschlägt.

Planen Sie Erneuerungen von Anfang an: Gmail Pub/Sub Watch-Abonnements laufen nach 7 Tagen ab und müssen erneuert werden. Microsoft Graph-Abonnements für Mail-Ressourcen laufen nach maximal etwa 3 Tagen ab. Integrieren Sie die Abonnement-Erneuerung in Ihre Hintergrundjob-Infrastruktur. vorher werden, andernfalls wird Ihre Integration keine Ereignisse mehr erhalten.

Webhooks & Ereignisse

Webhooks sind, wie eine moderne E-Mail-API Ihrem Backend in Echtzeit mitteilt, dass etwas passiert ist, ohne dass Sie nachfragen müssen. Anstatt abzufragen /Nachrichten alle 30 Sekunden (teuer und langsam), Sie abonnieren einmal, und der Anbieter sendet Ihnen jedes Mal, wenn eine neue E-Mail ankommt, gelesen wird, beantwortet wird oder gelöscht wird, eine JSON-Nutzlast an Ihren Endpunkt.

Die Veranstaltungen, die Sie normalerweise abonnieren, sind mail_empfangen (Eine neue Nachricht ist im Posteingang eingegangen), E-Mail gesendet (eine ausgehende Nachricht wurde erfolgreich zugestellt), Mail geöffnet (der Empfänger hat es geöffnet, falls Tracking aktiviert ist), E-Mail-Link_geklickt (der Empfänger klickte auf einen getrackten Link), und Kontostatus (Das verbundene Postfach muss neu authentifiziert werden, z. B. nach einer Passwortänderung). Jedes Ereignis enthält genügend Kontext, damit Ihre nachgelagerten Systeme reagieren können, ohne zusätzliche API-Aufrufe tätigen zu müssen.