POST /v1/send

Verstuurt een transactionele e-mail. Geeft een terminale bezorgingsstatus terug.

Request

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

Body

{
  "to": "user@example.com",
  "from": "hallo@jouwdomein.nl",
  "subject": "Factuur klaar",
  "html": "<p>Je factuur is bijgevoegd.</p>",
  "text": "Je factuur is bijgevoegd.",
  "reply_to": "support@jouwdomein.nl",
  "attachments": [
    {
      "filename": "factuur.pdf",
      "content": "base64-gecodeerde-inhoud"
    }
  ],
  "headers": {
    "X-Entity-Ref-ID": "jouw-interne-id"
  }
}

Velden

Veld	Type	Verplicht	Beschrijving
to	string | string[]	Ja	Ontvangeradres(sen)
from	string	Ja	Geverifieerd verzendadres
subject	string	Ja	Onderwerp
html	string	Één van html/text	HTML-inhoud
text	string	Één van html/text	Platte tekst-inhoud
reply_to	string	Nee	Antwoordadres
attachments	Attachment[]	Nee	Bestandsbijlagen
headers	object	Nee	Aangepaste e-mailheaders

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"
}

Foutresponses

Status	Code	Beschrijving
400	invalid_payload	Ontbrekende verplichte velden of ongeldige JSON
400	invalid_address	Ongeldig e-mailadres
401	invalid_api_key	Ontbrekende of ongeldige Authorization-header
403	domain_not_verified	Verzenddomein niet geverifieerd
429	rate_limit_exceeded	Tier-limiet bereikt. Bevat retry_after
500	transient_failure	Tijdelijke infrastructuurfout. Veilig opnieuw proberen.

SDK-voorbeeld

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: 'facturatie@jouwdomein.nl',
  subject: 'Factuur klaar',
  html: '<p>Je factuur is klaar.</p>'
})

if (response.status === 'delivered') {
  // bezorging vastleggen
} else if (response.status === 'bounced') {
  // contactrecord bijwerken — response.reason bevat details
} else if (response.status === 'rejected') {
  // niet opnieuw proberen — onderdrukt of ongeldig adres
}