Error handling

Error format

All errors return a JSON object with error, code, and optional hint fields.

{
  "error": "Domain example.com is not verified",
  "code": "DOMAIN_NOT_VERIFIED",
  "hint": "Add and verify example.com at /v1/domains before sending."
}

Error codes

Common error codes: • INVALID_API_KEY — Key is missing, invalid, or revoked • DOMAIN_NOT_VERIFIED — The from domain is not verified in your account • QUOTA_EXCEEDED — Monthly send limit reached (upgrade or buy credits) • VALIDATION_ERROR — Request body failed schema validation • TEMPLATE_NOT_FOUND — Referenced template ID does not exist • SUPPRESSED — One or more recipients are on the suppression list • IDEMPOTENCY_MISMATCH — Same idempotency key reused with different payload

Handling errors in Node.js

import MailSetu, { MailSetuError } from 'mailsetu'

const client = new MailSetu(process.env.MAILSETU_API_KEY!)

try {
  const email = await client.emails.send({ ... })
  console.log('Sent:', email.id)
} catch (err) {
  if (err instanceof MailSetuError) {
    console.error('Code:', err.code)    // 'DOMAIN_NOT_VERIFIED'
    console.error('Message:', err.message)
    console.error('Hint:', err.hint)    // optional
  }
}