Vernal Developer Platform
Everything you need to integrate Vernal into your applications, set up custom domains with 2048-bit DKIM, and maintain perfect deliverability.
Table of Contents
Quickstart
Install the official Vernal Node.js / TypeScript SDK. The SDK has zero runtime dependencies and includes full TypeScript types for every payload and deliverability report.
1. Install Package
npm install @vernal-mail/sdk2. Dispatch Your First Payload
import { VernalClient } from "@vernal-mail/sdk";
const vernal = new VernalClient({
apiKey: process.env.VERNAL_API_KEY, // e.g. "sec_live_example_key"
// Default edge gateway
baseUrl: "https://vernalmail.dev"
});
// Dispatch transactional payload
const res = await vernal.send({
to: "developer@vernalmail.dev",
template: "otp",
templateData: {
code: "892019",
appName: "Bank of Vernal",
expiresInMinutes: 10
},
headers: {
"X-Vernal-Weight": "50lb",
"X-Parcel-Post": "1916"
}
});
console.log("Mailed:", res.messageId, "Deliverability Score:", res.lint?.score);Built-In Dynamic Templates
Instead of designing custom HTML from scratch or dealing with broken mobile rendering, Vernal provides pre-compiled, bulletproof responsive templates. Both HTML and plain-text parts are generated automatically.
One-time security passwords, 2FA verification codes, and expiration countdowns.
Itemized transaction receipts, bills of lading, and freight invoices.
System infrastructure notifications with severity badges (info, warning, critical).
Template Usage Examples
await vernal.send({
to: "developer@vernalmail.dev",
template: "otp",
templateData: {
code: "482019",
appName: "Bank of Vernal Vault",
expiresInMinutes: 5
},
headers: {
"X-Vernal-Weight": "50lb",
"X-Parcel-Post": "1916"
}
});Deliverability Linter & Rate Pacing
The Vernal linter runs before every email is queued or dispatched. If a message scores below 70 (Grade F), it is rejected to safeguard your domain reputation.
| Rule Code | Severity | Description |
|---|---|---|
| MISSING_TEXT_PART | error (-25) | Email has HTML body but lacks a plain-text fallback part. |
| BULK_UNSUBSCRIBE_MISSING | error (-20) | Marketing/bulk emails without RFC 8058 List-Unsubscribe header. |
| ALL_CAPS_SUBJECT | warning (-10) | Subject line contains excessive capitalization (>70%). |
| SPAM_TRIGGER_WORDS | warning (-15) | Subject or body contains aggressive spam keywords. |
| SUSPICIOUS_LINKS | warning (-10) | Links targeting raw IP addresses or known URL shorteners. |
In 1916, 80,000 bricks were shipped to build the Bank of Vernal in 50 lb packages, forcing the USPS to institute its first-ever daily rate limit (200 lbs per sender per day). Vernal honors this precedent with an in-memory priority queue (`SendQueue`) operating at a 1,500ms pacing interval (40 emails/min ceiling) to prevent upstream provider throttling and ensure monotonic dispatch order.
Custom Domains & Cryptographic DKIM
Vernal provides cryptographic isolation for every client domain. When you register a
domain in the console or via POST /v1/domains,
Vernal generates a dedicated 2048-bit RSA key pair.
Host: vernal._domainkey.vernalmail.dev
Value: v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BA...
Host: vernalmail.dev
Value: v=spf1 include:_spf.google.com ~all
Host: _dmarc.vernalmail.dev
Value: v=DMARC1; p=none; adkim=r; aspf=r; fo=1; pct=100
REST API Reference
All endpoints accept and return JSON. Authenticate by providing your tenant API key in the Authorization: Bearer <key> header. Custom headers like X-Vernal-Weight and X-Parcel-Post are preserved throughout the dispatch
pipeline.