Quickstart

Als je niet binnen 2 minuten een deterministische response kunt ontvangen, neem contact op met support.

1. API key aanmaken

Registreer je en genereer een API key via het dashboard.

export TRUNCUS_API_KEY=tr_live_...

Nog geen API key? Maak er een aan in 10 seconden →

2. Versturen via curl

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": "hallo@jouwdomein.nl",
    "subject": "Testbericht",
    "html": "<p>Hallo van Truncus.</p>"
  }'

3. SDK installeren

npm install @truncus/node

4. Eerste e-mail versturen

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: 'hallo@jouwdomein.nl',
  subject: 'Testbericht',
  html: '<p>Hallo van Truncus.</p>'
})

console.log(response)

5. Response bekijken

Elke verzending geeft een terminale status terug. Fouten bevatten een machineleesbare reden.

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

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

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

Geen afgeleide status. Geen impliciete retries. Geen optimistische succescodes.

6. Domein configureren

Aanbevolen voor productie. Voeg SPF-, DKIM- en DMARC-records toe voor je verzenddomein.

Dashboard → Domeinen → Domein toevoegen

Nieuwe domeinen beginnen op 500 e-mails/dag en warmen automatisch op over 5 dagen. Voortgang zichtbaar in het dashboard.

7. Bezorgingsstatus verwerken via webhook

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

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

  if (event.status === 'rejected') {
    // onderdrukt adres — niet opnieuw proberen
  }

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

Alle bezorgevenementen worden opgeslagen en zijn herhaalbaar. Als je endpoint niet bereikbaar was, kunnen events opnieuw worden afgespeeld via het dashboard of de API.

Rate limits

Bij overschrijding van het tier-limiet:

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

Wacht retry_after seconden en probeer opnieuw. Geen stille fouten.

Productie-checklist

Domein geverifieerd (SPF, DKIM, DMARC)
Webhook-endpoint bereikbaar en geeft 200 terug
Retry-logica geïmplementeerd voor 429-responses
Monitoring op bounced- en rejected-status