POST /v1/send

Sendet eine transaktionale E-Mail. Gibt einen terminalen Zustellungsstatus zurück.

Request

POST https://truncus.co/api/v1/emails/send
Authorization: Bearer tr_live_...
Content-Type: application/json
Idempotency-Key: ihr-idempotency-key  (optional)

Body

{
  "to": "user@example.com",
  "from": "hallo@ihredomain.de",
  "subject": "Rechnung bereit",
  "html": "<p>Ihre Rechnung ist angehängt.</p>",
  "text": "Ihre Rechnung ist angehängt.",
  "reply_to": "support@ihredomain.de",
  "attachments": [
    {
      "filename": "rechnung.pdf",
      "content": "base64-enkodierter-inhalt"
    }
  ],
  "headers": {
    "X-Entity-Ref-ID": "ihre-interne-id"
  }
}

Felder

Feld	Typ	Pflicht	Beschreibung
to	string | string[]	Ja	Empfängeradresse(n)
from	string	Ja	Verifizierte Absenderadresse
subject	string	Ja	Betreff
html	string	Eines von html/text	HTML-Inhalt
text	string	Eines von html/text	Nur-Text-Inhalt
reply_to	string	Nein	Antwortadresse
attachments	Attachment[]	Nein	Dateianhänge
headers	object	Nein	Benutzerdefinierte E-Mail-Header

Response

200 — delivered

{
  "status": "delivered",
  "message_id": "msg_8f21a3b4"
}

200 — bounced

{
  "status": "bounced",
  "message_id": "msg_9b44c1e2",
  "reason": "mailbox_full"
}

200 — rejected

{
  "status": "rejected",
  "message_id": "msg_a2f7e8d1",
  "reason": "suppression_list"
}

Fehler-Responses

Status	Code	Beschreibung
400	invalid_payload	Fehlende Pflichtfelder oder ungültiges JSON
400	invalid_address	Ungültige E-Mail-Adresse
401	invalid_api_key	Fehlender oder ungültiger Authorization-Header
403	domain_not_verified	Absender-Domain nicht verifiziert
429	rate_limit_exceeded	Tier-Limit erreicht. Enthält retry_after
500	transient_failure	Transienter Infrastrukturfehler. Sicher wiederholbar.

SDK-Beispiel

import { Truncus } from '@truncus/node'

const truncus = new Truncus({ apiKey: process.env.TRUNCUS_API_KEY })

const response = await truncus.emails.send({
  to: 'user@example.com',
  from: 'abrechnung@ihredomain.de',
  subject: 'Rechnung bereit',
  html: '<p>Ihre Rechnung ist bereit.</p>'
})

if (response.status === 'delivered') {
  // Zustellung protokollieren
} else if (response.status === 'bounced') {
  // Kontaktdatensatz aktualisieren — response.reason enthält Details
} else if (response.status === 'rejected') {
  // Nicht erneut versuchen — unterdrückte oder ungültige Adresse
}