Quickstart

If you can't send and receive a deterministic response in under 2 minutes, contact support.

1. Create an API key

export TRUNCUS_API_KEY=tr_live_...

Don't have an API key yet? Create one in 10 seconds →

2. Send 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": "hello@yourdomain.com",
    "subject": "Test message",
    "html": "<p>Hello from Truncus.</p>"
  }'

3. Install the SDK

npm install @truncus/node

4. Send your first email

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@yourdomain.com',
  subject: 'Test message',
  html: '<p>Hello from Truncus.</p>'
})

console.log(response)

5. Inspect the response

Every send returns a terminal state. Failures include a machine-readable reason.

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

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

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

No inferred status. No implicit retries. No optimistic success codes.

6. Configure your domain

Recommended for production. Add SPF, DKIM, and DMARC records for your sending domain.

Dashboard → Domains → Add domain

New domains start at 500 emails/day and warm up automatically over 5 days. Progress is visible in the dashboard.

7. Handle delivery state via webhook

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

  if (event.status === 'bounced') {
    // update your records — mailbox_full, no_mx_record, etc.
  }

  if (event.status === 'rejected') {
    // suppressed address — do not retry
  }

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

All delivery events are stored and replayable. If your endpoint is down, replay events from the dashboard or via the API.

Rate limits

If you exceed your tier limit:

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

Back off for retry_after seconds and retry. No silent failures.

Production checklist

Domain verified (SPF, DKIM, DMARC)
Webhook endpoint reachable and returning 200
Retry logic on 429 responses
Monitoring on bounced and rejected states