Documentation

TrueMail Developer Docs

Everything you need to plug TrueMail into your signup flow, internal tools, or marketing automation. Explore the quick start below or jump into the SDKs.

Demo the API

1. Authenticate every request

Send a Bearer token generated in the dashboard. Rotate keys anytime without downtime. All endpoints require HTTPS.

curl https://api.truemails.net/v1/verify \
  -H "Authorization: Bearer sk_live_123" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","ip":"203.0.113.10"}'

2. Interpret the response

Each response includes a trust score (0–100), verdict, and the signals that triggered it. Use these to auto-block or add friction.

{
  "verdict": "fail",
  "score": 18,
  "signals": ["disposable_domain", "role_inbox"],
  "meta": {
    "mx_valid": false,
    "domain_age_days": 0
  }
}

3. Stream events via webhook

Receive verification events in real time. Retries are signed and exponential backoff is handled automatically.

POST https://yourapp.com/webhooks/true-mail
Signature: t=1714140000,v1=1d1e5...

{
  "type": "email.checked",
  "data": {
    "email": "[email protected]",
    "score": 12,
    "verdict": "fail"
  }
}

SDKs & integrations

Install our official SDKs in your preferred language. Each SDK provides typed responses, automatic retries, and webhook verification.

Node.js

npm install @truemail/node

import { TrueMail } from '@truemail/node';

const client = new TrueMail('sk_live_123');

const result = await client.verify({
  email: '[email protected]',
  ip: '203.0.113.10'
});

console.log(result.verdict); // "pass" or "fail"

💡

All SDKs include built-in TypeScript definitions, error handling, and automatic token refresh. Check the full documentation for advanced configuration options.

🔌 Webhook verification

All SDKs include helpers to verify webhook signatures and parse payloads securely.

⚡ Automatic retries

Built-in exponential backoff with configurable retry limits for network resilience.