LinkedIn
Instagram
WhatsApp
Telegramm
Google Kalender
Slack-Gemeinschaft beitretenE-Mail Sync-API: Wie die E-Mail-Synchronisierung für SaaS-Produkte funktioniert
Entwickeln Sie SaaS-Funktionen, die Benutzer-Inboxes in Echtzeit synchronisieren. Verbinden Sie Gmail, Outlook und IMAP über eine einzige E-Mail-Synchronisierungs-API, mit Webhooks, OAuth-Flows und vollem Ordnerzugriff.
const UnipileClient = require('@unipile/node-sdk');
const client = new UnipileClient({
dsn: process.env.UNIPILE_DSN,
Token: process.env.UNIPILE_TOKEN
});
// Abrufen synchronisierter E-Mails aus verknüpftem Konto
const Emails = await client.email.ListeE-Mails({
Konto_id: 'acc_gmail_xyz',
Ordner: 'POSTeingang',
Grenze: 50
});
// Echtzeit: Webhook registrieren
await client.webhook.create({
URL 'https://yourapp.com/webhooks/email',
Ereignisse: ['E-Mail.neu', 'email.lesen']
});
Was ist eine E-Mail-Synchronisierungs-API?
Eine E-Mail-Synchronisierungs-API ist eine programmatische Schnittstelle, mit der Ihre Anwendung kontinuierlich die Mailbox eines Benutzers spiegeln kann – neue Nachrichten lesen, Statusänderungen verfolgen (gelesen/ungelesen, verschoben, gelöscht) und Ordnerstrukturen widerspiegeln – ohne dass der Benutzer Daten manuell exportieren muss. Im Gegensatz zu einer reinen Send-API E-Mail-Synchronisations-API behält eine Live-Zwei-Wege-Replik des Posteingangs innerhalb Ihres Produkts bei.
Auf Protokollebene stellt jeder Anbieter sein eigenes Synchronisierungsprimitiv bereit: Gmail verwendet Geschichte.Liste with a historyId Cursor, Microsoft Graph verwendet Delta-Abfragen auf dem /nachrichten/delta Endpunkt, und Standard-IMAP-Server unterstützen die IDLE Befehl für Push-Benachrichtigungen. A vereinheitlichte E-Mail-Synchronisierungs-API so Unipile abstrahiert diese drei Protokolle hinter einem einzigen Endpunkt, sodass Ihr Team die Synchronisationslogik einmal schreibt und für alle Anbieter ausliefert.
Wenn Sie ein CRM, ein Vertriebstool, einen KI-E-Mail-Assistenten oder ein SaaS-Produkt erstellen, das Live-Posteingangsdaten benötigt, ist eine E-Mail-Synchronisierungs-API die Grundlage. Für den Versand von Transaktions-E-Mails (Passwort zurücksetzen, Quittungen) ist dies eine andere Kategorie – siehe unser vollständiger E-Mail-API-Leitfaden für unser engagiertes Synchrone vs. transaktionale Vergleiche.
E-Mail-Synchronisierung vs. E-Mail-Versand: Warum die Unterscheidung wichtig ist
Entwickler verwechseln oft E-Mail-Synchronisierungs-APIs mit Transaktions-E-Mail-APIs. Sie dienen gegensätzlichen Zwecken. Die falsche Kategorie zu wählen, wirft Ihre Architektur um Wochen zurück.
Liest und spiegelt das vorhandene Postfach eines Benutzers in Ihre Anwendung. Erfordert die Autorisierung des Benutzers für den Zugriff auf sein Konto (OAuth oder IMAP-Anmeldedaten). Ihre App wird zu einem sekundären Leser ihres Posteingangs.
Genutzt von: CRMs, Sales-Engagement-Tools, KI-E-Mail-Assistenten, Helpdesks, E-Mail-Archivierung, Posteingangsanalysen.
Sendet systemgenerierte E-Mails von Ihrer eigenen Domain. Keine Benutzerautorisierung erforderlich. Sie authentifizieren sich als Absender (API-Schlüssel), nicht als Benutzer. Beispiele: SendGrid, Mailgun, Resend, Amazon SES.
Unipile gehört NICHT in diese Kategorie. Unipile ist die Synchronisationsseite – Lesen und Spiegeln von Benutzereingangskörben über OAuth.
Wer braucht eine E-Mail-Synchronisierungs-API?
Jedes SaaS-Produkt, das eingehende E-Mails eines Benutzers anzeigen, analysieren oder darauf reagieren muss, ist auf eine E-Mail-Synchronisierungs-API angewiesen. Dies sind die fünf häufigsten Anwendungsfälle, die wir in der Praxis sehen.
Protokolliere automatisch jede eingehende und ausgehende E-Mail im richtigen Kontakt-Datensatz. Vertriebsmitarbeiter müssen keine E-Mails mehr kopieren und einfügen; das CRM wird in Echtzeit zum System der Aufzeichnungen. Kein manuelles Weiterleiten von BCC erforderlich.
E-Mail-API-LeitfadenNachverfolgen von Antwortraten, Erkennen von Abwesenheitsnachrichten und Auslösen von Folgeaktionen basierend auf Inbox-Ereignissen. Eine E-Mail-Synchronisierungs-API gibt Ihren Sequenzen Echtzeit-Einblicke in das, was im Posteingang des potenziellen Kunden passiert.
E-Mail programmgesteuert sendenSpeisen Sie einen Live-E-Mail-Stream in einen LLM-Agenten ein, der Antworten entwirft, eingehende Nachrichten kategorisiert, Aufgaben extrahiert oder Tickets weiterleitet. Der Agent benötigt einen kontinuierlichen Synchronisierungsfeed, keinen einmaligen Export. Eine Echtzeit-E-Mail-Synchronisierungs-API ist zwingend erforderlich.
E-Mails programmatisch lesenE-Mails von Kunden automatisch in Support-Tickets umwandeln, einschließlich des gesamten Thread-Kontextes und aller Anhänge. Den Ticketstatus synchronisieren, wenn der Agent antwortet, damit der Posteingang des Kunden den Lösungs-Thread widerspiegelt.
Vergleiche E-Mail-API-AnbieterErfassen Sie jede eingehende und ausgehende E-Mail für Compliance, rechtliche Erkundung oder Analyse. Eine E-Mail-Synchronisierungs-API ermöglicht es Ihnen, ein abfragbares Archiv aller Unternehmenskommunikationen zu erstellen, ohne den Mailserver direkt zu berühren.
Kostenlose E-Mail-API-StufeAnalysieren Sie das E-Mail-Volumen, die Antwortzeiten, die Konversationsmuster und die Stimmung über die verknüpften Konten eines Teams. Marketing-, Operations- und Finanzteams nutzen Inbox-Analysen, um die Kommunikationsqualität zu messen und Engpässe zu identifizieren.
E-Mail-API Vollständige AnleitungWie E-Mail-Synchronisierung funktioniert: OAuth, Delta Sync und Webhooks
Eine E-Mail-Synchronisierungs-API ist mehr als nur ein Lese-Endpunkt. Es ist eine zustandsbehaftete Pipeline, die Benutzer authentifiziert, die Aktualität von Tokens aufrechterhält, den Zustand des Postfachs verfolgt und Änderungen nahezu in Echtzeit liefert. Hier ist, was auf jeder Ebene geschieht.
Der Nutzer klickt in Ihrer App auf "Posteingang verbinden". Er wird auf die Zustimmungsseite von Google oder Microsoft weitergeleitet, wo er die von Ihrer Anwendung angeforderten Bereiche genehmigt. Für Gmail bedeutet das gmail.readonly oder Gmail ändern; für Outlook bedeutet dies Mail.Lesen oder Mail.ReadWrite. Nach der Zustimmung erhält Ihre App einen Zugriffstoken (1 Stunde gültig für Google, 1 Stunde gültig für Microsoft) und ein Aktualisierungstoken (langzeitstabil). IMAP-Konten verwenden Benutzername + Passwort oder OAuth, abhängig von der Konfiguration des Anbieters.
Bei der ersten Synchronisierung führt die E-Mail-Synchronisierungs-API eine vollständige Rücksicherung durch: Sie ruft die Ordnerliste ab (INBOX, Gesendet, Entwürfe, benutzerdefinierte Labels) und ruft aktuelle Nachrichten bis zu einer konfigurierbaren Verlaufsicht ab. Für Gmail wird hierfür users.messages.list mit Paginierung. Für Microsoft Graph verwendet es GET /me/messages. Für IMAP gibt es die Ausgabe POSTEINGANG AUSWÄHLEN gefolgt von einem HOLEN Bereich. Der Schnappschuss gibt Ihrer Datenbank ihren Basiszustand, einschließlich Nachrichten-IDs und Thread-Gruppierungen.
Nachdem der erste Schnappschuss erstellt wurde, wäre es eine Verschwendung des Kontingents und eine Verlangsamung Ihrer App, die gesamte Mailbox wiederholt abzurufen. Delta-Synchronisierung ist die Lösung. Gmail bietet eine historyId Cursor: Du rufst Benutzerverlauf Liste mit dem letzten Bekannten historyId und nur die Änderungen (neue Nachrichten, Label-Änderungen, Löschungen) seit diesem Zeitpunkt erhalten. Microsoft Graph verwendet GET /me/messages/delta with a $Delta-Token. IMAP verwendet UID HOLEN with a GEÄNDERTSEIT Modifikator (CONDSTORE-Erweiterung). Dies Delta Synchronisierung Das Muster hält API-Aufrufe selbst für E-Mail-Postfächer mit hohem Volumen minimal.
Zugriffstoken laufen ab. Ihre E-Mail-Synchronisierungsinfrastruktur muss erkennen 401 Unerlaubt antworten, verwenden Sie den Aktualisierungstoken, um einen neuen Zugriffstoken von Google oder Microsoft zu erhalten, und wiederholen Sie die fehlgeschlagene Anfrage. Dies muss transparent geschehen, ohne die Benutzersitzung zu unterbrechen. Aktualisierungstoken selbst können widerrufen werden – vom Benutzer, durch eine Admin-Richtlinie oder nach 6 Monaten Inaktivität (Google) – daher muss Ihr System den Widerruf erkennen und den Benutzer zur erneuten Autorisierung auffordern.
Regelmäßiges Abfragen führt zu Latenzen – eine 30-sekündige Abfrage bedeutet, dass E-Mails bis zu 30 Sekunden veraltet sein können. Für Echtzeit-Posteingangsfunktionen muss die E-Mail-Synchronisierungs-API unterstützen Push-Benachrichtigungen. Gmail nutzt Google Cloud Pub/Sub: Sie registrieren ein Thema und Gmail veröffentlicht eine Benachrichtigung, wann immer die historyId Fortschritte. Microsoft Graph nutzt Änderungsbenachrichtigungen auf /me/mailFolders/inbox/messages resource. Eine einheitliche E-Mail-Synchronisierungs-API (wie Unipile) normalisiert diese in ein einziges Webhook-Ereignis - E-Mail.Neu - an Ihren Endpunkt geliefert, unabhängig vom Anbieter.
Native E-Mail-Synchronisierungs-APIs: Gmail, Microsoft Graph und IMAP
Jeder der drei E-Mail-Anbieter stellt eine andere Synchronisierungsschnittstelle bereit. Wenn man die Unterschiede versteht, wird klar, warum die Entwicklung einer E-Mail-Synchronisierungs-API für mehrere Anbieter von Grund auf Monate und nicht nur Tage in Anspruch nimmt.
Gmail - history.list + Pub/Sub
Google Workspace & persönliche Konten
Das Synchronisierungsmodell von Gmail basiert auf historyId Cursor. Nach Ihrer anfänglichen Synchronisierung ruft jede nachfolgende Aufforderung Benutzerverlauf Liste gibt nur die Änderungen seit dem letzten bekannten Stand zurück historyId - neue Nachrichten, Hinzufügungen von Labels, Entfernungen von Labels und Löschungen.
Für Echtzeit-Push, Gmail erfordert, dass Sie ein Google Cloud Pub/Sub-Thema einrichten und folgendes aufrufen Benutzer ansehen um es zu registrieren. Gmail sendet daraufhin eine Benachrichtigung (die einen neuen historyId) zu Ihrem Thema, wann immer sich die Mailbox ändert. Ihr Worker abonniert das Thema und ruft Geschichte.Liste um die tatsächlichen Änderungen abzurufen.
Höchstsätze: 1 Milliarde Quoten-Einheiten pro Tag pro Projekt, mit pro Benutzer geltenden Beschränkungen. Benutzer.Nachrichten.Abrufen kostet 5 Einheiten; Benutzerverlauf Liste kostet 2 Einheiten. Für eine Mandantenanwendung wird die Quotenverwaltung zu einer Vollzeitaufgabe. Siehe die E-Mail-API-Leitfaden für mehr.
from googleapiclient.discovery import bauen
#-Delta-Synchronisierung unter Verwendung des „historyId“-Cursors
def Änderungen abrufen(Dienstleistung, Versions-ID):
Ergebnis = service.users().history().list(
NutzerId=ich,
startVerlaufId=historie_id,
Historientypen=[
'NachrichtHinzugefügt',
'NachrichtGelöscht',
'LabelHinzugefügt'
]
).ausführen()
return result.get('Geschichte', [])
Outlook / Microsoft 365 - Graph-Delta-Abfragen
Persönlicher Outlook & Exchange Online / M365
Microsoft Graph verwendet Delta-Abfragen über die /ich/nachrichten/delta Endpunkt. Der erste Aufruf gibt eine vollständige Seite mit Nachrichten zurück, plus ein @odata.deltaLink. Nachfolgende Aufrufe dieses Delta-Links geben nur geänderte Nachrichten seit dem vorherigen Aufruf zurück – neue, geänderte und gelöschte Elemente.
Für Echtzeit-Push, Microsoft Graph unterstützt Änderungsbenachrichtigungen über Webhooks. Sie registrieren ein Abonnement für /me/mailFolders/inbox/messages with a BenachrichtigungsURL. Microsoft sendet eine POST zu Ihrer URL, wenn sich Nachrichten ändern. Abonnements müssen alle 4230 Minuten (ca. 3 Tage) erneuert werden, sonst laufen sie ab.
Anmerkung: Dies umfasst sowohl persönliche Outlook-Konten als auch Microsoft 365 / Exchange Online – sie verwenden dieselbe Graph-API. Siehe Microsoft Graph E-Mail-Integrationshandbuch für Einzelheiten zur App-Registrierung und Zustimmung des Administrators.
// Microsoft Graph Delta-Synchronisation
async function DeltaNachrichten abrufen(Kunde, deltaLink) {
const URL = DeltaLink
|| '/ich/nachrichten/delta';
const res = await client
.API(URL)
.Auswählen('id,Betreff,Von,receivedDateTime')
.bekommen.();
return {
Nachrichten: res.value,
nextDelta: res['@odata.deltaLink']
};
}
IMAP - IDLE-Befehl + UID FETCH
Universeller Fallback für jeden Mailserver
IMAP (RFC 3501) gibt es Jahrzehnte vor modernen Sync-APIs. Es stellt pro Ordner zur Verfügung Sequenznummern und UIDs. Für Delta-Synchronisation, die CONDSTORE Erweiterung (RFC 7162) fügt eine MODSEQUENZ Wert zu jeder Nachricht, sodass Sie nur Nachrichten mit einem abrufen können MODSEQUENZ höher als Ihr letzter bekannter Wert per UID FETCH * (FLAGS) (CHANGEDSINCE modseq).
Für Echtzeit-Push, IMAP unterstützt die IDLE Befehl (RFC 2177). Ihr Client sendet IDLE und der Server drückt EXISTIERT oder löschen Benachrichtigungen bei Ordneränderungen – kein Abfragen erforderlich. Die meisten IMAP-Server unterstützen IDLE; Verbindungen müssen alle 29 Minuten neu aufgebaut werden, um Timeouts zu vermeiden.
IMAP ist entscheidend, da es jeden Mailserver abdeckt, der nicht von Google oder Microsoft verwaltet wird: Corporate Exchange (On-Premise), ProtonMail, Zoho, Fastmail und benutzerdefinierte Domains. Siehe IMAP-Integrationsanleitung für eine vollständige Implementierungsanleitung.
const Imap = require('imap');
const imap = new Imap({ host, port: 993, tls: true });
imap.einmal('bereit', () => {
imap.OpenBox('POSTeingang', true, () => {
imap.on('E-Mail', (NeuAnzahl) => {
// IDLE Push: Neue E-Mail eingetroffen
Neue Nachrichten abrufen(neueAnzahl);
});
});
});E-Mail-API-Funktionsabdeckung nach Anbieter
Eine einzige Unipile-Integration gibt Ihnen Zugriff auf alle E-Mail-Operationen für Gmail, Outlook und IMAP-Anbieter. Klicken Sie auf eine Anbieterüberschrift, um die vollständige Integrationsanleitung zu lesen.
| Merkmal | Google Mail | Outlook / M365 | IMAP / SMTP |
|---|---|---|---|
| Authentifizierung | |||
| OAuth2 (keine Passwortspeicherung) | ✓ | ✓ | App-Passwort |
| Gehosteter Authentifizierungs-/Zustimmungsablauf | ✓ | ✓ | ✓ |
| Automatische Token-Aktualisierung | ✓ | ✓ | ✓ |
| E-Mail-Betrieb | |||
| E-Mail vom Benutzerkonto senden | ✓ | ✓ | ✓ |
| E-Mails lesen & auflisten | ✓ | ✓ | ✓ |
| Senden mit Anhängen | ✓ | ✓ | ✓ |
| Im bestehenden Thread antworten | ✓ | ✓ | ✓ |
| Entwurfsverwaltung | ✓ | ✓ | ✓ |
| Beschriftungen / Ordner | ✓Etiketten | ✓Ordner | ✓Ordner |
| Tägliches Sendelimit (ca.) | ~500 / Tag | ~10.000 / Tag | Serverabhängig |
| Synchronisation & Ereignisse | |||
| Webhooks in Echtzeit | ✓ | ✓ | ✓ |
| Inkrementeller Delta-Sync | ✓ | ✓ | ✓ |
| Thread-Gruppierung | ✓ | ✓ | ✓ |
| SOC 2 Typ II / CASA Stufe 2 | ✓ | ✓ | ✓ |
Google MailOutlook / M365IMAP / SMTPGoogle MailOutlook / M365IMAP / SMTPGoogle MailOutlook / M365IMAP / SMTPGoogle MailOutlook / M365IMAP / SMTPGoogle MailOutlook / M365IMAP / SMTPGoogle MailOutlook / M365IMAP / SMTPGoogle MailOutlook / M365IMAP / SMTPGoogle MailOutlook / M365IMAP / SMTPGoogle MailOutlook / M365IMAP / SMTPGoogle MailOutlook / M365IMAP / SMTPGoogle MailOutlook / M365IMAP / SMTPGoogle MailOutlook / M365IMAP / SMTPGoogle MailOutlook / M365IMAP / SMTPGoogle MailOutlook / M365IMAP / SMTPÜberspringen Sie den Gmail + Graph + IMAP Boilerplate. Eine E-Mail-Synchronisierungs-API deckt alle drei ab.
Die einheitliche E-Mail-Synchronisierungs-API von Unipile verbindet sich über einen einzigen Endpunkt mit Gmail, Outlook und IMAP. OAuth-Flows, Token-Aktualisierung, Delta-Synchronisierung und Webhooks – alles wird für Sie erledigt. Kostenlos starten, keine Kreditkarte erforderlich.
Die verborgene Komplexität der E-Mail-Synchronisierung in großem Maßstab
Der Aufbau einer Proof-of-Concept-E-Mail-Synchronisierungs-API dauert ein Wochenende. Der Aufbau einer für die Produktion zuverlässigen API mit 1.000 verknüpften Konten dauert Monate. Hier ist, was Ihnen niemand vorher erzählt.
Gmail erzwingt pro Benutzer Kontingente (250 Kontingenteinheiten/Sekunde) und tägliche Limits pro Projekt. Microsoft Graph drosselt mit 10.000 Anfragen/10 Minuten pro Anwendung. Bei 500 verknüpften Konten, die alle nach Zeitplan synchronisiert werden, benötigen Sie einen verteilten Ratenbegrenzer mit exponentiellem Backoff, Jitter und isolierten Warteschlangen pro Konto. Eine einzelne Spitzenlast von einem Konto kann das Kontingent für alle anderen erschöpfen.
Jedes verknüpfte Konto hat ein Zugriffstoken, das abläuft. Bei 1.000 Konten können Sie während der Spitzen-Synchronisierungsfenster mit Dutzenden gleichzeitiger Token-Aktualisierungen rechnen. Eine einzelne fehlgeschlagene Aktualisierung führt zu verpassten Synchronisierungszyklen. Sie benötigen einen dedizierten Token-Lebenszyklusdienst mit Wiederholungslogik, Widerrufserkennung und einer Alarmpipeline, um Benutzer aufzufordern, die Autorisierung erneut zu erteilen, wenn Aktualisierungstoken ablaufen.
Gmail verwendet Labels (eine Nachricht kann gleichzeitig mehrere Labels haben). Outlook verwendet Ordner (hierarchisch, mit Verschiebevorgängen). IMAP verwendet ebenfalls Ordner, aber mit Namensräume die je nach Serveranbieter variieren. Die Normalisierung in ein einheitliches Ordner-Modell für Ihre Anwendung erfordert anbieterspezifische Mapping-Logik. Sonderfälle sind freigegebene Postfächer, delegierter Zugriff und die Unterscheidung zwischen "Alle E-Mails" und "Posteingang" bei Gmail.
E-Mail-Anhänge können groß sein. Das Abrufen und Speichern von Anhängen für jede synchronisierte E-Mail über Tausende von Konten hinweg summiert sich schnell in Bezug auf Bandbreite und Speicherkosten. Sie benötigen eine Streaming-Pipeline, die Anhänge nur bei Bedarf herunterlädt, deduplizierten Speicher und eine CDN-Schicht, um sie aus Ihrem Produkt bereitzustellen. MIME-Parsing selbst führt zu Fehlern – E-Mails mit mehreren Teilen, quoted-printable-Kodierung und Inline-Anhänge erfordern jeweils eine spezielle Handhabung.
Gmail-Threads nach ThreadId - ein serverseitiges Konzept. IMAP hat keine native Thread-Funktionalität; Sie rekonstruieren Threads mithilfe des Referenzen und Antwort auf Header (RFC 5322). Outlook hat Gesprächs-ID. Die Normalisierung von Threads über verschiedene Anbieter hinweg – insbesondere bei Antworten über Anbietergrenzen hinweg – erfordert Fallback-Heuristiken, die auf der Subjekt-Normalisierung und Message-ID-Ketten basieren.
Gmail Pub/Sub-Benachrichtigungen sind nicht garantiert – Nachrichten, die während Ausfallzeiten verloren gehen, werden nicht erneut gesendet. Microsoft Graph Webhook-Abonnements laufen ab und müssen erneuert werden. Wenn Ihr Webhook-Empfänger während einer Push-Benachrichtigung nicht verfügbar ist, verpassen Sie das Ereignis und greifen auf Polling zurück. Eine Produktions-E-Mail-Synchronisierungs-API benötigt eine Abgleichschleife, die verpasste Ereignisse mithilfe des Delta-Synchronisierungs-Cursors periodisch erfasst, unabhängig von der Verfügbarkeit von Webhooks.
3 E-Mail-Synchronisierungsarchitekturen im Vergleich
Teams, die E-Mail-Synchronisierungsfunktionen entwickeln, bewerten in der Regel drei Implementierungsmuster. Hier ist ein ehrlicher Vergleich jedes einzelnen, vom Aufwand für die Erstellung bis zu den laufenden Wartungskosten.
E-Mails mit der Unified Email Sync API von Unipile synchronisieren
Die E-Mail-Synchronisierungs-API von Unipile deckt Gmail, Outlook und IMAP über eine einheitliche Schnittstelle ab. OAuth-Flows, Token-Aktualisierung, Delta-Synchronisierung und Webhook-Bereitstellung werden für Sie verwaltet – Ihr Team entwickelt die Funktion, nicht die Infrastruktur.
Registrieren Sie sich unter dashboard.unipile.com. Die kostenlose E-Mail-API-Stufe bietet Ihnen Zugriff auf alle Anbieter ohne Kreditkarte. Sie erhalten Ihren DSN (Data Source Name) und API-Token sofort.
Nutzen Sie den gehosteten OAuth-Flow von Unipile, damit Ihre Benutzer den Zugriff auf ihr Gmail- oder Outlook-Konto autorisieren können. Sammeln Sie für IMAP ihre Anmeldedaten und übergeben Sie sie an POST /konten. Unipile handhabt den OAuth-Redirect, den Token-Austausch und speichert den Refresh-Token sicher.
Rufen GET /E-Mails mit dem account_id des verknüpften Kontos. Unipile führt die Delta-Synchronisation gegen Gmail durch Geschichte.Liste, der Delta-Endpunkt von Microsoft Graph oder IMAP CONDSTORE - Sie erhalten immer die gleiche normalisierte JSON-Antwort, unabhängig vom Anbieter.
POSTE Ihre Endpunkt-URL an die Webhook-API von Unipile. Wenn eine neue E-Mail in einem verknüpften Konto eintrifft – egal ob Gmail, Outlook oder IMAP – liefert Unipile eine normalisierte E-Mail.Neu Ereignis an Ihre URL. Keine Pub/Sub-Einrichtung, keine Erneuerung von Graph-Abonnements, keine Verwaltung von IDLE-Verbindungen. Siehe E-Mail-API-Leitfaden als vollständige Referenz für die Veranstaltung.
Rufen GET /emails/{id} um den vollständigen Nachrichteninhalt (HTML und reinen Text), Header, MIME-Teile und Anhängreferenzen abzurufen. Anhänge werden über signierte URLs bereitgestellt - Sie müssen nie rohe MIME-Daten selbst speichern. Siehe E-Mails programmatisch lesen zum Beispiel.
const axios = require('axios');
const DSN = process.env.UNIPILE_DSN;
const TOKEN = process.env.UNIPILE_TOKEN;
const API = axios.create({
BasisURL: `https://${DSN}/api/v1`,
Kopfzeilen: { 'X-API-KEY': TOKEN }
});
// Schritt 3 – Synchronisierte E-Mails auflisten
async function ListeE-Mails(KontoId) {
const { Daten } = await API.bekommen.('/E-Mails', {
params: {
account_id: accountId,
Ordner: 'POSTeingang',
Grenze: 20
}
});
return Datenpunkte;
}
// Schritt 4 - Webhook registrieren
async function Webhook registrieren() {
await API.Beitrag('/webhooks', {
URL 'https://yourapp.com/api/email-events',
Ereignisse: ['E-Mail.neu', 'E-Mail.aktualisiert']
});
}
// Schritt 5 - Vollständigen E-Mail-Inhalt abrufen
async function E-Mail erhalten(emailId) {
const { Daten } = await API.bekommen.(`/emails/${emailId}`);
return Daten;
}Hören Sie auf, dieselbe E-Mail-Synchronisierungs-Pipeline für jeden Anbieter neu zu erstellen.
Synchronisieren Sie Gmail, Outlook und IMAP über eine einzige E-Mail-Synchronisierungs-API. Echtzeit-Webhooks, Delta-Synchronisierung und OAuth-Token-Verwaltung – alles abgedeckt. Ihr Team konzentriert sich auf das Produkt, nicht auf die Technik.
Echtzeitsynchronisierung von E-Mails: Webhooks vs. Polling vs. IMAP IDLE
Die Wahl des falschen Echtzeitmechanismus für Ihre E-Mail-Synchronisierungs-API erhöht die Latenz, verbraucht Kontingente oder lässt Ihre App bei Ausfällen im Dunkeln. Hier ist ein direkter Vergleich der drei Ansätze.
| Ansatz | Wie es funktioniert | Latenzzeit | Am besten für | Komplexität |
|---|---|---|---|---|
| Webhooks (Push) | Anbieter sendet HTTP POST an deinen Endpunkt, wenn sich ein Postfach ändert. Gmail verwendet Pub/Sub; Microsoft Graph verwendet Änderungsbenachrichtigungen. | Unter 5 Jahren | Gmail, Outlook, vereinheitlichte APIs wie Unipile | Mittel - Abonnementverwaltung erforderlich |
| Umfragen (geplant) | Ihr Worker ruft die Anbieter-API nach einem Zeitplan auf (alle 30 Sek., 1 Min., 5 Min.) und ruft Änderungen mit einem Delta-Cursor ab. | 30 Sek. - 5 Min. | Alle Anbieter, einfache Einrichtung | Niedrig - aber quota-intensiv in großem Maßstab |
| IMAP IDLE (Long-Polling) | Ihr Client sendet IDLE an den Server; der Server sendet EXISTS-Benachrichtigungen, wenn neue E-Mails eintreffen. Verbindung wird bis zu 29 Minuten offen gehalten. | Unter 1 Jahr | Nur IMAP-Server | Hoch - eine TCP-Verbindung pro Mailbox |
Produktionsempfehlung: Nutzen Sie Webhooks als primären Echtzeitmechanismus und führen Sie ein Delta-Sync-Polling als Fallback (alle 5 Minuten) durch, um während Ausfallzeiten verpasste Ereignisse zu erfassen. Mit der E-Mail-Synchronisierungs-API von Unipile sind beides einmal konfiguriert – die vereinheitlichte E-Mail.Neu Der Webhook wird unabhängig davon ausgelöst, ob das Konto Gmail, Outlook oder IMAP ist, und eine Hintergrundabgleichschleife behandelt automatisch verpasste Ereignisse.
Sicherheit und Compliance für E-Mail-Synchronisierungs-APIs
Der Zugriff auf Benutzer-Postfächer schafft erhebliche Sicherheits- und regulatorische Verpflichtungen. Hier ist, was Ihre E-Mail-Synchronisierungs-API-Implementierung vor der Produktionsfreigabe berücksichtigen muss.
Fordern Sie nur die Berechtigungen an, die Ihre Anwendung benötigt. Für die schreibgeschützte E-Mail-Synchronisierung fordern Sie gmail.readonly anstatt Gmail ändern. Für Microsoft Graph, Konto Mail.Lesen anstatt Mail.ReadWrite. GOOGLES CASA-Verifizierung (erforderlich für Apps mit über 100 Nutzern) prüft Ihre angeforderten Bereiche genau – eine übermäßige Anforderung verzögert die Genehmigung.
OAuth-Aktualisierungstoken sind langlebige Anmeldeinformationen, die vollen Postfachzugriff gewähren. Sie müssen verschlüsselt gespeichert werden (mindestens AES-256) und dürfen niemals protokolliert werden. Rotieren Sie Ihre Token-Verschlüsselungsschlüssel regelmäßig. Ein kompromittiertes Aktualisierungstoken entspricht einem kompromittierten Passwort für das verbundene E-Mail-Konto.
Vom EU-Nutzer synchronisierte E-Mail-Inhalte sind gemäß der DSGVO personenbezogene Daten. Sie benötigen eine Rechtsgrundlage für die Verarbeitung (typischerweise die ausdrückliche Zustimmung des Nutzers über OAuth), eine Datenverarbeitungsvereinbarung mit Ihrem E-Mail-Synchronisierungs-API-Anbieter und eine klare Richtlinie zur Datenspeicherung. Wenn Ihre Infrastruktur in den USA ansässig ist, stellen Sie sicher, dass Sie Standardvertragsklauseln oder einen gleichwertigen Übertragungsmechanismus für EU-Daten haben.
Jede Anwendung, die Gmail OAuth-Geltungsbereiche mit mehr als 100 Benutzern verwendet, muss Googles CASA (Cloud Application Security Assessment). Dies ist eine Sicherheitsüberprüfung Ihrer Anwendung, die Code, Infrastruktur und OAuth-Berechtigungsbegründungen umfasst. Der Prozess dauert 4–8 Wochen. Beginnen Sie frühzeitig – ein Scheitern bei CASA bedeutet den Verlust des Gmail-Zugangs für alle Nutzer, bis Sie bestehen.
Verifizieren Sie stets die Signatur bei eingehenden Webhook-Payloads von Ihrer E-Mail-Synchronisierungs-API. Ein nicht signierter oder falsch verifizierter Webhook kann gefälscht werden, um gefälschte E-Mail-Ereignisse in Ihre Anwendung einzuschleusen. Unipile signiert alle Webhook-Lieferungen mit HMAC-SHA256. Verifizieren Sie die X-Unipile-Signatur Header vor der Verarbeitung eines jeden Ereignisses.
Protokolliere jede Aktion, die Ihre Anwendung mit synchronisierten E-Mail-Daten ausführt: Wer hat auf welche Nachrichten zugegriffen, wann und was wurde mit den Daten gemacht. Audit-Protokolle sind für die SOC 2 Typ II-Konformität erforderlich und werden von Unternehmenskunden bei Sicherheitsüberprüfungen oft als Erstes angefragt. Behalten Sie Protokolle mindestens 90 Tage lang auf, idealerweise 1 Jahr.
Häufige Fallstricke beim Erstellen einer E-Mail-Synchronisierungs-API
Das sind die Fehler und architektonischen Schwächen, die wir am häufigsten bei der Implementierung von E-Mail-Synchronisierungs-APIs beobachten. Alle sind mit den richtigen Designentscheidungen von Anfang an vermeidbar.
Wenn ein Aktualisierungstoken abläuft oder widerrufen wird, wirft eine naive Implementierung einen Fehler und stoppt die Synchronisierung – leise. Der Benutzer erfährt erst dann, dass seine Inbox nicht mehr synchronisiert wird, wenn er veraltete Daten bemerkt. Korrigieren: eine Widerrufserkennungsschicht implementieren, die abfängt ungültiger_grant Fehler, kennzeichnet das verknüpfte Konto als re-autorisierungsbedürftig und benachrichtigt den Nutzer über das Benachrichtigungssystem Ihres Produkts.
Das Abrufen von Daten alle 10 Sekunden über 200 verknüpfte Konten sprengt innerhalb weniger Stunden das Kontingent pro Projekt von Gmail. Microsoft Graph gibt zurück 429 Zu viele Ersuchen. Das Ergebnis sind stille Synchronisationsfehler für alle Konten – nicht nur für diejenigen, die die Drosselung ausgelöst haben. Korrigieren: Verwenden Sie Webhooks als primären Mechanismus mit einem 5-Minuten-Polling-Fallback und implementieren Sie pro Konto Ratenbegrenzung mit exponentiellem Backoff für alle 429 Antworten.
Roh-MIME ist groß, schwer abzufragen und teuer zu parsen. Eine einzelne E-Mail mit Anhängen kann Hunderte von Kilobytes groß sein. Korrigieren: MIME-Daten bei der Erfassung analysieren: HTML-Inhalt, Fallback-Text, Header und Metadaten von Anhängen separat extrahieren. Speichern Sie die Binärdateien der Anhänge im Objektspeicher (S3 oder gleichwertig), nicht in Ihrer Primärdatenbank. Allein dadurch lassen sich Ihre Speicherkosten bei typischen Unternehmens-E-Mail-Postfächern um 60–80 % senken.
Gmail ThreadId funktioniert nur innerhalb von Gmail. Wenn Ihre App einen Thread anzeigt, der sich über ein Gmail-Konto und ein Outlook-Konto erstreckt (z. B. eine Antwort, die von einem anderen Postfach gesendet wurde), sind die nativen Thread-IDs nutzlos. Korrigieren: eine plattformübergreifende Threading-Engine basierend auf der Nachrichten-ID, Antwort aufund Referenzen Betreffzeilen normalisieren (Re:/Fwd:-Präfixe entfernen) als Fallback für E-Mails, denen diese Kopfzeilen fehlen.
Delta-Synchronisation basiert auf einem gespeicherten Cursor: GMail's historyId, Microsoft Graph's DeltaLink, IMAP's MODSEQUENZ. Wenn Ihr Synchronisierungsarbeiter neu gestartet wird und der Cursor nur im Speicher gespeichert ist, verlieren Sie Ihre Position im Änderungsstrom. Die nächste Synchronisierung beginnt von vorne, wodurch alle historischen Nachrichten dupliziert oder die Lücke übersehen werden. Korrigieren: Speichern Sie den Cursor nach jedem erfolgreichen Synchronisierungszyklus atomar mit dem letzten Batch verarbeiteter Änderungen in Ihrer Datenbank.
Für CRM-Anwendungsfälle benötigen Sie sowohl eingehende (empfangene) als auch ausgehende (gesendete) E-Mails, um eine vollständige Kommunikationshistorie zu erstellen. Das Gmail-Label "INBOX" deckt nur empfangene E-Mails ab; Sie benötigen auch GESENDET. Microsoft Graph erfordert das Abfragen der Gesendete Elemente Ordner separat. IMAP erfordert die Auswahl des Gesendet explizit im Ordner. Korrigieren: Synchronisieren Sie alle relevanten Ordner beim Einrichten des Kontos, nicht nur den Posteingang, und ordnen Sie providerspezifische Ordnernamen normierten Typen in Ihrem Datenmodell zu.
Häufig gestellte Fragen zu E-Mail-Synchronisierungs-APIs
Die häufigsten Fragen, die Entwickler bei der erstmaligen Implementierung einer E-Mail-Synchronisierungs-API stellen.
historyId Cursor mit dem Benutzerverlauf Liste Endpunkt. Microsoft Graph verwendet einen DeltaLink zurückgegeben von der /nachrichten/delta Endpunkt. IMAP verwendet MODSEQUENZ Wert aus der CONDSTORE-Erweiterung. Eine einheitliche E-Mail-Synchronisierungs-API normalisiert diese drei unterschiedlichen Mechanismen hinter einer einheitlichen Schnittstelle.GET /E-Mails mit dem account_id um synchronisierte Nachrichten abzurufen und einen Webhook-Endpunkt zu registrieren, um Echtzeitdaten zu empfangen E-Mail.Neu Unipile übernimmt OAuth, Token-Aktualisierung, Delta-Synchronisierung und Webhook-Zustellung automatisch.gmail.readonly. Wenn Sie Nachrichten als gelesen markieren oder nach ihnen verschieben müssen, fordern Sie an Gmail ändern. Für Microsoft Graph, Konto Mail.Lesen für schreibgeschützten Zugriff oder Mail.ReadWrite für vollen Zugriff. Fordern Sie immer nur die Mindestberechtigungen an, die Ihre Anwendung tatsächlich benötigt - die CASA-Überprüfung von Google (erforderlich für Apps mit über 100 Nutzern) prüft die Begründung für Berechtigungen genau, und eine übermäßige Anforderung von Berechtigungen kann Ihre Zulassung verzögern.401 Unerlaubt Antworten, verwenden Sie den gespeicherten Aktualisierungstoken, um einen neuen Zugriffstoken zu erhalten, und versuchen Sie die fehlgeschlagene Anforderung transparent erneut. Aktualisierungstoken selbst können widerrufen werden. Wenn ein Widerruf erkannt wird (ungültiger_grant error), markiere das Konto als reauthorisierungsbedürftig und benachrichtige den Benutzer. Unipile verwaltet die gesamte Token-Lebenszyklusverwaltung für verknüpfte Konten automatisch.EXISTIERT Benachrichtigungen, wenn neue Nachrichten eingehen. Dies ermöglicht eine Synchronisation des Posteingangs in nahezu Echtzeit (Latenz unter 1 Sekunde) ohne ständiges Abfragen. IDLE-Verbindungen müssen alle 29 Minuten aktualisiert werden, um Server-Timeouts zu verhindern. IDLE funktioniert mit jedem IMAP-Server, der dies unterstützt, was die meisten modernen Mailserver einschließt, einschließlich Corporate Exchange, Gmail über IMAP und Outlook über IMAP.