Documentation & Reference

Vernal Developer Platform

Everything you need to integrate Vernal into your applications, set up custom domains with 2048-bit DKIM, and maintain perfect deliverability.

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/sdk

2. 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.

otp

One-time security passwords, 2FA verification codes, and expiration countdowns.

receipt

Itemized transaction receipts, bills of lading, and freight invoices.

alert

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 CodeSeverityDescription
MISSING_TEXT_PARTerror (-25)Email has HTML body but lacks a plain-text fallback part.
BULK_UNSUBSCRIBE_MISSINGerror (-20)Marketing/bulk emails without RFC 8058 List-Unsubscribe header.
ALL_CAPS_SUBJECTwarning (-10)Subject line contains excessive capitalization (>70%).
SPAM_TRIGGER_WORDSwarning (-15)Subject or body contains aggressive spam keywords.
SUSPICIOUS_LINKSwarning (-10)Links targeting raw IP addresses or known URL shorteners.
THE 200 LB RATE LIMIT Architectural Invariant

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.

1. TXT DKIM Record

Host: vernal._domainkey.vernalmail.dev
Value: v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BA...

2. TXT SPF Record

Host: vernalmail.dev
Value: v=spf1 include:_spf.google.com ~all

3. TXT DMARC Record

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.

GET /v1/health
Auth: None Checks edge gateway operational status, V8 isolate health, and runtime latency.
POST /v1/send
Auth: Bearer Key Validates preflight deliverability, renders templates, and enqueues/dispatches email.
POST /v1/batch
Auth: Bearer Key Enqueues up to 50 email dispatches in a single HTTP request.
GET /v1/domains
Auth: Bearer Key Lists registered custom sender domains with their DKIM, SPF, and DMARC status.
POST /v1/domains
Auth: Bearer Key Creates a custom domain and generates dedicated 2048-bit RSA DKIM key pairs.
POST /v1/domains/:id/verify
Auth: Bearer Key Performs live DNS-over-HTTPS queries to verify published DNS TXT DKIM records.
DELETE /v1/domains/:id
Auth: Bearer Key Deletes a registered custom domain and revokes its DKIM signing key.
GET /v1/messages
Auth: Bearer Key Lists recently sent dispatches, delivery statuses, attempt counts, and scores.
GET /v1/messages/:id
Auth: Bearer Key Fetches granular delivery audit trail and preflight findings for a specific message.