Entwicklerübersicht

Diese Seite fasst die Konventionen zusammen, die Sie kennen sollten, bevor Sie Code für Emailit schreiben: wo die API liegt, wie Anfragen authentifiziert werden, wie Objekte identifiziert werden und wie Fehler, Paginierung und Rate Limits funktionieren. Jeder Abschnitt verweist auf die ausführliche Referenz.

Integrationsmöglichkeiten

Sie sind unsicher, ob Sie die API oder SMTP verwenden sollen? Lesen Sie API oder SMTP.

Basis-URL und Versionierung

Alle REST-Endpunkte liegen unter einer Basis-URL:

https://api.emailit.com/v2

v2 ist die aktuelle und einzige dokumentierte Version. Die alte API v1 ist veraltet; siehe Versionierung.

Authentifizierung

Senden Sie bei jeder Anfrage einen API-Schlüssel als Bearer-Token im Header Authorization:

curl https://api.emailit.com/v2/domains \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

• API-Schlüssel beginnen mit secret_. Ältere Schlüssel ohne das Präfix funktionieren weiterhin.
• Jeder Schlüssel gehört zu einem Workspace und hat einen Scope: Full Access (full) kann jeden Endpunkt aufrufen, Sending Only (sending) kann nur senden und Sendungen verwalten. Siehe API-Schlüssel.
• OAuth-Zugriffstokens, die an OAuth-Apps ausgegeben wurden, werden im selben Header akzeptiert.
• Ein fehlender Schlüssel gibt 401 mit API key required zurück, ein unbekannter Schlüssel 401 mit Invalid API key und ein gesperrter Workspace 403 mit Workspace is suspended.

Rufen Sie die API nie mit Ihrem Schlüssel aus einem Browser oder einer mobilen App auf. Behalten Sie ihn auf Ihrem Server. Details: Authentifizierung.

IDs und Präfixe

Jedes Objekt hat eine String-ID mit einem Typpräfix, sodass Sie auf einen Blick erkennen, worauf sich eine ID bezieht.

Domains, die vor der Umstellung auf dom_-IDs erstellt wurden, können noch IDs mit sd_ oder sed_ haben.

Einige Endpunkte akzeptieren statt der ID auch eine lesbare Kennung: einen Namen bei API-Schlüsseln, Domains, Webhooks, Kampagnen und Kontaktlisten und eine E-Mail-Adresse bei Kontakten und Sperrungen. E-Mails, Vorlagen und Events werden nur per ID gefunden.

Anfragen und Antworten

• JSON rein, JSON raus. Senden Sie Anfrage-Bodys als JSON mit Content-Type: application/json. Fehlerhaftes JSON gibt 400 mit Invalid JSON in request body zurück. Ein Anfrage-Body darf bis zu 50 MB groß sein, die endgültige MIME-Nachricht einer E-Mail bis zu 40 MB.
• Fehler. Die meisten Fehler geben {"statusCode", "error", "message"} zurück. Validierungsfehler enthalten zusätzlich ein Array details, Versandfehler geben validation_errors zurück. Tarifabhängige Funktionen geben 403 mit "error": "plan_required" zurück. Siehe Fehler.
• Paginierung. Listen-Endpunkte akzeptieren page und limit (1 bis 100) und geben data, next_page_url und previous_page_url zurück. Vorlagen und Automatisierungen verwenden page und per_page. Siehe Paginierung.
• Filtern und Sortieren. Filtern Sie mit field.condition=value, kombinieren Sie Filter mit match=all oder match=or und sortieren Sie mit order und direction. Zum Beispiel GET /v2/emails?status.exact=bounced&order=created_at&direction=desc. Siehe Filtern.
• Idempotenz. Senden Sie bei POST /emails und POST /emails/:id/forward einen Header Idempotency-Key, damit Wiederholungen sicher sind. Emailit liefert 24 Stunden lang die erste Antwort erneut aus. Siehe Idempotenz.
• Rate Limits. Der Versand ist pro Workspace begrenzt, standardmäßig auf 2 E-Mails pro Sekunde und 5.000 E-Mails pro Tag, gemeinsam für API und SMTP. Antworten enthalten ratelimit-*-Header, und eine Antwort mit 429 enthält retry-after. Siehe Rate Limits und Limits.

SDKs

Offizielle Bibliotheken kapseln die REST-API für Node.js, PHP, Laravel, Python, Ruby, Go, Java, .NET und Rust. Alle liegen auf GitHub. Installationsbefehle finden Sie unter SDKs und Bibliotheken, vollständige Beispiele in den Framework-Anleitungen, beginnend mit Node.js.

Webhooks

Webhooks senden Events an Ihren Endpunkt, sobald sie eintreten: Zustellungen, Bounces, Öffnungen, Klicks, eingehende E-Mails und Änderungen an Domains, Kontakten und anderen Ressourcen. Jede Anfrage enthält ein JSON-Array mit bis zu 100 Events und ist mit HMAC-SHA256 im Header X-Emailit-Signature signiert. Fehlgeschlagene Anfragen werden in bis zu 11 Versuchen wiederholt. Beginnen Sie mit Webhook einrichten und Anfragesignatur.

MCP-Server und KI-Tools

Der gehostete MCP-Server unter https://api.emailit.com/mcp stellt KI-Assistenten 109 Tools bereit, die die gesamte API v2 abdecken, vom E-Mail-Versand bis zu Kampagnen und Automatisierungen. Assistenten melden sich per OAuth oder mit einem API-Schlüssel an, und die Emailit-Plugins ergänzen Skills für ChatGPT, Codex, Claude Code, Cursor und Grok.

Die Doku wird auch für KI veröffentlicht: Jede Seite hat eine Markdown-Version, und /docs/llms.txt indexiert sie alle.

Nächste Schritte