Email API — REST-API für event-getriebene Anwendungen

Was ist eine Email API?

Eine Email API ist ein HTTP/JSON-basierter Web-Service zur Versand-Abwicklung — als Alternative zum traditionellen SMTP-Protokoll. Statt einer SMTP-Konnektion mit ihren spezifischen Befehlen (HELO, MAIL FROM, RCPT TO, DATA, QUIT) führt Ihre Anwendung einen einfachen HTTP POST-Aufruf mit JSON-Payload aus. Der Antwort-Code zeigt Erfolg oder Fehler unmittelbar an, ohne komplexe Connection-State-Verwaltung.

Der entscheidende Unterschied zwischen API und SMTP liegt aber nicht in der Übertragung — sondern in der Beobachtbarkeit. Über Webhooks erfahren Sie in Echtzeit, was mit jeder einzelnen Nachricht geschieht: zugestellt (delivered), geöffnet (opened), angeklickt (clicked), zurückgewiesen (bounced), als Spam markiert (complained), abgemeldet (unsubscribed). Diese Beobachtbarkeit ist Voraussetzung für event-getriebene Workflows, in denen E-Mail-Versand integraler Bestandteil des Produkts ist.

Wann ist Email API die richtige Wahl?

API-Endpoints und Versand-Beispiel

Versand einer Nachricht

POST https://api.authorizehosting.com/v3/emails
Authorization: Bearer [Ihr API-Key]
Content-Type: application/json

{
  "from": {
    "email": "noreply@ihre-domain.de",
    "name": "Ihr Unternehmen"
  },
  "to": [{"email": "kunde@example.com", "name": "Kundenname"}],
  "reply_to": {"email": "support@ihre-domain.de"},
  "subject": "Ihre Bestellung wurde bestätigt",
  "html": "<p>Hallo Kundenname,</p>...",
  "text": "Hallo Kundenname, ...",
  "custom_args": {
    "event_type": "order_confirmation",
    "order_id": "ORD-12345",
    "customer_id": "CUST-678"
  },
  "categories": ["transactional", "order_lifecycle"],
  "headers": {
    "X-Idempotency-Key": "order-ORD-12345-v1"
  }
}

Erfolgreiche Antwort

HTTP 202 Accepted
{
  "message_id": "msg_abc123xyz789",
  "queued_at": "2026-04-25T08:30:15Z",
  "status": "queued"
}

Webhooks — die wichtigste Funktion

Webhooks sind das, was API-basierten Versand vom SMTP-Versand qualitativ unterscheidet. Sie konfigurieren eine HTTP-URL in Ihrem System, an die wir POST-Anfragen senden, sobald ein Event eintritt. Ihre Anwendung verarbeitet diese Events in Echtzeit für Datenbank-Updates, Trigger-Aktionen, Reporting an interne Stakeholder.

Webhook-Payload-Beispiel (delivered + opened)

POST https://ihre-anwendung.de/webhooks/email-events
Content-Type: application/json
X-Authorize-Signature: sha256=...

[
  {
    "event": "delivered",
    "timestamp": 1735689600,
    "email": "kunde@example.com",
    "message_id": "msg_abc123xyz789",
    "custom_args": {
      "event_type": "order_confirmation",
      "order_id": "ORD-12345",
      "customer_id": "CUST-678"
    }
  },
  {
    "event": "opened",
    "timestamp": 1735689780,
    "email": "kunde@example.com",
    "message_id": "msg_abc123xyz789",
    "user_agent": "Mozilla/5.0...",
    "ip": "203.0.113.45",
    "custom_args": { ... }
  }
]

Verfügbare Event-Typen

Idempotency und Zuverlässigkeit

Account-Lifecycle-E-Mails — Passwort-Reset, Verifikation, 2FA-Codes — sind Kategorien, in denen Doppelversand inakzeptabel ist. Unsere API unterstützt Idempotency-Keys nativ: Sie übergeben einen eindeutigen Schlüssel pro Versand-Intent (nicht pro Versuch), und unsere Infrastruktur erkennt Wiederholungs-Anfragen mit gleichem Schlüssel und gibt die ursprüngliche Antwort zurück, ohne die Nachricht erneut zu versenden.

Beispiel-Pattern für robusten Versand:

def send_password_reset(user_id):
    idempotency_key = f"pwreset-{user_id}-{token_hash}"
    response = api.post(
        "/v3/emails",
        json={
            "from": {"email": "noreply@app.de"},
            "to": [{"email": user.email}],
            "subject": "Passwort zurücksetzen",
            "html": render_template(...)
        },
        headers={"X-Idempotency-Key": idempotency_key}
    )
    # Bei Wiederholungs-Aufruf mit gleichem Key:
    # Antwort enthält die ursprüngliche message_id, kein Doppelversand

SDK-Unterstützung und Beispiel-Code

Wir bieten offizielle SDKs für die gängigen Sprachen (Python, Node.js, PHP, Java, Go, Ruby). Alternativ funktioniert die API mit jedem HTTP-Client-Library Ihrer Wahl — die API folgt REST-Konventionen und gängigen JSON-Strukturen.

Python (mit offiziellem SDK)

from authorizehosting import Client

client = Client(api_key="...")
response = client.emails.send(
    to=[{"email": "kunde@example.com"}],
    from_={"email": "noreply@ihre-domain.de"},
    subject="Bestellung bestätigt",
    html="<p>...</p>"
)
print(response.message_id)

Node.js (mit offiziellem SDK)

const { Client } = require('@authorizehosting/sdk');
const client = new Client({ apiKey: '...' });

const response = await client.emails.send({
  to: [{ email: 'kunde@example.com' }],
  from: { email: 'noreply@ihre-domain.de' },
  subject: 'Bestellung bestätigt',
  html: '<p>...</p>'
});
console.log(response.messageId);

Häufige Fragen zur Email API