API-Schlüssel und Webhooks

Mail Merge hat eine REST-API und ausgehende Webhooks für Entwickler und No-Code-Builder. Mit einem API-Schlüssel können Ihre Skripte das tun, was die Web-App tut: Ihr Konto lesen, Vorlagen und Kontakte auflisten, Kampagnen versenden und deren Empfänger verfolgen. Mit einem Webhook ruft Mail Merge Ihr Endpoint auf, sobald eine Kampagne abgeschlossen ist oder ein Empfänger öffnet, klickt, antwortet, abprallt oder sich abmeldet. So bleibt ein CRM, eine Tabelle oder ein Slack-Kanal synchron, ohne abfragen zu müssen.

Beide befinden sich unter Einstellungen → Entwickler in der Web-App und sind Teil des Professional-Plans (siehe Preise). Wenn Sie lieber mit einem KI-Assistenten mit Mail Merge sprechen möchten, anstatt Code zu schreiben, verwenden Sie stattdessen den MCP-Server: Er stellt die gleichen Funktionen als Tools auf jedem Plan zur Verfügung.

API-Schlüssel

Einen Schlüssel erstellen

1. Öffnen Sie Einstellungen → Entwickler → API-Schlüssel und klicken Sie auf Schlüssel erstellen.
2. Benennen Sie ihn nach dem Ort, an dem er verwendet wird (Zapier, CRM-Synchronisierung), damit Sie später den richtigen widerrufen können.
3. Kopieren Sie den Schlüssel. Er wird nur einmal angezeigt: Mail Merge speichert nur einen Hash davon. Wenn Sie ihn verlieren, widerrufen Sie ihn und erstellen Sie einen neuen.

Sie können bis zu 10 Schlüssel pro Konto haben. Das Widerrufen eines Schlüssels führt dazu, dass jede damit gemachte Anfrage sofort fehlschlägt. Die Zeile verschwindet aus der Liste.

Authentifizierung

Senden Sie den Schlüssel als Bearer-Token bei jeder Anfrage gegen die auf der Karte angezeigte Basis-URL:

curl https://merge.email/api/v1/me \
  -H "Authorization: Bearer mm_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Ein Schlüssel fungiert als das Konto, das ihn erstellt hat, genau wie eine angemeldete Sitzung: die gleiche Google-Berechtigung, das gleiche tägliche Kontingent, die gleichen Plan-Limits. Es gibt keinen separaten “API-Benutzer”.

Endpoints

Die API ist die gleiche /v1-Oberfläche, die die Web-App verwendet, daher hat alles, was Sie auf einem Bildschirm tun können, einen Endpoint dahinter. Die, die Integrationen am häufigsten verwenden:

Aufruf	Was es tut
GET /v1/me	Das Konto: Plan, tägliches Kontingent (Maximum, verwendet, verbleibend), Zeitzone, Template-Metadaten.
GET /v1/templates · GET /v1/templates/{templateId}	Ihre gespeicherten Vorlagen; der Body wird pro Template geladen.
GET /v1/contacts · POST /v1/contacts	Das Adressbuch (paginiert mit limit / cursor → nextCursor).
POST /v1/campaigns	Versenden, planen oder autopilot eine Kampagne aus einem Google Sheet. Der Body ist derselbe, den der Campaign Builder sendet: das Sheet, die Empfängerspalte, der Betreff und Body mit {{merge tags}} und die Versendungsoptionen.
GET /v1/campaigns · GET /v1/campaigns/{campaignId}/recipients	Ihre Kampagnen und den Status jedes Empfängers (versendet, gelesen, geklickt, geantwortet, abgeprallt, abgemeldet).
POST /v1/campaigns/{campaignId}/status	Unterbrechen, fortsetzen oder stoppen Sie eine laufende Kampagne.
POST /v1/recipients/verify	Der Email-Verifizierer.

Request- und Response-Bodies sind JSON. Die vollständige typisierte Oberfläche wird vom Server als OpenAPI-Dokument generiert. Kontaktieren Sie uns, wenn Sie das Schema für einen Client-Generator benötigen.

Fehler und Rate Limit

Fehler sind echte HTTP-Status mit einer Hülle:

{ "error": { "code": "professional_plan_required", "message": "API access is a Professional plan feature" } }

Status	code	Bedeutung
401		Unbekannter oder widerrufener Schlüssel, oder der Google-Zugriff des Kontos muss erneut verbunden werden.
403	professional_plan_required	Das Konto des Schlüssels ist nicht mehr im Professional-Plan. Schlüssel werden bei einem Downgrade nicht gelöscht. Sie funktionieren wieder, wenn der Plan es tut.
429	rate_limited	Mehr als 600 Anfragen pro Minute auf einem Schlüssel. Warten Sie eine Minute und versuchen Sie es erneut.
400 / 404 / 409	bad_request, not_found, conflict, …	Die Anfrage selbst, mit einer Nachricht, die sagt, was zu beheben ist.

Das Rate Limit wird pro Schlüssel auf jeder API-Server-Instanz gezählt, daher ist die effektive Obergrenze “etwa 600 pro Minute”: Planen Sie nicht, dieses Limit zu erreichen.

Webhooks

Ein Endpoint hinzufügen

1. Öffnen Sie Einstellungen → Entwickler → Webhooks und klicken Sie auf Webhook hinzufügen.
2. Geben Sie eine HTTPS-URL ein (einfaches http:// wird abgelehnt) und aktivieren Sie die Ereignisse, die es erhalten soll.
3. Klicken Sie auf Test senden in der neuen Zeile: Mail Merge sendet einen ping und der Toast zeigt Ihnen, wie Ihr Endpoint geantwortet hat.

Jeder Endpoint erhält sein eigenes Signing Secret (whsec_…), das in der Zeile mit einer Kopierenschaltfläche angezeigt wird. Sie können bis zu 5 Endpoints pro Konto haben.

Ereignisse

Ereignis	Wann	data
campaign.completed	Die letzte E-Mail einer Kampagne wurde verarbeitet.	campaignId, name, status: "completed", sentCount, campaignSize
campaign.paused · campaign.resumed · campaign.stopped	Sie haben eine Kampagne unterbrochen, fortgesetzt oder gestoppt.	campaignId, name, status (paused / active / stopped), sentCount
email.opened	Ein Empfänger hat eine E-Mail geöffnet, nur das erste Mal pro Kampagne.	campaignId, recipient, at
email.clicked	Ein Empfänger hat auf einen verfolgten Link geklickt, bei jedem Klick.	campaignId, recipient, at, url
email.replied	Eine Antwort wurde in einem gesendeten Thread erkannt.	campaignId, recipient, at
email.bounced	Ein Abprall wurde erkannt.	campaignId, recipient, at
recipient.unsubscribed	Ein Empfänger hat den Abmeldelink verwendet, nur das erste Mal pro Kampagne.	campaignId, recipient, at, method

Öffnungen und Klicks benötigen Tracking für die Kampagne. Antworten und Abpraller kommen vom Reply-Scan, der jeder gesendeten Kampagne folgt.

Zustellung

Mail Merge sendet einen POST pro Ereignis pro abonniertem Endpoint mit einem JSON-Body:

{
  "id": "6f1c2d3e-…",
  "event": "email.opened",
  "createdAt": "2026-10-15T14:03:21.512Z",
  "data": { "campaignId": "…", "recipient": "ada@example.com", "at": "2026-10-15T14:03:21.498Z" }
}

und drei Header:

Header	Wert
X-MailMerge-Event	Der Ereignisname, gleich wie event im Body.
X-MailMerge-Delivery	Die Zustellungs-ID, gleich wie id. Verwenden Sie sie, um ein Duplikat zu ignorieren.
X-MailMerge-Signature	sha256= gefolgt vom Hex HMAC-SHA256 des Raw Body, mit dem Geheimnis des Endpoints verschlüsselt.

Antworten Sie mit einem beliebigen 2xx innerhalb von 5 Sekunden. Bei einem Netzwerkfehler oder einem 5xx versucht Mail Merge einmal nach 2 Sekunden erneut. Ein 4xx wird als Ihr Urteil genommen und nicht erneut versucht. Die gleiche Zustellungs-ID wird beim Wiederversuch gesendet. Nach 20 fehlgeschlagenen Zustellungen hintereinander wird der Endpoint deaktiviert und die Zeile zeigt dies an: Beheben Sie den Endpoint, löschen Sie ihn dann und fügen Sie ihn erneut hinzu. Jede erfolgreiche Zustellung setzt den Zähler zurück.

Ereignisse werden mindestens einmal und in keiner garantierten Reihenfolge zugestellt. Öffnungen kommen besonders in Schüben an (jeder Mail-Client, der das Tracking-Pixel rendert), daher machen Sie Ihren Handler idempotent auf X-MailMerge-Delivery oder auf (event, campaignId, recipient).

Die Signatur verifizieren

Verifizieren Sie immer, bevor Sie eine Payload vertrauen. Berechnen Sie das HMAC über den Raw Request Body (die exakten Bytes, vor jeglichem JSON-Parsing) und vergleichen Sie es in konstanter Zeit:

// Node.js (Express mit `express.raw({ type: "application/json" })`)
import { createHmac, timingSafeEqual } from "node:crypto"

export function verifyMailMergeSignature(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex")
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader ?? "")
  return a.length === b.length && timingSafeEqual(a, b)
}

app.post("/mailmerge", (req, res) => {
  if (!verifyMailMergeSignature(req.body, req.get("X-MailMerge-Signature"), process.env.MAILMERGE_WEBHOOK_SECRET)) {
    return res.status(401).end()
  }
  const payload = JSON.parse(req.body)
  // … handle payload.event / payload.data
  res.status(204).end()
})

# Python
import hashlib, hmac

def verify_mailmerge_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

Zapier, Make und n8n

Kein Code erforderlich: Erstellen Sie einen Catch Hook (Zapier Webhooks by Zapier), einen Custom webhook (Make) oder einen Webhook-Trigger-Node (n8n), fügen Sie die URL, die er Ihnen gibt, als Endpoint ein, aktivieren Sie die Ereignisse und klicken Sie auf Test senden, damit das Tool die Payload samplen kann. Die data-Felder werden zu den Variablen, die Sie im nächsten Schritt zuordnen (eine Zeile zu einem Sheet hinzufügen, einen CRM-Kontakt aktualisieren, zu Slack posten). Diese Tools verifizieren Signaturen nicht standardmäßig. Die URL, die sie Ihnen geben, ist nicht zu erraten, was der Schutz ist, auf den sie sich verlassen.

Nächste Schritte

• KI-Agenten (MCP), wenn ein Assistent Mail Merge für Sie statt eines Skripts steuern soll.
• Kampagnen, um zu verstehen, was die Status im Recipients-Endpoint bedeuten.
• Preise, um zu sehen, was der Professional-Plan beinhaltet.