Build on NVM

Seal your email’s links with a signing key, let NVM answer every click, and read who was a person from the API. Or send NVM the opens and clicks you track yourself and get a verdict for each.

Quickstart

1. Make two keys in the admin. An API key, nvm_live_…, reads verdicts and judges activity. A signing key, nvm_sk_…, seals your links. Keep both on your servers.
2. Seal every link of each email with the SDK, or implement the token format in your own language. Sealing happens on your servers, with no request to NVM per link.
3. Send as usual. Turn off your email platform’s own click tracking, so a reader passes one redirect, not two.
4. Read the verdicts by campaign, by click or by reader.

// The SDK, one file with no dependencies:
// https://nvm-6amcity.vercel.app/sdk/nvm.ts
import { Nvm } from './nvm';

const nvm = new Nvm({
  // nvm_sk_<id>_<secret>, from the admin.
  secret: process.env.NVM_SIGNING_SECRET,
  // NVM's address, or your own link domain.
  origin: 'https://nvm-6amcity.vercel.app',
});

const html = nvm.wrap(issueHtml, {
  // Your id for the issue, up to 64 bytes.
  campaign: 'greenville-2026-10-14',
  // Your id for the reader, never the address.
  recipient: subscriber.id,
  // Only its domain is used: who hosts the mailbox.
  email: subscriber.email,
  // When you hand this email to your platform.
  sentAt: new Date(),
});

curl https://nvm-6amcity.vercel.app/v1/campaigns/greenville-2026-10-14 \
  -H "Authorization: Bearer $NVM_API_KEY"

# Every click NVM settled since your last sync, oldest first:
curl "https://nvm-6amcity.vercel.app/v1/clicks?sort=updated&updated_since=2026-10-14T10:00:00Z&limit=1000" \
  -H "Authorization: Bearer $NVM_API_KEY"

Keys

Send the API key on every request to https://nvm-6amcity.vercel.app/v1 as Authorization: Bearer nvm_live_… or as X-API-Key. Each key has a limit of requests a minute, set in the admin, and answers 429 with Retry-After beyond it. A revoked key stops working within two minutes.

A signing key seals links; NVM keeps no copy of its secret and shows it once. Revoke it in the admin and its links answer 410 Gone within a minute. To change keys without breaking links in readers’ inboxes, make a new key, seal new sends with it, and revoke the old one when its emails no longer matter.

Links

A sealed link is https://nvm-6amcity.vercel.app/c/<token> and the open pixel https://nvm-6amcity.vercel.app/o/<token>.gif. NVM answers each click in the US region nearest the reader, from the request alone:

No sum of soft signs ever stops a click: only what no person’s browser sends does. Three policy flags, sealed into each link, change how strict NVM is: strict checks every click in the browser, for links sold by the click; anyCountry drops the weight on readers abroad; and early drops the weight on clicks soon after the send, for transactional email.

Your own link domain. Point a subdomain such as links.yournewsletter.com at NVM with a CNAME to cname.vercel-dns.com, DNS only, never through a proxy: NVM reads the reader’s own address, network and TLS handshake, which a proxy in front would replace with its own. Ask NVM’s team to add the domain.

Hidden trap link. With trap: true, wrap() adds a link no person sees, which catches scanners that fetch every link before delivery. It is off by default: Gmail’s sender guidelines say hidden content can send mail to spam, and NVM’s browser check stops those scanners anyway.

Verdicts

Every click settles into one verdict within a minute, or eleven minutes when its reader got the browser check:

released says whether the reader went on to the destination; basis lists the signs the verdict rests on. A campaign’s unique_humans per link counts each reader a person clicked for once: the payable click.

Opens come in classes. apple-privacy: Apple Mail loads every image, read or not. gmail-proxy and yahoo-proxy: the mail service fetches for a reader who opened the email. Then outlook, scanner, person and unknown. A reader’s engagement counts human clicks and opens only; machine clicks and opens never make a reader active.

Judge any open or click

Send NVM the opens and clicks your own pixel, redirect or email platform saw, one or up to 1,000 per request, and NVM answers for each in order, in about a millisecond: human, true or false; a verdict of human, machine or uncertain, a confidence, and the signs. Give what you have. An IP address and a User-Agent are enough; request headers, your edge’s network and TLS readings, and the delivery time make the answer surer. A missing header weighs nothing either way.

// An SES open or click event, as SES publishes it, judged by NVM:
const verdicts = await fetch('https://nvm-6amcity.vercel.app/v1/classify', {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.NVM_API_KEY}`, 'content-type': 'application/json' },
  body: JSON.stringify({ events: sesEvents.map(e => ({
    id: e.mail.messageId,
    type: e.eventType === 'Open' ? 'open' : 'click',
    at: (e.open ?? e.click).timestamp,
    ip: (e.open ?? e.click).ipAddress,
    user_agent: (e.open ?? e.click).userAgent,
    url: e.click?.link,
    sent_at: e.mail.timestamp,
    campaign: e.mail.tags?.campaign?.[0],
    recipient: e.mail.tags?.recipient?.[0],
  })) }),
}).then(r => r.json());

Events of one email in one request are judged together: four links of one email opened from one network within three seconds are a scanner. NVM keeps each event for its own learning; the address is kept 30 days, then only its network block.

Send events in batches as they arrive, not one request each. In NVM’s tests a batch of 1,000 was answered in about 0.2 seconds, and an address that sent thousands of requests within seconds was turned away by Vercel’s protection before NVM saw them.

Conventions

• JSON in and out; times are ISO 8601 in UTC; every object names its type in object.
• Lists return has_more and next_cursor; pass the cursor back for the next page.
• Incremental sync: sort=updated with updated_since returns every row NVM wrote since, oldest first, at least 30 seconds behind, so no row is skipped.
• Errors are { "error": { "type", "code", "message", "param" } } with 400, 401, 404, 409, 429, 500 or 503.
• A 429 or a 503 carries Retry-After: send the same request again after that many seconds. A 503 means NVM could not reach its data for a moment.
• The OpenAPI document is at /v1/openapi.json.

Reference

Token format

nvm_sk_<key id>_<secret>

encKey = HMAC-SHA256(secret, "nvm-link-enc-v1")
macKey = HMAC-SHA256(secret, "nvm-link-mac-v1")

header = [1, keyId >> 8, keyId & 0xff]                      3 bytes: version 1, the key id big-endian
siv    = HMAC-SHA256(macKey, header || plaintext)[0..16]     16 bytes
ctr    = siv with the top bit of byte 8 and of byte 12 cleared
body   = AES-256-CTR(encKey, initial counter block = ctr, plaintext)
token  = base64url(header || siv || body), without padding

signing secret   nvm_sk_7_AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE   (32 bytes of 0x01)
encKey           965896e1669a53c559e80794c844ab8134b07078c0a86a19be2566845a0b02b1
macKey           a14475917caec3e2ef8fa09b6954578618a7277b938e04b032e5a08913de2abd
claims           click, policy 0, mailbox gmail, sent at 1760000000, slot 3,
                 campaign "greenville-2026-10-14", recipient "sub_8d1f20",
                 url "https://example.com/story?a=1"
plaintext        101068e778000315677265656e76696c6c652d323032362d31302d31340a7375625f386431663230016578616d706c652e636f6d2f73746f72793f613d31
siv              a57939f2a6e6ca55299ce8d1a8219290
token            AQAHpXk58qbmylUpnOjRqCGSkBdI8J8P0OrdvA8Z5e87mO8DZyKQcN_QyzS6J03EzWvjuRwiPfek7Gs6eTL1hZmtv7ooMIo6r3TJX5-Pr-gN