Support: support@tinplate.dev · Zero-Retention Edge Security Support Trust Center DPA GitHub Issues
Email & Domain Tier 3 All-Access

RFC 8058 One-Click Unsubscribe & Consent Token API — Stateless HMAC Tokens

Issue and verify stateless HMAC unsubscribe tokens and RFC 8058 List-Unsubscribe headers. Issue and verify stateless, tamper-proof HMAC-SHA256 unsubscribe tokens and RFC 8058 List-Unsubscribe headers without a token database.

Additional endpoints in this module: POST /v1/consent-tokens/verify

Interactive Sandbox · No API Key Required 200 OK · Ready
POST /v1/consent-tokens/issueinput
200 OK sample / live responsejson
{
  "ok": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkNUSyIsImtpZCI6InYxIn0.eyJzdWIiOiJ1c2VyXzg4MjEiLCJzY29wZSI6Im1hcmtldGluZ193ZWVrbHkiLCJwdXJwb3NlIjpudWxsLCJpYXQiOjE3OTQ2Nzc5NzcsImV4cCI6MTc5NzI2OTk3NywianRpIjoiZTdiZjdlZWUyM2YwNTE5ZjZmMTc5YzdmIn0.RtcMe0_1rKoCjq2g-CU-YO2c3hLtUniFFU2M6B7U8PM",
    "kid": "v1",
    "issued_at": "2026-11-14T17:39:37.000Z",
    "expires_at": "2026-12-14T17:39:37.000Z",
    "payload": {
      "sub": "user_8821",
      "scope": "marketing_weekly",
      "purpose": null,
      "iat": 1794677977,
      "exp": 1797269977,
      "jti": "e7bf7eee23f0519f6f179c7f"
    },
    "rfc8058_headers": null
  },
  "meta": {
    "request_id": "req_ct_01",
    "ms": 1
  }
}
OpenAPI 3.0.3 Get All-Access Key ($29/mo) No signup. No payload storage.
Quickstart Code Examples
curl -X POST "https://api.tinplate.dev/v1/consent-tokens/issue" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TINPLATE_KEY" \
  -d '{"subject":"user_8821","scope":"marketing_weekly","secret":"unsubscribe-hmac-secret-key-2026","ttl_seconds":2592000,"unsubscribe_base_url":"https://example.com/unsub"}'
import { TinplateClient } from "@tinplate/sdk";

const tinplate = new TinplateClient({
  apiKey: process.env.TINPLATE_API_KEY!,
});

const { data, meta } = await tinplate.call("/v1/consent-tokens/issue", {
  "subject": "user_8821",
  "scope": "marketing_weekly",
  "secret": "unsubscribe-hmac-secret-key-2026",
  "ttl_seconds": 2592000,
  "unsubscribe_base_url": "https://example.com/unsub"
});
console.log(`[${meta.ms} ms]`, data);
import requests

response = requests.post(
    "https://api.tinplate.dev/v1/consent-tokens/issue",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_TINPLATE_KEY",
    },
    json={
  "subject": "user_8821",
  "scope": "marketing_weekly",
  "secret": "unsubscribe-hmac-secret-key-2026",
  "ttl_seconds": 2592000,
  "unsubscribe_base_url": "https://example.com/unsub"
}
)
print(response.json())
const response = await fetch("https://api.tinplate.dev/v1/consent-tokens/issue", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_TINPLATE_KEY",
  },
  body: JSON.stringify({
  "subject": "user_8821",
  "scope": "marketing_weekly",
  "secret": "unsubscribe-hmac-secret-key-2026",
  "ttl_seconds": 2592000,
  "unsubscribe_base_url": "https://example.com/unsub"
}),
});
const result = await response.json();
console.log(result);
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tinplate_consent_tokens",
    "arguments": {
      "subject": "user_8821",
      "scope": "marketing_weekly",
      "secret": "unsubscribe-hmac-secret-key-2026",
      "ttl_seconds": 2592000,
      "unsubscribe_base_url": "https://example.com/unsub"
    }
  }
}
OpenAPI 3.0.3 Schema Contract

Request Parameters & Response Schema Reference

Request Body Parameters (POST /v1/consent-tokens/issue)

ParameterType & ConstraintsDescription
subject required string
minLen: 1, maxLen: 256
Opaque subscriber or user identifier (avoid raw email if not needed).
scope required string
minLen: 1, maxLen: 128
Consent or unsubscribe scope.
purpose optional string
minLen: 1, maxLen: 128
Field 'purpose'
ttl_seconds optional integer
min: 60, max: 31536000
Token lifetime in seconds (default 30 days).
kid optional string
minLen: 1, maxLen: 64
Key identifier for key rotation.
secret optional string
minLen: 16, maxLen: 512
Tenant HMAC-SHA256 signing secret (min 16 chars; or omit from body and pass via X-Tinplate-Signing-Secret header, never logged or stored).
unsubscribe_base_url optional string
maxLen: 512
Optional HTTPS URL to generate RFC 8058 List-Unsubscribe headers.

Response data Object Fields (200 OK)

FieldTypeDescription
token string Field 'token'
kid string Field 'kid'
issued_at string Field 'issued_at'
expires_at string Field 'expires_at'
payload object Field 'payload'
rfc8058_headers object | null Field 'rfc8058_headers'

What Stateless Consent & One-Click Unsubscribe Tokens API Detects & Validates

  • Signs compact URL-safe tokens binding user ID, mailing list/channel, and expiration timestamp
  • Generates ready-to-send RFC 8058 List-Unsubscribe and List-Unsubscribe-Post email headers required by Gmail & Yahoo
  • Verifies token integrity and expiration in constant time via WebCrypto HMAC-SHA256
Honest Engineering Boundaries

Known Limitations & Test Verification

Release: v1.0.39 · Verified: 16 November 2026 · Portfolio Median: 0.318 ms in-Worker V8 compute (add 15–65 ms HTTPS RTT) · See Full Portfolio Benchmarks →

  • Stateless tokens remain valid until exp unless rotated or checked against a revocation list in your application.
  • Tested v1.0.4 (14 November 2026).

Direct All-Access & Marketplace Plans

Direct Polar All-Access Keys unlock all 42 APIs (49 endpoints), /v1/pipeline, and /mcp on api.tinplate.dev: Pro ($29/mo · 120 req/min · 100k/mo · 128 KB) or Team ($79/mo · 300 req/min · 500k/mo · 256 KB).

PlanMonthly PriceIncluded RequestsRate LimitMax PayloadBest For
BASIC$0.00 / mo500 / month10 req / min64 KBEvaluation & CI smoke tests
PRO$9.99 / mo15,000 / month60 req / min128 KBSolo devs & production apps
ULTRA$29.99 / mo100,000 / month300 req / min256 KBGrowing SaaS & multi-agent pipelines
MEGA$79.99 / mo500,000 / month1,000 req / min256 KBHigh-volume enterprise workloads

Frequently Asked Questions

Why do I need RFC 8058 List-Unsubscribe headers?

Gmail and Yahoo mandate RFC 8058 one-click unsubscribe headers on all marketing and bulk emails.

Do I need a database to store issued unsubscribe tokens?

No. The token is self-contained and cryptographically signed with your HMAC secret.

How do I verify a token when a user clicks unsubscribe?

Send the token and your secret to POST /v1/consent-tokens/verify to recover the verified subject and channel.

Zero Payload Logging

Data Handling, Privacy & Proxy Disclosure

Signing secrets and subject identifiers are never logged or stored.

Worker Zero-Logging Guarantee: Cloudflare Workers Observability and invocation logging are disabled (observability.enabled = false, head_sampling_rate = 0, invocation_logs = false). Requests via RapidAPI or Zyla traverse marketplace proxies; use a Direct Bearer Key for zero-intermediary routing.

Related Tinplate APIs

POST /v1/email-dns Live

Email DNS Deliverability Auditor API

Audit MX, SPF 10-lookup limits, DMARC, DKIM, BIMI, and MTA-STS with a 0–100 score.

POST /v1/email-dns-generator Email & Domain

SPF, DKIM & DMARC Record Linter & Generator API

Lint existing SPF/DMARC strings and generate clean, RFC-compliant DNS TXT records.

POST /v1/agent-action-receipts/issue AI Safety & Agents

Agent Action Receipts API

Issue and verify tamper-evident HMAC-signed receipts for autonomous AI agent actions.