Dokumentation für Entwickler

Erste Schritte

1. Legen Sie ein Konto und eine Marke an und verifizieren Sie die Domain, von der Sie senden möchten.
2. Erstellen Sie in der Konsole einen API-Schlüssel für diese Marke und wählen Sie die Berechtigungen, die er braucht. Berechtigungen lassen sich nachträglich nicht ändern: Dafür erstellen Sie einen neuen Schlüssel.
3. Rufe die API auf, mit dem Schlüssel im Header Authorization.

Basis-URL

https://api.mailronix.com

Authentifizierung

Authorization: Bearer mrx_live_…

Der erste Versand

Der Absender muss auf der verifizierten Domain der Marke liegen, an die der Schlüssel gebunden ist. Die Antwort 202 bedeutet, dass die Nachricht in der Warteschlange ist, nicht dass sie zugestellt wurde.

curl -X POST https://api.mailronix.com/email/send \
  -H "Authorization: Bearer mrx_live_<la-tua-chiave>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ordine-4821" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Conferma ordine #4821",
    "html_body": "<p>Il tuo ordine #4821 è confermato.</p>"
  }'

Derselbe Versand in Node.js, ohne Abhängigkeiten:

const risposta = await fetch('https://api.mailronix.com/email/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MAILRONIX_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'ordine-4821',
  },
  body: JSON.stringify({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Conferma ordine #4821',
    html_body: '<p>Il tuo ordine #4821 è confermato.</p>',
  }),
})

if (!risposta.ok) {
  const { error } = await risposta.json()
  throw new Error(`${error.code}: ${error.message}`)
}
console.log(await risposta.json()) // { status: 'queued', email_log_id: '…' }

Antwort

202 Accepted
{ "status": "queued", "email_log_id": "9c4e2f1a-7d3b-4a5e-8f6c-1b2a3d4e5f6a" }

Um ohne Duplikatrisiko zu wiederholen, sende den Header Idempotency-Key: Eine erneute Anfrage mit demselben Schlüssel und demselben Inhalt innerhalb von 24 Stunden liefert die Antwort des ersten Aufrufs.

Absendername, Antworten und Anhänge

Drei optionale Felder von POST /email/send. Wer sie nicht sendet, erhält dasselbe Verhalten wie bisher.

Beispiel mit den drei Feldern

{
  "from": "[email protected]",
  "from_name": "Acme Assistenza",
  "reply_to": "[email protected]",
  "to": "[email protected]",
  "subject": "La tua fattura",
  "html_body": "<p>In allegato la fattura.</p>",
  "attachments": [
    {
      "filename": "fattura-2026-0412.pdf",
      "content_type": "application/pdf",
      "content": "JVBERi0xLjcK…"
    }
  ]
}

• from_name: der Name, den der Empfänger statt der Adresse sieht, 1 bis 78 Zeichen (Akzente sind erlaubt; kein @, < >, keine Anführungszeichen, Zeilenumbrüche oder Webadressen). Fehlt er, wird der an der Marke hinterlegte Name verwendet.
• reply_to: die Adresse, an die Antworten gehen, auf beliebiger Domain außer der von Mailronix. Muss in der Konsole in den Markeneinstellungen mit „reply_to in der Anfrage erlauben“ aktiviert werden: standardmäßig aus und nicht per API-Schlüssel aktivierbar, weil ein gestohlener Schlüssel Antworten nicht umleiten können darf (ohne Zustimmung lautet die Antwort 403 reply_to_not_allowed).
• attachments: bis zu 5 Anhänge pro Nachricht, insgesamt 7 MB Dateien und die vollständige E-Mail unter 10 MB (in der E-Mail sind Anhänge etwa ein Drittel größer). Erlaubte Typen: PDF, PNG, JPEG, GIF, Text, CSV und Kalender. Nur bei transaktionalen Nachrichten, in allen Tarifen: mit "marketing": true lautet die Antwort 400 attachments_not_allowed_for_marketing.
• Anhänge bleiben nur für die Dauer des Versands bei uns, höchstens 24 Stunden; das Nachrichtenprotokoll behält Name, Typ, Größe und Prüfsumme, nie den Inhalt. Es gibt keinen Virenscan: Der Inhalt liegt in Ihrer Verantwortung. Für einen erneuten Versuch mit demselben Idempotency-Key senden Sie dieselben Bytes noch einmal.

Was ein Schlüssel kann

Jeder Schlüssel trägt nur die bei der Erstellung gewählten Berechtigungen. Ohne die passende Berechtigung antwortet die API mit 403 capability_not_granted.

POST /email/send

Eine transaktionale E-Mail senden, mit direktem Inhalt oder aus einer Vorlage mit Variablen.

Berechtigung: email:send

GET /email/{id}

Den Status eines Versands lesen.

Berechtigung: email:read

POST /contacts

Einen Kontakt anlegen. Er entsteht unbestätigt: Die Bestätigungsanfrage sendet Mailronix.

Berechtigung: contacts:write

POST /contacts/revoke

Die Abmeldung einer Adresse erfassen.

Berechtigung: contacts:unsubscribe

POST /contacts/delete

Einen Kontakt löschen. Erfordert zusätzlich die Berechtigung zur Abmeldung.

Berechtigung: contacts:delete

GET /contacts/revocations

Die Widerrufe der Marke des Schlüssels auflisten, per Cursor.

Berechtigung: revocations:read

Regeln, die Sie kennen sollten

• Ein Schlüssel schreibt immer nur unter der Marke, an die er bei der Erstellung gebunden wurde. Bei mehreren Marken erstelle einen Schlüssel pro Marke.
• Eine Nachricht ist standardmäßig transaktional. Mit "marketing": true geht sie nur an Kontakte, die ihre Anmeldung bestätigt haben, und enthält den Abmeldelink.
• Sie können keine anderswo eingeholte Einwilligung angeben: Eine Einwilligung gilt nur, wenn der Empfänger sie mit seinem eigenen Klick bestätigt.
• language (optional, bei POST /email/send und POST /contacts): it, en, es, de oder fr. Es wählt die Sprache der Service-Texte und verlinkten Seiten; HTML und Vorlagen werden nicht übersetzt. Ohne das Feld gilt die Sprache der Marke; jeder andere Wert ergibt 400 invalid_language.
• Fehler haben immer dieselbe Form, mit einem stabilen Code für Programme und einer Meldung für Menschen.
• Das Anfragelimit gilt pro Schlüssel (429 rate_limited). Ist das Monatskontingent des Tarifs aufgebraucht, werden Sendungen abgelehnt (403 plan_limit_exceeded), bis der nächste UTC-Kalendermonat beginnt; der Free-Tarif hat zusätzlich ein Limit von 500 einzelnen Empfängern pro Tag.

{ "error": { "code": "rate_limited", "message": "…" } }

Was nicht über die API geht

Kampagnen, das Erstellen und Widerrufen von API-Schlüsseln, Vorlagen, die Webhook-Konfiguration und die Abrechnung verwalten Sie nur in der Konsole, mit einer Sitzung. Das ist eine Sicherheitsentscheidung: Ein gestohlener Schlüssel soll weder Zugangsdaten erzeugen noch die Daten Ihrer Sendungen umleiten können.

API-Referenz

Jeder Endpunkt, jedes Feld und jede Antwort, erzeugt aus der Spezifikation und lesbar, ohne sie herunterzuladen.

OpenAPI-Spezifikation

Die OpenAPI-3.1-Spezifikation beschreibt jeden Endpunkt, jedes Feld und jeden Fehler: Importieren Sie sie in Ihren Client oder Ihr Testwerkzeug. Sie ist auf Italienisch verfasst.

Ausgehende Webhooks

Um kein Polling zu betreiben, können Sie in der Konsole HTTPS-Adressen eintragen, an die Mailronix die Ereignisse Ihres Kontos sendet, mit HMAC-Signatur und automatischen Wiederholungen.