Quickstart

Wenn Sie innerhalb von 2 Minuten keine deterministische Antwort erhalten können, kontaktieren Sie den Support.

1. API-Key erstellen

Registrieren Sie sich und generieren Sie einen API-Key im Dashboard.

export TRUNCUS_API_KEY=tr_live_...

Noch keinen API-Key? In 10 Sekunden erstellen →

2. Per curl senden

curl -X POST https://truncus.co/api/v1/emails/send   -H "Authorization: Bearer $TRUNCUS_API_KEY"   -H "Content-Type: application/json"   -d '{
    "to": "user@example.com",
    "from": "hello@ihredomain.de",
    "subject": "Testnachricht",
    "html": "<p>Hallo von Truncus.</p>"
  }'

3. SDK installieren

npm install @truncus/node

4. Erste E-Mail senden

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: 'hello@ihredomain.de',
  subject: 'Testnachricht',
  html: '<p>Hallo von Truncus.</p>'
})

console.log(response)

5. Response prüfen

Jeder Versand gibt einen terminalen Status zurück. Fehler enthalten einen maschinenlesbaren Grund.

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

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

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

Kein abgeleiteter Status. Keine impliziten Wiederholungen. Keine optimistischen Erfolgscodes.

6. Domain konfigurieren

Empfohlen für die Produktion. SPF-, DKIM- und DMARC-Einträge für Ihre Versanddomain hinzufügen.

Dashboard → Domains → Domain hinzufügen

Neue Domains beginnen bei 500 E-Mails/Tag und wärmen sich automatisch über 5 Tage auf. Fortschritt im Dashboard sichtbar.

7. Zustellungsstatus per Webhook verarbeiten

app.post('/truncus/webhook', (req, res) => {
  const event = req.body

  if (event.status === 'bounced') {
    // Datensatz aktualisieren — mailbox_full, no_mx_record, etc.
  }

  if (event.status === 'rejected') {
    // Unterdrückte Adresse — nicht erneut versuchen
  }

  res.status(200).send('ok')
})

Alle Zustellereignisse werden gespeichert und sind wiederholbar. Wenn Ihr Endpoint nicht erreichbar war, können Sie Ereignisse über das Dashboard oder die API wiederholen.

Rate Limits

Bei Überschreitung des Tier-Limits:

HTTP 429
{
  "error": "rate_limit_exceeded",
  "retry_after": 60
}

Warten Sie retry_after Sekunden und wiederholen Sie den Versuch. Keine stillen Fehler.

Produktions-Checkliste

Domain verifiziert (SPF, DKIM, DMARC)
Webhook-Endpoint erreichbar und gibt 200 zurück
Retry-Logik für 429-Responses implementiert
Monitoring auf bounced- und rejected-Status