# Fromenance docs: full text

Source: https://docs.fromenance.com. Generated from the built pages at build time, in sidebar order. The integration guide is https://docs.fromenance.com/getting-started/integration-guide.


---

Page: Integration guide, end to end
URL: https://docs.fromenance.com/getting-started/integration-guide

# Integration guide, end to end

Fromenance is a communication provenance platform: an institution registers each outbound communication at send time, and a customer who forwards a suspicious message to verify@ on the institution’s domain or pastes it on a verify page gets Verified, Not verified, or Known fraud in seconds. This guide is the whole integration as a checklist, written so that a person or an AI agent can execute it top to bottom from this page alone.

There is nothing to install. Fromenance is a REST API: one HTTPS call at send time, one TXT record, one redirect rule. Base URL https://api.fromenance.com , JSON in and out, Authorization: Bearer <api key> , errors as RFC 9457 problem documents (see Errors ). The example institution throughout is JT Merlin Bank, domain jtmerlin.example , tenant slug jtmerlin ; substitute your own.

By the end you will have completed steps 1 to 6 (required), decided on 7 to 9 (optional), and confirmed the whole path with step 10.

Collect these values first; every step below refers to them by name.

| Name
| What it is
| Where it comes from
|

| FROMENANCE_API_KEY
| fr_test_... or fr_live_...
| step 1, shown once
|

| FROMENANCE_TENANT_SECRET
| the recipient hashing secret
| step 1, Settings
|

| DOMAIN
| the institution’s sending domain, for example jtmerlin.example
| you
|

| SLUG
| the tenant slug, for example jtmerlin
| GET /v1/tenant
|

| DNS access
| a way to add one TXT record on DOMAIN (dashboard or API credential)
| you
|

| Mail platform admin
| to create verify@DOMAIN and one redirect rule
| you
|

Order matters only where stated: step 2 (TXT) must be verified before step 4 (forwarding test), and step 6 works as soon as step 1 is done. A plain text copy of this whole guide is served at /integration-guide.md for tools that prefer Markdown.

## Step 1: get a login and create an API key

Do. Sign in to app.fromenance.com with an owner or admin account (email magic link or passkey). Open Settings, API keys, Mint key . Name it, choose the mode, choose the scopes register and read .

- fr_test_ keys are for the sandbox: registrations and submissions are marked sandbox: true , replies go to the tenant’s fraud contact address instead of a customer. Use one for the whole of this guide first.

- fr_live_ keys are for production. Repeat step 6 with a live key when you go live.

- The secret is shown once. Store it as FROMENANCE_API_KEY .

- Also copy the recipient hashing secret from Settings and store it as FROMENANCE_TENANT_SECRET . It is a separate value from the API key and never travels to the API.

Request (alternative, with an existing admin key).

```http
POST https://api.fromenance.com/v1/api-keys
Authorization: Bearer fr_live_...
Content-Type: application/json

{ "name": "integration", "mode": "test", "scopes": ["register", "read"] }
```

Read. 201 with id (key_... ), prefix (the first 12 characters, the only part stored), mode , scopes , and secret (the full key, this response only).

Confirm.

```http
GET https://api.fromenance.com/v1/tenant
Authorization: Bearer fr_test_...
```

200 with slug (for example jtmerlin ), verify_address (jtmerlin@verify.fromenance.com ), journal_address , minimal_reply_address , retention_days , match_threshold , sandbox . Keep slug and verify_address ; steps 2 and 3 use them.

## Step 2: add the domain and publish the TXT record

Do. Register the domain that will host verify@ and that your outbound mail is signed with.

Request.

```http
POST https://api.fromenance.com/v1/domains
Authorization: Bearer fr_test_...
Content-Type: application/json

{ "domain": "jtmerlin.example" }
```

Read. 201 with id (dom_... ), status (pending ), roles (["trust", "sender"] ), and txt_record :

```json
{ "name": "_fromenance.jtmerlin.example", "type": "TXT", "value": "v=fromenance1; t=jtmerlin; k=0123456789abcdef0123456789abcdef" }
```

Publish exactly that record at your DNS provider: name _fromenance.<domain> , type TXT, value v=fromenance1; t=<slug>; k=<key> as one quoted string, TTL 300. The key is not a secret; it binds the zone to your tenant. The record is the only DNS change Fromenance needs; it never touches MX, SPF, or DKIM.

If the zone is on Cloudflare, one API call publishes it (token with Zone DNS Edit on that zone):

```bash
curl -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records"   -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" -H "Content-Type: application/json"   -d '{"type":"TXT","name":"_fromenance.jtmerlin.example","content":"v=fromenance1; t=jtmerlin; k=0123456789abcdef0123456789abcdef","ttl":300}'
```

Route 53, Google Cloud DNS, Azure DNS, and registrar panels all take the same three values (name, TXT, value). Check propagation from the public resolvers before asking Fromenance to re-check:

```bash
curl -s -H "accept: application/dns-json" "https://cloudflare-dns.com/dns-query?name=_fromenance.jtmerlin.example&type=TXT"
# expect an Answer entry whose data is the quoted value above
```

Confirm. Fromenance polls every hour for 24 hours, then daily. Force a check and repeat until status is verified :

```http
POST https://api.fromenance.com/v1/domains/dom_.../check
Authorization: Bearer fr_test_...
```

200 with the domain; read status , verified_at , and last_check_result (for example found 1 TXT record(s), none matched while the old record is still cached). DNS propagation is the usual wait; a TTL of 300 on the record shortens it.

Other calls you may need: GET /v1/domains (list), PATCH /v1/domains/{id} with { "roles": ["trust", "sender", "reply"] } (roles), DELETE /v1/domains/{id} . Trust model and rejection reasons: Domains and mail .

## Step 3: create verify@ and the redirect rule

Do. On your mail platform, create the address verify@jtmerlin.example (a group, shared mailbox, or user) and a rule that redirects everything it receives to your tenant inbox, the verify_address from step 1: jtmerlin@verify.fromenance.com . Redirect, not forward: a redirect keeps the customer as the sender and the platform’s DKIM signature or ARC seal intact, so Fromenance can authenticate the hop and reply to the customer.

Click by click for each platform: Google Workspace (default routing rule, Change envelope recipient), Microsoft 365 (mail flow rule, Redirect the message to), Proofpoint , Mimecast , Cisco Secure Email .

Confirm. Step 4 is the confirmation.

## Step 4: run the forwarding test

Request.

```http
POST https://api.fromenance.com/v1/domains/dom_.../forwarding-test
Authorization: Bearer fr_test_...
```

Requires status: verified from step 2 (otherwise 409 ). Fromenance emails verify@jtmerlin.example with a token in the subject and an X-Fromenance-Forward-Test header.

Read. 200 with status (sent ), sent_at , to (verify@jtmerlin.example ).

Confirm. Poll every 5 to 10 seconds for up to two minutes:

```http
GET https://api.fromenance.com/v1/domains/dom_.../forwarding-test
Authorization: Bearer fr_test_...
```

Stop when status is working ; result reads working via dkim jtmerlin.example or working via arc jtmerlin.example . If status is failed , result reads failed: <reason> ; the reasons and fixes are on Domains and mail . Fix the rule and POST again.

## Step 5: compute the recipient hash and the content fingerprint

Two values are computed on your side for every message. Neither the address nor the body is ever sent.

### recipient_hash (required)

```text
recipient_hash = "hmac-sha256:" + lowercase_hex( HMAC-SHA256( key = FROMENANCE_TENANT_SECRET, message = canonical(address) ) )
canonical(address) = trim; if a display name is present keep only the part inside < >; lowercase; strip a leading "mailto:"
```

The API validates the shape ^hmac-sha256:[0-9a-f]{64}$ and rejects anything else.

- TypeScript (WebCrypto)
- Python (hmac)
- Shell (openssl)

```ts samples/recipient-hash.ts
/**
 * recipient_hash for Fromenance registrations. No dependencies; WebCrypto runs in Node 18+, Bun, Deno, and Workers.
 *
 *   recipient_hash = "hmac-sha256:" + hex( HMAC-SHA256( key = tenant HMAC secret, message = canonical(address) ) )
 *   canonical(address): trim, keep only the part inside <> when a display name is present, lowercase,
 *                       strip a leading "mailto:"
 *
 * "Jane Doe" <Jane@Bank.com > and jane@bank.com produce the same hash. The raw address never leaves your process.
 */

export function canonicalAddress(input: string): string {
  let s = input.trim();
  const angle = s.match(/<([^>]+)>/);
  if (angle?.[1]) s = angle[1];
  s = s.trim().toLowerCase();
  s = s.replace(/^mailto:/, "");
  return s;
}

export async function recipientHash(address: string, tenantSecret: string): Promise<string> {
  const key = await crypto.subtle.importKey(
    "raw",
    new TextEncoder().encode(tenantSecret),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"],
  );
  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(canonicalAddress(address)));
  let hex = "";
  for (const b of new Uint8Array(sig)) hex += b.toString(16).padStart(2, "0");
  return `hmac-sha256:${hex}`;
}
```

### content_fingerprint (optional, recommended)

What the API accepts, exactly: content_fingerprint is an object with two required fields, simhash matching ^0x[0-9a-fA-F]{1,16}$ and sha256 matching ^[0-9a-f]{64}$ . There is no field for the raw body and no way to send sha256 alone: send both, or omit the object. Without it a registration still verifies by code plus recipient; with it, a forward that lost its code (screenshot, heavy rewrapping) can still verify by recipient plus fingerprint, and a real footer pasted into a different message is caught as a replay.

Both hashes are computed over the same normalized text. The pipeline, which Fromenance also runs on the customer’s forward at verify time:

- HTML to text: drop comments, script , style , head , title , noscript , template , hidden preheaders (display:none , max-height:0 , font-size:0 ), and images (alt text kept); keep each link’s visible text followed by its http(s) href; block tags become newlines; decode entities.

- Unwrap gateway rewritten links: Proofpoint URL Defense v2 and v3, Microsoft Defender rewritten links, Google redirect, Mimecast; up to four layers.

- Strip forward chrome: forwarded message markers, From: /Sent: /To: /Subject: header blocks, “On … wrote:” lines, quote markers, external banners, device signatures, the Fromenance footer sentence and the Reference: line, any line containing a checksum valid verify code; cut at a -- signature line.

- Replace every URL with the registered domain of its host (co.uk style suffixes keep three labels).

- Lowercase; keep only letters, digits, and @ ; collapse whitespace.

- simhash : 64 bit SimHash over word 3-gram shingles (a text with fewer than 3 words is one shingle), each shingle hashed with FNV-1a 64 over its UTF-8 bytes; bit set when the count is positive. sha256 : SHA-256 hex of the normalized text. If the normalized text is empty, omit content_fingerprint .

The following file is the complete pipeline with no dependencies, and the docs test suite asserts it produces the same bits as the reference implementation on every build. Copy it as is.

```ts samples/fingerprint.ts
/**
 * Content fingerprint for Fromenance registrations. No dependencies; runs in Node 18+, Bun, Deno, and Workers.
 *
 * The API accepts `content_fingerprint: { simhash: "0x<16 hex>", sha256: "<64 hex>" }`. Both values are computed
 * over the same normalized text, and Fromenance runs this exact pipeline on the customer's forward at verify time,
 * so the bits must match. This file is a byte for byte port of the reference implementation:
 *
 *   1. HTML to text (scripts, styles, hidden preheaders, and images dropped; link hrefs kept as text)
 *   2. Unwrap gateway rewritten links (Proofpoint v2 and v3, Microsoft Defender, Google redirect, Mimecast)
 *   3. Strip forward chrome, header blocks, "wrote:" lines, device signatures, the Fromenance footer, and cut at "--"
 *   4. Replace every URL with the registered domain of its host
 *   5. Lowercase, keep letters, digits, and @, collapse whitespace
 *   6. SimHash: 64 bit, word 3-gram shingles hashed with FNV-1a 64; SHA-256 of the same text
 *
 * The fingerprint is optional. Without it a registration still verifies by code plus recipient.
 */

export interface ContentFingerprint {
  /** `0x` plus 16 lowercase hex characters, ready for the API. */
  simhash: string;
  /** 64 lowercase hex characters. */
  sha256: string;
  /** Number of normalized tokens. 0 means there was no usable text; omit content_fingerprint in that case. */
  tokens: number;
  /** The normalized text, for tests only. Never send or store it. */
  normalized: string;
}

export async function fingerprintContent(input: {
  html?: string | null;
  text?: string | null;
}): Promise<ContentFingerprint> {
  const normalized = normalizeContent(input);
  const simhash = simhash64(normalized);
  return {
    simhash: `0x${simhash.toString(16).padStart(16, "0")}`,
    sha256: await sha256Hex(normalized),
    tokens: normalized.length === 0 ? 0 : normalized.split(" ").length,
    normalized,
  };
}

/** Subject fingerprint: SHA-256 of the subject with Fwd/Re prefixes removed and collapsed. */
export async function fingerprintSubject(subject: string): Promise<string> {
  let s = subject.trim();
  for (let i = 0; i < 5; i++) s = s.replace(/^\s*(fwd?|fw|re|tr|wg|aw)\s*:\s*/i, "");
  return sha256Hex(collapse(s));
}

// ---- Normalization ------------------------------------------------------------------------------------------------

export function normalizeContent(input: { html?: string | null; text?: string | null }): string {
  const source = input.html && input.html.trim().length > 0 ? htmlToText(input.html) : (input.text ?? "");
  const unwrapped = source.replace(URL_RE, (m) => unwrapUrl(m));
  const stripped = stripForwardChrome(unwrapped);
  const domains = stripped.replace(URL_RE, (m) => {
    const host = hostOf(m);
    return host ? registeredDomain(host) : "";
  });
  return collapse(domains);
}

const NAMED_ENTITIES: Record<string, string> = {
  amp: "&",
  lt: "<",
  gt: ">",
  quot: '"',
  apos: "'",
  nbsp: " ",
  ensp: " ",
  emsp: " ",
  thinsp: " ",
  zwnj: "",
  zwj: "",
  ndash: "-",
  mdash: "-",
  lsquo: "'",
  rsquo: "'",
  ldquo: '"',
  rdquo: '"',
  hellip: "...",
  copy: "(c)",
  reg: "(r)",
  trade: "(tm)",
  bull: "*",
  middot: "*",
};

function safeFromCodePoint(cp: number): string {
  try {
    return String.fromCodePoint(cp);
  } catch {
    return "";
  }
}

export function decodeEntities(input: string): string {
  return input.replace(/&(#x[0-9a-fA-F]+|#[0-9]+|[a-zA-Z]+);/g, (whole, body: string) => {
    if (body.startsWith("#x") || body.startsWith("#X")) {
      const cp = Number.parseInt(body.slice(2), 16);
      return Number.isFinite(cp) ? safeFromCodePoint(cp) : whole;
    }
    if (body.startsWith("#")) {
      const cp = Number.parseInt(body.slice(1), 10);
      return Number.isFinite(cp) ? safeFromCodePoint(cp) : whole;
    }
    const named = NAMED_ENTITIES[body];
    return named === undefined ? whole : named;
  });
}

const BLOCK_TAGS =
  "p|div|br|tr|li|h1|h2|h3|h4|h5|h6|table|blockquote|section|article|header|footer|ul|ol|pre|hr|td|th";

export function htmlToText(html: string): string {
  let s = html;
  s = s.replace(/<!--[\s\S]*?-->/g, " ");
  s = s.replace(/<(script|style|head|title|noscript|template)[^>]*>[\s\S]*?<\/\1>/gi, " ");
  // Preheader and hidden blocks that clients never show.
  s = s.replace(
    /<[^>]+style=("|')[^"']*(display\s*:\s*none|max-height\s*:\s*0|font-size\s*:\s*0)[^"']*\1[^>]*>[\s\S]*?<\/(div|span|p|td)>/gi,
    " ",
  );
  // Tracking pixels and every other image: alt text is kept when it is a word, never the source.
  s = s.replace(/<img[^>]*alt=("|')([^"']*)\1[^>]*>/gi, (_m, _q, alt: string) => ` ${alt} `);
  s = s.replace(/<img[^>]*>/gi, " ");
  // Anchors: keep the href as text so link domains flow into the normalized body, then the visible text.
  s = s.replace(
    /<a[^>]*href=("|')([^"']*)\1[^>]*>([\s\S]*?)<\/a>/gi,
    (_m, _q, href: string, inner: string) => {
      const h = href.trim();
      const isHttp = /^https?:\/\//i.test(h);
      return ` ${inner} ${isHttp ? h : ""} `;
    },
  );
  s = s.replace(new RegExp(`<\\/?(${BLOCK_TAGS})\\b[^>]*>`, "gi"), "\n");
  s = s.replace(/<[^>]+>/g, " ");
  s = decodeEntities(s);
  s = s.replace(/\r\n?/g, "\n");
  return s;
}

const URL_RE = /\bhttps?:\/\/[^\s<>"'()[\]{}]+/gi;

function decodeProofpointV2(u: string): string {
  let out = "";
  for (let i = 0; i < u.length; i++) {
    const ch = u[i] as string;
    if (ch === "_") out += "/";
    else if (ch === "-" && /^[0-9A-Fa-f]{2}$/.test(u.slice(i + 1, i + 3))) {
      out += String.fromCharCode(Number.parseInt(u.slice(i + 1, i + 3), 16));
      i += 2;
    } else out += ch;
  }
  return out;
}

function safeDecode(v: string): string {
  try {
    return decodeURIComponent(v);
  } catch {
    return v;
  }
}

function queryParam(url: string, name: string): string | null {
  const q = url.indexOf("?");
  if (q < 0) return null;
  const params = url.slice(q + 1).split("&");
  for (const p of params) {
    const eq = p.indexOf("=");
    const k = eq < 0 ? p : p.slice(0, eq);
    if (k === name) return eq < 0 ? "" : p.slice(eq + 1);
  }
  return null;
}

/** Unwrap one URL that a security gateway or mail client rewrote, up to four layers deep. */
export function unwrapUrl(url: string): string {
  let current = url;
  for (let i = 0; i < 4; i++) {
    const next = unwrapOnce(current);
    if (next === current) break;
    current = next;
  }
  return current;
}

function unwrapOnce(url: string): string {
  const lower = url.toLowerCase();
  if (lower.includes("urldefense.proofpoint.com/v2/url")) {
    const u = queryParam(url, "u");
    if (u) return decodeProofpointV2(u);
  }
  if (lower.includes("urldefense.com/v3/__")) {
    const start = url.indexOf("__") + 2;
    const end = url.indexOf("__;", start);
    if (start > 1 && end > start) return url.slice(start, end).replace(/\*/g, "");
  }
  if (lower.includes("safelinks.protection.outlook.com")) {
    const u = queryParam(url, "url");
    if (u) return safeDecode(u);
  }
  if (/^https?:\/\/(www\.)?google\.[a-z.]+\/url\?/i.test(url)) {
    const q = queryParam(url, "q") ?? queryParam(url, "url");
    if (q) return safeDecode(q);
  }
  if (lower.includes("mimecastprotect.com/s/") || lower.includes("mimecast.com/s/")) {
    const d = queryParam(url, "domain");
    if (d) return `https://${safeDecode(d)}/`;
  }
  return url;
}

const MULTI_PART_TLDS = new Set([
  "co.uk",
  "org.uk",
  "ac.uk",
  "gov.uk",
  "com.au",
  "net.au",
  "org.au",
  "co.nz",
  "co.jp",
  "com.br",
  "com.mx",
  "co.in",
  "com.sg",
  "co.za",
  "com.ar",
  "com.tr",
]);

/** Registered domain: last two labels, or three when the suffix is a known multi part TLD. */
export function registeredDomain(host: string): string {
  const h = host.toLowerCase().replace(/\.$/, "");
  const labels = h.split(".").filter(Boolean);
  if (labels.length <= 2) return labels.join(".");
  const lastTwo = labels.slice(-2).join(".");
  if (MULTI_PART_TLDS.has(lastTwo)) return labels.slice(-3).join(".");
  return lastTwo;
}

function hostOf(url: string): string | null {
  const m = url.match(/^[a-z][a-z0-9+.-]*:\/\/([^/?#:]+)/i);
  return m?.[1] ? m[1].toLowerCase() : null;
}

const FORWARD_MARKERS = [
  /^-{2,}\s*forwarded message\s*-{2,}$/i,
  /^begin forwarded message:?$/i,
  /^-{3,}\s*original message\s*-{3,}$/i,
  /^_{8,}$/,
  /^-{10,}$/,
  /^forwarded message:?$/i,
  /^\[(external|ext)\]\s*.*$/i,
  /^caution:?\s+this (email|message) originated from outside/i,
  /^this (email|message) (originated|was sent) from (outside|an external)/i,
];
const HEADER_LINE = /^(from|sent|to|cc|bcc|date|subject|reply-to|sent by|de|para|von|an)\s*:/i;
const WROTE_LINE = /^on\b.{6,200}\bwrote:\s*$/i;
const DEVICE_SIG = [
  /^sent from my (iphone|ipad|galaxy|android|samsung|pixel|blackberry|windows phone).*$/i,
  /^sent froms+(mail|outlook)s+fors+(windows|ios|android).*$/i,
  /^get outlook for (ios|android).*$/i,
  /^sent from yahoo mail.*$/i,
  /^sent via .*$/i,
  /^sent from my mobile.*$/i,
];
const FOOTER_SENTENCE =
  /^(not sure|unsure|wondering) (if )?this (email|message|communication) (is|was|really).*$/i;

/**
 * Remove everything a forward adds: forwarded message markers, From/Sent/To/Subject header blocks, "wrote:" lines,
 * quote markers, external banners, device signatures, and the Fromenance footer. Also cuts at the "--" signature line.
 */
export function stripForwardChrome(text: string): string {
  const codes = new Set(extractVerifyCodes(text));
  const lines = text.replace(/\r\n?/g, "\n").split("\n");
  const kept: string[] = [];
  let inHeaderBlock = false;
  let pendingOn: string | null = null;
  let forwardStart: number | null = null;
  for (const raw of lines) {
    let line = raw.replace(/^\s*(?:>\s?)+/, "").trim();
    if (line === "--" || line === "-- ") break;
    if (pendingOn !== null) {
      const joined = `${pendingOn} ${line}`;
      if (WROTE_LINE.test(joined)) {
        pendingOn = null;
        continue;
      }
      kept.push(pendingOn);
      pendingOn = null;
    }
    if (line.length === 0) {
      inHeaderBlock = false;
      continue;
    }
    if (FORWARD_MARKERS.some((re) => re.test(line))) {
      inHeaderBlock = true;
      if (forwardStart === null) forwardStart = kept.length;
      continue;
    }
    if (HEADER_LINE.test(line)) {
      inHeaderBlock = true;
      if (forwardStart === null) forwardStart = kept.length;
      continue;
    }
    if (inHeaderBlock && /^[A-Za-z-]{2,20}:\s/.test(line)) continue;
    inHeaderBlock = false;
    if (WROTE_LINE.test(line)) continue;
    if (/^on\b.{6,200}$/i.test(line) && !/wrote:/i.test(line)) {
      pendingOn = line;
      continue;
    }
    if (DEVICE_SIG.some((re) => re.test(line))) continue;
    if (FOOTER_SENTENCE.test(line)) continue;
    if (/^reference:\s*[0-9a-z]{4}[\s-]?[0-9a-z]{4}\s*$/i.test(line)) continue;
    if (codes.size > 0) {
      let hasCode = false;
      for (const c of extractVerifyCodes(line)) if (codes.has(c)) hasCode = true;
      if (hasCode) continue;
    }
    line = line.replace(/\[(external|ext|caution)\]\s*/gi, "");
    kept.push(line);
  }
  if (pendingOn !== null) kept.push(pendingOn);
  const body = forwardStart === null ? kept : kept.slice(forwardStart);
  return body.join("\n");
}

/** Lowercase, drop everything that is not a letter, digit, or @, collapse whitespace. */
export function collapse(text: string): string {
  return text
    .toLowerCase()
    .replace(/[^\p{L}\p{N}@]+/gu, " ")
    .replace(/\s+/g, " ")
    .trim();
}

// ---- Verify codes (needed to strip the footer) --------------------------------------------------------------------

const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
const VALUE_OF: Record<string, number> = {};
for (let i = 0; i < CROCKFORD.length; i++) VALUE_OF[CROCKFORD[i] as string] = i;
VALUE_OF.O = 0;
VALUE_OF.I = 1;
VALUE_OF.L = 1;

function checksumSymbol(first7: string): string {
  let sum = 0;
  for (const ch of first7) sum += VALUE_OF[ch.toUpperCase()] as number;
  return CROCKFORD[sum % 32] as string;
}

/** 8 Crockford symbols with a checksum in the last position; returns null when the checksum does not validate. */
export function canonicalizeVerifyCode(input: string): string | null {
  const stripped = input.replace(/[\s\-\u2013\u2014_.]/g, "").toUpperCase();
  if (stripped.length !== 8) return null;
  let body = "";
  for (const ch of stripped) {
    const v = VALUE_OF[ch];
    if (v === undefined) return null;
    body += CROCKFORD[v];
  }
  if (checksumSymbol(body.slice(0, 7)) !== body[7]) return null;
  return body;
}

const CODE_RE = /(?<![0-9A-Za-z])([0-9A-Za-z]{4})[\s\-\u2013\u2014_.]?([0-9A-Za-z]{4})(?![0-9A-Za-z])/g;

export function extractVerifyCodes(text: string): string[] {
  const counts = new Map<string, number>();
  for (const m of text.matchAll(CODE_RE)) {
    const candidate = canonicalizeVerifyCode(`${m[1]}${m[2]}`);
    if (candidate) counts.set(candidate, (counts.get(candidate) ?? 0) + 1);
  }
  return [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([c]) => c);
}

// ---- Hashing --------------------------------------------------------------------------------------------------------

const U64_MASK = (1n << 64n) - 1n;
const FNV_OFFSET = 0xcbf29ce484222325n;
const FNV_PRIME = 0x100000001b3n;

/** FNV-1a 64 over the UTF-8 bytes of the input. BigInt keeps the arithmetic identical across runtimes. */
export function fnv1a64(input: string): bigint {
  const bytes = new TextEncoder().encode(input);
  let hash = FNV_OFFSET;
  for (const b of bytes) {
    hash ^= BigInt(b);
    hash = (hash * FNV_PRIME) & U64_MASK;
  }
  return hash;
}

/** Word 3-gram shingles. Short texts fall back to a single shingle so a two word message still hashes. */
export function shingles(text: string, n = 3): string[] {
  const tokens = text.split(/\s+/).filter((t) => t.length > 0);
  if (tokens.length === 0) return [];
  if (tokens.length < n) return [tokens.join(" ")];
  const out: string[] = [];
  for (let i = 0; i + n <= tokens.length; i++) out.push(tokens.slice(i, i + n).join(" "));
  return out;
}

/** 64 bit SimHash over word 3-gram shingles hashed with FNV-1a 64. Returns 0n for empty input. */
export function simhash64(normalizedText: string): bigint {
  const grams = shingles(normalizedText);
  if (grams.length === 0) return 0n;
  const counts = new Array<number>(64).fill(0);
  for (const g of grams) {
    const h = fnv1a64(g);
    for (let bit = 0; bit < 64; bit++) {
      if ((h >> BigInt(bit)) & 1n) counts[bit]! += 1;
      else counts[bit]! -= 1;
    }
  }
  let out = 0n;
  for (let bit = 0; bit < 64; bit++) if (counts[bit]! > 0) out |= 1n << BigInt(bit);
  return out;
}

/** Hamming distance between two 64 bit SimHashes. Fromenance matches at 6 or less by default. */
export function hamming(a: bigint, b: bigint): number {
  let x = (a ^ b) & U64_MASK;
  let count = 0;
  while (x) {
    x &= x - 1n;
    count++;
  }
  return count;
}

export async function sha256Hex(input: string): Promise<string> {
  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
  let s = "";
  for (const b of new Uint8Array(digest)) s += b.toString(16).padStart(2, "0");
  return s;
}
```

subject_fingerprint is simpler: strip leading Fwd: , Fw: , Re: style prefixes, apply step 5, SHA-256 hex.

## Step 6: register at send time and place the footer

Do. For every message, immediately before or after handing it to your sending system, make one call. Use the message id as the Idempotency-Key so a retried send registers once.

Request.

```http
POST https://api.fromenance.com/v1/communications
Authorization: Bearer fr_test_...
Content-Type: application/json
Idempotency-Key: <c1b2@jtmerlin.example>

{
  "channel": "email",
  "recipient_hash": "hmac-sha256:9f2c...64 hex...",
  "message_id": "<c1b2@jtmerlin.example>",
  "from_address": "alerts@jtmerlin.example",
  "sent_at": "2026-09-24T14:42:10Z",
  "subject_fingerprint": "e3b0...64 hex...",
  "content_fingerprint": { "simhash": "0x9a4d3c2b1f0e8d7c", "sha256": "e3b0...64 hex..." },
  "link_domains": ["jtmerlin.example"],
  "template_id": "new-device-alert-v2",
  "campaign_id": null,
  "provider": "api"
}
```

Required: recipient_hash , message_id , from_address , sent_at . Everything else is optional; the full field table is on Registering communications .

Read. 201 :

```json
{ "id": "com_01J...", "verify_code": "KX73-PQ9G", "expires_at": "2026-12-23T14:42:10Z", "sandbox": true }
```

A replay with the same key and body returns the same document with idempotent-replayed: true . 400 validation lists the failing fields in errors[] . 429 carries Retry-After (600 calls per minute per key).

Place the footer. Substitute verify_code for {{fromenance_code}} and put this text at the end of the message. The code appears twice on purpose so one copy survives rewrapping and screenshot OCR.

```text
Not sure this email is from JT Merlin Bank? Forward it to verify@jtmerlin.example
or enter code {{fromenance_code}} at jtmerlin.example/verify. Reference: {{fromenance_code}}
```

For KX73-PQ9G :

```text
Not sure this email is from JT Merlin Bank? Forward it to verify@jtmerlin.example
or enter code KX73-PQ9G at jtmerlin.example/verify. Reference: KX73-PQ9G
```

Use your institution name, your verify@ address, and your verify page URL (step 8), or omit the verify page clause until step 8 is done. An HTML version with the address and page as links is fine as long as the sentence and the Reference: line stay visible text.

Complete runnable samples.

- TypeScript (fetch)
- Python (urllib)

```ts samples/quickstart.ts
/**
 * Quickstart: register one rendered email with plain fetch and render the footer. Nothing to install.
 * Runs on Node 18+ (`npx tsx samples/quickstart.ts`) or Bun (`bun run samples/quickstart.ts`).
 *
 * Environment:
 *   FROMENANCE_API_KEY        fr_test_... from Settings, API keys (scope: register)
 *   FROMENANCE_TENANT_SECRET  the recipient hashing secret from Settings
 *   FROMENANCE_API_ORIGIN     optional, defaults to https://api.fromenance.com
 *
 * The recipient address and the body are hashed in this process. Only the HMAC and the fingerprint are sent.
 */
import { fingerprintContent, fingerprintSubject } from "./fingerprint.ts";
import { recipientHash } from "./recipient-hash.ts";

export interface RegistrationResponse {
  id: string;
  verify_code: string;
  expires_at: string;
  sandbox: boolean;
}

export interface Problem {
  type: string;
  title: string;
  status: number;
  detail?: string;
  instance?: string;
  errors?: { path: string; message: string }[];
  request_id?: string;
}

const API = (process.env.FROMENANCE_API_ORIGIN ?? "https://api.fromenance.com").replace(/\/$/, "");

/** One call at send time. Throws with the RFC 9457 problem document when the API rejects the request. */
export async function register(
  apiKey: string,
  body: Record<string, unknown>,
  idempotencyKey: string,
): Promise<RegistrationResponse> {
  const res = await fetch(`${API}/v1/communications`, {
    method: "POST",
    headers: {
      authorization: `Bearer ${apiKey}`,
      "content-type": "application/json",
      "idempotency-key": idempotencyKey,
    },
    body: JSON.stringify(body),
  });
  if (!res.ok) {
    const problem = (await res.json()) as Problem;
    throw new Error(
      `${problem.status} ${problem.title}: ${problem.detail ?? ""} (request ${problem.request_id})`,
    );
  }
  return (await res.json()) as RegistrationResponse;
}

/** The footer text. The code appears twice on purpose so one copy survives rewrapping and screenshot OCR. */
export function footer(
  code: string,
  institution: string,
  verifyAddress: string,
  verifyPageUrl: string,
): string {
  const page = verifyPageUrl.replace(/^https?:\/\//, "");
  return [
    `Not sure this email is from ${institution}? Forward it to ${verifyAddress}`,
    `or enter code ${code} at ${page}. Reference: ${code}`,
  ].join("\n");
}

export async function main(): Promise<{ id: string; verifyCode: string; footer: string }> {
  const apiKey = process.env.FROMENANCE_API_KEY;
  const tenantSecret = process.env.FROMENANCE_TENANT_SECRET;
  if (!apiKey || !tenantSecret) throw new Error("Set FROMENANCE_API_KEY and FROMENANCE_TENANT_SECRET");

  // The email exactly as your sending system renders it, before the footer is added.
  const messageId = `<${crypto.randomUUID()}@jtmerlin.example>`;
  const to = "jane.doe@example.com";
  const subject = "A new device signed in to your account";
  const html = `<p>Hi Jane,</p>
<p>A new device signed in to your JT Merlin Bank account on September 24 at 10:42 AM.</p>
<p>If this was you, no action is needed. If not, open the app and lock your card.</p>`;

  // Hash and fingerprint locally. Neither the address nor the body is sent.
  const fp = await fingerprintContent({ html });
  const body = {
    channel: "email",
    recipient_hash: await recipientHash(to, tenantSecret),
    message_id: messageId,
    from_address: "alerts@jtmerlin.example",
    sent_at: new Date().toISOString(),
    subject_fingerprint: await fingerprintSubject(subject),
    content_fingerprint: fp.tokens > 0 ? { simhash: fp.simhash, sha256: fp.sha256 } : undefined,
    link_domains: ["jtmerlin.example"],
    template_id: "new-device-alert-v2",
    provider: "api",
  };

  // The message id is a good Idempotency-Key: a retried send registers once.
  const registration = await register(apiKey, body, messageId);

  // Paste this footer into the message before it goes out.
  const text = footer(
    registration.verify_code,
    "JT Merlin Bank",
    "verify@jtmerlin.example",
    "https://jtmerlin.example/verify",
  );

  console.log(`registered ${registration.id} with code ${registration.verify_code}`);
  console.log(text);
  return { id: registration.id, verifyCode: registration.verify_code, footer: text };
}

if (process.argv[1]?.endsWith("quickstart.ts")) {
  main().catch((err) => {
    console.error(err);
    process.exit(1);
  });
}
```

Confirm.

```http
GET https://api.fromenance.com/v1/communications/com_01J...
Authorization: Bearer fr_test_...
```

200 with status: "registered" , verify_code , content_fingerprint (or null ), sandbox , and an empty verifications array until step 10. GET /v1/communications?limit=20 lists recent registrations.

## Step 7 (optional): batch and reserve

Batch , for statement runs. Up to 1,000 items per call, 6,000 items per minute per key, per item results in input order, one bad item does not fail the batch.

```http
POST https://api.fromenance.com/v1/communications/batch
Authorization: Bearer fr_test_...
Content-Type: application/json
Idempotency-Key: statements-2026-09-batch-0

{ "items": [ { ...registration... }, { ...registration... } ] }
```

Read 200 with results[] (index , ok , id , verify_code , expires_at , or error ), registered , failed .

Reserve , when the code must exist before the send does (ESP merge fields). Body optional.

```http
POST https://api.fromenance.com/v1/communications/reserve
Authorization: Bearer fr_test_...
Content-Type: application/json

{ "recipient_hash": "hmac-sha256:...", "template_id": "fraud-alert-v3", "provider": "sendgrid", "expires_in_hours": 24 }
```

Read 201 with id , verify_code , expires_at . Place the code, send, then complete with the message id and send time (an ESP adapter does this for you when its event carries the code):

```http
PATCH https://api.fromenance.com/v1/communications/com_01J...
Authorization: Bearer fr_test_...
Content-Type: application/json

{ "message_id": "<c1b2@jtmerlin.example>", "sent_at": "2026-09-24T14:42:10Z", "content_fingerprint": { "simhash": "0x...", "sha256": "..." } }
```

Read 200 with status: "registered" and completed_at . An expired reservation answers 409 . ESP specifics: Resend , SendGrid , Amazon SES , Postmark , Mailgun , Salesforce Marketing Cloud , Braze , Generic webhook .

## Step 8 (optional): put the verify widget on your site

Request. Create a site key bound to the origins that will host the page.

```http
POST https://api.fromenance.com/v1/site-keys
Authorization: Bearer fr_test_...
Content-Type: application/json

{ "name": "Public verify page", "allowed_origins": ["https://jtmerlin.example", "https://www.jtmerlin.example"], "normal_rate_per_minute": 60 }
```

Read. 201 with public_key (sk_pub_... , public by design), allowed_origins , embed.script , embed.iframe .

Do. Paste the script on https://jtmerlin.example/verify :

```html
<div id="fromenance-verify"></div>
<script src="https://cdn.fromenance.com/verify.js" data-site-key="sk_pub_..." data-target="#fromenance-verify" data-institution="JT Merlin Bank" data-theme="auto" async></script>
```

Then set the page URL on the tenant so replies and the footer can reference it:

```http
PATCH https://api.fromenance.com/v1/tenant
Authorization: Bearer fr_test_...
Content-Type: application/json

{ "verify_page_url": "https://jtmerlin.example/verify", "fraud_contact": "fraud@jtmerlin.example" }
```

Confirm. Load the page, paste the footer text from step 6 with a registered code, enter the registered address, submit. The card reads Verified. Rate limits, Turnstile, the iframe variant, and the raw POST /v1/public/submit API are on Verify page and Verify page API .

## Step 9 (optional): receive webhooks

Request.

```http
POST https://api.fromenance.com/v1/webhook-endpoints
Authorization: Bearer fr_test_...
Content-Type: application/json

{ "url": "https://siem.jtmerlin.example/hooks/fromenance", "events": ["verdict.created", "submission.replay_detected", "indicator.new"] }
```

Read. 201 with id (whe_... ) and secret (whsec_... , shown once).

Do. On every delivery, before parsing the body, check the signature: x-fromenance-signature is v1= plus the hex HMAC-SHA256 of <x-fromenance-timestamp>.<raw body> keyed with the secret; reject timestamps more than 5 minutes from now; compare in constant time; deduplicate on x-fromenance-delivery . Respond 2xx within 10 seconds; failures retry with backoff for about 21 hours.

```ts samples/verify-webhook.ts
/**
 * Verify a Fromenance outbound webhook (TypeScript, Node 18+ or Bun).
 *
 * Headers on every delivery:
 *   x-fromenance-event      verdict.created | submission.replay_detected | indicator.new | campaign.detected
 *   x-fromenance-delivery   whd_... delivery id, stable across retries and replays of the same delivery
 *   x-fromenance-timestamp  Unix seconds when the request was signed
 *   x-fromenance-signature  v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>" keyed with the endpoint secret>
 *
 * Reject anything older than 5 minutes and compare in constant time.
 */
import { createHmac, timingSafeEqual } from "node:crypto";

export const TOLERANCE_SECONDS = 5 * 60;

export interface FromenanceHeaders {
  "x-fromenance-event"?: string;
  "x-fromenance-delivery"?: string;
  "x-fromenance-timestamp"?: string;
  "x-fromenance-signature"?: string;
}

export function signFromenance(secret: string, timestamp: string, rawBody: string): string {
  return `v1=${createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex")}`;
}

export function verifyFromenanceSignature(
  headers: FromenanceHeaders,
  rawBody: string,
  secret: string,
  nowSeconds: number = Math.floor(Date.now() / 1000),
): boolean {
  const timestamp = headers["x-fromenance-timestamp"];
  const signature = headers["x-fromenance-signature"];
  if (!timestamp || !signature) return false;
  if (!/^\d+$/.test(timestamp)) return false;
  if (Math.abs(nowSeconds - Number(timestamp)) > TOLERANCE_SECONDS) return false;

  const expected = signFromenance(secret, timestamp, rawBody);
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(signature, "utf8");
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

/** Example handler for a fetch style runtime (Workers, Bun, Node 18+ with a fetch adapter). */
export async function handleWebhook(request: Request, secret: string): Promise<Response> {
  const rawBody = await request.text();
  const headers: FromenanceHeaders = {
    "x-fromenance-event": request.headers.get("x-fromenance-event") ?? undefined,
    "x-fromenance-delivery": request.headers.get("x-fromenance-delivery") ?? undefined,
    "x-fromenance-timestamp": request.headers.get("x-fromenance-timestamp") ?? undefined,
    "x-fromenance-signature": request.headers.get("x-fromenance-signature") ?? undefined,
  };
  if (!verifyFromenanceSignature(headers, rawBody, secret)) {
    return new Response("invalid signature", { status: 401 });
  }
  const event = JSON.parse(rawBody) as { id: string; type: string; created_at: string; data: unknown };
  // Deduplicate on x-fromenance-delivery or event.id before acting; retries resend the same payload.
  console.log(`accepted ${event.type} ${headers["x-fromenance-delivery"]}`);
  return new Response(null, { status: 204 });
}
```

Python and Go versions: Verify signatures .

Confirm.

```http
POST https://api.fromenance.com/v1/webhook-endpoints/whe_.../test
Authorization: Bearer fr_test_...
```

A synthetic verdict.created arrives; GET /v1/webhook-endpoints/whe_.../deliveries shows it as delivered .

## Step 10: verify end to end and read the verdict

Do. Send a real message that carries a footer with a code from step 6 to the address you registered. From that mailbox, forward it to verify@jtmerlin.example . Within seconds a reply arrives from your reply identity (jtmerlin@reply.fromenance.com until branded replies are set up). With a test key the reply goes to the tenant’s fraud contact address instead of the forwarding mailbox.

Read. The locked verdict block in the reply, and the same verdict in the API:

```http
GET https://api.fromenance.com/v1/submissions?limit=5
Authorization: Bearer fr_test_...
```

200 with data[] ; each has entry (forward or web ), verify_code_found , headers_present , dkim , arc , trust , and verdict with outcome , rule , replay , matched.communication_id , signals , replied_at .

| Outcome
| Reply text
| Rule you should see
| Meaning
|

| verified
| Verified: this message matches a communication we registered and sent to you on <sent_at> .
| code+recipient+content , code+recipient , or recipient+fingerprint
| The code (or the fingerprint) resolved to a registration for this recipient
|

| not_verified
| Not verified: no registered communication matches this message. That does not by itself mean it is fraudulent, but treat it with caution.
| no_match , code:replay , code:recipient_mismatch , code+recipient:content_mismatch
| Nothing matched, or a real footer was replayed on a different message or by a different recipient (replay: true )
|

| not_verified in Authoritative Mode
| Not verified: we did not send this message.
| no_match:authoritative
| Same as above for a tenant whose coverage has been reviewed and Authoritative Mode enabled
|

| known_fraud
| Known fraud: this message matches an impersonation attempt our fraud team has confirmed. Do not interact with it.
| fraud_list:indicator , fraud_list:fingerprint
| An indicator is on your fraud list or the content matches a sample an analyst marked as fraud
|

Confirm the three outcomes. Forward the registered message from the registered mailbox: Verified. Forward it from a different mailbox: Not verified with replay: true . Add a domain from a phishing sample to the fraud list (POST /v1/fraud-list with { "items": [ { "kind": "domain", "value": "jtmerlin-secure-login.example" } ] } ) and forward a message containing it: Known fraud. Full detail on reading submissions, overrides, and exports: Verifications .

## Going live

Repeat steps 1 and 6 with an fr_live_ key, set reply_mode to branded after Branded replies , set expected_daily_volume on the tenant or the source so coverage is measured, and watch Sources and the Overview for coverage gaps.

## Copy for your agent

```text
Fromenance integration checklist (docs: https://docs.fromenance.com/getting-started/integration-guide). Base URL https://api.fromenance.com, header Authorization: Bearer <api key>, JSON bodies, RFC 9457 errors. Nothing to install.
1. Get an owner or admin login at https://app.fromenance.com. Settings, API keys: mint a key with scopes register and read; fr_test_ for the sandbox, fr_live_ for production; shown once. Copy the recipient hashing secret from Settings. Confirm: GET /v1/tenant returns slug and verify_address.
2. POST /v1/domains {"domain":"<domain>"}. Publish txt_record: name _fromenance.<domain>, type TXT, value "v=fromenance1; t=<slug>; k=<key>". POST /v1/domains/{id}/check until status is verified.
3. Create verify@<domain> on the mail platform and a rule that REDIRECTS (not forwards) it to <slug>@verify.fromenance.com. Guides: /domains-and-mail/google, /domains-and-mail/microsoft-365, /domains-and-mail/proofpoint, /domains-and-mail/mimecast, /domains-and-mail/cisco-secure-email.
4. POST /v1/domains/{id}/forwarding-test, then GET the same path every few seconds until status is working. failed: <reason> is explained at /domains-and-mail#rejection-reasons.
5. recipient_hash = "hmac-sha256:" + lowercase hex HMAC-SHA256(key = tenant secret, message = trimmed, lowercased address without display name). content_fingerprint (optional) = {"simhash":"0x<16 hex>","sha256":"<64 hex>"} over the normalized body using the pipeline and code at /getting-started/integration-guide#step-5-compute-the-recipient-hash-and-the-content-fingerprint; both fields or omit the object.
6. At send time POST /v1/communications with Idempotency-Key = message id and body {channel:"email", recipient_hash, message_id, from_address, sent_at, subject_fingerprint?, content_fingerprint?, link_domains?, template_id?, campaign_id?, provider?}. Read verify_code. Append the footer: "Not sure this email is from <Institution>? Forward it to verify@<domain> or enter code <verify_code> at <domain>/verify. Reference: <verify_code>".
7. Optional: POST /v1/communications/batch {"items":[...]} up to 1,000; POST /v1/communications/reserve to get a code before send, then PATCH /v1/communications/{id} with message_id and sent_at.
8. Optional: POST /v1/site-keys {"name","allowed_origins":[origins]}; embed <script src="https://cdn.fromenance.com/verify.js" data-site-key="sk_pub_..." data-target="#fromenance-verify" data-institution="<Institution>" async> on <domain>/verify; PATCH /v1/tenant {"verify_page_url","fraud_contact"}.
9. Optional: POST /v1/webhook-endpoints {"url","events":["verdict.created","submission.replay_detected","indicator.new"]}; verify x-fromenance-signature = "v1=" + hex HMAC-SHA256(secret, "<x-fromenance-timestamp>.<raw body>"), reject timestamps older than 5 minutes, compare in constant time, respond 2xx.
10. Send a registered message with the footer, forward it to verify@<domain>, read the reply and GET /v1/submissions. Verified = matches a registration for this recipient; Not verified = no match or a replayed footer (replay:true); Known fraud = fraud list hit.
More: https://docs.fromenance.com/llms.txt and https://fromenance.com/llms.txt
```

---

Page: What Fromenance does
URL: https://docs.fromenance.com/getting-started

# Make every customer communication verifiable

Fromenance is a communication provenance platform. Your institution registers each outbound message at send time; a customer forwards a suspicious message to verify@ on your domain or pastes it on your verify page and gets Verified, Not verified, or Known fraud in seconds.
15 minute quickstart API reference

Fromenance is a communication provenance platform for banks, credit unions, insurers, and utilities. Communication provenance means the institution can state, with a record behind it, whether a specific message was sent to a specific recipient.

By the end of this page you will know the three moving parts and where to go next.

## The three parts

Registration

At send time your application, ESP webhook, or a journal copy tells Fromenance that a message went to a recipient. Only a keyed hash of the address and a fingerprint of the body are stored. Each registration gets a verify code such as KX73-PQ9G that you place in the footer.

Verification

A customer forwards the message to verify@yourdomain.com , which your mail platform redirects to your tenant inbox at Fromenance, or pastes it on yourdomain.com/verify . Fromenance extracts the code, the recipient, and a content fingerprint, matches them against the registry, and answers.

Verdict

Verified, Not verified, or Known fraud, in your voice, from your domain, within seconds. Every non verified submission becomes an indicator set you can export to your SIEM or takedown vendor.

## What matching is built on

No language model sits on the verdict path. Extraction is regular expressions, MIME parsing, a 64 bit SimHash, and HMAC comparison, so the same input always yields the same verdict.

| Signal
| Where it comes from
| Strength
|

| Verify code
| The footer, including OCR’d screenshots. Checksummed, so account numbers and order ids do not false match.
| Strongest
|

| Recipient
| The forwarding customer’s address, hashed with your tenant secret and compared to the registered hash
| Required alongside the code
|

| Content fingerprint
| SimHash of the normalized body, Hamming distance 6 or less by default
| Confirms the code, or matches on its own with the recipient
|

| Headers
| DKIM for your sending domains when the customer forwarded as an attachment
| When present
|

| Indicators
| URLs, domains, emails, phone numbers, IPs
| Drives Known fraud
|

## Going live

A tenant is live once it has a verified domain, a working redirect rule, and one registered stream. The setup wizard in the admin app walks through the six steps; the quickstart below does the same from the command line.

Quickstart Create a key, publish the TXT record, create the redirect rule, register one email over HTTPS, forward it, read the reply. Nothing to install.
Integration guide, end to end The numbered checklist a person or an AI agent can execute top to bottom, with every request and response field.
Concepts Registration, verify codes, fingerprints, recipient hashes, verdict rules, replay, Authoritative Mode.
Domains and mail The trust model and click by click redirect rules for Google Workspace, Microsoft 365, Proofpoint, Mimecast, and Cisco.
Registering communications The REST API, recipient hashing, fingerprints, batch, reserve, and one page per ESP adapter.

---

Page: Quickstart
URL: https://docs.fromenance.com/getting-started/quickstart

# Quickstart

Fromenance is a communication provenance platform: you register each outbound message at send time and customers can ask whether a message is real. This quickstart takes an empty tenant to a Verified reply in about 15 minutes.

There is nothing to install. Fromenance is a REST API: one HTTPS call at send time, one TXT record, one redirect rule.

At the end you will have an API key, a verified domain, a working redirect rule, one registered communication with its footer, and a reply in your inbox that says the message matches a communication you registered. For the complete, agent executable version of these steps with every request and response field, see the Integration guide .

You need: an owner or admin login to app.fromenance.com , DNS access for your domain, admin access to your mail platform, and either curl , Node 18+, Bun, or Python 3.9+. Replace jtmerlin.example with your domain and jtmerlin with your tenant slug throughout.

Create an API key.

In the admin app open Settings, API keys, and mint a key named quickstart with mode test and scope register . The secret is shown once. Test keys (fr_test_ ) write to a sandbox partition and never mail a real customer: sandbox replies go to the fraud contact address set in Settings, so set that to your own address now. Copy the recipient hashing secret from Settings as well; it is separate from the API key.

You can also mint the key from the API with an existing admin key:

```bash
curl -X POST https://api.fromenance.com/v1/api-keys \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"quickstart","mode":"test","scopes":["register"]}'
```

Export the values the samples read:

```bash
export FROMENANCE_API_KEY=fr_test_...
export FROMENANCE_TENANT_SECRET=...   # the recipient hashing secret from Settings
export FROMENANCE_API_ORIGIN=https://api.fromenance.com
```

Add your domain and publish the TXT record.

```bash
curl -X POST https://api.fromenance.com/v1/domains \
  -H "Authorization: Bearer $FROMENANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"jtmerlin.example"}'
```

The response includes txt_record . Publish it at your DNS provider:

```text
_fromenance.jtmerlin.example.  TXT  "v=fromenance1; t=jtmerlin; k=<32 hex characters>"
```

Fromenance polls DNS every hour for 24 hours. Force a check and confirm status is verified :

```bash
curl -X POST https://api.fromenance.com/v1/domains/dom_.../check \
  -H "Authorization: Bearer $FROMENANCE_API_KEY"
```

The domain gets the roles trust and sender by default. trust lets forwards that authenticate for it through; sender lets it appear as a registered From address.

Create the redirect rule.

Create the mailbox or group verify@jtmerlin.example and add a rule that redirects (not forwards) everything it receives to your tenant inbox, jtmerlin@verify.fromenance.com . The address is shown as verify_address on GET /v1/tenant .

Redirect keeps the customer as the sender, so Fromenance can reply to them, and preserves the DKIM signature your platform adds. A forward rewrites the sender to verify@ and the reply would come back to you.

Click by click guides: Google Workspace , Microsoft 365 , Proofpoint , Mimecast , Cisco Secure Email .

Send the forwarding test.

```bash
curl -X POST https://api.fromenance.com/v1/domains/dom_.../forwarding-test \
  -H "Authorization: Bearer $FROMENANCE_API_KEY"
```

Fromenance emails verify@jtmerlin.example with a token. When the redirect delivers it to your tenant inbox with a DKIM or ARC pass for your domain, the rule is marked Working. Poll until status is working :

```bash
curl https://api.fromenance.com/v1/domains/dom_.../forwarding-test \
  -H "Authorization: Bearer $FROMENANCE_API_KEY"
```

A failed result names the rejection reason . The common one is auth_failed , which means the rule forwarded instead of redirecting.

Register the first communication.

One POST /v1/communications per recipient at send time. You send two hashes, never the address or the body: recipient_hash (HMAC-SHA256 of the lowercased, trimmed address keyed with your tenant secret) and, optionally, content_fingerprint (a SimHash and SHA-256 of the normalized body). The response carries the verify code for the footer.

- TypeScript
- curl
- Python

Plain fetch , no dependencies. fingerprint.ts and recipient-hash.ts next to it are the two helpers it imports; both are on the Integration guide and in the docs repository.

```ts samples/quickstart.ts
/**
 * Quickstart: register one rendered email with plain fetch and render the footer. Nothing to install.
 * Runs on Node 18+ (`npx tsx samples/quickstart.ts`) or Bun (`bun run samples/quickstart.ts`).
 *
 * Environment:
 *   FROMENANCE_API_KEY        fr_test_... from Settings, API keys (scope: register)
 *   FROMENANCE_TENANT_SECRET  the recipient hashing secret from Settings
 *   FROMENANCE_API_ORIGIN     optional, defaults to https://api.fromenance.com
 *
 * The recipient address and the body are hashed in this process. Only the HMAC and the fingerprint are sent.
 */
import { fingerprintContent, fingerprintSubject } from "./fingerprint.ts";
import { recipientHash } from "./recipient-hash.ts";

export interface RegistrationResponse {
  id: string;
  verify_code: string;
  expires_at: string;
  sandbox: boolean;
}

export interface Problem {
  type: string;
  title: string;
  status: number;
  detail?: string;
  instance?: string;
  errors?: { path: string; message: string }[];
  request_id?: string;
}

const API = (process.env.FROMENANCE_API_ORIGIN ?? "https://api.fromenance.com").replace(/\/$/, "");

/** One call at send time. Throws with the RFC 9457 problem document when the API rejects the request. */
export async function register(
  apiKey: string,
  body: Record<string, unknown>,
  idempotencyKey: string,
): Promise<RegistrationResponse> {
  const res = await fetch(`${API}/v1/communications`, {
    method: "POST",
    headers: {
      authorization: `Bearer ${apiKey}`,
      "content-type": "application/json",
      "idempotency-key": idempotencyKey,
    },
    body: JSON.stringify(body),
  });
  if (!res.ok) {
    const problem = (await res.json()) as Problem;
    throw new Error(
      `${problem.status} ${problem.title}: ${problem.detail ?? ""} (request ${problem.request_id})`,
    );
  }
  return (await res.json()) as RegistrationResponse;
}

/** The footer text. The code appears twice on purpose so one copy survives rewrapping and screenshot OCR. */
export function footer(
  code: string,
  institution: string,
  verifyAddress: string,
  verifyPageUrl: string,
): string {
  const page = verifyPageUrl.replace(/^https?:\/\//, "");
  return [
    `Not sure this email is from ${institution}? Forward it to ${verifyAddress}`,
    `or enter code ${code} at ${page}. Reference: ${code}`,
  ].join("\n");
}

export async function main(): Promise<{ id: string; verifyCode: string; footer: string }> {
  const apiKey = process.env.FROMENANCE_API_KEY;
  const tenantSecret = process.env.FROMENANCE_TENANT_SECRET;
  if (!apiKey || !tenantSecret) throw new Error("Set FROMENANCE_API_KEY and FROMENANCE_TENANT_SECRET");

  // The email exactly as your sending system renders it, before the footer is added.
  const messageId = `<${crypto.randomUUID()}@jtmerlin.example>`;
  const to = "jane.doe@example.com";
  const subject = "A new device signed in to your account";
  const html = `<p>Hi Jane,</p>
<p>A new device signed in to your JT Merlin Bank account on September 24 at 10:42 AM.</p>
<p>If this was you, no action is needed. If not, open the app and lock your card.</p>`;

  // Hash and fingerprint locally. Neither the address nor the body is sent.
  const fp = await fingerprintContent({ html });
  const body = {
    channel: "email",
    recipient_hash: await recipientHash(to, tenantSecret),
    message_id: messageId,
    from_address: "alerts@jtmerlin.example",
    sent_at: new Date().toISOString(),
    subject_fingerprint: await fingerprintSubject(subject),
    content_fingerprint: fp.tokens > 0 ? { simhash: fp.simhash, sha256: fp.sha256 } : undefined,
    link_domains: ["jtmerlin.example"],
    template_id: "new-device-alert-v2",
    provider: "api",
  };

  // The message id is a good Idempotency-Key: a retried send registers once.
  const registration = await register(apiKey, body, messageId);

  // Paste this footer into the message before it goes out.
  const text = footer(
    registration.verify_code,
    "JT Merlin Bank",
    "verify@jtmerlin.example",
    "https://jtmerlin.example/verify",
  );

  console.log(`registered ${registration.id} with code ${registration.verify_code}`);
  console.log(text);
  return { id: registration.id, verifyCode: registration.verify_code, footer: text };
}

if (process.argv[1]?.endsWith("quickstart.ts")) {
  main().catch((err) => {
    console.error(err);
    process.exit(1);
  });
}
```

```bash
bun run samples/quickstart.ts
# or: npx tsx samples/quickstart.ts
```

Paste the footer into the message and send it to yourself.

Substitute the code from the response for {{fromenance_code}} . The code appears twice on purpose: once in the sentence and once as a bare reference, so one survives client rewrapping and screenshot OCR.

```text
Not sure this email is from JT Merlin Bank? Forward it to verify@jtmerlin.example
or enter code {{fromenance_code}} at jtmerlin.example/verify. Reference: {{fromenance_code}}
```

With KX73-PQ9G substituted:

```text
Not sure this email is from JT Merlin Bank? Forward it to verify@jtmerlin.example
or enter code KX73-PQ9G at jtmerlin.example/verify. Reference: KX73-PQ9G
```

Send the email, with the footer, from alerts@jtmerlin.example to the address you registered (jane.doe@example.com in the samples; use one you control).

Forward it and read the reply.

From the recipient mailbox, forward the message to verify@jtmerlin.example . Within seconds a reply arrives from your reply identity (jtmerlin@reply.fromenance.com until you set up branded replies ). Its locked verdict block reads:

Verified: this message matches a communication we registered and sent to you on September 24, 2026 at 2:42 PM UTC.

Because this is a sandbox key, the reply goes to your fraud contact address rather than to the forwarding mailbox. The submission also appears in the admin app under Submissions with rule code+recipient+content (or code+recipient when you registered without a fingerprint) and the verdict.created event fires on any webhook endpoint you have configured.

Forward the same message from a different mailbox than the one you registered: the reply says Not verified and the submission is flagged as a footer replay. Add a domain from a phishing sample to the fraud list and forward a message containing it: the reply says Known fraud.

## Next

- The complete checklist with every request and response: Integration guide .

- Wire your real sending path: Registering communications and the adapter page for your ESP.

- Put the verify widget on your site: Verify page .

- Send verdicts to your SIEM: Webhooks .

---

Page: Concepts
URL: https://docs.fromenance.com/getting-started/concepts

# Concepts

Fromenance is a communication provenance platform: it keeps a registry of what an institution sent and answers whether a message a customer holds is in it. This page defines every term the rest of the documentation uses.

By the end you will be able to read a verdict, its rule, and its signals in the admin app and know exactly why the answer came out the way it did.

## Communication provenance

Communication provenance is the ability to state, from a record made at send time, whether a specific communication was sent to a specific recipient. SPF, DKIM, and DMARC authenticate a domain, not a message; a lookalike domain passes all three. Provenance answers the customer’s actual question: did my bank send this to me?

## Registration

A registration is one row in the registry: one message to one recipient. It carries a channel (email in v1), the recipient hash, the message id, the visible From address, the send time, optional subject and content fingerprints, link domains, your own template and campaign ids, the provider, and an expiry. It never carries the recipient address or the body.

Three paths create registrations: the REST API from your own code, ESP webhooks through an adapter, and a journal or BCC copy sent to journal-<slug>@ingest.fromenance.com . See Registering communications .

Registrations expire at the tenant retention setting (90 days by default) or at the expires_at you pass. Ids are prefixed ULIDs: com_ for communications, sub_ for submissions, ver_ for verdicts, src_ for sources, dom_ for domains, whe_ and whd_ for webhook endpoints and deliveries.

## Verify code

Every registration is issued a verify code: 8 Crockford base32 symbols shown as XXXX-XXXX , for example KX73-PQ9G . The eighth symbol is a checksum (the sum of the first seven symbol values modulo 32). Extraction only accepts codes whose checksum validates, which keeps account numbers, order ids, and capitalised words from producing false matches. Lowercase, spaces, missing hyphens, and the Crockford aliases (O as 0 , I and L as 1 ) are all read correctly, including from OCR.

The code is bound to the recipient. A real footer pasted into a different message, or a real message forwarded by someone it was not sent to, does not verify.

## Content fingerprint

The fingerprint is a 64 bit SimHash over word 3-gram shingles of the normalized visible text, plus a SHA-256 of the same text. Normalization strips HTML to text, unwraps gateway rewritten links (Proofpoint, Microsoft Defender, Google redirects), removes forward chrome (forwarded message markers, header blocks, “wrote:” lines, quote markers, device signatures), removes the Fromenance footer itself, cuts at a signature delimiter, replaces every URL with its registered domain, collapses whitespace, and lowercases. Fromenance runs the identical pipeline on the customer’s forward at verify time, and the dependency free implementation on the Integration guide produces the same bits in Node, Bun, and Cloudflare Workers.

Two fingerprints match when their Hamming distance is 6 or less (match_threshold on the tenant, 0 to 20). A Gmail, Outlook, Apple Mail, or Proofpoint rewritten forward of the same message lands within that distance; an unrelated lure lands far away. The normalized text is never stored; only the hashes are.

## Recipient hash

recipient_hash is hmac-sha256:<64 hex> : HMAC-SHA256 of the lowercased, trimmed address (display name and angle brackets removed) keyed with a secret issued per tenant. You compute it locally with any HMAC library; the API rejects anything that is not already a hash. When a customer forwards a message, Fromenance hashes their address with the same secret and compares. The registry never holds a raw recipient address; the column does not exist.

## Submission

A submission is one customer question: a forward to verify@ (entry forward ) or a paste, .eml , screenshot, or typed code on the verify page (entry web ). It records the code found, the recipient hash found, the fingerprint, whether original headers were present, DKIM, ARC, and trust results, and the extracted indicators. The same customer submitting the same message again increments count on the existing submission instead of creating a second one, and gets the same reply again.

## Verdicts

Every submission ends in one of three outcomes, with the exact rule that produced it.

| Outcome
| Customer reads
| Rule values
|

| Verified
| “matches a communication we registered and sent to you on <sent_at> ”
| code+recipient , code+recipient+content , recipient+fingerprint
|

| Not verified
| “no registered communication matches this message”
| no_match , code:replay , code:recipient_mismatch , code+recipient:content_mismatch , no_match:authoritative
|

| Known fraud
| “matches an impersonation attempt our fraud team has confirmed”
| fraud_list:indicator , fraud_list:fingerprint
|

The verdict block is locked in every reply template. It states only whether a registered communication matches, never vouches for the message beyond that, never quotes the suspicious message, and never repeats its links or its sender.

## Matching rules

The verdict function is pure: no I/O, no model, no randomness. It evaluates in this order.

- Known fraud. Any extracted indicator is on the tenant fraud list (fraud_list:indicator ), or the fingerprint matches a submission an analyst marked as fraud (fraud_list:fingerprint ).

- Code and recipient match. The code resolves to a registration whose recipient hash equals the submitter’s hash (or the hash of the innermost To header). Verified by code+recipient when no fingerprint is available on one side, code+recipient+content when both fingerprints are close. When both fingerprints exist and are far apart, the customer gets Not verified by code+recipient:content_mismatch and the submission is flagged as a replay: a real footer was pasted into a different message and sent to the same person.

- Code resolves, recipient does not. Not verified. Flagged as a replay (code:replay ) when the fingerprint is far or unavailable. A close fingerprint with the wrong recipient is code:recipient_mismatch : a real message forwarded from a mailbox it was not sent to, not an attack.

- No code. The nearest registration for the submitter within the registration window (90 days) and within the threshold is Verified by recipient+fingerprint . Confidence degrades with distance.

- Nothing matched. Not verified by no_match , or no_match:authoritative when the tenant is in Authoritative Mode.

Each verdict carries signals : code_found , recipient_match , fingerprint_distance , headers_present , dkim .

## Footer replay

A footer replay is a valid code on the wrong message or from the wrong recipient. Attackers copy real footers to make lures look legitimate. Fromenance reports it to the customer as Not verified, sets replay: true on the verdict, sends the submission.replay_detected webhook event, and queues the indicators with high priority. Codes rotate per message, so a copied footer never verifies for anyone but its original recipient.

## Authoritative Mode

By default Not verified means “no record”, because a coverage gap on your side must not read as fraud to your customer. Authoritative Mode changes the locked text to “we did not send this message” and the rule to no_match:authoritative . It is a per tenant flag that only a Fromenance operator can enable, after your coverage has been reviewed: the proposal is 95 percent coverage for 30 days. It is shown read only in Settings.

## Coverage and sources

Coverage is registered volume against the volume you state you send, per source per day. A sending source is one integration: the API, an ESP webhook adapter, or the journal address. Each source tracks last event, events per hour, signature failures, reservations against completions, and coverage gaps, and raises a silence alert when no event arrives within its configured expectation. Gaps are visible before a customer finds one.

## Reserve flow

ESPs that cannot hand over the rendered body need the code before the send exists. POST /v1/communications/reserve issues a code bound to a recipient; you place it through the ESP’s merge field; the ESP’s send event completes the registration with the message id and send time. A reservation not completed within 24 hours (configurable 1 to 72) expires and counts as a coverage gap.

## Trust model

A forward to <slug>@verify.fromenance.com is processed only when it authenticates for a domain you own: a DKIM signature that verifies for the domain, or an ARC chain whose last seal is by it, and that domain has a verified _fromenance.<domain> TXT record with your token and the trust role. Everything else is held for 24 hours and never answered. Details in Domains and mail .

## Indicators and the fraud list

Indicators are URLs, domains, email addresses, phone numbers, and IPs extracted from every submission (low priority on Verified ones, so nothing is lost). The fraud list is the tenant’s block list. Entries come only from analyst action; nothing is added automatically from a single submission, because anyone can forward anything through your rule.

## Campaigns

Campaigns cluster submissions that share indicators, fingerprints within distance 10, or a phishing kit fingerprint. They are a Phase 2 feature of the intelligence tier. The campaigns table and the campaign_id on submissions exist in v1 so nothing has to be backfilled, and the admin app shows a placeholder.

---

Page: Domains and mail
URL: https://docs.fromenance.com/domains-and-mail

# Domains and mail

Fromenance is a communication provenance platform that answers customer forwards in your name, so it only accepts forwards that provably came through your mail platform. This page explains the trust model behind the verify@ inbox and how to read a rejection.

By the end you will have published the TXT record, understood what the redirect rule must do, and know what each rejection reason means.

## Two records, one rule

Your DNS footprint for the forward path is a single TXT record. The optional branded reply identity adds three more on a subdomain. Fromenance never asks you to CNAME anything to fromenance.com.

### The trust TXT record

When you add a domain (POST /v1/domains or Domains in the admin app) the response includes txt_record :

```text
_fromenance.jtmerlin.example.  TXT  "v=fromenance1; t=jtmerlin; k=<32 hex character token>"
```

- v=fromenance1 is the record version.

- t= is your tenant slug, which is also the local part of your tenant inbox jtmerlin@verify.fromenance.com .

- k= is a token minted for this domain. It is not a secret; it proves that whoever controls the DNS zone intended to bind the domain to this tenant.

Fromenance polls the record every hour for 24 hours after you add the domain, then daily. POST /v1/domains/{id}/check runs the check immediately. A domain moves from pending to verified when the record resolves and the token matches; a verified domain whose record disappears moves to suspended and inbound for it is paused until the record is back.

### Domain roles

Each domain carries roles. New domains get trust and sender ; reply is added when you create a branded reply identity.

| Role
| Meaning
|

| trust
| Forwards that authenticate for this domain are accepted into your tenant inbox
|

| sender
| Registered communications may carry a From address on this domain; journal copies from other domains are rejected
|

| reply
| Verdict replies are sent from verify@verify.<domain> (or the subdomain you chose)
|

A tenant can own several domains (jtmerlin.example , jtmerlinalerts.example ). Each needs its own TXT record. Any of them can host the verify@ rule and any with sender can be a registered From.

## The redirect rule

Customers write to verify@yourdomain.com . Your mail platform must redirect that mail to your tenant inbox, <slug>@verify.fromenance.com . The address is verify_address on GET /v1/tenant and is shown in the setup wizard.

Redirect and forward are different operations on every platform, and only redirect works:

|
| Redirect
| Forward
|

| Envelope and visible sender
| The customer stays the sender, so Fromenance can reply to them
| Rewritten to verify@ , so the reply would come back to you
|

| Original headers
| Preserved, including the customer’s forwarded message structure
| Often rewrapped, and the innermost message can be flattened
|

| Authentication seen by Fromenance
| Your platform’s DKIM signature or ARC seal for your domain
| Usually the same, but the reply path is already broken
|

Because the customer’s own domain is what the message was originally signed by, your platform must add its own authentication on the way out. Google Workspace signs redirected mail with DKIM for your domain; Microsoft 365 adds an ARC seal by your tenant’s domain and, depending on configuration, a DKIM signature. Proofpoint, Mimecast, and Cisco sit in front of one of those two and hand the redirect to it. Each platform guide covers what to check.

Click by click guides: Google Workspace , Microsoft 365 , Proofpoint , Mimecast , Cisco Secure Email .

## The trust check

Every message arriving at <slug>@verify.fromenance.com goes through the same check before anything is parsed for content.

- The slug resolves to an active tenant.

- The message carries a DKIM signature that verifies for a domain the tenant owns, or an ARC chain whose last seal is by such a domain. Fromenance runs DKIM (RFC 6376) and ARC (RFC 8617) verification itself on the raw MIME it receives; it does not trust upstream Authentication-Results headers.

- That domain is verified (its TXT token matched on the last check) and carries the trust role.

Subdomains count: a signature for mail.jtmerlin.example vouches for a tenant that owns jtmerlin.example .

Only the forward path needs this check. The verify page is authenticated by its site key and origin.

## Rejection reasons

A message that fails the trust check is stored for 24 hours as rejected inbound, never processed, and never answered. The reason is visible to Fromenance support during onboarding, and the forwarding test in the setup wizard reports it as failed: <reason> .

| Reason
| Meaning
| Fix
|

| unknown_inbox
| The local part before @verify.fromenance.com is not a tenant slug
| Check the redirect target address against verify_address
|

| tenant_inactive
| The tenant is suspended
| Contact support
|

| no_domains
| The tenant has no domains at all
| Add a domain and publish the TXT record
|

| auth_failed
| No DKIM signature verified and no ARC seal passed. The detail lists each signature and why it failed
| The rule forwarded instead of redirecting, or your platform does not sign outbound mail for the domain. Fix the rule; confirm DKIM signing is on
|

| domain_not_owned
| A signature passed, but for a domain not in your tenant
| Add that domain (for example a separate sending subdomain your platform signs with)
|

| domain_not_verified
| The signing domain is in your tenant but its TXT record has not resolved yet
| Wait for the poll or run a check
|

| domain_suspended
| The TXT record was removed after verification
| Republish the record
|

| domain_no_trust_role
| The domain exists and is verified but lacks the trust role
| Add the role with PATCH /v1/domains/{id}
|

## Troubleshooting: my forwards are rejected

- Run the forwarding test from the setup wizard or POST /v1/domains/{id}/forwarding-test and read result .

- auth_failed with a detail like dkim jtmerlin.example/google: fail (body hash mismatch) means something modified the message after signing: a disclaimer stamped by a gateway after the redirect, or a rule that rewrites the body. Move the redirect after the gateway or exclude verify@ from stamping.

- auth_failed with no signatures means the redirect path does not sign at all. On Microsoft 365 confirm ARC sealing is on for the tenant; on Google Workspace confirm DKIM authentication is set up for the domain.

- domain_not_owned with a domain like jtmerlin-example.mail.onmicrosoft.com means the platform signed with its tenant domain rather than yours. Configure DKIM for your custom domain.

- Send a plain message from a personal mailbox to verify@yourdomain.com and check that a reply arrives within a minute. Until you have registered anything, the reply is Not verified, which confirms the path end to end.

---

Page: Google Workspace
URL: https://docs.fromenance.com/domains-and-mail/google

# Google Workspace

Fromenance is a communication provenance platform that answers forwards sent to verify@yourdomain.com . On Google Workspace, that address is a group or user with a routing rule that changes the envelope recipient to your tenant inbox.

By the end you will have verify@ created, a routing rule that redirects it to <slug>@verify.fromenance.com , DKIM signing confirmed, and the forwarding test marked Working.

## Before you start

- Super admin or an admin role with Gmail settings access in the Google Admin console.

- Your tenant inbox address, verify_address in the setup wizard, for example jtmerlin@verify.fromenance.com .

- The domain verified in Fromenance.

## 1. Create the verify@ address

Either works. A group is simpler to keep unattended.

As a group

- Admin console, Directory, Groups, Create group.

- Name Verify , group email verify@yourdomain.com .

- Access type: Public, and under “Who can post” allow anyone on the internet. External customers must be able to write to it.

- Do not add members. Mail is routed on before delivery.

As a user

- Admin console, Directory, Users, Add new user, primary email verify@yourdomain.com .

- Set a strong password and store it; nobody signs in to it.

## 2. Create the routing rule

Use a default routing rule so the redirect happens at the domain edge, before the group or mailbox.

- Admin console, Apps, Google Workspace, Gmail, Routing (or Default routing on older consoles).

- Under Default routing , click Add another rule (or Configure ).

- Specify envelope recipients : choose Single recipient and enter verify@yourdomain.com .

- If the envelope recipient matches the above, do the following : choose Modify message .

- Tick Change envelope recipient and enter your tenant inbox, jtmerlin@verify.fromenance.com , in Replace recipient .

- Leave Add X-Gm-Original-To header ticked. Leave Also deliver to unticked and do not add other recipients.

- Do not tick Bypass spam filter for this message unless you see customer forwards blocked by spam filtering; Fromenance handles abuse itself.

- Options: Perform this action on non-recognized and recognized addresses .

- Save. Google can take up to an hour to apply routing changes; usually it is a few minutes.

This rule redirects: the customer remains the sender, the original headers are kept, and Google signs the outbound copy with DKIM for your domain.

## 3. Keep DKIM signing on

- Admin console, Apps, Google Workspace, Gmail, Authenticate email.

- Select your domain. Status must read “Authenticating email” with a selector (usually google ).

- If it reads “Not authenticating email”, generate a record, publish the google._domainkey TXT record at your DNS provider, and click Start authentication .

Redirected mail is signed with this key. Without it the trust check fails with auth_failed .

Mail that leaves Google through a third party outbound gateway (Proofpoint, Mimecast, Cisco) is signed by Google before the gateway sees it; make sure the gateway does not stamp a disclaimer or rewrite the body on the way out, or the body hash check fails. If your gateway adds an ARC seal for your domain instead, that also passes.

## 4. Confirm with the forwarding test

- In the setup wizard, step 4, click Send test , or call POST /v1/domains/{id}/forwarding-test .

- Fromenance emails verify@yourdomain.com with a token. Within a minute the status should read Working via dkim yourdomain.com .

- failed: auth_failed with no signatures means the routing rule is not matching yet or DKIM is off. failed: domain_not_owned names a different signing domain; add it as a domain in Fromenance or fix the DKIM configuration for your primary domain.

Then forward any message from a personal mailbox to verify@yourdomain.com and confirm a Not verified reply arrives.

## Notes

- Keep verify@ out of any rule that appends footers or disclaimers; content modification after signing breaks DKIM.

- If you use a content compliance rule that quarantines external mail with attachments, add an exception for verify@ . Customers forward .eml attachments.

- Google groups can be set to moderate external messages; make sure message moderation is off for this group.

---

Page: Microsoft 365
URL: https://docs.fromenance.com/domains-and-mail/microsoft-365

# Microsoft 365

Fromenance is a communication provenance platform that answers forwards sent to verify@yourdomain.com . On Microsoft 365, that address is a mailbox or distribution group with an Exchange Online mail flow rule that redirects it to your tenant inbox.

By the end you will have verify@ created, a mail flow rule with Redirect the message to (not forward), ARC sealing and DKIM confirmed for your domain, and the forwarding test marked Working.

## Before you start

- Exchange administrator role in the Microsoft 365 admin center.

- Your tenant inbox address, verify_address in the setup wizard, for example jtmerlin@verify.fromenance.com .

- The domain verified in Fromenance.

## 1. Create the verify@ address

As a shared mailbox (recommended, no license)

- Exchange admin center, Recipients, Mailboxes, Add a shared mailbox .

- Display name Verify , email verify@yourdomain.com . Do not add members.

As a distribution group

- Exchange admin center, Recipients, Groups, Add a group , type Distribution.

- Email verify@yourdomain.com . Under Settings, allow people outside the organization to send to the group. Do not add members.

## 2. Create the mail flow rule

Exchange admin center, Mail flow, Rules , Add a rule , Create a new rule .

Name: Fromenance verify redirect .

Apply this rule if : The recipient > is this person , choose verify@yourdomain.com .

Do the following : Redirect the message to > these recipients , and enter your tenant inbox jtmerlin@verify.fromenance.com . Exchange accepts an external address here.

Do not choose Forward the message for approval or Bcc the message . Both rewrite or copy; only redirect keeps the customer as the sender and the headers intact.

Leave Except if empty.

Rule settings: Enforce , severity Low, Stop processing more rules ticked so a later disclaimer or encryption rule cannot touch it. Match sender address in message: Header .

Save and enable. Rules typically apply within 30 minutes.

## 3. Confirm authentication on the redirected copy

Exchange Online adds an ARC seal to mail it processes. The seal is by your tenant’s domain when your accepted domain is configured for DKIM; Fromenance accepts an ARC chain whose last seal is by a domain you own, or a DKIM signature that verifies for one.

- Microsoft Defender portal, Email and collaboration, Policies and rules, Threat policies, Email authentication settings , DKIM .

- Select yourdomain.com and confirm Sign messages for this domain with DKIM signatures is enabled. If not, create the two selector1._domainkey and selector2._domainkey CNAME records shown and enable it.

- If the redirected copy is signed with yourtenant.onmicrosoft.com instead of your domain, the forwarding test reports domain_not_owned with that domain. Enable DKIM for your custom domain, or add the onmicrosoft.com domain to Fromenance with only the trust role and publish its TXT record.

### ARC sealing note

Exchange Online seals with your domain only when it is the last hop before Fromenance. If a third party gateway (Proofpoint, Mimecast, Cisco) relays your outbound mail, that gateway must either preserve the Microsoft seal and the DKIM signature untouched or add its own ARC seal for your domain. Add your gateway to Trusted ARC sealers in Email authentication settings for inbound; for outbound, disable disclaimer stamping and body rewriting on the connector that carries the redirect.

## 4. Confirm with the forwarding test

- In the setup wizard, step 4, click Send test , or call POST /v1/domains/{id}/forwarding-test .

- Within a minute the status should read Working via arc yourdomain.com or Working via dkim yourdomain.com .

- failed: auth_failed with a body hash mismatch means something changed the message after signing, usually a disclaimer rule ordered after the redirect. Move the redirect rule above it and set Stop processing more rules .

Then forward any message from a personal mailbox to verify@yourdomain.com and confirm a Not verified reply arrives.

## Notes

- Do not set mailbox level forwarding on the shared mailbox (Mailbox, Email forwarding). That is a forward, and it also delivers a copy locally.

- Outbound spam policies can block automatic external forwarding. If the redirect never leaves, open Microsoft Defender, Anti-spam policies, Anti-spam outbound policy , and set Automatic forwarding rules to On for the policy that covers verify@ , or create a custom policy for that one address.

- Attachment blocking rules can drop .eml forwards. Exempt verify@ .

---

Page: Proofpoint
URL: https://docs.fromenance.com/domains-and-mail/proofpoint

# Proofpoint

Fromenance is a communication provenance platform that answers forwards sent to verify@yourdomain.com . When Proofpoint fronts your mail, the redirect can live in Proofpoint or behind it in Google Workspace or Microsoft 365; this page covers both placements and what Proofpoint must not do to the message.

By the end you will have chosen where the redirect lives, configured it, kept the outbound copy signed for your domain, and seen the forwarding test marked Working.

## Choose where the redirect lives

| Placement
| When to use
| Authentication Fromenance sees
|

| Behind Proofpoint, in Google Workspace or Microsoft 365
| Default. Proofpoint only filters inbound; the platform redirects outbound and signs
| Platform DKIM or ARC for your domain
|

| In Proofpoint, as a routing rule to an external recipient
| The mailbox platform cannot redirect, or you want the redirect before any mailbox
| Requires Proofpoint outbound DKIM signing for your domain
|

In both cases the outbound copy that reaches <slug>@verify.fromenance.com must carry a DKIM signature or ARC seal for a domain you own, and its body must not be modified after signing. Proofpoint URL Defense rewrites links inside the customer’s forward; that happens on the inbound leg before the redirect and is expected. Fromenance unwraps Proofpoint v2 and v3 rewritten links when fingerprinting, so rewriting does not hurt matching.

## Option A: redirect behind Proofpoint

- Allow external mail to verify@yourdomain.com through Proofpoint: Email Protection, Policy Routes or Spam Policies, make sure verify@ is not on a quarantine only route. Customers write from personal addresses, often with .eml attachments, which attachment defense may sandbox; allow message/rfc822 attachments for this recipient.

- Configure the redirect on the mailbox platform: Google Workspace or Microsoft 365 .

- On the outbound leg, if Proofpoint relays outbound mail for your domain, open Email Protection, Email Firewall (or Outbound policy), and make sure no rule appends a disclaimer or footer to mail whose sender is external (the customer) and whose recipient is @verify.fromenance.com . Add a rule with Recipient equals *@verify.fromenance.com and action Deliver now placed above disclaimer rules.

## Option B: redirect in Proofpoint

Proofpoint Email Protection (on premises or hosted)

- Email Protection, Email Firewall , Rules , Add .

- Conditions: Recipient equals verify@yourdomain.com .

- Action: Redirect to (in some versions Change recipient ), value jtmerlin@verify.fromenance.com . Do not use Copy to or Forward to , which add recipients or rewrite the sender.

- Set the rule to stop processing further rules and place it above any disclaimer or DLP rule.

- Outbound signing: DKIM Signing under System, Domain Keys. Add a signing key for yourdomain.com , publish the selector TXT record, and enable signing for outbound mail on the route that carries the redirect. Without this the copy leaves unsigned and Fromenance rejects it with auth_failed .

Proofpoint Essentials

- Administration, Company Settings, Filters , New filter , direction Inbound .

- Scope: Specific user verify@yourdomain.com .

- Action: Redirect to and enter jtmerlin@verify.fromenance.com .

- Essentials cannot sign outbound mail for your domain by itself; the redirect is delivered by the Essentials relay. If the forwarding test fails with auth_failed , use Option A instead.

## Confirm with the forwarding test

- Setup wizard, step 4, Send test , or POST /v1/domains/{id}/forwarding-test .

- Status should read Working via dkim yourdomain.com (Option B or Google behind Proofpoint) or Working via arc yourdomain.com (Microsoft 365 behind Proofpoint).

- failed: auth_failed naming a body hash mismatch means a disclaimer or footer was stamped after signing. Move the deliver now rule above it.

- failed: domain_not_owned naming pphosted.com or a Proofpoint relay domain means the copy was signed by Proofpoint’s domain rather than yours. Enable DKIM signing for your domain in Proofpoint, or add that relay domain to Fromenance with the trust role only if it is dedicated to your tenant.

Then forward any message from a personal mailbox to verify@yourdomain.com and confirm a Not verified reply arrives.

---

Page: Mimecast
URL: https://docs.fromenance.com/domains-and-mail/mimecast

# Mimecast

Fromenance is a communication provenance platform that answers forwards sent to verify@yourdomain.com . With Mimecast in front of your mail, the redirect usually stays on the mailbox platform and Mimecast only has to let the customer’s forward in and the redirected copy out untouched.

By the end you will have verify@ reachable through Mimecast, the redirect configured, disclaimer stamping excluded for the redirected copy, and the forwarding test marked Working.

## Where the redirect lives

Mimecast does not offer a per recipient redirect to an external address in its standard policy set; address alteration policies rewrite addresses on inbound or outbound mail rather than redirecting delivery. Keep the redirect on the mailbox platform (Google Workspace or Microsoft 365 ) and configure Mimecast so the two legs pass cleanly:

- Inbound leg : a customer at any external address writes to verify@yourdomain.com with a forwarded message, often as an .eml attachment.

- Outbound leg : the platform redirects that message to jtmerlin@verify.fromenance.com . The customer is still the sender. Mimecast sees external sender, external recipient, on your outbound route.

## 1. Let customer forwards in

- Administration Console, Gateway, Policies , Attachment Management (or Attachment Protection). Add a definition that permits message/rfc822 and .eml attachments, and a policy scoped to recipient verify@yourdomain.com that applies it. Sandboxing the attachment is fine; blocking or stripping it removes the message the customer is asking about.

- Gateway, Policies, Spam Scanning : confirm verify@ inherits the default action of deliver with tagging rather than hold. Held mail never reaches Fromenance.

- Gateway, Policies, Impersonation Protection : forwards of phishing samples trigger impersonation hits by design. Add a bypass policy with recipient verify@yourdomain.com so samples are delivered rather than held. Fromenance handles abuse on its side; the fraud list is only ever written by your analysts.

## 2. Let the redirected copy out unchanged

- Gateway, Policies, Stationery (disclaimers and signatures): create a policy at the top of the list with Emails to = *@verify.fromenance.com , stationery None , and Policy override enabled so it wins. A stamped disclaimer breaks the DKIM body hash and Fromenance rejects the copy with auth_failed .

- Gateway, Policies, Document Services or Content Examination : exclude recipient *@verify.fromenance.com from any policy that rewrites or strips content.

- Gateway, Policies, DNS Authentication - Outbound (DKIM signing): if Mimecast is your outbound relay, confirm signing is enabled for yourdomain.com with a published selector. The redirected copy is signed by whichever system is the last hop; if that is Mimecast, its signature for your domain is what Fromenance checks. If Mimecast relays but does not sign, the Microsoft ARC seal or the Google DKIM signature from the platform must survive untouched, which the policies above ensure.

- URL Protect rewrites links in the customer’s forward on the inbound leg. That is expected and Fromenance’s normalization handles rewritten links from Mimecast, Proofpoint, Microsoft, and Google.

## 3. Configure the redirect on the platform

Follow Google Workspace or Microsoft 365 . If Mimecast is also your outbound connector, the platform’s redirect is delivered through Mimecast; nothing else changes.

## 4. Confirm with the forwarding test

- Setup wizard, step 4, Send test , or POST /v1/domains/{id}/forwarding-test .

- Status should read Working via dkim yourdomain.com or Working via arc yourdomain.com within a minute.

- failed: auth_failed with a body hash mismatch: a stationery or content policy modified the copy. Re-check the policy order and the override flag.

- failed: domain_not_owned naming a mimecast.com domain: the copy was signed by Mimecast’s own domain. Enable DKIM signing for your domain in DNS Authentication - Outbound.

- Nothing arrives: check Message Center, Held for the test message. A hold policy on the inbound or outbound leg is the usual cause.

Then forward any message from a personal mailbox to verify@yourdomain.com and confirm a Not verified reply arrives.

---

Page: Cisco Secure Email
URL: https://docs.fromenance.com/domains-and-mail/cisco-secure-email

# Cisco Secure Email

Fromenance is a communication provenance platform that answers forwards sent to verify@yourdomain.com . On Cisco Secure Email (the Email Security Appliance and Cloud Gateway, formerly IronPort), the redirect can be a content filter with the Alter Delivery action or a redirect behind the gateway on your mailbox platform.

By the end you will have chosen the placement, configured the redirect, DKIM signing confirmed for the outbound copy, and the forwarding test marked Working.

## Choose where the redirect lives

| Placement
| When to use
| Authentication Fromenance sees
|

| Behind Cisco, in Google Workspace or Microsoft 365
| Default. Cisco filters inbound; the platform redirects and signs
| Platform DKIM or ARC for your domain
|

| In Cisco, as an incoming content filter that alters delivery
| The mailbox platform cannot redirect, or you want no mailbox at all
| Cisco outbound DKIM signing for your domain
|

## Option A: redirect behind Cisco

- Mail Policies, Incoming Mail Policies : make sure verify@yourdomain.com is on a policy whose anti-spam action is deliver (with a subject prefix if you like) rather than quarantine, and whose Advanced Malware Protection and attachment filtering allow message/rfc822 attachments. Customers forward .eml files.

- Configure the redirect on the mailbox platform: Google Workspace or Microsoft 365 .

- If Cisco is your outbound relay, Mail Policies, Outgoing Content Filters : any filter that adds a disclaimer must exclude recipients matching @verify.fromenance.com . Create a filter with condition Envelope Recipient ends with @verify.fromenance.com and action Skip Remaining Content Filters , and order it first.

## Option B: redirect in Cisco

- Mail Policies, Incoming Content Filters , Add Filter . Name fromenance_verify_redirect .

- Condition: Envelope Recipient , Ends With or Is , verify@yourdomain.com .

- Action: Alter Delivery , Alter Recipient To (the alt-rcpt-to action), value jtmerlin@verify.fromenance.com . This rewrites the envelope recipient only; the sender and headers are untouched. Do not use Bcc or Send Copy To , and do not use a mailbox forward on the platform.

- Add a second action Skip Remaining Content Filters so no disclaimer filter runs afterwards.

- Apply the filter to the incoming mail policy that covers your domain and commit changes.

Because the message now leaves the appliance with an external sender and an external recipient, the appliance treats it as relayed mail. Confirm the outbound path:

- Network, Listeners : the outbound listener’s Mail Flow Policy must allow relay for mail originating from the redirect. On a single listener deployment this is the default; on a two listener deployment add a rule so that recipients under verify.fromenance.com are accepted for relay from the incoming listener (Network, SMTP Routes, add verify.fromenance.com to route through your normal outbound path).

- Mail Policies, Signing Profiles (DKIM): create a domain signing profile for yourdomain.com , generate the key, publish the selector TXT record, and enable DKIM Signing on the Mail Flow Policy that carries the redirected copy. The copy must be signed with your domain, or the forwarding test fails with auth_failed (unsigned) or domain_not_owned (signed with the appliance hostname domain).

## Confirm with the forwarding test

- Setup wizard, step 4, Send test , or POST /v1/domains/{id}/forwarding-test .

- Status should read Working via dkim yourdomain.com within a minute.

- failed: auth_failed with a body hash mismatch: a disclaimer or footer was stamped after signing, or the filter order lets a later filter touch the message. Check the Skip Remaining Content Filters action and the outgoing filter order.

- Nothing arrives: Monitor, Message Tracking , search for the recipient verify@yourdomain.com ; the tracking detail shows which filter or policy held it.

Then forward any message from a personal mailbox to verify@yourdomain.com and confirm a Not verified reply arrives.

---

Page: Branded replies
URL: https://docs.fromenance.com/domains-and-mail/branded-replies

# Branded replies

Fromenance is a communication provenance platform that replies to customers in your institution’s name, so the reply should come from your domain. This page sets up the branded reply identity and explains the minimal identity used during pilots.

By the end you will have a sending subdomain such as verify.yourdomain.com verified, three DNS records published, and replies arriving from verify@verify.yourdomain.com with a DKIM pass for that subdomain.

## Two reply identities

| Mode
| Reply From
| DNS
| Use
|

| Branded (recommended)
| JT Merlin Bank <verify@verify.yourdomain.com>
| The trust TXT record plus three records on the sending subdomain
| Production
|

| Minimal
| JT Merlin Bank <jtmerlin@reply.fromenance.com>
| The trust TXT record only
| Pilots. The wizard says so and production tenants should not stay on it
|

reply_mode on the tenant (branded or minimal ) selects the identity; reply_from_name sets the display name. The web verify page renders the verdict on the page and needs no reply identity at all.

## 1. Create the reply identity

In the admin app open Domains, choose the domain, and click Set up reply identity . Or from the API:

```bash
curl -X POST https://api.fromenance.com/v1/domains/dom_.../reply-identity \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"subdomain":"verify"}'
```

subdomain is optional and defaults to verify , giving verify.yourdomain.com . Fromenance creates that subdomain as a sending domain through Resend, adds the reply role to your domain, and returns reply_identity.records .

## 2. Publish the three records

The exact values come back in the response and are shown in the admin app; the shape is:

| Record
| Name
| Type
| Value
|

| DKIM
| resend._domainkey.verify.yourdomain.com
| TXT
| p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC...
|

| SPF (return path)
| send.verify.yourdomain.com
| MX, priority 10
| feedback-smtp.us-east-1.amazonses.com
|

| SPF
| send.verify.yourdomain.com
| TXT
| v=spf1 include:amazonses.com ~all
|

Together with the trust TXT record this is four records total. Nothing on your apex or your main sending domain changes, and your existing DMARC policy applies: replies are DKIM aligned with verify.yourdomain.com , which is a subdomain of your organizational domain, so p=reject with relaxed alignment passes. If you use strict DKIM alignment (adkim=s ) add an explicit _dmarc.verify.yourdomain.com record.

## 3. Verify the records

Click Verify in the admin app or call:

```bash
curl -X POST https://api.fromenance.com/v1/domains/dom_.../reply-identity/verify \
  -H "Authorization: Bearer fr_live_..."
```

reply_identity.status moves to verified once Resend sees all three records; each record also carries its own status . Then set reply_mode to branded and reply_domain_id to this domain:

```bash
curl -X PATCH https://api.fromenance.com/v1/tenant \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"reply_mode":"branded","reply_domain_id":"dom_...","reply_from_name":"JT Merlin Bank"}'
```

## 4. Send a test reply

Reply templates, choose any outcome, Send test (POST /v1/reply-templates/{outcome}/test ) mails the rendered template to your own address from the reply identity. Confirm the message shows verify@verify.yourdomain.com as the sender and passes DKIM in your client’s authentication details.

## Notes

- Replies are only ever sent to the customer who forwarded the message, from the identity above, and never quote the forwarded message or its links.

- Sandbox submissions (test keys, sandbox tenants) never mail a customer; the reply goes to the fraud contact address in Settings when it is an email address.

- The reply subdomain is only used for verdict replies. Do not point application mail at it.

---

Page: Registering communications
URL: https://docs.fromenance.com/registering

# Registering communications

Fromenance is a communication provenance platform, and registration is the act of telling it, at send time, that a specific communication went to a specific recipient. Everything downstream depends on coverage, so there are three ways in and all three are first class.

By the end you will know which path fits each sending system, what a registration carries, how to hash and fingerprint correctly with no dependencies, and how reservations and batches work. Every request on this page is a plain HTTPS call; the Integration guide walks them in order.

## Three paths in

| Path
| Fits
| Body available for fingerprinting
| Page
|

| REST API from your own code
| Your own application or sending pipeline
| Yes, computed locally
| This page
|

| ESP webhook adapter
| SendGrid, Amazon SES, Resend, Postmark, Mailgun, Salesforce Marketing Cloud, Braze, or anything that can call a webhook
| Depends on the provider; see each adapter page
| Resend , SendGrid , Amazon SES , Postmark , Mailgun , Salesforce Marketing Cloud , Braze , Generic webhook
|

| Journal or BCC copy to journal-<slug>@ingest.fromenance.com
| Core banking and statement vendors you cannot change
| Yes, from the copy
| Below
|

## Authentication

Registration calls use an API key with the register scope as a bearer token: Authorization: Bearer fr_live_... . Keys are minted in Settings, API keys, shown once, hashed at rest, and revocable. fr_test_ keys write to a sandbox partition: registrations and submissions are marked sandbox: true , and replies never reach a real customer. Use a test key while integrating and a live key for production.

## What a registration carries

POST /v1/communications accepts:

| Field
| Required
| Notes
|

| channel
| no
| email , the default and the only value in v1
|

| recipient_hash
| yes
| hmac-sha256:<64 lowercase hex> of the canonical recipient address keyed with your tenant secret
|

| message_id
| yes
| The RFC 5322 Message-ID or the ESP’s message id, 1 to 998 characters
|

| from_address
| yes
| The visible From, 3 to 320 characters. Should be on a domain you own with the sender role
|

| sent_at
| yes
| ISO 8601 with offset or Z
|

| subject_fingerprint
| no
| 64 hex: SHA-256 of the normalized subject
|

| content_fingerprint
| no
| { "simhash": "0x9a4d3c2b1f0e8d7c", "sha256": "<64 hex>" } of the normalized body. Both fields are required when the object is present; there is no way to send the raw body instead. Strongly recommended: without it the registration matches on code plus recipient only
|

| link_domains
| no
| Up to 50 registered domains (253 characters each) that appear in links, used to whitelist during matching
|

| template_id , campaign_id
| no
| Your own identifiers, up to 120 characters or null , shown in the admin app and returned on verdicts
|

| provider
| no
| api (default), sendgrid , ses , resend , postmark , mailgun , sfmc , braze , relay , journal , generic . Groups the registration under the matching source for coverage
|

| expires_at
| no
| ISO 8601. Defaults to now plus your retention setting (90 days by default)
|

| verify_code
| no
| Only when completing a code you reserved earlier; otherwise omit and one is issued
|

Response, 201 Created :

```json
{ "id": "com_01J...", "verify_code": "KX73-PQ9G", "expires_at": "2026-12-26T14:42:10Z", "sandbox": false }
```

Every registration is unique on (tenant, verify code). Rate limit: 600 requests per minute per key on register and reserve; a 429 carries Retry-After .

## Recipient hashing

The API never receives a recipient address. Compute:

```text
recipient_hash = "hmac-sha256:" + lowercase_hex( HMAC-SHA256( key = tenant secret, message = canonical(address) ) )
canonical(address) = trim, take the part inside <> if a display name is present, lowercase, strip a leading "mailto:"
```

"Jane Doe" <Jane@Bank.com > and jane@bank.com hash identically. WebCrypto, Python hmac , and openssl dgst -sha256 -hmac all produce the same value; code for each is on the Integration guide . The tenant secret is shown in Settings, is different from your API keys, and never travels to the API; keep it in the same secret store as a live key.

## Content fingerprint

The fingerprint is two hashes over the same normalized text: a 64 bit SimHash over word 3-gram shingles hashed with FNV-1a 64 (sent as 0x plus 16 hex characters), and a SHA-256 (64 hex characters). Normalization strips HTML to text, unwraps gateway rewritten links, removes forward chrome and the Fromenance footer, cuts at a signature delimiter, replaces every URL with the registered domain of its host, lowercases, and collapses whitespace. Fromenance runs the identical pipeline on the customer’s forward at verify time, so a forward lands within the Hamming threshold (6 by default) of what you registered. The normalized text is never persisted anywhere.

Pass the rendered email exactly as it goes out, before the footer is added (the normalizer strips the footer anyway). When the normalized text is empty, for example an image only message, omit content_fingerprint ; matching then relies on the code plus recipient.

A dependency free TypeScript implementation, tested bit for bit against the reference, is on the Integration guide . It is the same file the samples on this page import.

## The footer and the {{fromenance_code}} merge tag

Place the verify code in the message where your templating system substitutes it. The generic placeholder is {{fromenance_code}} ; each ESP has its own syntax, listed on its adapter page (-fromenance_code- on SendGrid legacy templates, %%=v(@fromenance_code)=%% on Marketing Cloud, a Liquid attribute on Braze). The code appears twice on purpose so one copy survives rewrapping and screenshot OCR.

```text
Not sure this email is from JT Merlin Bank? Forward it to verify@jtmerlin.example
or enter code {{fromenance_code}} at jtmerlin.example/verify. Reference: {{fromenance_code}}
```

An HTML version with the address and page as links is fine; keep the sentence and the bare Reference: line as visible text.

## Idempotency

Send Idempotency-Key (up to 200 characters) on every creating POST. Fromenance stores the response for 24 hours per (tenant, key). A replay with the same body returns the stored response with the header idempotent-replayed: true ; a replay with a different body is rejected with 422 idempotency-mismatch . The message id is a good key: a retried send registers once.

## Batch

POST /v1/communications/batch takes { "items": [ ...1 to 1,000 registrations ] } and returns per item results in input order. One bad item does not fail the batch. Rate limit: 6,000 items per minute per key. Codes are allocated in one pass, so a 1,000 item statement run completes in about a second.

```json
{
  "results": [
    { "index": 0, "ok": true, "id": "com_01J...", "verify_code": "KX73-PQ9G", "expires_at": "2026-12-26T14:42:10Z" },
    { "index": 1, "ok": false, "error": "invalid verify code" }
  ],
  "registered": 1,
  "failed": 1
}
```

```ts samples/register-batch.ts
/**
 * Register a statement run: up to 1,000 rendered emails in one call, with plain fetch. Nothing to install.
 * Each item is hashed and fingerprinted locally; per item results come back in input order.
 */
import { fingerprintContent, fingerprintSubject } from "./fingerprint.ts";
import { recipientHash } from "./recipient-hash.ts";

export interface StatementEmail {
  to: string;
  messageId: string;
  html: string;
}

export interface BatchItemResult {
  index: number;
  ok: boolean;
  id?: string;
  verify_code?: string;
  expires_at?: string;
  error?: string;
}

export interface BatchResponse {
  results: BatchItemResult[];
  registered: number;
  failed: number;
}

const API = (process.env.FROMENANCE_API_ORIGIN ?? "https://api.fromenance.com").replace(/\/$/, "");

export async function registerStatementRun(
  apiKey: string,
  tenantSecret: string,
  emails: StatementEmail[],
): Promise<{ registered: number; failed: number; codesByMessageId: Map<string, string> }> {
  const codesByMessageId = new Map<string, string>();
  let registered = 0;
  let failed = 0;
  const subject = "Your September statement is ready";

  // Chunk at 1,000 items, the batch limit. 6,000 items per minute are accepted per key.
  for (let i = 0; i < emails.length; i += 1000) {
    const chunk = emails.slice(i, i + 1000);
    const items = await Promise.all(
      chunk.map(async (e) => {
        const fp = await fingerprintContent({ html: e.html });
        return {
          channel: "email",
          recipient_hash: await recipientHash(e.to, tenantSecret),
          message_id: e.messageId,
          from_address: "statements@jtmerlin.example",
          sent_at: new Date().toISOString(),
          subject_fingerprint: await fingerprintSubject(subject),
          content_fingerprint: fp.tokens > 0 ? { simhash: fp.simhash, sha256: fp.sha256 } : undefined,
          template_id: "monthly-statement-v7",
          provider: "api",
        };
      }),
    );
    const res = await fetch(`${API}/v1/communications/batch`, {
      method: "POST",
      headers: {
        authorization: `Bearer ${apiKey}`,
        "content-type": "application/json",
        "idempotency-key": `statements-2026-09-batch-${i / 1000}`,
      },
      body: JSON.stringify({ items }),
    });
    if (!res.ok) throw new Error(`batch rejected: ${res.status} ${await res.text()}`);
    const result = (await res.json()) as BatchResponse;
    registered += result.registered;
    failed += result.failed;
    for (const item of result.results) {
      const source = chunk[item.index];
      if (item.ok && item.verify_code && source) codesByMessageId.set(source.messageId, item.verify_code);
      else if (!item.ok) console.warn(`item ${item.index} rejected: ${item.error}`);
    }
  }
  return { registered, failed, codesByMessageId };
}

export async function main(): Promise<void> {
  const apiKey = process.env.FROMENANCE_API_KEY;
  const tenantSecret = process.env.FROMENANCE_TENANT_SECRET;
  if (!apiKey || !tenantSecret) throw new Error("Set FROMENANCE_API_KEY and FROMENANCE_TENANT_SECRET");
  const run = Array.from({ length: 3 }, (_, n) => ({
    to: `customer${n}@example.com`,
    messageId: `<stmt-${crypto.randomUUID()}@jtmerlin.example>`,
    html: `<p>Your statement for September is ready. Balance: $${(n + 1) * 100}.00</p>`,
  }));
  const out = await registerStatementRun(apiKey, tenantSecret, run);
  console.log(`registered ${out.registered}, failed ${out.failed}`);
}
```

## Reserve

Use POST /v1/communications/reserve when the code must exist before the send does: ESPs that merge fields at send time and cannot hand back the rendered body. The body is optional; pass what you know:

| Field
| Notes
|

| recipient_hash
| Bind the code to the recipient now so a send event with a different recipient cannot claim it
|

| template_id , campaign_id , from_address , provider
| Recorded on the reservation
|

| expires_in_hours
| 1 to 72, default 24
|

Response is the same shape as register with the code to inject. The reservation is completed either by the ESP’s send event carrying the code (each adapter reads it from the provider’s custom field), or by PATCH /v1/communications/{id} with message_id , sent_at , and optionally the fingerprint. A reservation not completed before it expires is marked expired , counts as a coverage gap on the source, and a later PATCH returns 409 .

```ts samples/reserve-complete.ts
/**
 * Reserve flow with plain fetch: get a verify code before the send exists, inject it through your ESP's merge
 * field, then complete the registration once the message id and send time are known. ESP adapters complete
 * reservations automatically when the send event carries the code.
 */
import { fingerprintContent } from "./fingerprint.ts";
import { recipientHash } from "./recipient-hash.ts";

const API = (process.env.FROMENANCE_API_ORIGIN ?? "https://api.fromenance.com").replace(/\/$/, "");

async function call<T>(apiKey: string, method: string, path: string, body: unknown): Promise<T> {
  const res = await fetch(`${API}${path}`, {
    method,
    headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`${method} ${path} failed: ${res.status} ${await res.text()}`);
  return (await res.json()) as T;
}

export async function reserveThenComplete(apiKey: string, tenantSecret: string, to: string) {
  const recipient_hash = await recipientHash(to, tenantSecret);

  // 1. Reserve. The code is bound to this recipient and expires in 24 hours unless completed.
  const reserved = await call<{ id: string; verify_code: string; expires_at: string }>(
    apiKey,
    "POST",
    "/v1/communications/reserve",
    { recipient_hash, template_id: "fraud-alert-v3", provider: "sendgrid" },
  );
  console.log(`reserved ${reserved.id} code ${reserved.verify_code}`);

  // 2. Send through your ESP with the code in the footer merge field, for example
  //    custom_args.fromenance_code = reserved.verify_code on SendGrid.
  const messageId = `<${crypto.randomUUID()}@jtmerlin.example>`;
  const html = "<p>We noticed a sign in from a new device.</p>";

  // 3. Complete. Not needed when the ESP webhook is connected and echoes the code back.
  const fp = await fingerprintContent({ html });
  const completed = await call<{ status: string; completed_at: string | null }>(
    apiKey,
    "PATCH",
    `/v1/communications/${reserved.id}`,
    {
      message_id: messageId,
      from_address: "alerts@jtmerlin.example",
      sent_at: new Date().toISOString(),
      content_fingerprint: fp.tokens > 0 ? { simhash: fp.simhash, sha256: fp.sha256 } : undefined,
    },
  );
  console.log(`status ${completed.status}, completed_at ${completed.completed_at}`);
  return completed;
}

export async function main(): Promise<void> {
  const apiKey = process.env.FROMENANCE_API_KEY;
  const tenantSecret = process.env.FROMENANCE_TENANT_SECRET;
  if (!apiKey || !tenantSecret) throw new Error("Set FROMENANCE_API_KEY and FROMENANCE_TENANT_SECRET");
  await reserveThenComplete(apiKey, tenantSecret, "jane.doe@example.com");
}
```

## Journal or BCC

Add journal-<slug>@ingest.fromenance.com (journal_address on GET /v1/tenant ) as a BCC or journaling target on the sending system. Fromenance receives the full copy, checks that the From is on a domain with the sender role, hashes the customer recipient (the To address that is not the journal inbox), fingerprints the body, registers it under the Journal source, and deletes the raw copy. If the footer already carries a reserved code, the reservation is completed; if a static per template code is reused for another recipient, a fresh code bound to that recipient is registered instead.

The reply to the customer still needs a code in the footer, so this path pairs with the reserve flow or with a static per template code. A copy whose From is not on a sender domain is dropped and logged as rejected on the source.

## Reading a registration back

GET /v1/communications/{id} (scope read ) returns the registration with status (reserved , registered , expired ), retro (created by an analyst override), and every verification made against it with its submission id, outcome, rule, and time. GET /v1/communications searches by code, message id, template, and date.

Everything on this page works identically with an fr_test_ key. Sandbox registrations and the submissions that match them are marked sandbox: true , and replies go to your fraud contact address instead of a customer.

---

Page: Resend
URL: https://docs.fromenance.com/registering/resend

# Resend

Fromenance is a communication provenance platform, and the Resend adapter turns Resend’s email.sent and email.delivered events into registrations without changing your application code. Resend exposes the rendered body through its API, so registrations made this way carry a full content fingerprint.

By the end you will have a Resend source with a webhook URL and secret, the Resend webhook pointed at it, the code placed in your template, and events showing on the source’s health panel.

## 1. Create the source

Admin app: Sources, Add source , kind Resend . Or from the API with an admin key:

```bash
curl -X POST https://api.fromenance.com/v1/sending-sources \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Resend transactional","kind":"resend","config":{"api_key":"re_..."},"expected_daily_volume":20000,"silence_alert_minutes":120}'
```

The response includes webhook_url (https://api.fromenance.com/v1/hooks/esp/src_... ) and secret , shown once. config.api_key is optional: a Resend API key with read access lets Fromenance fetch the rendered body of each sent email (GET https://api.resend.com/emails/{id} ) so the registration gets a fingerprint. It is encrypted at rest with your tenant key.

## 2. Configure the webhook at Resend

- Resend dashboard, Webhooks , Add webhook .

- Endpoint URL: the webhook_url from step 1.

- Events: email.sent and email.delivered . Other event types are ignored.

- Save, then copy the Signing secret Resend shows (whsec_... ) and paste it into the source in the admin app (Sources, the source, Signing secret ). The secret Fromenance generated at creation is replaced by Resend’s, because Resend signs with its own key.

## What Resend sends and how it is verified

Resend signs webhooks through Svix. Each request carries svix-id , svix-timestamp , and svix-signature ; Fromenance verifies the HMAC-SHA256 over id.timestamp.body with the signing secret and rejects requests outside the timestamp tolerance. A failed check returns 401 and increments signature_failures on the source.

From each event Fromenance reads, per recipient in data.to :

| Registration field
| Resend field
|

| message_id
| data.email_id
|

| recipient (hashed immediately, never stored)
| each address in data.to
|

| sent_at
| data.created_at
|

| from_address
| data.from
|

| subject fingerprint
| data.subject
|

| verify code
| tag fromenance_code , or the X-Fromenance-Code header when Resend echoes headers
|

| template_id , campaign_id
| tags template_id , campaign_id
|

| content fingerprint
| fetched through the Messages API when config.api_key is set
|

## 3. Place the code

The adapter does not require a reservation: a send event without a code registers the message and issues a code. But a code that is not in the footer cannot help the customer, so for Resend you have two options.

Option A, reserve before send (recommended). Call POST /v1/communications/reserve with the recipient, place the code in the template, and send with the tag so the event completes the reservation:

```ts
await resend.emails.send({
  from: "alerts@jtmerlin.example",
  to: [customer.email],
  subject: "A new device signed in to your account",
  html: render(template, { fromenance_code: reserved.verify_code }),
  tags: [
    { name: "fromenance_code", value: reserved.verify_code },
    { name: "template_id", value: "new-device-alert-v2" },
  ],
});
```

Option B, register from your code and skip the webhook. If you already render the email in your code, one POST /v1/communications at send time gives you the code before send with no webhook at all (Integration guide ). Use the webhook when sends happen in systems you do not control.

## 4. Confirm

- Sources, the source, Send test event (POST /v1/sending-sources/{id}/test-event ) runs a synthetic sent event through the adapter and creates a sandbox registration.

- Send one real message. Within seconds health.last_event_at updates and registered_today increments.

## Source health

| Field
| Meaning
|

| last_event_at , events_last_hour
| Webhook traffic
|

| signature_failures
| Requests rejected for a bad Svix signature. A non zero and rising count means the secret in Fromenance does not match Resend
|

| reserved , completed , reserve_to_complete_ratio
| Reservations versus sends that completed them
|

| coverage_gaps
| Reservations that expired without a send event
|

| silent
| No event within silence_alert_minutes (default 1440) while the source is active. Raises an alert in the admin app
|

Rotate the secret with POST /v1/sending-sources/{id}/rotate-secret if it leaks; Resend’s own signing secret is replaced from the Resend dashboard.

---

Page: SendGrid
URL: https://docs.fromenance.com/registering/sendgrid

# SendGrid

Fromenance is a communication provenance platform, and the SendGrid adapter turns Event Webhook processed and delivered events into registrations. SendGrid does not expose the rendered body, so the adapter uses the reserve flow: you fetch a code before the send, place it through a substitution tag, and the event completes the registration.

By the end you will have a SendGrid source, the Signed Event Webhook pointed at it, the reserve call in your send path, and completions showing on the source’s health panel.

## 1. Create the source

Because SendGrid signs with a public key rather than a shared secret, paste SendGrid’s Verification Key into the source when you create it. Get it first (step 2) or create the source now and update config later.

```bash
curl -X POST https://api.fromenance.com/v1/sending-sources \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"SendGrid alerts","kind":"sendgrid","config":{"verification_key":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..."},"expected_daily_volume":50000}'
```

The response includes webhook_url (https://api.fromenance.com/v1/hooks/esp/src_... ). No shared secret is returned for SendGrid sources; the verification key is the credential. In the admin app the field is labelled Verification key on the Add source form.

## 2. Configure the Event Webhook at SendGrid

- SendGrid, Settings , Mail Settings , Event Webhook , Create new webhook (or edit the existing one).

- HTTP Post URL : the webhook_url from step 1.

- Actions to be posted : tick Processed and Delivered . Other events are ignored; ticking them costs nothing but traffic.

- Save, then open Signature verification , enable Signed Event Webhook , and copy the Verification Key (a base64 ECDSA P-256 public key). Put it in the source’s config.verification_key if you did not at creation:

```bash
curl -X PATCH https://api.fromenance.com/v1/sending-sources/src_... \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"config":{"verification_key":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..."}}'
```

- Use Test Your Integration ; a 200 confirms the URL is reachable. Signature failures show as 401 and count on the source.

## What SendGrid sends and how it is verified

SendGrid signs each POST with ECDSA over timestamp + body and sends X-Twilio-Email-Event-Webhook-Signature (DER, base64) and X-Twilio-Email-Event-Webhook-Timestamp . Fromenance verifies the signature against your verification key with SHA-256. A request without both headers, or that fails verification, is rejected with 401 and signature_failures increments.

From each processed or delivered event:

| Registration field
| SendGrid field
|

| message_id
| sg_message_id up to .filter , or smtp-id
|

| recipient (hashed immediately, never stored)
| email
|

| sent_at
| timestamp (Unix seconds)
|

| verify code
| fromenance_code (from custom_args )
|

| template_id
| template_id from custom_args , else the first category
|

| campaign_id
| campaign_id from custom_args
|

| content fingerprint
| not available from SendGrid; add it later with PATCH /v1/communications/{id} if you render the body yourself
|

## 3. Reserve, inject, send

Before each send, reserve a code for the recipient and pass it both in the footer and in custom_args so the event can complete the reservation:

```ts
import { recipientHash } from "./recipient-hash.ts"; // from the Integration guide, step 5
import sgMail from "@sendgrid/mail";

// One HTTPS call, no dependencies. See the Integration guide, step 7.
async function reserve(body: Record<string, unknown>) {
  const res = await fetch("https://api.fromenance.com/v1/communications/reserve", {
    method: "POST",
    headers: { authorization: `Bearer ${process.env.FROMENANCE_API_KEY}`, "content-type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`reserve failed: ${res.status}`);
  return (await res.json()) as { id: string; verify_code: string; expires_at: string };
}

const reserved = await reserve({
  recipient_hash: await recipientHash(customer.email, process.env.FROMENANCE_TENANT_SECRET!),
  template_id: "fraud-alert-v3",
  provider: "sendgrid",
});

await sgMail.send({
  to: customer.email,
  from: "alerts@jtmerlin.example",
  templateId: "d-...",
  dynamicTemplateData: { first_name: customer.firstName, fromenance_code: reserved.verify_code },
  customArgs: { fromenance_code: reserved.verify_code, template_id: "fraud-alert-v3" },
});
```

In the template footer, use the substitution tag that matches your template type: {{fromenance_code}} in dynamic (Handlebars) templates, -fromenance_code- in legacy templates with substitutions . The code must appear twice:

```text
Not sure this email is from JT Merlin Bank? Forward it to verify@jtmerlin.example
or enter code {{fromenance_code}} at jtmerlin.example/verify. Reference: {{fromenance_code}}
```

A processed event with a fromenance_code that matches a reservation completes it with the message id and time. An event without a code still registers the message (with a code you never placed), so matching for that message relies on the recipient plus fingerprint, which SendGrid cannot supply. Always reserve.

## 4. Confirm

- Send test event on the source runs a synthetic event through the adapter.

- Send one real message. health.completed increments and reserve_to_complete_ratio approaches 1.

## Source health

silent is raised when no event arrives within silence_alert_minutes (default 1440). A falling reserve_to_complete_ratio means sends are reserving codes but the webhook is not delivering: check the Event Webhook status page in SendGrid. coverage_gaps counts reservations that expired after 24 hours without an event. Rotate the source with a new verification key by updating config ; the rotate-secret call is not needed for SendGrid.

---

Page: Amazon SES
URL: https://docs.fromenance.com/registering/amazon-ses

# Amazon SES

Fromenance is a communication provenance platform, and the Amazon SES adapter turns Send and Delivery events, delivered through an SNS HTTPS subscription, into registrations. SES does not expose the rendered body, so the adapter uses the reserve flow: you fetch a code before the send, place it in the template, and send it as the message tag fromenance_code .

By the end you will have an SES source, a configuration set publishing Send and Delivery to an SNS topic subscribed to the source’s webhook URL, the reserve call in your send path, and completions showing on the source’s health panel.

## 1. Create the source

```bash
curl -X POST https://api.fromenance.com/v1/sending-sources \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"SES notifications","kind":"ses","expected_daily_volume":100000}'
```

The response includes webhook_url (https://api.fromenance.com/v1/hooks/esp/src_... ). The secret returned is not used by SNS, which signs with Amazon’s certificate; keep it anyway, since the URL is the only thing that binds the topic to your source.

## 2. Publish events to SNS

- SES console, Configuration sets , create one (for example fromenance ) or open the one you send with.

- Event destinations , Add destination . Event types: Send and Delivery . Destination: Amazon SNS , choose or create a topic.

- SNS console, that topic, Create subscription . Protocol HTTPS , endpoint the webhook_url from step 1. Leave Enable raw message delivery off; the adapter expects the SNS JSON envelope.

- Fromenance confirms the subscription automatically by fetching the SubscribeURL from the SubscriptionConfirmation message, provided its host ends in amazonaws.com . The subscription shows as Confirmed within a few seconds.

- Send every message with the configuration set: the ConfigurationSetName parameter, or the X-SES-CONFIGURATION-SET header for raw sends.

## What SNS sends and how it is verified

Every SNS message carries SignatureVersion (1 for SHA1withRSA, 2 for SHA256withRSA), Signature , and SigningCertURL . Fromenance fetches the certificate only from https://sns.<region>.amazonaws.com , verifies the signature over the canonical string of the message, and rejects anything else with 401 . Messages of type Notification whose SES eventType is Send or Delivery become registrations; everything else is acknowledged and ignored.

From each event, per address in mail.destination :

| Registration field
| SES field
|

| message_id
| mail.messageId
|

| recipient (hashed immediately, never stored)
| each address in mail.destination
|

| sent_at
| mail.timestamp
|

| from_address
| mail.source
|

| subject fingerprint
| mail.commonHeaders.subject
|

| verify code
| message tag fromenance_code , else the X-Fromenance-Code header
|

| template_id
| tag template_id , else the ses:configuration-set tag
|

| campaign_id
| tag campaign_id
|

| content fingerprint
| not available from SES; add it later with PATCH /v1/communications/{id} if you render the body yourself
|

## 3. Reserve, tag, send

```ts
import { SESv2Client, SendEmailCommand } from "@aws-sdk/client-sesv2";
import { recipientHash } from "./recipient-hash.ts"; // from the Integration guide, step 5

// One HTTPS call, no dependencies. See the Integration guide, step 7.
async function reserve(body: Record<string, unknown>) {
  const res = await fetch("https://api.fromenance.com/v1/communications/reserve", {
    method: "POST",
    headers: { authorization: `Bearer ${process.env.FROMENANCE_API_KEY}`, "content-type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`reserve failed: ${res.status}`);
  return (await res.json()) as { id: string; verify_code: string; expires_at: string };
}
const ses = new SESv2Client({});

const reserved = await reserve({
  recipient_hash: await recipientHash(customer.email, process.env.FROMENANCE_TENANT_SECRET!),
  template_id: "statement-ready-v4",
  provider: "ses",
});

await ses.send(
  new SendEmailCommand({
    FromEmailAddress: "statements@jtmerlin.example",
    Destination: { ToAddresses: [customer.email] },
    ConfigurationSetName: "fromenance",
    EmailTags: [
      { Name: "fromenance_code", Value: reserved.verify_code },
      { Name: "template_id", Value: "statement-ready-v4" },
    ],
    Content: {
      Template: {
        TemplateName: "statement-ready-v4",
        TemplateData: JSON.stringify({ first_name: customer.firstName, fromenance_code: reserved.verify_code }),
      },
    },
  }),
);
```

In the SES template footer use {{fromenance_code}} twice. Message tag values are limited to ASCII letters, digits, underscores, and hyphens, which a verify code satisfies.

## 4. Confirm

- Send test event on the source runs a synthetic Send event through the adapter.

- SES console, the configuration set, Send test email with the tag set. Within seconds health.completed increments.

## Source health

silent is raised when no event arrives within silence_alert_minutes . If events_last_hour is zero while you are sending, check the SNS subscription status and CloudWatch delivery failures on the topic. Because SES can publish one Send and one Delivery per message, the second event for the same message and recipient is ignored, not double counted. coverage_gaps counts reservations that expired without an event.

---

Page: Postmark
URL: https://docs.fromenance.com/registering/postmark

# Postmark

Fromenance is a communication provenance platform, and the Postmark adapter turns Delivery webhook events into registrations. With a server token on the source, Fromenance fetches the rendered body through Postmark’s Messages API, so registrations carry a full content fingerprint.

By the end you will have a Postmark source, the Delivery webhook configured with basic auth, the code carried as metadata, and events showing on the source’s health panel.

## 1. Create the source

```bash
curl -X POST https://api.fromenance.com/v1/sending-sources \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Postmark transactional","kind":"postmark","config":{"server_token":"..."},"expected_daily_volume":8000}'
```

The response includes webhook_url and secret . For Postmark the secret is a basic auth pair in the form fromenance:<password> , shown once. config.server_token is optional: a Postmark server API token lets Fromenance call GET /messages/outbound/{id}/details to fetch HtmlBody and TextBody for fingerprinting. It is encrypted at rest.

## 2. Configure the webhook at Postmark

- Postmark, your Server , the Message Stream you send from, Webhooks , Add webhook .

- Webhook URL : the webhook_url from step 1.

- HTTP Auth : username fromenance , password the part after the colon in the secret.

- Events : tick Delivery . Other record types are acknowledged and ignored.

- Check sends a test payload; Postmark must show a 200 .

## What Postmark sends and how it is verified

Each webhook POST carries Authorization: Basic <base64 user:pass> . Fromenance decodes it and compares it with the source secret in constant time; a mismatch returns 401 and increments signature_failures .

From each Delivery record:

| Registration field
| Postmark field
|

| message_id
| MessageID
|

| recipient (hashed immediately, never stored)
| Recipient
|

| sent_at
| DeliveredAt , else ReceivedAt
|

| verify code
| Metadata.fromenance_code
|

| template_id
| Metadata.template_id , else Tag
|

| campaign_id
| Metadata.campaign_id
|

| content fingerprint
| fetched through the Messages API when config.server_token is set
|

## 3. Place the code

Reserve a code before each send and pass it as metadata and in the template model:

```ts
import { ServerClient } from "postmark";
import { recipientHash } from "./recipient-hash.ts"; // from the Integration guide, step 5

// One HTTPS call, no dependencies. See the Integration guide, step 7.
async function reserve(body: Record<string, unknown>) {
  const res = await fetch("https://api.fromenance.com/v1/communications/reserve", {
    method: "POST",
    headers: { authorization: `Bearer ${process.env.FROMENANCE_API_KEY}`, "content-type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`reserve failed: ${res.status}`);
  return (await res.json()) as { id: string; verify_code: string; expires_at: string };
}
const postmark = new ServerClient(process.env.POSTMARK_SERVER_TOKEN!);

const reserved = await reserve({
  recipient_hash: await recipientHash(customer.email, process.env.FROMENANCE_TENANT_SECRET!),
  template_id: "password-changed-v1",
  provider: "postmark",
});

await postmark.sendEmailWithTemplate({
  From: "alerts@jtmerlin.example",
  To: customer.email,
  TemplateAlias: "password-changed-v1",
  TemplateModel: { first_name: customer.firstName, fromenance_code: reserved.verify_code },
  Tag: "password-changed-v1",
  Metadata: { fromenance_code: reserved.verify_code, template_id: "password-changed-v1" },
});
```

In the Postmark template footer use {{fromenance_code}} twice. Because the body is fetched, a Delivery event without a code still produces a registration with a fingerprint, and forwards of that message can match by recipient plus fingerprint; the customer just has no code to type on the verify page. Reserve so the footer carries one.

## 4. Confirm

- Send test event on the source runs a synthetic Delivery event through the adapter.

- Send one real message. health.registered_today or health.completed increments within seconds of delivery.

## Source health

silent is raised when no event arrives within silence_alert_minutes . A rising signature_failures means the basic auth pair in Postmark no longer matches; POST /v1/sending-sources/{id}/rotate-secret issues a new fromenance:<password> pair to paste into Postmark. A registration without a fingerprint while server_token is set means the token lacks access to the stream; Postmark returns 403 on the details call and Fromenance registers without the body.

---

Page: Mailgun
URL: https://docs.fromenance.com/registering/mailgun

# Mailgun

Fromenance is a communication provenance platform, and the Mailgun adapter turns delivered and accepted webhook events into registrations. Mailgun does not return the rendered body on events, so the adapter uses the reserve flow: you fetch a code before the send and pass it as the user variable v:fromenance_code .

By the end you will have a Mailgun source, the webhook configured for your sending domain, the signing key on the source, the reserve call in your send path, and events showing on the source’s health panel.

## 1. Create the source

```bash
curl -X POST https://api.fromenance.com/v1/sending-sources \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Mailgun alerts","kind":"mailgun","expected_daily_volume":30000}'
```

The response includes webhook_url and a secret . Mailgun signs with its own HTTP webhook signing key , so paste that key into the source (Sources, the source, Signing key ); the minted secret is replaced.

## 2. Configure the webhook at Mailgun

- Mailgun, Sending , your domain, Webhooks .

- Copy the HTTP webhook signing key shown at the top and put it on the source.

- Add webhook , event type Delivered Messages , URL the webhook_url from step 1. Optionally add Accepted as well; both are treated as sends and the second event for the same message and recipient is ignored.

- Save. Mailgun sends a test on save; a 200 confirms the URL.

## What Mailgun sends and how it is verified

Each POST carries a signature object with timestamp , token , and signature . Fromenance computes HMAC-SHA256 over timestamp + token with the signing key, compares in constant time, and rejects timestamps more than 5 minutes from now. A failure returns 401 and increments signature_failures .

From event-data of each delivered or accepted event:

| Registration field
| Mailgun field
|

| message_id
| message.headers.message-id , wrapped in angle brackets
|

| recipient (hashed immediately, never stored)
| recipient
|

| sent_at
| timestamp
|

| from_address
| message.headers.from
|

| subject fingerprint
| message.headers.subject
|

| verify code
| user-variables.fromenance_code
|

| template_id
| user-variables.template_id , else the first tag
|

| campaign_id
| user-variables.campaign_id
|

| content fingerprint
| not available from Mailgun; add it later with PATCH /v1/communications/{id} if you render the body yourself
|

## 3. Reserve, set the variable, send

```ts
import FormData from "form-data";
import Mailgun from "mailgun.js";
import { recipientHash } from "./recipient-hash.ts"; // from the Integration guide, step 5

// One HTTPS call, no dependencies. See the Integration guide, step 7.
async function reserve(body: Record<string, unknown>) {
  const res = await fetch("https://api.fromenance.com/v1/communications/reserve", {
    method: "POST",
    headers: { authorization: `Bearer ${process.env.FROMENANCE_API_KEY}`, "content-type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`reserve failed: ${res.status}`);
  return (await res.json()) as { id: string; verify_code: string; expires_at: string };
}
const mg = new Mailgun(FormData).client({ username: "api", key: process.env.MAILGUN_API_KEY! });

const reserved = await reserve({
  recipient_hash: await recipientHash(customer.email, process.env.FROMENANCE_TENANT_SECRET!),
  template_id: "card-declined-v2",
  provider: "mailgun",
});

await mg.messages.create("mg.jtmerlin.example", {
  from: "JT Merlin Bank <alerts@jtmerlin.example>",
  to: [customer.email],
  template: "card-declined-v2",
  "h:X-Mailgun-Variables": JSON.stringify({ first_name: customer.firstName, fromenance_code: reserved.verify_code }),
  "v:fromenance_code": reserved.verify_code,
  "v:template_id": "card-declined-v2",
});
```

In a Mailgun template use {{fromenance_code}} twice in the footer. For batch sends with recipient variables, use %recipient.fromenance_code% and supply a per recipient code from a batch of reservations. Variables set with the v: prefix are echoed back in user-variables on the event, which is how the reservation is completed.

## 4. Confirm

- Send test event on the source runs a synthetic delivered event through the adapter.

- Send one real message. health.completed increments within seconds of delivery.

## Source health

silent is raised when no event arrives within silence_alert_minutes . Mailgun retries failed webhook deliveries for 8 hours; a burst of signature_failures after rotating the signing key in Mailgun means the source still holds the old key. coverage_gaps counts reservations that expired without an event.

---

Page: Salesforce Marketing Cloud
URL: https://docs.fromenance.com/registering/salesforce-marketing-cloud

# Salesforce Marketing Cloud

Fromenance is a communication provenance platform, and the Salesforce Marketing Cloud adapter turns Event Notification Service (ENS) EmailSent and EmailDelivered events into registrations. Marketing Cloud does not expose the rendered body, so the adapter uses the reserve flow: a pre send call reserves a code, AMPscript places it in the footer, and the event carries it back.

By the end you will have an SFMC source, an ENS callback and subscription pointed at it, the reserve call wired into the send, and events showing on the source’s health panel. This is the longest adapter setup; plan for a Marketing Cloud admin and an email developer.

## 1. Create the source

```bash
curl -X POST https://api.fromenance.com/v1/sending-sources \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Marketing Cloud journeys","kind":"sfmc","expected_daily_volume":250000,"silence_alert_minutes":360}'
```

The response includes webhook_url and a secret . Use the secret as the ENS callback signature key in step 2; the callback signs with the key you configure, so the two match by construction.

## 2. Create the ENS callback and subscription

ENS is configured through the Marketing Cloud REST API (an installed package with the Event Notification Callbacks and Subscriptions scopes).

- Create the callback with the source’s webhook_url and the source secret as signatureKey :

```http
POST https://{subdomain}.rest.marketingcloudapis.com/platform/v1/ens-callbacks
Authorization: Bearer <SFMC access token>
Content-Type: application/json

[{ "callbackName": "fromenance", "url": "https://api.fromenance.com/v1/hooks/esp/src_...", "signatureKey": "whsec_..." }]
```

- Marketing Cloud sends a verification request to the URL containing a verificationKey . Fromenance answers 200 to that request. Complete verification by posting the key back:

```http
POST https://{subdomain}.rest.marketingcloudapis.com/platform/v1/ens-verify
{ "callbackId": "<callbackId>", "verificationKey": "<key from the verification request>" }
```

- Subscribe the callback to send events for the sends you register:

```http
POST https://{subdomain}.rest.marketingcloudapis.com/platform/v1/ens-subscriptions
[{
  "callbackId": "<callbackId>",
  "subscriptionName": "fromenance-sends",
  "eventCategoryTypes": ["TransactionalSendEvents.EmailSent", "TransactionalSendEvents.EmailDelivered", "EngagementEvents.EmailSent"],
  "filters": [],
  "status": "Active"
}]
```

## What ENS sends and how it is verified

ENS posts a JSON array of events with the header x-sfmc-ens-signature , a base64 HMAC-SHA256 of the raw body keyed with the signature key. Fromenance recomputes it with the source secret and compares in constant time; a mismatch returns 401 and increments signature_failures . Events whose eventCategoryType does not contain EmailSent or EmailDelivered are ignored.

From each event:

| Registration field
| ENS field
|

| message_id
| composite.messageKey , else composite.sendId , else eid
|

| recipient (hashed immediately, never stored)
| info.emailAddress , else info.to , else composite.emailAddress
|

| sent_at
| info.sendTime , else timestampUTC
|

| verify code
| info.fromenance_code
|

| template_id
| info.templateId , else info.emailName , else composite.jobId
|

| campaign_id
| composite.jobId
|

| content fingerprint
| not available from Marketing Cloud
|

The code reaches the event through info , which carries the attributes of the send. Populate a data extension field named fromenance_code on the sendable data extension or the transactional send definition’s attributes, so it is present on the event.

## 3. Reserve before render and place the code with AMPscript

For journey and triggered sends, reserve the code when the contact enters the send step and write it to the data extension, then output it in the email:

```text
%%[
  /* fromenance_code was written to the sendable DE by the reserve call before this send */
  SET @fromenance_code = AttributeValue("fromenance_code")
]%%
Not sure this email is from JT Merlin Bank? Forward it to verify@jtmerlin.example
or enter code %%=v(@fromenance_code)=%% at jtmerlin.example/verify. Reference: %%=v(@fromenance_code)=%%
```

For transactional messaging API sends, reserve in your application and pass the code as an attribute:

```ts
// POST /v1/communications/reserve with the recipient hash; see the Integration guide, steps 5 and 7.
const reserved = await reserve({ recipient_hash: await recipientHash(customer.email, tenantSecret), template_id: "alert-v1", provider: "sfmc" });
await fetch(`https://${subdomain}.rest.marketingcloudapis.com/messaging/v1/email/messages/${messageKey}`, {
  method: "POST",
  headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
  body: JSON.stringify({
    definitionKey: "alert-v1",
    recipient: { contactKey: customer.id, to: customer.email, attributes: { fromenance_code: reserved.verify_code } },
  }),
});
```

Where reservation must happen inside Marketing Cloud (batch journeys with no application in the loop), a Script Activity in Automation Studio can call POST /v1/communications/reserve per row with SSJS HTTP.Post and write the code into the data extension before the send. Because the recipient address is known at that point, hash it with your tenant secret inside the script (Platform.Function.SHA256 does not do HMAC; use the recipient_hash free reservation and let the send event bind the recipient).

## 4. Confirm

- Send test event on the source runs a synthetic EmailSent event through the adapter.

- Trigger one send. health.completed increments once the EmailSent event arrives, typically within a minute.

## Source health

Set silence_alert_minutes to match your send cadence; a journey that sends nightly should not alert every hour. signature_failures after rotating the source secret means the callback still has the old signatureKey ; update it with PUT /platform/v1/ens-callbacks/{id} . coverage_gaps counts reservations that expired without an event, which on Marketing Cloud usually means a subscription filter excluded the send.

---

Page: Braze
URL: https://docs.fromenance.com/registering/braze

# Braze

Fromenance is a communication provenance platform, and the Braze adapter turns Currents users.messages.email.Send and users.messages.email.Delivery events into registrations. Braze does not expose the rendered body, so the adapter uses the reserve flow: Connected Content reserves a code during rendering, stores it on the user, and Liquid places it in the footer.

By the end you will have a Braze source, a Currents connector or webhook posting email events to it with the bearer token, the Connected Content call in your template, and events showing on the source’s health panel.

## 1. Create the source

```bash
curl -X POST https://api.fromenance.com/v1/sending-sources \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Braze campaigns","kind":"braze","expected_daily_volume":120000}'
```

The response includes webhook_url and a secret . Braze authenticates outbound HTTP with a header you configure, so set Authorization: Bearer <secret> on the connector.

## 2. Send email events to the source

Currents (HTTP connector)

- Braze, Partner Integrations , Data Export , Currents , Create new Current , HTTP .

- Endpoint URL: the webhook_url from step 1.

- Headers: Authorization with value Bearer whsec_... (the source secret).

- Events: Email Send and Email Delivery . Other events are ignored.

- Save. Currents batches events, so expect a delay of up to a few minutes rather than seconds.

Webhook campaign step (when Currents is not on your plan)

Use a webhook message step after the email step that posts the event fields listed below to the webhook_url with the same Authorization header. The body must be one JSON event or { "events": [...] } with event_type set to users.messages.email.Send .

## What Braze sends and how it is verified

Every request must carry Authorization: Bearer <source secret> ; Fromenance compares it in constant time and rejects anything else with 401 , incrementing signature_failures . Bodies may be a single event or { "events": [...] } . Events whose type does not match email.Send or email.Delivery are ignored.

From each event’s properties :

| Registration field
| Braze field
|

| message_id
| dispatch_id , else send_id
|

| recipient (hashed immediately, never stored)
| email_address
|

| sent_at
| time (Unix seconds)
|

| verify code
| fromenance_code
|

| template_id
| message_variation_id
|

| campaign_id
| campaign_id , else canvas_id
|

| content fingerprint
| not available from Braze
|

## 3. Reserve with Connected Content and place the code with Liquid

Call the reserve endpoint from the template with Connected Content, save the code as a custom attribute so the event can carry it, and print it in the footer:

```liquid
{% connected_content https://api.fromenance.com/v1/communications/reserve
   :method post
   :headers {"Authorization": "Bearer {{ 'FROMENANCE_API_KEY' | secret }}", "Content-Type": "application/json"}
   :body {"template_id": "{{campaign.${name}}}", "provider": "braze"}
   :content_type application/json
   :save fromenance %}

Not sure this email is from JT Merlin Bank? Forward it to verify@jtmerlin.example
or enter code {{fromenance.verify_code}} at jtmerlin.example/verify. Reference: {{fromenance.verify_code}}
```

Store the key with Braze’s secret management rather than inline. Because Liquid renders before the recipient is known to Fromenance, the reservation is made without recipient_hash ; the Send event binds the recipient when it completes the reservation. To carry the code on the event, set the custom attribute fromenance_code on the user in the same campaign (a User Update step, or the /users/track API from your side) so it appears in properties.fromenance_code . Where that is not possible, the Send event still registers the message with a fresh code and the customer’s forward matches by recipient plus fingerprint only.

## 4. Confirm

- Send test event on the source runs a synthetic Email Send event through the adapter.

- Send a test message from the campaign to yourself. Because Currents batches, allow a few minutes, then check health.completed .

## Source health

Set silence_alert_minutes above the Currents batching interval and your quietest sending window. reserve_to_complete_ratio well below 1 means Connected Content is reserving but the event does not carry fromenance_code ; check the custom attribute. Rotate the secret with POST /v1/sending-sources/{id}/rotate-secret and update the connector header.

---

Page: Generic webhook
URL: https://docs.fromenance.com/registering/generic-webhook

# Generic webhook

Fromenance is a communication provenance platform, and the generic adapter covers any system that can make an HTTP call after a send: a core banking platform, a print and mail vendor’s notification feed, an internal queue consumer. You post one JSON event per send, signed with the source secret, and Fromenance registers it.

By the end you will have a generic source, a signed POST in your send path, and events showing on the source’s health panel.

## 1. Create the source

```bash
curl -X POST https://api.fromenance.com/v1/sending-sources \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Core banking notices","kind":"generic","expected_daily_volume":5000,"silence_alert_minutes":720}'
```

The response includes webhook_url (https://api.fromenance.com/v1/hooks/esp/src_... ) and secret (whsec_... ), shown once.

## 2. Post send events

Body: one event, or { "events": [ ... ] } .

| Field
| Required
| Notes
|

| message_id
| yes
| Your message id or the RFC 5322 Message-ID
|

| recipient
| yes
| The recipient address. Hashed with your tenant secret on arrival and never stored
|

| sent_at
| no
| ISO 8601; defaults to now
|

| from
| no
| The visible From address
|

| code
| no
| A code you reserved and placed in the footer. Completes the reservation
|

| template_id , campaign_id
| no
| Your identifiers
|

| html , text , subject
| no
| The rendered message. Fingerprinted on arrival and not stored. Include it when you can; it is what lets a forward without a readable code still match
|

Header: X-Fromenance-Signature: sha256=<hex HMAC-SHA256 of the raw request body keyed with the source secret> . Sign the exact bytes you send; re-serializing JSON on either side changes the signature.

Response: { "ok": true, "registered": n, "completed": n, "ignored": n } . ignored counts events for a message and recipient already registered, so redelivery is harmless.

```ts samples/generic-webhook.ts
/**
 * Generic webhook adapter: post a send event to Fromenance from any system that can make an HTTP call.
 * The raw body is signed with HMAC-SHA256 using the source secret and sent as
 *   X-Fromenance-Signature: sha256=<hex>
 *
 * Environment:
 *   FROMENANCE_SOURCE_WEBHOOK_URL  https://api.fromenance.com/v1/hooks/esp/src_... (shown when the source is created)
 *   FROMENANCE_SOURCE_SECRET       whsec_... (shown once when the source is created)
 */
import { createHmac } from "node:crypto";

export interface GenericSendEvent {
  message_id: string;
  recipient: string;
  sent_at?: string;
  from?: string;
  /** A reserved verify code you placed in the footer. Completes the reservation. */
  code?: string;
  template_id?: string;
  campaign_id?: string;
  /** Optional rendered body so Fromenance can fingerprint it. The body is fingerprinted and not stored. */
  html?: string;
  text?: string;
  subject?: string;
}

export function signGenericEvent(secret: string, rawBody: string): string {
  return `sha256=${createHmac("sha256", secret).update(rawBody).digest("hex")}`;
}

export async function postSendEvents(
  webhookUrl: string,
  secret: string,
  events: GenericSendEvent[],
  f: typeof fetch = fetch,
): Promise<{ registered: number; completed: number; ignored: number }> {
  const rawBody = JSON.stringify(events.length === 1 ? events[0] : { events });
  const res = await f(webhookUrl, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-fromenance-signature": signGenericEvent(secret, rawBody),
    },
    body: rawBody,
  });
  if (!res.ok) throw new Error(`hook rejected: ${res.status} ${await res.text()}`);
  return (await res.json()) as { registered: number; completed: number; ignored: number };
}

export async function main(): Promise<void> {
  const url = process.env.FROMENANCE_SOURCE_WEBHOOK_URL;
  const secret = process.env.FROMENANCE_SOURCE_SECRET;
  if (!url || !secret) throw new Error("Set FROMENANCE_SOURCE_WEBHOOK_URL and FROMENANCE_SOURCE_SECRET");
  const result = await postSendEvents(url, secret, [
    {
      message_id: `<${crypto.randomUUID()}@jtmerlin.example>`,
      recipient: "jane.doe@example.com",
      sent_at: new Date().toISOString(),
      from: "alerts@jtmerlin.example",
      template_id: "fraud-alert-v3",
      html: "<p>We noticed a sign in from a new device.</p>",
    },
  ]);
  console.log(result);
}
```

Equivalent with curl:

```bash
BODY='{"message_id":"<n-1042@jtmerlin.example>","recipient":"jane.doe@example.com","sent_at":"2026-09-24T14:42:10Z","from":"notices@jtmerlin.example","template_id":"rate-change-v1"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$FROMENANCE_SOURCE_SECRET" | awk '{print $NF}')
curl -X POST "$FROMENANCE_SOURCE_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-Fromenance-Signature: sha256=$SIG" \
  --data "$BODY"
```

## Verification

Fromenance recomputes the HMAC over the raw body with the source secret and compares in constant time. A missing or wrong signature returns 401 and increments signature_failures on the source. There is no timestamp in this scheme; if replay of a captured event matters in your environment, include sent_at and treat the ignored count as the dedupe signal, or register from your own code with POST /v1/communications instead, which authenticates with your API key.

## Reserve flow

When the footer must carry the code before the send exists, reserve first and pass the code in the event:

- POST /v1/communications/reserve with recipient_hash and template_id , get verify_code .

- Render the footer with the code and send.

- Post the event with code set. The reservation is completed with the message id and time; if you include html or text , the fingerprint is added too.

If you render the message in code you control, one POST /v1/communications at send time does all of this without a source (Integration guide ). The generic adapter is for the systems where that is not possible.

## Source health

silent is raised when no event arrives within silence_alert_minutes (default 1440); set it to a value longer than your quietest sending window. coverage_gaps counts reservations that expired after 24 hours without an event. Rotate the secret with POST /v1/sending-sources/{id}/rotate-secret ; the old secret stops working immediately.

---

Page: Verify page
URL: https://docs.fromenance.com/verify-page

# Verify page

Fromenance is a communication provenance platform, and the verify page is the second way a customer can ask “did you send this?”: they paste the message, upload the .eml , upload a screenshot, or type the reference code on a page on your domain and the verdict renders on the page. It needs no mailbox, no reply identity, and no account.

By the end you will have a site key bound to your page’s origin, the widget on yourdomain.com/verify in your branding, and a verdict rendering on the page.

## Where the page lives

The page is yours: jtmerlin.example/verify or any URL on an origin you allow. Fromenance serves only the script and an optional iframe document from cdn.fromenance.com ; there is no hosted verify page on fromenance.com, and the customer never sees the Fromenance name. The widget posts to api.fromenance.com/v1/public/submit with your site key and renders the response in your branding.

## 1. Create a site key

Admin app: Verify page, New site key , name it, and add the allowed origins. Or:

```bash
curl -X POST https://api.fromenance.com/v1/site-keys \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Public verify page","allowed_origins":["https://jtmerlin.example","https://www.jtmerlin.example"],"normal_rate_per_minute":60}'
```

| Field
| Notes
|

| public_key
| sk_pub_... . Public by design; it is bound to the origins below, so it is useless elsewhere
|

| allowed_origins
| Up to 20 full origins (https://host ). Requests whose Origin is not in the list are rejected
|

| normal_rate_per_minute
| 5 to 6,000, default 60. Above this rate the key requires a Turnstile token (see below)
|

| turnstile_required
| true requires Turnstile on every submission
|

| theme
| Free form key value pairs used by the admin app preview
|

The response includes embed.script and embed.iframe , ready to paste, and the admin app shows a live preview of the widget with your name, logo, and accent colour from Settings, Branding.

## 2. Embed the widget

Script tag (recommended)

```html
<div id="fromenance-verify"></div>
<script
  src="https://cdn.fromenance.com/verify.js"
  data-site-key="sk_pub_..."
  data-target="#fromenance-verify"
  data-institution="JT Merlin Bank"
  data-theme="auto"
  async
></script>
```

Attributes:

| Attribute
| Notes
|

| data-site-key
| Required
|

| data-target
| CSS selector of the container; a div is inserted before the script when omitted
|

| data-institution
| The name shown in “Did this message come from JT Merlin Bank?”
|

| data-theme
| light , dark , or auto (follows the visitor’s system setting)
|

| data-accent
| Button and link colour, for example #0f4c81 . The verdict card also picks up the accent set in Settings, Branding
|

| data-turnstile
| Your Cloudflare Turnstile site key, needed when the key is or can become Turnstile gated
|

| data-api
| Only for staging; defaults to https://api.fromenance.com
|

The script also exposes window.Fromenance.mount({ siteKey, target, institutionName, theme, accent, turnstileSiteKey, onVerdict }) for single page applications, and window.Fromenance.version .

Iframe

```html
<iframe
  src="https://cdn.fromenance.com/embed.html?key=sk_pub_...&name=JT Merlin%20Bank&theme=auto"
  title="Verify a message"
  style="width:100%;min-height:520px;border:0"
></iframe>
```

Query parameters mirror the data attributes: key , name , theme , accent , turnstile , api . The iframe posts two messages to the parent window: { type: "fromenance:height", height } whenever its content height changes, so you can resize it, and { type: "fromenance:verdict", verdict } after each answer. The allowed origin check applies to the page that embeds the iframe, so add your site’s origin to the site key, not cdn.fromenance.com .

## What the customer sees

A message textarea, an optional reference code field, an optional field for the address that received the message (recommended, since the recipient is half of the strongest match), and file inputs for an .eml or a screenshot (PNG, JPEG, WebP, up to 6 MB). Text and .eml answer in under three seconds; screenshots show “Reading the screenshot” while OCR runs and answer within about fifteen seconds.

The verdict card carries your logo, the outcome label (Verified, Not verified, Known fraud), the locked verdict text, a next step that includes your fraud contact, and a link to your support URL. Outcomes use the same three colours as the admin app and nothing else in the widget uses them.

## Handling the verdict on the page

Pass onVerdict to mount() or listen for the iframe message to record analytics or route the customer:

```js
window.Fromenance.mount({
  siteKey: "sk_pub_...",
  target: document.querySelector("#fromenance-verify"),
  institutionName: "JT Merlin Bank",
  onVerdict: (v) => {
    analytics.track("verify_result", { outcome: v.outcome, rule: v.rule, submission: v.submission_id });
    if (v.outcome === "known_fraud") location.assign("/security/report-fraud");
  },
});
```

The verdict object is the same one the verify page API returns.

## Rate limits and Turnstile

- 60 submissions per minute per IP address and 600 per minute per site key. Over the limit the API answers 429 with Retry-After and the widget shows “Too many checks right now”.

- When a site key exceeds its normal_rate_per_minute , or has turnstile_required set, the API answers 428 turnstile-required . The widget then loads Cloudflare Turnstile with the site key from data-turnstile , and resubmits with the token once the challenge passes. Without data-turnstile the customer sees “Please complete the security check” and cannot continue, so set it if your page can see bursts.

## Privacy on the web path

The address the customer types is hashed with your tenant secret to compare against registrations, stored encrypted only so the submission can be linked to a later forward, and purged 30 days after the verdict. Uploaded .eml files and screenshots are stored encrypted under your tenant prefix and follow your retention setting. The widget never sets cookies.

---

Page: Verify page API
URL: https://docs.fromenance.com/verify-page/api

# Verify page API

Fromenance is a communication provenance platform, and POST /v1/public/submit is the endpoint the verify widget calls. Use it directly when you build your own verify UI, a mobile app flow, or a chat bot step on your domain.

By the end you will be able to submit each of the four inputs, read every field of the response, poll for a screenshot verdict, and handle the two non 2xx cases.

## Authentication

Two things authenticate a call: the header X-Site-Key: sk_pub_... and the request Origin , which must be in the key’s allowed origins. There is no secret. Browsers set Origin automatically; from a server or a native app set it to one of the allowed origins yourself, and treat the key as public.

## Submit

POST https://api.fromenance.com/v1/public/submit

```json
{
  "text": "…the pasted message, plain text or HTML…",
  "eml_base64": "…base64 of a .eml file…",
  "image_base64": "…base64 of a PNG, JPEG, or WebP…",
  "code": "KX73-PQ9G",
  "email": "jane.doe@example.com",
  "turnstile_token": "…"
}
```

| Field
| Limit
| Notes
|

| text
| 200,000 characters
| The message as the customer pasted it. HTML is fine
|

| eml_base64
| 2,000,000 characters
| A full .eml with headers. Best input: headers let Fromenance check DKIM for your sending domains and read the innermost To
|

| image_base64
| 8,000,000 characters (6 MB decoded)
| A screenshot. OCR runs asynchronously; only the extracted text feeds the deterministic extractors
|

| code
| 12 characters
| A reference code the customer typed. Combined with text or .eml when both are present
|

| email
|
| The address that received the message. Hashed with the tenant secret to match recipient_hash ; the encrypted copy is purged after 30 days
|

| turnstile_token
| 4,000 characters
| Required after a 428
|

At least one of text , eml_base64 , image_base64 , or code is required. When eml_base64 is present it wins over text ; when only image_base64 is present the response is 202 with a poll token.

## Response: PublicVerdict

200 for text, .eml , and code. 202 for screenshots.

```json
{
  "status": "decided",
  "poll_token": null,
  "submission_id": "sub_01J...",
  "outcome": "verified",
  "rule": "code+recipient+content",
  "matched_sent_at": "2026-09-24T14:42:10.000Z",
  "signals": { "code_found": true, "recipient_match": true, "fingerprint_distance": 2 },
  "display": {
    "institution_name": "JT Merlin Bank",
    "logo_url": "https://jtmerlin.example/logo.png",
    "accent": "#0f4c81",
    "fraud_contact": "fraud@jtmerlin.example",
    "support_url": "https://jtmerlin.example/security",
    "outcome_label": "Verified",
    "verdict_text": "Verified: this message matches a communication we registered and sent to you on September 24, 2026 at 2:42 PM UTC.",
    "next_step": "You can act on it. If anything still looks wrong, contact us at fraud@jtmerlin.example."
  }
}
```

| Field
| Notes
|

| status
| decided or pending
|

| poll_token
| Set while pending ; pass it to the verdict endpoint
|

| submission_id
| sub_... , the same id the admin app shows
|

| outcome
| verified , not_verified , known_fraud , or null while pending
|

| rule
| The matching rule, see Concepts
|

| matched_sent_at
| When the matched registration was sent, on Verified
|

| signals
| code_found , recipient_match (null when no address was given), fingerprint_distance (null when no body on either side)
|

| display
| Everything needed to render the answer in your branding. verdict_text is the locked block and next_step already contains your fraud contact
|

Repeat submissions of the same message by the same customer return the same verdict and increment the count on the existing submission rather than creating a new one.

## Poll for a screenshot

GET https://api.fromenance.com/v1/public/verdict/{poll_token} with the same X-Site-Key and Origin . Returns the same shape; status becomes decided once OCR and matching finish, usually within 15 seconds. If the image could not be read the endpoint answers 502 upstream with the detail “We could not read that screenshot. Paste the message text instead.” The widget polls every 1.5 seconds for up to 60 seconds.

## Errors

| Status
| Type
| Meaning
|

| 400 bad-request
|
| No input, or an image that is not PNG, JPEG, WebP, or GIF
|

| 401 unauthorized
|
| Missing or revoked site key, or an Origin not on the allow list
|

| 413 payload-too-large
|
| Screenshot over 6 MB
|

| 428 turnstile-required
|
| The key is over its normal rate or has Turnstile required. Render Cloudflare Turnstile with your Turnstile site key and resend with turnstile_token
|

| 429 rate-limited
|
| 60 per minute per IP or 600 per minute per site key. Retry-After is 60 seconds for the IP limit and 10 for the key limit
|

Errors are RFC 9457 problem documents; see Errors .

## Sample

```ts samples/public-submit.ts
/**
 * Call the public verify API directly, the same way the embeddable widget does.
 * Authenticated by the site key (sk_pub_...) and the page origin. No secret is involved.
 *
 * Environment:
 *   FROMENANCE_SITE_KEY    a site key whose allowed origins include the Origin you send
 *   FROMENANCE_ORIGIN      the page origin the site key allows, for example https://jtmerlin.example
 *   FROMENANCE_API_ORIGIN  optional, defaults to https://api.fromenance.com
 */

export interface PublicVerdict {
  status: "decided" | "pending";
  poll_token: string | null;
  submission_id: string;
  outcome: "verified" | "not_verified" | "known_fraud" | null;
  rule: string | null;
  matched_sent_at: string | null;
  signals: {
    code_found: boolean;
    recipient_match: boolean | null;
    fingerprint_distance: number | null;
  } | null;
  display: {
    institution_name: string;
    logo_url: string | null;
    accent: string | null;
    fraud_contact: string | null;
    support_url: string | null;
    outcome_label: string;
    verdict_text: string;
    next_step: string;
  } | null;
}

export interface SubmitInput {
  text?: string;
  eml_base64?: string;
  image_base64?: string;
  code?: string;
  email?: string;
  turnstile_token?: string;
}

export interface PublicClientOptions {
  siteKey: string;
  origin: string;
  apiOrigin?: string;
  fetch?: typeof fetch;
}

export async function submit(opts: PublicClientOptions, input: SubmitInput): Promise<PublicVerdict> {
  const api = (opts.apiOrigin ?? "https://api.fromenance.com").replace(/\/$/, "");
  const f = opts.fetch ?? fetch;
  const res = await f(`${api}/v1/public/submit`, {
    method: "POST",
    headers: { "content-type": "application/json", "x-site-key": opts.siteKey, origin: opts.origin },
    body: JSON.stringify(input),
  });
  if (res.status === 428)
    throw new Error("Turnstile required: render the challenge and resend with turnstile_token");
  if (res.status === 429)
    throw new Error(`Rate limited, retry after ${res.headers.get("retry-after")} seconds`);
  if (!res.ok) throw new Error(`submit failed: ${res.status} ${await res.text()}`);
  return (await res.json()) as PublicVerdict;
}

/** Screenshots answer 202 with a poll token. Poll until status is decided; the widget polls every 1.5 s for 60 s. */
export async function pollVerdict(opts: PublicClientOptions, token: string): Promise<PublicVerdict> {
  const api = (opts.apiOrigin ?? "https://api.fromenance.com").replace(/\/$/, "");
  const f = opts.fetch ?? fetch;
  for (let i = 0; i < 40; i++) {
    await new Promise((r) => setTimeout(r, 1500));
    const res = await f(`${api}/v1/public/verdict/${token}`, {
      headers: { "x-site-key": opts.siteKey, origin: opts.origin },
    });
    if (!res.ok) throw new Error(`poll failed: ${res.status}`);
    const v = (await res.json()) as PublicVerdict;
    if (v.status === "decided") return v;
  }
  throw new Error("screenshot verdict took longer than 60 seconds");
}

export async function main(): Promise<void> {
  const siteKey = process.env.FROMENANCE_SITE_KEY;
  const origin = process.env.FROMENANCE_ORIGIN;
  if (!siteKey || !origin) throw new Error("Set FROMENANCE_SITE_KEY and FROMENANCE_ORIGIN");
  const opts: PublicClientOptions = { siteKey, origin, apiOrigin: process.env.FROMENANCE_API_ORIGIN };
  const verdict = await submit(opts, {
    text: "Not sure this email is from JT Merlin Bank? Reference: KX73-PQ9G",
    email: "jane.doe@example.com",
  });
  const decided =
    verdict.status === "pending" && verdict.poll_token
      ? await pollVerdict(opts, verdict.poll_token)
      : verdict;
  console.log(decided.display?.outcome_label, decided.rule, decided.display?.verdict_text);
}
```

---

Page: Verifications
URL: https://docs.fromenance.com/verifications

# Verifications

Fromenance is a communication provenance platform, and every customer question ends up as a submission with a verdict. This page is for the analyst who works the Submissions and Indicators screens and for the engineer who pulls the same data through the API.

By the end you will be able to read a submission end to end, override a verdict and know what that changes, and export indicators to your SIEM or takedown vendor.

## Submissions list

Admin app: Submissions. API: GET /v1/submissions (scope read ), cursor paginated with cursor and limit , returning { data, next_cursor } .

| Filter
| Values
|

| outcome
| verified , not_verified , known_fraud (an override counts as its override outcome)
|

| entry
| forward , web , api
|

| replay
| true or false
|

| has_headers
| true when the customer forwarded as an attachment and original headers were present
|

| from , to
| ISO 8601 bounds on received_at
|

Each row carries entry , status , received_at , processed_at , count (how many times the same customer sent the same message), verify_code_found , submitter_hash , recipient_hash_found , headers_present , dkim , arc , trust (dkim:jtmerlin.example on the forward path), from_domain , imitated_template_id (the nearest registered template by fingerprint on Not verified), campaign_id , sandbox , the verdict , and any override . Global search in the top bar finds submissions by code, address hash, domain, or indicator.

## Submission detail

Admin app: click a row to open the detail drawer. API: GET /v1/submissions/{id} adds:

- subject and preview_text : the forwarded message as plain text with every link replaced by its bare domain. The admin app renders this as a preview with links disabled; nothing in it is clickable and no remote content loads.

- headers_summary : the Received chain, DKIM, ARC, SPF, and trust results.

- indicators : each with kind , value , on_fraud_list , and submission_count across your tenant, with one click Add to fraud list .

- raw_available : whether the raw MIME is still within retention. Download raw (GET /v1/submissions/{id}/raw ) is limited to analysts, admins, and owners, and every download is written to the audit log.

## Verdict and signals

The verdict block shows the outcome, the rule that produced it, replay , authoritative , and the matched registration (communication_id , sent_at , template_id ) when there is one. signals explains the rule: code_found , recipient_match , fingerprint_distance , headers_present , dkim . Rules are listed in Concepts .

Two things to look at first on a Not verified: whether code_found is true (a replay or a coverage gap on the matched template) and imitated_template_id (which of your templates the lure copies).

## Overrides

Analysts, admins, and owners can override any verdict. Admin app: Override in the detail drawer with a note. API: POST /v1/submissions/{id}/override with { "outcome": "fraud" | "legitimate", "note": "..." } .

| Override
| What changes
|

| fraud
| The verdict shows Known fraud. Every indicator on the submission is added to the fraud list, and its fingerprint is recorded so later submissions with the same content resolve to Known fraud by fraud_list:fingerprint without a lookup. Overriding a Verified verdict to fraud is treated as an incident and alerts Fromenance operations
|

| legitimate
| The verdict shows Verified. A registration is created retroactively (retro: true ) for the matched recipient and fingerprint, and a coverage gap is flagged on the source that should have registered it
|

Overrides are recorded on the verdict (override.outcome , by , at , note ) and in the audit log. The original outcome and rule are kept.

## Indicators

Admin app: Indicators, grouped by kind with first and last seen, submission count, priority, and fraud list status, with bulk Add to fraud list . API: GET /v1/indicators with filters kind (url , domain , email , phone , ip ), q , on_fraud_list , since , priority (low , normal , high ).

Indicators are extracted from every submission, including Verified ones at low priority, and skip your own domains. Replays raise the priority of their indicators to high. A new indicator on a non verified submission fires the indicator.new webhook .

## Exports

Admin app: Export CSV or Export STIX on Indicators, and CSV on every table. API: GET /v1/indicators/export with the same filters and either Accept: text/csv or Accept: application/stix+json (or ?format=csv|stix ).

- CSV columns: kind,value,first_seen,last_seen,submission_count,priority,on_fraud_list , served as an attachment named fromenance-indicators-<date>.csv .

- STIX 2.1: a bundle of indicator objects with STIX patterns ([url:value = '...'] , [domain-name:value = '...'] , [email-addr:value = '...'] , [ipv4-addr:value = '...'] , [x-phone-number:value = '...'] ), valid_from set to first seen, and labels carrying the kind and fraud list status. Import it into your TIP or SIEM as any other STIX feed.

## Fraud list

Admin app: Fraud list. API: GET /v1/fraud-list , POST /v1/fraud-list with { "items": [ { "kind": "domain", "value": "jtmerlin-secure-login.example", "note": "campaign 2026-09-12" } ] } (up to 500 per call), DELETE /v1/fraud-list/{id} .

Entries come only from analyst action: a manual add, or an override to fraud. Nothing is added automatically from a single submission, because anyone can forward anything through your rule, including attempts to poison the list. Each entry records source (analyst , campaign , feed ), who added it, the note, and the submission it came from. A submission whose extracted indicators hit the list resolves to Known fraud by fraud_list:indicator before any other rule runs.

## Overview numbers

The Overview screen and GET /v1/stats give daily counts of registered, submitted, by outcome, by entry, by source, replays, coverage gaps, code found rate, reply p95, and the top indicators of the week. Coverage per source is registered volume against the expected daily volume you set on the source or the tenant.

---

Page: Webhooks
URL: https://docs.fromenance.com/webhooks

# Webhooks

Fromenance is a communication provenance platform, and outbound webhooks push every verdict, replay, and new indicator to your own systems within seconds. Each delivery is signed with a per endpoint secret, retried with backoff for about a day, and replayable from the admin app.

By the end you will have an endpoint subscribed to the events you need, know the envelope and headers of each delivery, and know how retries and replays behave.

## Events

| Event
| Fires
| data
|

| verdict.created
| Once per verdict, after matching and before the reply is sent
| The verdict object: submission_id , outcome , rule , replay , authoritative , matched (communication_id , sent_at , template_id ), signals , indicators (kind , value ), replied_at , created_at , plus tenant_id
|

| submission.replay_detected
| When a verdict is flagged as a footer replay, in addition to verdict.created
| submission_id , tenant_id , rule , code
|

| indicator.new
| The first time an indicator is seen on a non verified submission
| tenant_id , indicator (id , kind , value , first_seen , submission_id , priority )
|

| campaign.detected
| Phase 2, when a cluster becomes a campaign
| Subscribable now; nothing is sent until the intelligence tier ships
|

The list of events is also returned as events on GET /v1/webhook-endpoints .

## Create an endpoint

Admin app: Webhooks, Add endpoint , URL, events. Or:

```bash
curl -X POST https://api.fromenance.com/v1/webhook-endpoints \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://siem.jtmerlin.example/hooks/fromenance","events":["verdict.created","submission.replay_detected","indicator.new"],"description":"Splunk HEC relay"}'
```

The response includes secret (whsec_... ), shown once and encrypted at rest with your tenant key. Endpoints default to verdict.created only. PATCH changes the URL, events, description, or status (active , paused ); DELETE removes it. A paused endpoint fails pending deliveries with “endpoint disabled” rather than queueing them.

## Delivery

Each delivery is an HTTPS POST with a JSON body:

```json
{
  "id": "evt_01J...",
  "type": "verdict.created",
  "created_at": "2026-09-26T16:01:04.221Z",
  "data": { "submission_id": "sub_01J...", "outcome": "not_verified", "rule": "code:replay", "replay": true, "...": "..." }
}
```

Headers:

| Header
| Value
|

| content-type
| application/json
|

| user-agent
| fromenance-webhooks/1.0
|

| x-fromenance-event
| The event type
|

| x-fromenance-delivery
| whd_... , the delivery id. The same id is reused on every retry of one delivery; a replay gets a new id with replay_of pointing at the original
|

| x-fromenance-timestamp
| Unix seconds when the request was signed
|

| x-fromenance-signature
| v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>"> keyed with the endpoint secret
|

Respond with any 2xx within 10 seconds. Anything else, a timeout, or a connection error counts as a failed attempt. Verify the signature on every request before parsing the body; samples in TypeScript, Python, and Go are on Verify signatures .

## Retries

Failed deliveries are retried with backoff: after 1 minute, then 5, 15, and 30 minutes, then 1, 1, 2, 2, 4, 4, and 6 hours, for 12 attempts in total over roughly 21 hours. After the last failure the delivery is marked failed and stays in the log. Deliveries to different endpoints are independent; a slow endpoint never delays another.

Because retries resend the same payload with the same x-fromenance-delivery , make your handler idempotent on that header or on id in the body.

## Delivery log and replay

Admin app: Webhooks, the endpoint, Deliveries shows every delivery with status (pending , retrying , delivered , failed ), attempts , last_status_code , last_error , next_attempt_at , delivered_at , and the payload. API: GET /v1/webhook-endpoints/{id}/deliveries .

Replay re-sends any delivery, delivered or failed, as a new delivery with replay_of set: POST /v1/webhook-endpoints/{id}/deliveries/{delivery_id}/replay . Use it after an outage on your side, or to backfill a new SIEM index. Send test (POST /v1/webhook-endpoints/{id}/test ) delivers a synthetic verdict.created so you can confirm signature verification before real traffic.

## Payload notes

- Payloads never contain the customer’s address, the forwarded message, or its links. Indicators are the extracted values (a phishing domain, a phone number), which is what your SIEM needs.

- signals on verdict.created is an open object; new keys may be added. Do not fail on unknown keys.

- Verdicts on sandbox submissions (from fr_test_ keys) are delivered like any other, so you can test your pipeline without live traffic. Use Send test for a synthetic event with a known shape.

---

Page: Verify signatures
URL: https://docs.fromenance.com/webhooks/verify-signatures

# Verify signatures

Fromenance is a communication provenance platform, and every webhook it sends is signed so your handler can prove the verdict came from Fromenance and was not modified in transit. This page gives working verification code in three languages.

By the end you will have a handler that rejects unsigned, tampered, replayed, and stale deliveries, and accepts real ones.

## The scheme

| Header
| Value
|

| x-fromenance-event
| Event type
|

| x-fromenance-delivery
| Delivery id, whd_...
|

| x-fromenance-timestamp
| Unix seconds, as a decimal string
|

| x-fromenance-signature
| v1= followed by lowercase hex HMAC-SHA256
|

The signed string is the timestamp, a period, and the raw request body exactly as received:

```text
signature = "v1=" + hex( HMAC-SHA256( key = endpoint secret, message = timestamp + "." + raw_body ) )
```

Four rules, in this order:

- Read the body as raw bytes before any JSON parsing. Re-serialized JSON does not match.

- Reject if x-fromenance-timestamp is more than 5 minutes from your clock, in either direction. This bounds replay of a captured request.

- Compute the expected signature and compare it with the header using a constant time comparison. Never use == on the strings.

- Only then parse the body and act. Deduplicate on x-fromenance-delivery or the id in the body, since retries resend the same payload.

The secret is the whsec_... value returned once when the endpoint was created. Header names are case insensitive on the wire; the samples read them lowercase.

## Samples

Each sample is a complete file from the docs repository and is compiled or executed by the docs test suite.

- TypeScript
- Python
- Go

```ts samples/verify-webhook.ts
/**
 * Verify a Fromenance outbound webhook (TypeScript, Node 18+ or Bun).
 *
 * Headers on every delivery:
 *   x-fromenance-event      verdict.created | submission.replay_detected | indicator.new | campaign.detected
 *   x-fromenance-delivery   whd_... delivery id, stable across retries and replays of the same delivery
 *   x-fromenance-timestamp  Unix seconds when the request was signed
 *   x-fromenance-signature  v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>" keyed with the endpoint secret>
 *
 * Reject anything older than 5 minutes and compare in constant time.
 */
import { createHmac, timingSafeEqual } from "node:crypto";

export const TOLERANCE_SECONDS = 5 * 60;

export interface FromenanceHeaders {
  "x-fromenance-event"?: string;
  "x-fromenance-delivery"?: string;
  "x-fromenance-timestamp"?: string;
  "x-fromenance-signature"?: string;
}

export function signFromenance(secret: string, timestamp: string, rawBody: string): string {
  return `v1=${createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex")}`;
}

export function verifyFromenanceSignature(
  headers: FromenanceHeaders,
  rawBody: string,
  secret: string,
  nowSeconds: number = Math.floor(Date.now() / 1000),
): boolean {
  const timestamp = headers["x-fromenance-timestamp"];
  const signature = headers["x-fromenance-signature"];
  if (!timestamp || !signature) return false;
  if (!/^\d+$/.test(timestamp)) return false;
  if (Math.abs(nowSeconds - Number(timestamp)) > TOLERANCE_SECONDS) return false;

  const expected = signFromenance(secret, timestamp, rawBody);
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(signature, "utf8");
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

/** Example handler for a fetch style runtime (Workers, Bun, Node 18+ with a fetch adapter). */
export async function handleWebhook(request: Request, secret: string): Promise<Response> {
  const rawBody = await request.text();
  const headers: FromenanceHeaders = {
    "x-fromenance-event": request.headers.get("x-fromenance-event") ?? undefined,
    "x-fromenance-delivery": request.headers.get("x-fromenance-delivery") ?? undefined,
    "x-fromenance-timestamp": request.headers.get("x-fromenance-timestamp") ?? undefined,
    "x-fromenance-signature": request.headers.get("x-fromenance-signature") ?? undefined,
  };
  if (!verifyFromenanceSignature(headers, rawBody, secret)) {
    return new Response("invalid signature", { status: 401 });
  }
  const event = JSON.parse(rawBody) as { id: string; type: string; created_at: string; data: unknown };
  // Deduplicate on x-fromenance-delivery or event.id before acting; retries resend the same payload.
  console.log(`accepted ${event.type} ${headers["x-fromenance-delivery"]}`);
  return new Response(null, { status: 204 });
}
```

## Testing your handler

- Create the endpoint and store the secret.

- Webhooks, the endpoint, Send test (POST /v1/webhook-endpoints/{id}/test ). A synthetic verdict.created arrives within a second.

- Confirm your handler returned 2xx and the delivery shows delivered in the log. A 401 from your side shows as last_status_code: 401 with the delivery retrying; fix the secret or the raw body handling, then Replay the delivery.

- Change one character of the secret in your handler and replay again: the delivery must now fail. Restore it.

## Rotating a secret

There is no in place rotation of an endpoint secret in v1. Create a second endpoint with the same URL and events, deploy the new secret to your handler so it accepts either secret for a few hours, then delete the old endpoint.

---

Page: Admin
URL: https://docs.fromenance.com/admin

# Admin

Fromenance is a communication provenance platform administered from app.fromenance.com . This page covers roles and the map of the admin app; the two pages after it cover users and keys, and retention and privacy.

By the end you will know which role to give each person on your team and where every setting is.

## Roles

Every user in a tenant has exactly one role. Sign in is by email magic link or passkey; there are no passwords.

| Role
| Intended for
| Can
|

| Owner
| The accountable executive or the tenant creator
| Everything an admin can, plus billing changes and deleting the tenant
|

| Admin
| Security or IT lead who owns the account
| Settings, users and roles, API keys, domains, sources, reply templates, webhooks, submissions, overrides, fraud list, indicators, exports, audit log, billing (read)
|

| Analyst
| Fraud or security team member working incidents
| Submissions and their detail, raw MIME download, overrides, fraud list, indicators, exports, registrations, dashboards, webhook delivery logs (read), audit log (read)
|

| Integrator
| The developer or ESP admin wiring registration in
| API keys, domains, sources, reply templates, webhooks, registrations and coverage, dashboards, test tools. No submission content
|

| Viewer
| Anyone who needs the numbers
| Dashboards, indicators, registrations, and read only lists
|

Permissions by area:

| Area
| Owner
| Admin
| Analyst
| Integrator
| Viewer
|

| Tenant settings, branding, retention
| yes
| yes
|
|
|
|

| Users and roles
| yes
| yes
|
|
|
|

| API keys
| yes
| yes
|
| yes
|
|

| Domains and reply identity
| yes
| yes
|
| yes
|
|

| Sending sources
| yes
| yes
|
| yes
|
|

| Reply templates
| yes
| yes
|
| yes
|
|

| Webhook endpoints (write)
| yes
| yes
|
| yes
|
|

| Webhook delivery log (read)
| yes
| yes
| yes
| yes
| yes
|

| Submissions, detail, raw MIME
| yes
| yes
| yes
|
|
|

| Overrides
| yes
| yes
| yes
|
|
|

| Fraud list (write)
| yes
| yes
| yes
|
|
|

| Indicators and exports
| yes
| yes
| yes
|
| yes
|

| Registrations and coverage
| yes
| yes
| yes
| yes
| yes
|

| Dashboards and stats
| yes
| yes
| yes
| yes
| yes
|

| Audit log
| yes
| yes
| yes
|
|
|

| Billing
| yes
| read
|
|
|
|

| Delete tenant
| yes
|
|
|
|
|

The same permission set applies to API keys: a key with the admin scope acts as an admin, read as a viewer plus submissions, and register only registers. See Users and keys .

## Where things live

| Screen
| What is there
|

| Overview
| Today and 30 days: submissions by outcome, registrations by source, reply p95, replay attempts, coverage gap count, top indicators
|

| Submissions
| The main table with filters and the detail drawer. See Verifications
|

| Indicators
| Extracted indicators with fraud list status, bulk add, CSV and STIX export
|

| Fraud list
| The tenant block list with source and history
|

| Campaigns
| Placeholder until the intelligence tier ships
|

| Registrations
| Search by code, message id, template, and date; coverage per source against expected volume
|

| Sources
| Sending sources with health, webhook URL, secret rotation, adapter instructions, and the test event button
|

| Domains
| Domains with TXT status and the copyable record, re-check, role toggles, reply identity setup
|

| Verify page
| Site keys, allowed origins, embed snippets, live widget preview
|

| Reply templates
| One MJML template per outcome with the locked verdict block, preview with sample data, send test
|

| Webhooks
| Endpoints, event selection, delivery log with replay, send test
|

| Settings
| Profile, branding (logo, accent, display name, support URL, fraud contact), retention days, Authoritative Mode (read only), users and roles, API keys, audit log, billing
|

| Setup
| The six step wizard, re-enterable from Settings
|

## Audit log

Every write in the admin app and API is recorded with the actor (user or API key), action, target, and before and after values: key minted or revoked, user invited or role changed, domain added, template saved, override recorded, raw MIME downloaded, fraud list entry added. Settings, Audit log lists it; GET /v1/audit returns it with cursor pagination.

---

Page: Users and keys
URL: https://docs.fromenance.com/admin/users-and-keys

# Users and keys

Fromenance is a communication provenance platform, and access to a tenant is through user accounts with roles and through scoped API keys. This page covers both.

By the end you will have invited your team with the right roles and minted keys with the smallest scope that does the job.

## Users

Settings, Users and roles, Invite . Or POST /v1/users with { "email": "...", "role": "analyst", "name": "..." } . The invitee gets a magic link; on first sign in they can register a passkey. Roles are described on Admin .

- Change a role with PATCH /v1/users/{id} ; remove a user with DELETE /v1/users/{id} . Both need the admin or owner role and are audited.

- A tenant must keep at least one owner.

- The same person can belong to several tenants (for example a managed security provider). The tenant switcher in the top bar changes context; GET /v1/me lists memberships.

- Single sign on (SAML and OIDC) is planned for a later release.

## API keys

Settings, API keys, Mint key . Or:

```bash
curl -X POST https://api.fromenance.com/v1/api-keys \
  -H "Authorization: Bearer fr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"statements-batch","mode":"live","scopes":["register"]}'
```

| Property
| Notes
|

| Format
| fr_live_ or fr_test_ followed by 40 hex characters. Only the first 12 characters (prefix ) and a SHA-256 hash are stored; the secret is shown once
|

| mode
| live writes to production. test writes to a sandbox partition: registrations and submissions are marked sandbox: true and replies go to your fraud contact address, never to a customer
|

| scopes
| One or more of register , read , admin
|

| last_used_at
| Updated on use, visible in the list
|

| Revoke
| DELETE /v1/api-keys/{id} . Takes effect within a minute at the edge
|

Scopes map to endpoint groups:

| Scope
| Allows
|

| register
| POST /v1/communications , /batch , /reserve , PATCH /v1/communications/{id}
|

| read
| GET on communications, submissions, indicators, fraud list, stats, search, webhook delivery logs, and the tenant
|

| admin
| Everything an admin user can do: users, keys, domains, sources, templates, webhooks, overrides, fraud list writes, site keys, audit log
|

Give your sending system a register key and nothing else. Give your SIEM integration a read key. Reserve admin keys for provisioning scripts and rotate them when the script is done.

Use the key as a bearer token: Authorization: Bearer fr_live_... . Rate limits are per key: 600 requests per minute on register and reserve, 6,000 items per minute on batch.

## The tenant secret

Recipient hashing uses a second secret, issued with your tenant and separate from every API key. The samples read it as FROMENANCE_TENANT_SECRET . It never travels to the API. Store it with the same care as a live key, since anyone holding it can compute the recipient hash for an address. Ask your Fromenance contact if you need it re-issued; re-issuing invalidates the recipient hashes on every existing registration, so it is done with a re-registration plan.

## Site keys

Site keys (sk_pub_... ) authenticate the verify widget and are public by design; they are bound to allowed origins rather than kept secret. Verify page, New site key , or POST /v1/site-keys . Revoke with DELETE /v1/site-keys/{id} . Details on Verify page .

## Sessions

The admin app uses a session cookie (fromenance.session_token ) issued by magic link or passkey sign in. Sessions are bound to the browser and expire on sign out. API keys, not sessions, are the right credential for anything automated.

## Signing in with Identizen

The admin app and the backoffice accept three ways in: an emailed magic link, a passkey registered under Settings, and Identizen, the accountless phone login. Identizen is a standard OpenID Connect provider: your phone approves the login, Fromenance receives a per site identifier and never your email or phone number, and nothing at Identizen can sign in as you.

Because the identifier carries no email, the first time a phone signs in Fromenance does not yet know which member it is. It asks once: enter the address your institution invited, open the link that arrives, and the phone is attached to your account. From then on, Continue with Identizen is a single approval on the phone. You can also attach or detach a phone from Settings, Profile (backoffice: the Account page). The magic link keeps working as the fallback.

---

Page: Retention and privacy
URL: https://docs.fromenance.com/admin/retention-and-privacy

# Retention and privacy

Fromenance is a communication provenance platform that handles customer mail on your behalf, so what it keeps and for how long is a setting you control and a list you can read here. This page is written for the person answering your vendor security questionnaire.

By the end you will know every stored field, every retention clock, and the four things that are never stored.

## Retention setting

Settings, Retention, or PATCH /v1/tenant with retention_days (7 to 730, default 90). It drives:

| Data
| Lifetime
|

| Registrations
| Expire at expires_at , which defaults to send time plus retention_days . Expired registrations no longer match; a registration you pass an explicit expires_at for keeps that value
|

| Raw MIME of forwarded messages and uploaded .eml files
| Deleted after retention_days , with a deletion record in the audit log
|

| Screenshots
| Same as raw MIME
|

| Submissions, verdicts, indicators
| Kept for the life of the tenant; they hold hashes, results, and extracted indicators, not message content
|

Independent of the setting:

| Data
| Lifetime
|

| Submitter address (the customer who forwarded or typed their address)
| Encrypted with your tenant key, kept only to send the reply and link repeat submissions, purged 30 days after the reply
|

| Subject of a forwarded message
| Encrypted with your tenant key, follows the raw MIME lifetime
|

| Rejected inbound (mail that failed the trust check)
| 24 hours, then deleted
|

| Idempotency keys and stored responses
| 24 hours
|

| Uncompleted reservations
| 24 hours by default (1 to 72 per call), then marked expired
|

| Webhook deliveries and payloads
| Kept in the delivery log for the life of the tenant. Payloads contain verdicts and indicators, never message content
|

| Audit log
| Kept for the life of the tenant
|

## What is stored

Per registration: the recipient hash, message id, From address, send time, subject and content fingerprints (one way hashes), link domains, your template and campaign ids, the provider, the verify code, and expiry.

Per submission: entry point, timestamps, the code found, the submitter hash, the recipient hash found in the innermost To header, the content fingerprint, whether headers were present, DKIM, ARC, and trust results, the sending domain, the raw MIME key (until deletion), the encrypted submitter address (until purge), and the extracted indicators.

Per verdict: outcome, rule, confidence, signals, the matched registration id, reply time, and any override with its note.

## What is never stored

- A raw recipient address on a registration. The API rejects anything that is not already an HMAC; you hash locally before the call. The column does not exist in the schema.

- The normalized text used for fingerprinting. It exists in memory for the duration of one call and is discarded; only the SimHash and SHA-256 are kept.

- Quoted message content in replies. Replies never include the suspicious message, its links, or its sender. The verdict block is locked text.

- Your message bodies from the API path. register() sends fingerprints. Only the journal path and ESP body retrieval see a body, and then only to fingerprint it before it is discarded.

## Encryption

Each tenant has its own data key. Encrypted columns (submitter addresses, subjects, source configuration, webhook and source secrets, the recipient hashing secret) are AES-256-GCM ciphertext under that key. Raw MIME and screenshots in object storage are encrypted under the tenant key as well and stored under a per tenant prefix. Keys are wrapped by a master key that lives only in the runtime’s secret store. See Security .

## Exporting and deleting

- Indicators export as CSV or STIX 2.1 from the admin app or GET /v1/indicators/export ; every table exports CSV.

- Raw MIME is downloadable by analysts, admins, and owners while within retention, and every download is audited.

- Deleting the tenant (owner only) removes registrations, submissions, verdicts, indicators, raw objects, and keys; only the audit record of the deletion remains. Ask your Fromenance contact for a signed deletion confirmation if your policy requires one.

## Data residency

All storage and processing is in the United States in v1. A DPA is available from day one; see Security for the subprocessor list.

---

Page: Errors
URL: https://docs.fromenance.com/api/errors

# Errors

Fromenance is a communication provenance platform whose API returns one error shape everywhere: an RFC 9457 problem details document with content type application/problem+json . This page lists every problem type and what to do about it.

By the end you will be able to parse any error, find the offending field, quote a request id to support, and back off correctly when rate limited.

## The problem document

```json
{
  "type": "https://docs.fromenance.com/api/errors#validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "The request body did not match the schema.",
  "instance": "/v1/communications",
  "errors": [
    { "path": "recipient_hash", "message": "Invalid input: must match pattern ^hmac-sha256:[0-9a-f]{64}$" }
  ],
  "request_id": "a1b2c3d4e5f6"
}
```

| Field
| Notes
|

| type
| A URL on this page. The fragment is the stable problem code; match on it, not on title
|

| title
| Short human readable summary, stable per type
|

| status
| The HTTP status, repeated
|

| detail
| What went wrong in this instance. May change wording between releases
|

| instance
| The request path
|

| errors[]
| Only on validation : one entry per failing field with a JSON path (items.3.sent_at for a batch item) and a message
|

| request_id
| Also sent as the x-request-id response header on every response. Quote it when contacting support
|

Read type and status first, then errors[] when present, and log request_id with every failure.

## Problem types

| Type
| Status
| When
| What to do
|

| #bad-request
| 400
| The request is malformed in a way a schema does not describe: no input on the verify page, a screenshot that is not an image, an unparseable webhook body
| Fix the request
|

| #validation
| 400
| The body, query, or path did not match the schema
| Read errors[] ; each path names the field
|

| #unauthorized
| 401
| Missing, revoked, or malformed credential; a site key used from an origin not on its allow list; a provider webhook with a bad signature
| Check the bearer token, the X-Site-Key and Origin , or the provider’s signing secret
|

| #forbidden
| 403
| The credential is valid but lacks the scope or role, or a tenant context is required
| Use a key with the right scope or a user with the right role
|

| #not-found
| 404
| No such resource in your tenant. Ids are tenant scoped, so another tenant’s id is also a 404
| Check the id and its prefix
|

| #conflict
| 409
| The action does not fit the current state: a forwarding test on an unverified domain, completing an expired reservation
| Resolve the state first
|

| #payload-too-large
| 413
| A screenshot over 6 MB
| Send a smaller image or the message text
|

| #idempotency-mismatch
| 422
| The Idempotency-Key was already used with a different body within 24 hours
| Use a new key for a new request
|

| #turnstile-required
| 428
| The site key is over its normal rate or has Turnstile required
| Render Turnstile and resend with turnstile_token
|

| #rate-limited
| 429
| Over a rate limit
| Wait for Retry-After seconds, then retry
|

| #internal
| 500
| Something failed on the Fromenance side. Logged with the request id
| Retry with backoff; contact support with the request id if it persists
|

| #upstream
| 502
| A dependency failed: the raw message could not be fetched from the inbound provider, an adapter is temporarily disabled, a screenshot could not be read
| Retry later, or use a different input
|

## Rate limits

| Limit
| Scope
| Retry-After
|

| 600 requests per minute
| Per API key on POST /v1/communications and /reserve
| 10
|

| 6,000 items per minute
| Per API key on POST /v1/communications/batch , counted per 100 items
| 10
|

| 60 requests per minute
| Per IP on POST /v1/public/submit
| 60
|

| 600 requests per minute
| Per site key on POST /v1/public/submit
| 10
|

A 429 always carries Retry-After in seconds. Back off for at least that long; do not retry validation errors at all.

## Idempotent replays

A successful replay of a creating POST with the same Idempotency-Key and body returns the stored response with its original status and the header idempotent-replayed: true . It is not an error; treat it as a normal response.

---

Page: Overview
URL: https://docs.fromenance.com/api

# Overview

## Fromenance API 1.0.0

Communication provenance for banks, credit unions, insurers, and utilities. Register every outbound communication at send time; verify what customers forward or paste. Errors are RFC 9457 problem details. All timestamps are UTC ISO 8601. Cursor pagination with cursor and limit .

Fromenance

- https://docs.fromenance.com
- support@fromenance.com

Information

- Terms of Service
- OpenAPI version: 3.1.0

##
Operations

GET/healthz

GET/v1/communications

POST/v1/communications

POST/v1/communications/batch

POST/v1/communications/reserve

GET/v1/communications/{id}

PATCH/v1/communications/{id}

POST/v1/public/submit

GET/v1/public/verdict/{token}

POST/v1/leads

GET/v1/submissions

GET/v1/submissions/{id}

POST/v1/submissions/{id}/override

GET/v1/indicators

GET/v1/fraud-list

POST/v1/fraud-list

DELETE/v1/fraud-list/{id}

GET/v1/domains

POST/v1/domains

GET/v1/domains/{id}

DELETE/v1/domains/{id}

PATCH/v1/domains/{id}

POST/v1/domains/{id}/check

POST/v1/domains/{id}/reply-identity

POST/v1/domains/{id}/reply-identity/verify

GET/v1/domains/{id}/forwarding-test

POST/v1/domains/{id}/forwarding-test

GET/v1/sending-sources

POST/v1/sending-sources

GET/v1/sending-sources/{id}

DELETE/v1/sending-sources/{id}

PATCH/v1/sending-sources/{id}

POST/v1/sending-sources/{id}/rotate-secret

POST/v1/sending-sources/{id}/test-event

GET/v1/reply-templates

PUT/v1/reply-templates/{outcome}

POST/v1/reply-templates/{outcome}/preview

POST/v1/reply-templates/{outcome}/test

GET/v1/webhook-endpoints

POST/v1/webhook-endpoints

DELETE/v1/webhook-endpoints/{id}

PATCH/v1/webhook-endpoints/{id}

GET/v1/webhook-endpoints/{id}/deliveries

POST/v1/webhook-endpoints/{id}/deliveries/{delivery_id}/replay

POST/v1/webhook-endpoints/{id}/test

GET/v1/stats

GET/v1/me

GET/v1/tenant

PATCH/v1/tenant

GET/v1/users

POST/v1/users

DELETE/v1/users/{id}

PATCH/v1/users/{id}

GET/v1/api-keys

POST/v1/api-keys

DELETE/v1/api-keys/{id}

GET/v1/audit

GET/v1/site-keys

POST/v1/site-keys

DELETE/v1/site-keys/{id}

PATCH/v1/site-keys/{id}

GET/v1/search

GET/v1/setup

##
Authentication

### ApiKey

Tenant API key with fr_live_ or fr_test_ prefix.

Security scheme type: http

### SiteKey

Public site key for the verify widget. Bound to allowed origins.

Security scheme type: apiKey
Header parameter name: X-Site-Key

### Session

Admin app or backoffice session.

Security scheme type: apiKey
Cookie parameter name: fromenance.session_token

---

Page: Health check
URL: https://docs.fromenance.com/api/operations/healthz

# Health check

GET
/healthzFetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/healthz
```

- Production

Returns ok when the Worker can reach D1. Neon is checked only when ?deep=1 .

##
Parameters

### Query Parameters

deep

string

##
Responses

### 200

Healthy

application/json

object

status
required

string
Allowed values: ok degraded

version
required

string

environment
required

string

checks
required

object

neon
required

string
Allowed values: ok error skipped

d1
required

string
Allowed values: ok error

time
required

string
Example

```json
{
  "status": "ok",
  "checks": {
    "neon": "ok",
    "d1": "ok"
  }
}
```

---

Page: Overview
URL: https://docs.fromenance.com/api/operations/tags/communications

# Overview

## Communications

Registration of sent communications.

##
Operations

GET/v1/communications

POST/v1/communications

POST/v1/communications/batch

POST/v1/communications/reserve

GET/v1/communications/{id}

PATCH/v1/communications/{id}

---

Page: Search registrations
URL: https://docs.fromenance.com/api/operations/v1communications/get

# Search registrations

GET
/v1/communicationsFetchcURL

```sh
curl --request GET \
  --url 'https://api.fromenance.com/v1/communications?status=registered' \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey
read

##
Parameters

### Query Parameters

code

string

message_id

string

template_id

string

status

string
Allowed values: registered reserved expired

source_id

string

from

string format: date-time

to

string format: date-time

limit

string

##
Responses

### 200

Communications

application/json

object

data
required

Array<object>

object

id
required

string

channel
required

string

status
required

string

recipient_hash
required

string | null

message_id
required

string | null

from_address
required

string | null

sent_at
required

string | null

verify_code
required

string

subject_fingerprint
required

string | null

content_fingerprint
required

object

simhash
required

string
/^0x[0-9a-fA-F]{1,16}$/

sha256
required

string
/^[0-9a-f]{64}$/

link_domains
required

Array<string>

template_id
required

string | null

campaign_id
required

string | null

provider
required

string | null

source_id
required

string | null

retro
required

boolean

sandbox
required

boolean

reserved_at
required

string | null

completed_at
required

string | null

expires_at
required

string

created_at
required

string

verifications

Array<object>

object

submission_id
required

string

outcome
required

string

rule
required

string

received_at
required

string
Example

```json
{
  "data": [
    {
      "content_fingerprint": {
        "simhash": "0x9a4d3c2b1f0e8d7c"
      }
    }
  ]
}
```

---

Page: Register one sent communication
URL: https://docs.fromenance.com/api/operations/v1communications/post

# Register one sent communication

POST
/v1/communicationsFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/communications \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "channel": "email", "recipient_hash": "example", "message_id": "example", "from_address": "example", "sent_at": "2026-04-15T12:00:00Z", "subject_fingerprint": "example", "content_fingerprint": { "simhash": "0x9a4d3c2b1f0e8d7c", "sha256": "example" }, "link_domains": [ "example" ], "template_id": "example", "campaign_id": "example", "provider": "api", "expires_at": "2026-04-15T12:00:00Z", "verify_code": "example" }'
```

- Production

Call at send time. Send only the recipient HMAC and the content fingerprint; never the address or the body. Returns the verify code to place in the footer. Supports Idempotency-Key .

## Authorizations

- ApiKey
register

## Request Body

application/json

object

channel

string
Allowed values: email

recipient_hash
required

HMAC-SHA256 of the lowercased, trimmed recipient address keyed with your tenant secret.

string
/^hmac-sha256:[0-9a-f]{64}$/

message_id
required

string
>= 1 characters <= 998 characters

from_address
required

string
>= 3 characters <= 320 characters

sent_at
required

string format: date-time

subject_fingerprint

string
/^[0-9a-f]{64}$/

content_fingerprint

object

simhash
required

string
/^0x[0-9a-fA-F]{1,16}$/
Example

```plaintext
0x9a4d3c2b1f0e8d7c
```

sha256
required

string
/^[0-9a-f]{64}$/

link_domains

Array<string>
<= 50 items

template_id

string | null
<= 120 characters

campaign_id

string | null
<= 120 characters

provider

string
Allowed values: api sendgrid ses resend postmark mailgun sfmc braze relay journal generic

expires_at

string format: date-time

verify_code

Only when completing a reserved code; otherwise omit and one is issued.

string
<= 9 characters

##
Responses

### 201

Registered

application/json

object

id
required

string

verify_code
required

string

expires_at
required

string

sandbox
required

boolean
Example

```json
{
  "verify_code": "KX73-PQ9G"
}
```

### 400

Validation

application/problem+json

object

type
required

string

title
required

string

status
required

integer

detail

string

instance

string

errors

Present on validation problems.

Array<object>

object

path
required

string

message
required

string

request_id

string
Example

```json
{
  "type": "https://docs.fromenance.com/api/errors#validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "recipient_hash must start with hmac-sha256:",
  "instance": "/v1/communications"
}
```

### 429

Rate limited

application/problem+json

object

type
required

string

title
required

string

status
required

integer

detail

string

instance

string

errors

Present on validation problems.

Array<object>

object

path
required

string

message
required

string

request_id

string
Example

```json
{
  "type": "https://docs.fromenance.com/api/errors#validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "recipient_hash must start with hmac-sha256:",
  "instance": "/v1/communications"
}
```

---

Page: Register up to 1,000 communications
URL: https://docs.fromenance.com/api/operations/v1communicationsbatch

# Register up to 1,000 communications

POST
/v1/communications/batchFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/communications/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "items": [ { "channel": "email", "recipient_hash": "example", "message_id": "example", "from_address": "example", "sent_at": "2026-04-15T12:00:00Z", "subject_fingerprint": "example", "content_fingerprint": { "simhash": "0x9a4d3c2b1f0e8d7c", "sha256": "example" }, "link_domains": [ "example" ], "template_id": "example", "campaign_id": "example", "provider": "api", "expires_at": "2026-04-15T12:00:00Z", "verify_code": "example" } ] }'
```

- Production

Per item results in input order. One bad item does not fail the batch. Rate limited at 6,000 items per minute.

## Authorizations

- ApiKey
register

## Request Body

application/json

object

items
required

Array<object>
>= 1 items <= 1000 items

object

channel

string
Allowed values: email

recipient_hash
required

HMAC-SHA256 of the lowercased, trimmed recipient address keyed with your tenant secret.

string
/^hmac-sha256:[0-9a-f]{64}$/

message_id
required

string
>= 1 characters <= 998 characters

from_address
required

string
>= 3 characters <= 320 characters

sent_at
required

string format: date-time

subject_fingerprint

string
/^[0-9a-f]{64}$/

content_fingerprint

object

simhash
required

string
/^0x[0-9a-fA-F]{1,16}$/
Example

```plaintext
0x9a4d3c2b1f0e8d7c
```

sha256
required

string
/^[0-9a-f]{64}$/

link_domains

Array<string>
<= 50 items

template_id

string | null
<= 120 characters

campaign_id

string | null
<= 120 characters

provider

string
Allowed values: api sendgrid ses resend postmark mailgun sfmc braze relay journal generic

expires_at

string format: date-time

verify_code

Only when completing a reserved code; otherwise omit and one is issued.

string
<= 9 characters

##
Responses

### 200

Results

application/json

object

results
required

Array<object>

object

index
required

integer

ok
required

boolean

id

string

verify_code

string

expires_at

string

error

string

registered
required

integer

failed
required

integer
Examplegenerated

```json
{
  "results": [
    {
      "index": 1,
      "ok": true,
      "id": "example",
      "verify_code": "example",
      "expires_at": "example",
      "error": "example"
    }
  ],
  "registered": 1,
  "failed": 1
}
```

---

Page: Reserve a verify code before sending
URL: https://docs.fromenance.com/api/operations/v1communicationsreserve

# Reserve a verify code before sending

POST
/v1/communications/reserveFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/communications/reserve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "recipient_hash": "example", "template_id": "example", "campaign_id": "example", "provider": "api", "from_address": "example", "expires_in_hours": 1 }'
```

- Production

For ESPs that need the code as a merge field before the send event exists. Complete it with PATCH /v1/communications/{id} or through the ESP webhook. Unfinished reservations expire after 24 hours and count as a coverage gap.

## Authorizations

- ApiKey
register

## Request Body

application/json

object

recipient_hash

string
/^hmac-sha256:[0-9a-f]{64}$/

template_id

string | null
<= 120 characters

campaign_id

string | null
<= 120 characters

provider

string
Allowed values: api sendgrid ses resend postmark mailgun sfmc braze relay journal generic

from_address

string
<= 320 characters

expires_in_hours

integer
>= 1 <= 72

##
Responses

### 201

Reserved

application/json

object

id
required

string

verify_code
required

string

expires_at
required

string

sandbox
required

boolean
Example

```json
{
  "verify_code": "KX73-PQ9G"
}
```

---

Page: Registration detail with verifications against it
URL: https://docs.fromenance.com/api/operations/v1communicationsid/get

# Registration detail with verifications against it

GET
/v1/communications/{id}FetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/communications/com_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey
read

##
Parameters

### Path Parameters

id
required

string
/^com_[0-9A-Z]{26}$/
Example

```plaintext
com_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Communication

application/json

object

id
required

string

channel
required

string

status
required

string

recipient_hash
required

string | null

message_id
required

string | null

from_address
required

string | null

sent_at
required

string | null

verify_code
required

string

subject_fingerprint
required

string | null

content_fingerprint
required

object

simhash
required

string
/^0x[0-9a-fA-F]{1,16}$/

sha256
required

string
/^[0-9a-f]{64}$/

link_domains
required

Array<string>

template_id
required

string | null

campaign_id
required

string | null

provider
required

string | null

source_id
required

string | null

retro
required

boolean

sandbox
required

boolean

reserved_at
required

string | null

completed_at
required

string | null

expires_at
required

string

created_at
required

string

verifications

Array<object>

object

submission_id
required

string

outcome
required

string

rule
required

string

received_at
required

string
Example

```json
{
  "content_fingerprint": {
    "simhash": "0x9a4d3c2b1f0e8d7c"
  }
}
```

---

Page: Complete a reserved registration
URL: https://docs.fromenance.com/api/operations/v1communicationsid/patch

# Complete a reserved registration

PATCH
/v1/communications/{id}FetchcURL

```sh
curl --request PATCH \
  --url https://api.fromenance.com/v1/communications/com_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "recipient_hash": "example", "message_id": "example", "from_address": "example", "sent_at": "2026-04-15T12:00:00Z", "subject_fingerprint": "example", "content_fingerprint": { "simhash": "0x9a4d3c2b1f0e8d7c", "sha256": "example" }, "link_domains": [ "example" ], "template_id": "example", "campaign_id": "example", "expires_at": "2026-04-15T12:00:00Z" }'
```

- Production

## Authorizations

- ApiKey
register

##
Parameters

### Path Parameters

id
required

string
/^com_[0-9A-Z]{26}$/
Example

```plaintext
com_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

## Request Body

application/json

object

recipient_hash

string
/^hmac-sha256:[0-9a-f]{64}$/

message_id

string
>= 1 characters <= 998 characters

from_address

string
>= 3 characters <= 320 characters

sent_at

string format: date-time

subject_fingerprint

string
/^[0-9a-f]{64}$/

content_fingerprint

object

simhash
required

string
/^0x[0-9a-fA-F]{1,16}$/
Example

```plaintext
0x9a4d3c2b1f0e8d7c
```

sha256
required

string
/^[0-9a-f]{64}$/

link_domains

Array<string>
<= 50 items

template_id

string | null
<= 120 characters

campaign_id

string | null
<= 120 characters

expires_at

string format: date-time

##
Responses

### 200

Communication

application/json

object

id
required

string

channel
required

string

status
required

string

recipient_hash
required

string | null

message_id
required

string | null

from_address
required

string | null

sent_at
required

string | null

verify_code
required

string

subject_fingerprint
required

string | null

content_fingerprint
required

object

simhash
required

string
/^0x[0-9a-fA-F]{1,16}$/

sha256
required

string
/^[0-9a-f]{64}$/

link_domains
required

Array<string>

template_id
required

string | null

campaign_id
required

string | null

provider
required

string | null

source_id
required

string | null

retro
required

boolean

sandbox
required

boolean

reserved_at
required

string | null

completed_at
required

string | null

expires_at
required

string

created_at
required

string

verifications

Array<object>

object

submission_id
required

string

outcome
required

string

rule
required

string

received_at
required

string
Example

```json
{
  "content_fingerprint": {
    "simhash": "0x9a4d3c2b1f0e8d7c"
  }
}
```

---

Page: Overview
URL: https://docs.fromenance.com/api/operations/tags/public

# Overview

## Public

Web verify endpoints authenticated by site key.

##
Operations

POST/v1/public/submit

GET/v1/public/verdict/{token}

POST/v1/leads

---

Page: Verify a message from the web page
URL: https://docs.fromenance.com/api/operations/v1publicsubmit

# Verify a message from the web page

POST
/v1/public/submitFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/public/submit \
  --header 'Content-Type: application/json' \
  --header 'X-Site-Key: <X-Site-Key>' \
  --data '{ "text": "example", "eml_base64": "example", "image_base64": "example", "code": "example", "email": "hello@example.com", "turnstile_token": "example" }'
```

- Production

Authenticated by site key and origin. Rate limited per IP and per key; a Turnstile token is required once a key exceeds its normal rate. Text and .eml return the verdict synchronously; screenshots return a poll token.

## Authorizations

- SiteKey

## Request Body

application/json

object

text

Pasted message text or HTML.

string
<= 200000 characters

eml_base64

A .eml file, base64.

string
<= 2000000 characters

image_base64

A screenshot (PNG, JPEG, WebP), base64. Answered asynchronously.

string
<= 8000000 characters

code

Verify code typed by the customer.

string
<= 12 characters

email

The customer’s own address, hashed locally on our side and never stored in clear.

string format: email

turnstile_token

string
<= 4000 characters
Examplegenerated

```json
{
  "text": "example",
  "eml_base64": "example",
  "image_base64": "example",
  "code": "example",
  "email": "hello@example.com",
  "turnstile_token": "example"
}
```

##
Responses

### 200

Verdict

application/json

object

status
required

string
Allowed values: decided pending

poll_token
required

string | null

submission_id
required

string

outcome
required

string | null
Allowed values: verified not_verified known_fraud

rule
required

string | null

matched_sent_at
required

string | null

signals
required

object

code_found
required

boolean

recipient_match
required

boolean | null

fingerprint_distance
required

number | null

display
required

object

institution_name
required

string

logo_url
required

string | null

accent
required

string | null

fraud_contact
required

string | null

support_url
required

string | null

outcome_label
required

string

verdict_text
required

string

next_step
required

string
Example

```json
{
  "status": "decided",
  "outcome": "verified"
}
```

### 202

Pending (screenshot)

application/json

object

status
required

string
Allowed values: decided pending

poll_token
required

string | null

submission_id
required

string

outcome
required

string | null
Allowed values: verified not_verified known_fraud

rule
required

string | null

matched_sent_at
required

string | null

signals
required

object

code_found
required

boolean

recipient_match
required

boolean | null

fingerprint_distance
required

number | null

display
required

object

institution_name
required

string

logo_url
required

string | null

accent
required

string | null

fraud_contact
required

string | null

support_url
required

string | null

outcome_label
required

string

verdict_text
required

string

next_step
required

string
Example

```json
{
  "status": "decided",
  "outcome": "verified"
}
```

### 428

Turnstile required

### 429

Rate limited

---

Page: Poll a screenshot submission
URL: https://docs.fromenance.com/api/operations/v1publicverdicttoken

# Poll a screenshot submission

GET
/v1/public/verdict/{token}FetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/public/verdict/example \
  --header 'X-Site-Key: <X-Site-Key>'
```

- Production

## Authorizations

- SiteKey

##
Parameters

### Path Parameters

token
required

string
>= 8 characters <= 64 characters

##
Responses

### 200

Verdict or pending

application/json

object

status
required

string
Allowed values: decided pending

poll_token
required

string | null

submission_id
required

string

outcome
required

string | null
Allowed values: verified not_verified known_fraud

rule
required

string | null

matched_sent_at
required

string | null

signals
required

object

code_found
required

boolean

recipient_match
required

boolean | null

fingerprint_distance
required

number | null

display
required

object

institution_name
required

string

logo_url
required

string | null

accent
required

string | null

fraud_contact
required

string | null

support_url
required

string | null

outcome_label
required

string

verdict_text
required

string

next_step
required

string
Example

```json
{
  "status": "decided",
  "outcome": "verified"
}
```

---

Page: Submit a sales or pilot inquiry
URL: https://docs.fromenance.com/api/operations/v1leads

# Submit a sales or pilot inquiry

POST
/v1/leadsFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/leads \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "email": "hello@example.com", "institution": "example", "role": "example", "segment": "bank", "customers": "<250K", "message": "example", "source": "example", "turnstile_token": "example", "website": "example" }'
```

- Production

Used by the fromenance.com contact and pilot forms. Rate limited per IP.

## Request Body

application/json

object

name
required

string
>= 2 characters <= 120 characters

email
required

string format: email
<= 200 characters

institution

string
<= 200 characters

role

string
<= 120 characters

segment

string
Allowed values: bank credit_union insurance utility other

customers

string
Allowed values: <250K 250K-1M 1M-3M 3M+

message

string
<= 4000 characters

source

Page path the form was submitted from.

string
<= 200 characters

turnstile_token

string
<= 4000 characters

website

Honeypot. Leave empty.

string
<= 200 characters

##
Responses

### 202

Accepted

application/json

object

ok
required

boolean

id
required

string
Example

```json
{
  "ok": true
}
```

### 429

Rate limited

---

Page: List submissions
URL: https://docs.fromenance.com/api/operations/v1submissions

# List submissions

GET
/v1/submissionsFetchcURL

```sh
curl --request GET \
  --url 'https://api.fromenance.com/v1/submissions?limit=50&outcome=verified&entry=forward&replay=true&has_headers=true' \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey
read

##
Parameters

### Query Parameters

cursor

Opaque cursor from a previous response.

string

Opaque cursor from a previous response.

limit

Page size, 1 to 200, default 50.

string
Example

```json
50
```

Page size, 1 to 200, default 50.

outcome

string
Allowed values: verified not_verified known_fraud

entry

string
Allowed values: forward web api

replay

string
Allowed values: true false

has_headers

string
Allowed values: true false

code

string

submitter_hash

string

from

string

to

string

campaign_id

string

##
Responses

### 200

Submissions

application/json

object

data
required

Array<object>

object

id
required

string

entry
required

string

status
required

string

received_at
required

string

processed_at
required

string | null

count
required

integer

verify_code_found
required

string | null

submitter_hash
required

string | null

recipient_hash_found
required

string | null

headers_present
required

boolean

dkim
required

string | null

arc
required

string | null

trust
required

string | null

from_domain
required

string | null

imitated_template_id
required

string | null

campaign_id
required

string | null

sandbox
required

boolean

verdict
required

object

submission_id
required

string

outcome
required

string
Allowed values: verified not_verified known_fraud

rule
required

string

replay
required

boolean

authoritative
required

boolean

matched
required

object

communication_id
required

string

sent_at
required

string | null

template_id
required

string | null

signals
required

object

key
additional properties

indicators
required

Array<object>

object

kind
required

string

value
required

string

replied_at
required

string | null

created_at
required

string

override
required

object

outcome
required

string

by
required

string | null

at
required

string

note
required

string | null

next_cursor
required

string | null
Example

```json
{
  "data": [
    {
      "verdict": {
        "outcome": "verified"
      }
    }
  ]
}
```

---

Page: Submission detail
URL: https://docs.fromenance.com/api/operations/v1submissionsid

# Submission detail

GET
/v1/submissions/{id}FetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/submissions/sub_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

Extracted signals, verdict and rule, indicators with fraud list status, header summary, and a text preview with links disabled.

## Authorizations

- Session
- ApiKey
read

##
Parameters

### Path Parameters

id
required

string
/^sub_[0-9A-Z]{26}$/
Example

```plaintext
sub_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Detail

application/json

object

id
required

string

entry
required

string

status
required

string

received_at
required

string

processed_at
required

string | null

count
required

integer

verify_code_found
required

string | null

submitter_hash
required

string | null

recipient_hash_found
required

string | null

headers_present
required

boolean

dkim
required

string | null

arc
required

string | null

trust
required

string | null

from_domain
required

string | null

imitated_template_id
required

string | null

campaign_id
required

string | null

sandbox
required

boolean

verdict
required

object

submission_id
required

string

outcome
required

string
Allowed values: verified not_verified known_fraud

rule
required

string

replay
required

boolean

authoritative
required

boolean

matched
required

object

communication_id
required

string

sent_at
required

string | null

template_id
required

string | null

signals
required

object

key
additional properties

indicators
required

Array<object>

object

kind
required

string

value
required

string

replied_at
required

string | null

created_at
required

string

override
required

object

outcome
required

string

by
required

string | null

at
required

string

note
required

string | null

subject
required

string | null

preview_text
required

Plain text of the forwarded message with every link replaced by its bare domain.

string | null

headers_summary
required

object

received
required

Array<string>

dkim
required

string | null

arc
required

string | null

spf
required

string | null

trust
required

string | null

indicators
required

Array<object>

object

id
required

string

kind
required

string

value
required

string

on_fraud_list
required

boolean

submission_count
required

integer

raw_available
required

boolean
Example

```json
{
  "verdict": {
    "outcome": "verified"
  }
}
```

---

Page: Analyst override
URL: https://docs.fromenance.com/api/operations/v1submissionsidoverride

# Analyst override

POST
/v1/submissions/{id}/overrideFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/submissions/sub_01J8Z9X0Q3K4M5N6P7R8S9T0V1/override \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "outcome": "fraud", "note": "example" }'
```

- Production

Marking fraud adds the submission’s indicators and fingerprint to the tenant fraud list so later submissions resolve to Known fraud. Marking legitimate creates a registration retroactively and flags a coverage gap on the sending source.

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^sub_[0-9A-Z]{26}$/
Example

```plaintext
sub_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

## Request Body

application/json

object

outcome
required

string
Allowed values: fraud legitimate

note

string
<= 2000 characters

##
Responses

### 200

Updated submission

application/json

object

id
required

string

entry
required

string

status
required

string

received_at
required

string

processed_at
required

string | null

count
required

integer

verify_code_found
required

string | null

submitter_hash
required

string | null

recipient_hash_found
required

string | null

headers_present
required

boolean

dkim
required

string | null

arc
required

string | null

trust
required

string | null

from_domain
required

string | null

imitated_template_id
required

string | null

campaign_id
required

string | null

sandbox
required

boolean

verdict
required

object

submission_id
required

string

outcome
required

string
Allowed values: verified not_verified known_fraud

rule
required

string

replay
required

boolean

authoritative
required

boolean

matched
required

object

communication_id
required

string

sent_at
required

string | null

template_id
required

string | null

signals
required

object

key
additional properties

indicators
required

Array<object>

object

kind
required

string

value
required

string

replied_at
required

string | null

created_at
required

string

override
required

object

outcome
required

string

by
required

string | null

at
required

string

note
required

string | null
Example

```json
{
  "verdict": {
    "outcome": "verified"
  }
}
```

---

Page: List extracted indicators
URL: https://docs.fromenance.com/api/operations/v1indicators

# List extracted indicators

GET
/v1/indicatorsFetchcURL

```sh
curl --request GET \
  --url 'https://api.fromenance.com/v1/indicators?limit=50&kind=url&on_fraud_list=true&priority=low' \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

Set Accept: text/csv or Accept: application/stix+json on /v1/indicators/export for exports.

## Authorizations

- Session
- ApiKey
read

##
Parameters

### Query Parameters

cursor

Opaque cursor from a previous response.

string

Opaque cursor from a previous response.

limit

Page size, 1 to 200, default 50.

string
Example

```json
50
```

Page size, 1 to 200, default 50.

kind

string
Allowed values: url domain email phone ip

q

string

on_fraud_list

string
Allowed values: true false

since

string

priority

string
Allowed values: low normal high

##
Responses

### 200

Indicators

application/json

object

data
required

Array<object>

object

id
required

string

kind
required

string

value
required

string

first_seen
required

string

last_seen
required

string

submission_count
required

integer

priority
required

string

on_fraud_list
required

boolean

next_cursor
required

string | null
Examplegenerated

```json
{
  "data": [
    {
      "id": "example",
      "kind": "example",
      "value": "example",
      "first_seen": "example",
      "last_seen": "example",
      "submission_count": 1,
      "priority": "example",
      "on_fraud_list": true
    }
  ],
  "next_cursor": "example"
}
```

---

Page: The tenant's block list
URL: https://docs.fromenance.com/api/operations/v1fraud-list/get

# The tenant's block list

GET
/v1/fraud-listFetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/fraud-list \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey
read

##
Responses

### 200

Entries

application/json

object

data
required

Array<object>

object

id
required

string

kind
required

string

value
required

string

source
required

string

added_by
required

string | null

note
required

string | null

submission_id
required

string | null

created_at
required

string
Examplegenerated

```json
{
  "data": [
    {
      "id": "example",
      "kind": "example",
      "value": "example",
      "source": "example",
      "added_by": "example",
      "note": "example",
      "submission_id": "example",
      "created_at": "example"
    }
  ]
}
```

---

Page: Add indicators to the fraud list
URL: https://docs.fromenance.com/api/operations/v1fraud-list/post

# Add indicators to the fraud list

POST
/v1/fraud-listFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/fraud-list \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "items": [ { "kind": "url", "value": "example", "note": "example" } ] }'
```

- Production

Entries come only from analyst action; nothing is added automatically from a single submission.

## Authorizations

- Session
- ApiKey

## Request Body

application/json

object

items
required

Array<object>
>= 1 items <= 500 items

object

kind
required

string
Allowed values: url domain email phone ip

value
required

string
>= 2 characters <= 2000 characters

note

string
<= 500 characters

##
Responses

### 200

Added

application/json

object

added
required

integer

data
required

Array<object>

object

id
required

string

kind
required

string

value
required

string

source
required

string

added_by
required

string | null

note
required

string | null

submission_id
required

string | null

created_at
required

string
Examplegenerated

```json
{
  "added": 1,
  "data": [
    {
      "id": "example",
      "kind": "example",
      "value": "example",
      "source": "example",
      "added_by": "example",
      "note": "example",
      "submission_id": "example",
      "created_at": "example"
    }
  ]
}
```

---

Page: Remove an entry
URL: https://docs.fromenance.com/api/operations/v1fraud-listid

# Remove an entry

DELETE
/v1/fraud-list/{id}FetchcURL

```sh
curl --request DELETE \
  --url https://api.fromenance.com/v1/fraud-list/example \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string

##
Responses

### 200

Removed

application/json

object

ok
required

boolean
Example

```json
{
  "ok": true
}
```

---

Page: List domains
URL: https://docs.fromenance.com/api/operations/v1domains/get

# List domains

GET
/v1/domainsFetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/domains \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Responses

### 200

Domains

application/json

object

data
required

Array<object>

object

id
required

string

domain
required

string

status
required

Any of:

- string
- string

string
Allowed values: pending verified suspended

roles
required

Array

txt_record
required

object

name
required

string

type
required

string
Allowed values: TXT

value
required

string

verified_at
required

string | null

last_checked_at
required

string | null

last_check_result
required

string | null

reply_identity
required

object

resend_domain_id
required

string | null

status
required

string | null

records
required

Array<object> | null

object

record
required

string

name
required

string

type
required

string

value
required

string

priority

number

status

string

created_at
required

string
Example

```json
{
  "data": [
    {
      "status": "pending",
      "roles": [
        "trust"
      ],
      "txt_record": {
        "type": "TXT"
      }
    }
  ]
}
```

---

Page: Add a domain
URL: https://docs.fromenance.com/api/operations/v1domains/post

# Add a domain

POST
/v1/domainsFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/domains \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "domain": "northfieldbank.com", "roles": [ "trust" ] }'
```

- Production

Returns the TXT record to publish at _fromenance.<domain> . The domain is polled every hour for 24 hours, then daily once verified.

## Authorizations

- Session
- ApiKey

## Request Body

application/json

object

domain
required

string
>= 3 characters <= 253 characters
Example

```plaintext
northfieldbank.com
```

roles

Array<string>
Allowed values: trust sender reply

##
Responses

### 201

Domain

application/json

object

id
required

string

domain
required

string

status
required

Any of:

- string
- string

string
Allowed values: pending verified suspended

roles
required

Array

txt_record
required

object

name
required

string

type
required

string
Allowed values: TXT

value
required

string

verified_at
required

string | null

last_checked_at
required

string | null

last_check_result
required

string | null

reply_identity
required

object

resend_domain_id
required

string | null

status
required

string | null

records
required

Array<object> | null

object

record
required

string

name
required

string

type
required

string

value
required

string

priority

number

status

string

created_at
required

string
Example

```json
{
  "status": "pending",
  "roles": [
    "trust"
  ],
  "txt_record": {
    "type": "TXT"
  }
}
```

---

Page: Domain detail
URL: https://docs.fromenance.com/api/operations/v1domainsid/get

# Domain detail

GET
/v1/domains/{id}FetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/domains/dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^dom_[0-9A-Z]{26}$/
Example

```plaintext
dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Domain

application/json

object

id
required

string

domain
required

string

status
required

Any of:

- string
- string

string
Allowed values: pending verified suspended

roles
required

Array

txt_record
required

object

name
required

string

type
required

string
Allowed values: TXT

value
required

string

verified_at
required

string | null

last_checked_at
required

string | null

last_check_result
required

string | null

reply_identity
required

object

resend_domain_id
required

string | null

status
required

string | null

records
required

Array<object> | null

object

record
required

string

name
required

string

type
required

string

value
required

string

priority

number

status

string

created_at
required

string
Example

```json
{
  "status": "pending",
  "roles": [
    "trust"
  ],
  "txt_record": {
    "type": "TXT"
  }
}
```

---

Page: Remove a domain
URL: https://docs.fromenance.com/api/operations/v1domainsid/delete

# Remove a domain

DELETE
/v1/domains/{id}FetchcURL

```sh
curl --request DELETE \
  --url https://api.fromenance.com/v1/domains/dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^dom_[0-9A-Z]{26}$/
Example

```plaintext
dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Removed

application/json

object

ok
required

boolean
Example

```json
{
  "ok": true
}
```

---

Page: Change domain roles
URL: https://docs.fromenance.com/api/operations/v1domainsid/patch

# Change domain roles

PATCH
/v1/domains/{id}FetchcURL

```sh
curl --request PATCH \
  --url https://api.fromenance.com/v1/domains/dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "roles": [ "trust" ] }'
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^dom_[0-9A-Z]{26}$/
Example

```plaintext
dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

## Request Body

application/json

object

roles
required

Array<string>
>= 1 items
Allowed values: trust sender reply

##
Responses

### 200

Domain

application/json

object

id
required

string

domain
required

string

status
required

Any of:

- string
- string

string
Allowed values: pending verified suspended

roles
required

Array

txt_record
required

object

name
required

string

type
required

string
Allowed values: TXT

value
required

string

verified_at
required

string | null

last_checked_at
required

string | null

last_check_result
required

string | null

reply_identity
required

object

resend_domain_id
required

string | null

status
required

string | null

records
required

Array<object> | null

object

record
required

string

name
required

string

type
required

string

value
required

string

priority

number

status

string

created_at
required

string
Example

```json
{
  "status": "pending",
  "roles": [
    "trust"
  ],
  "txt_record": {
    "type": "TXT"
  }
}
```

---

Page: Re-check the TXT record now
URL: https://docs.fromenance.com/api/operations/v1domainsidcheck

# Re-check the TXT record now

POST
/v1/domains/{id}/checkFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/domains/dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1/check \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^dom_[0-9A-Z]{26}$/
Example

```plaintext
dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Domain after the check

application/json

object

id
required

string

domain
required

string

status
required

Any of:

- string
- string

string
Allowed values: pending verified suspended

roles
required

Array

txt_record
required

object

name
required

string

type
required

string
Allowed values: TXT

value
required

string

verified_at
required

string | null

last_checked_at
required

string | null

last_check_result
required

string | null

reply_identity
required

object

resend_domain_id
required

string | null

status
required

string | null

records
required

Array<object> | null

object

record
required

string

name
required

string

type
required

string

value
required

string

priority

number

status

string

created_at
required

string
Example

```json
{
  "status": "pending",
  "roles": [
    "trust"
  ],
  "txt_record": {
    "type": "TXT"
  }
}
```

---

Page: Create the branded reply identity
URL: https://docs.fromenance.com/api/operations/v1domainsidreply-identity

# Create the branded reply identity

POST
/v1/domains/{id}/reply-identityFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/domains/dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1/reply-identity \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "subdomain": "example" }'
```

- Production

Creates verify.<domain> (or the given subdomain) as a Resend sending domain and returns the DKIM, SPF, and MX records to publish. Replies then come from verify@verify.<domain> .

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^dom_[0-9A-Z]{26}$/
Example

```plaintext
dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

## Request Body

application/json

object

subdomain

string
/^[a-z0-9-]{1,30}$/
Examplegenerated

```json
{
  "subdomain": "example"
}
```

##
Responses

### 200

Domain with reply identity records

application/json

object

id
required

string

domain
required

string

status
required

Any of:

- string
- string

string
Allowed values: pending verified suspended

roles
required

Array

txt_record
required

object

name
required

string

type
required

string
Allowed values: TXT

value
required

string

verified_at
required

string | null

last_checked_at
required

string | null

last_check_result
required

string | null

reply_identity
required

object

resend_domain_id
required

string | null

status
required

string | null

records
required

Array<object> | null

object

record
required

string

name
required

string

type
required

string

value
required

string

priority

number

status

string

created_at
required

string
Example

```json
{
  "status": "pending",
  "roles": [
    "trust"
  ],
  "txt_record": {
    "type": "TXT"
  }
}
```

---

Page: Ask Resend to verify the reply identity records
URL: https://docs.fromenance.com/api/operations/v1domainsidreply-identityverify

# Ask Resend to verify the reply identity records

POST
/v1/domains/{id}/reply-identity/verifyFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/domains/dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1/reply-identity/verify \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^dom_[0-9A-Z]{26}$/
Example

```plaintext
dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Domain

application/json

object

id
required

string

domain
required

string

status
required

Any of:

- string
- string

string
Allowed values: pending verified suspended

roles
required

Array

txt_record
required

object

name
required

string

type
required

string
Allowed values: TXT

value
required

string

verified_at
required

string | null

last_checked_at
required

string | null

last_check_result
required

string | null

reply_identity
required

object

resend_domain_id
required

string | null

status
required

string | null

records
required

Array<object> | null

object

record
required

string

name
required

string

type
required

string

value
required

string

priority

number

status

string

created_at
required

string
Example

```json
{
  "status": "pending",
  "roles": [
    "trust"
  ],
  "txt_record": {
    "type": "TXT"
  }
}
```

---

Page: Forwarding test status
URL: https://docs.fromenance.com/api/operations/v1domainsidforwarding-test/get

# Forwarding test status

GET
/v1/domains/{id}/forwarding-testFetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/domains/dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1/forwarding-test \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^dom_[0-9A-Z]{26}$/
Example

```plaintext
dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Status

application/json

object

status
required

string
Allowed values: not_started sent working failed

sent_at
required

string | null

passed_at
required

string | null

result
required

string | null

to
required

string
Example

```json
{
  "status": "not_started"
}
```

---

Page: Send the forwarding test message to verify@<domain>
URL: https://docs.fromenance.com/api/operations/v1domainsidforwarding-test/post

# Send the forwarding test message to verify@

POST
/v1/domains/{id}/forwarding-testFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/domains/dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1/forwarding-test \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

The message carries a token. When the tenant’s redirect rule delivers it to the tenant inbox with a DKIM or ARC pass for the domain, the rule is marked Working. Poll GET on the same path.

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^dom_[0-9A-Z]{26}$/
Example

```plaintext
dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Status

application/json

object

status
required

string
Allowed values: not_started sent working failed

sent_at
required

string | null

passed_at
required

string | null

result
required

string | null

to
required

string
Example

```json
{
  "status": "not_started"
}
```

---

Page: List sending sources with health
URL: https://docs.fromenance.com/api/operations/v1sending-sources/get

# List sending sources with health

GET
/v1/sending-sourcesFetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/sending-sources \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Responses

### 200

Sources

application/json

object

data
required

Array<object>

object

id
required

string

name
required

string

kind
required

string

status
required

string

webhook_url
required

string | null

needs_reserve
required

boolean

footer_merge_tag
required

string | null

instructions
required

Array<string>

expected_daily_volume
required

integer | null

silence_alert_minutes
required

integer

health
required

object

last_event_at
required

string | null

events_last_hour
required

integer

signature_failures
required

integer

reserved
required

integer

completed
required

integer

reserve_to_complete_ratio
required

number | null

coverage_gaps
required

integer

silent
required

boolean

registered_today
required

integer

created_at
required

string
Examplegenerated

```json
{
  "data": [
    {
      "id": "example",
      "name": "example",
      "kind": "example",
      "status": "example",
      "webhook_url": "example",
      "needs_reserve": true,
      "footer_merge_tag": "example",
      "instructions": [
        "example"
      ],
      "expected_daily_volume": 1,
      "silence_alert_minutes": 1,
      "health": {
        "last_event_at": "example",
        "events_last_hour": 1,
        "signature_failures": 1,
        "reserved": 1,
        "completed": 1,
        "reserve_to_complete_ratio": 1,
        "coverage_gaps": 1,
        "silent": true,
        "registered_today": 1
      },
      "created_at": "example"
    }
  ]
}
```

---

Page: Create a sending source
URL: https://docs.fromenance.com/api/operations/v1sending-sources/post

# Create a sending source

POST
/v1/sending-sourcesFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/sending-sources \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "name": "example", "kind": "api", "config": { "additionalProperty": "example" }, "expected_daily_volume": 1, "silence_alert_minutes": 1 }'
```

- Production

Returns the webhook URL and the secret to configure at the provider. The secret is shown once. For Postmark the secret is the basic auth pair user:password.

## Authorizations

- Session
- ApiKey

## Request Body

application/json

object

name
required

string
>= 1 characters <= 80 characters

kind
required

string
Allowed values: api journal resend sendgrid ses generic postmark mailgun sfmc braze

config

Adapter specific, encrypted at rest. For example api_key for Resend body retrieval or server_token for Postmark.

object

key
additional properties

string

expected_daily_volume

integer | null

silence_alert_minutes

integer
>= 5 <= 20160

##
Responses

### 201

Source

application/json

object

id
required

string

name
required

string

kind
required

string

status
required

string

webhook_url
required

string | null

needs_reserve
required

boolean

footer_merge_tag
required

string | null

instructions
required

Array<string>

expected_daily_volume
required

integer | null

silence_alert_minutes
required

integer

health
required

object

last_event_at
required

string | null

events_last_hour
required

integer

signature_failures
required

integer

reserved
required

integer

completed
required

integer

reserve_to_complete_ratio
required

number | null

coverage_gaps
required

integer

silent
required

boolean

registered_today
required

integer

created_at
required

string

secret
required

string | null
Examplegenerated

```json
{
  "id": "example",
  "name": "example",
  "kind": "example",
  "status": "example",
  "webhook_url": "example",
  "needs_reserve": true,
  "footer_merge_tag": "example",
  "instructions": [
    "example"
  ],
  "expected_daily_volume": 1,
  "silence_alert_minutes": 1,
  "health": {
    "last_event_at": "example",
    "events_last_hour": 1,
    "signature_failures": 1,
    "reserved": 1,
    "completed": 1,
    "reserve_to_complete_ratio": 1,
    "coverage_gaps": 1,
    "silent": true,
    "registered_today": 1
  },
  "created_at": "example",
  "secret": "example"
}
```

---

Page: Source detail
URL: https://docs.fromenance.com/api/operations/v1sending-sourcesid/get

# Source detail

GET
/v1/sending-sources/{id}FetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/sending-sources/src_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^src_[0-9A-Z]{26}$/
Example

```plaintext
src_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Source

application/json

object

id
required

string

name
required

string

kind
required

string

status
required

string

webhook_url
required

string | null

needs_reserve
required

boolean

footer_merge_tag
required

string | null

instructions
required

Array<string>

expected_daily_volume
required

integer | null

silence_alert_minutes
required

integer

health
required

object

last_event_at
required

string | null

events_last_hour
required

integer

signature_failures
required

integer

reserved
required

integer

completed
required

integer

reserve_to_complete_ratio
required

number | null

coverage_gaps
required

integer

silent
required

boolean

registered_today
required

integer

created_at
required

string
Examplegenerated

```json
{
  "id": "example",
  "name": "example",
  "kind": "example",
  "status": "example",
  "webhook_url": "example",
  "needs_reserve": true,
  "footer_merge_tag": "example",
  "instructions": [
    "example"
  ],
  "expected_daily_volume": 1,
  "silence_alert_minutes": 1,
  "health": {
    "last_event_at": "example",
    "events_last_hour": 1,
    "signature_failures": 1,
    "reserved": 1,
    "completed": 1,
    "reserve_to_complete_ratio": 1,
    "coverage_gaps": 1,
    "silent": true,
    "registered_today": 1
  },
  "created_at": "example"
}
```

---

Page: Delete a source
URL: https://docs.fromenance.com/api/operations/v1sending-sourcesid/delete

# Delete a source

DELETE
/v1/sending-sources/{id}FetchcURL

```sh
curl --request DELETE \
  --url https://api.fromenance.com/v1/sending-sources/src_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^src_[0-9A-Z]{26}$/
Example

```plaintext
src_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Deleted

application/json

object

ok
required

boolean
Example

```json
{
  "ok": true
}
```

---

Page: Update a source
URL: https://docs.fromenance.com/api/operations/v1sending-sourcesid/patch

# Update a source

PATCH
/v1/sending-sources/{id}FetchcURL

```sh
curl --request PATCH \
  --url https://api.fromenance.com/v1/sending-sources/src_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "name": "example", "status": "active", "config": { "additionalProperty": "example" }, "expected_daily_volume": 1, "silence_alert_minutes": 1 }'
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^src_[0-9A-Z]{26}$/
Example

```plaintext
src_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

## Request Body

application/json

object

name

string
>= 1 characters <= 80 characters

status

string
Allowed values: active paused

config

object

key
additional properties

string

expected_daily_volume

integer | null

silence_alert_minutes

integer
>= 5 <= 20160

##
Responses

### 200

Source

application/json

object

id
required

string

name
required

string

kind
required

string

status
required

string

webhook_url
required

string | null

needs_reserve
required

boolean

footer_merge_tag
required

string | null

instructions
required

Array<string>

expected_daily_volume
required

integer | null

silence_alert_minutes
required

integer

health
required

object

last_event_at
required

string | null

events_last_hour
required

integer

signature_failures
required

integer

reserved
required

integer

completed
required

integer

reserve_to_complete_ratio
required

number | null

coverage_gaps
required

integer

silent
required

boolean

registered_today
required

integer

created_at
required

string
Examplegenerated

```json
{
  "id": "example",
  "name": "example",
  "kind": "example",
  "status": "example",
  "webhook_url": "example",
  "needs_reserve": true,
  "footer_merge_tag": "example",
  "instructions": [
    "example"
  ],
  "expected_daily_volume": 1,
  "silence_alert_minutes": 1,
  "health": {
    "last_event_at": "example",
    "events_last_hour": 1,
    "signature_failures": 1,
    "reserved": 1,
    "completed": 1,
    "reserve_to_complete_ratio": 1,
    "coverage_gaps": 1,
    "silent": true,
    "registered_today": 1
  },
  "created_at": "example"
}
```

---

Page: Rotate the webhook secret
URL: https://docs.fromenance.com/api/operations/v1sending-sourcesidrotate-secret

# Rotate the webhook secret

POST
/v1/sending-sources/{id}/rotate-secretFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/sending-sources/src_01J8Z9X0Q3K4M5N6P7R8S9T0V1/rotate-secret \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^src_[0-9A-Z]{26}$/
Example

```plaintext
src_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

New secret, shown once

application/json

object

secret
required

string
Examplegenerated

```json
{
  "secret": "example"
}
```

---

Page: Run a synthetic send event through the adapter
URL: https://docs.fromenance.com/api/operations/v1sending-sourcesidtest-event

# Run a synthetic send event through the adapter

POST
/v1/sending-sources/{id}/test-eventFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/sending-sources/src_01J8Z9X0Q3K4M5N6P7R8S9T0V1/test-event \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

Registers a sandbox communication for a test recipient so the integration engineer can see the source turn green without touching the provider.

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^src_[0-9A-Z]{26}$/
Example

```plaintext
src_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Result

application/json

object

ok
required

boolean

communication_id
required

string

verify_code
required

string
Example

```json
{
  "ok": true
}
```

---

Page: All four reply templates
URL: https://docs.fromenance.com/api/operations/v1reply-templates

# All four reply templates

GET
/v1/reply-templatesFetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/reply-templates \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Responses

### 200

Templates

application/json

object

data
required

Array<object>

object

outcome
required

string

subject
required

string

body_mjml
required

string

locked_block_version
required

integer

locked_block_text
required

string

updated_at
required

string

is_default
required

boolean

variables
required

Array<string>
Examplegenerated

```json
{
  "data": [
    {
      "outcome": "example",
      "subject": "example",
      "body_mjml": "example",
      "locked_block_version": 1,
      "locked_block_text": "example",
      "updated_at": "example",
      "is_default": true
    }
  ],
  "variables": [
    "example"
  ]
}
```

---

Page: Update a template
URL: https://docs.fromenance.com/api/operations/v1reply-templatesoutcome

# Update a template

PUT
/v1/reply-templates/{outcome}FetchcURL

```sh
curl --request PUT \
  --url https://api.fromenance.com/v1/reply-templates/verified \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "subject": "example", "body_mjml": "example" }'
```

- Production

The body must include {{verdict_block}}; the locked verdict text cannot be edited and vouching language is refused.

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

outcome
required

string
Allowed values: verified not_verified not_verified_authoritative known_fraud

## Request Body

application/json

object

subject
required

string
>= 1 characters <= 200 characters

body_mjml
required

string
>= 20 characters <= 50000 characters
Examplegenerated

```json
{
  "subject": "example",
  "body_mjml": "example"
}
```

##
Responses

### 200

Template

application/json

object

outcome
required

string

subject
required

string

body_mjml
required

string

locked_block_version
required

integer

locked_block_text
required

string

updated_at
required

string

is_default
required

boolean
Examplegenerated

```json
{
  "outcome": "example",
  "subject": "example",
  "body_mjml": "example",
  "locked_block_version": 1,
  "locked_block_text": "example",
  "updated_at": "example",
  "is_default": true
}
```

---

Page: Render a template with sample data
URL: https://docs.fromenance.com/api/operations/v1reply-templatesoutcomepreview

# Render a template with sample data

POST
/v1/reply-templates/{outcome}/previewFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/reply-templates/verified/preview \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "subject": "example", "body_mjml": "example" }'
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

outcome
required

string
Allowed values: verified not_verified not_verified_authoritative known_fraud

## Request Body

application/json

object

subject

string

body_mjml

string
Examplegenerated

```json
{
  "subject": "example",
  "body_mjml": "example"
}
```

##
Responses

### 200

Rendered

application/json

object

subject
required

string

html
required

string

text
required

string

errors
required

Array<string>

from
required

string
Examplegenerated

```json
{
  "subject": "example",
  "html": "example",
  "text": "example",
  "errors": [
    "example"
  ],
  "from": "example"
}
```

---

Page: Send a test reply to yourself
URL: https://docs.fromenance.com/api/operations/v1reply-templatesoutcometest

# Send a test reply to yourself

POST
/v1/reply-templates/{outcome}/testFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/reply-templates/verified/test \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "to": "hello@example.com" }'
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

outcome
required

string
Allowed values: verified not_verified not_verified_authoritative known_fraud

## Request Body

application/json

object

to

string format: email
Examplegenerated

```json
{
  "to": "hello@example.com"
}
```

##
Responses

### 200

Sent

application/json

object

ok
required

boolean

to
required

string

from
required

string

id
required

string
Example

```json
{
  "ok": true
}
```

---

Page: List endpoints
URL: https://docs.fromenance.com/api/operations/v1webhook-endpoints/get

# List endpoints

GET
/v1/webhook-endpointsFetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/webhook-endpoints \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Responses

### 200

Endpoints

application/json

object

data
required

Array<object>

object

id
required

string

url
required

string

events
required

Array<string>

status
required

string

description
required

string | null

last_delivery_at
required

string | null

last_status
required

integer | null

created_at
required

string

events
required

Array<string>
Examplegenerated

```json
{
  "data": [
    {
      "id": "example",
      "url": "example",
      "events": [
        "example"
      ],
      "status": "example",
      "description": "example",
      "last_delivery_at": "example",
      "last_status": 1,
      "created_at": "example"
    }
  ],
  "events": [
    "example"
  ]
}
```

---

Page: Create an endpoint
URL: https://docs.fromenance.com/api/operations/v1webhook-endpoints/post

# Create an endpoint

POST
/v1/webhook-endpointsFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/webhook-endpoints \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "url": "https://example.com", "events": [ "verdict.created" ], "description": "example" }'
```

- Production

Deliveries are signed with HMAC-SHA256 over timestamp.body using the returned secret (shown once), sent as X-Fromenance-Signature: v1= with X-Fromenance-Timestamp. Retried with backoff for 24 hours.

## Authorizations

- Session
- ApiKey

## Request Body

application/json

object

url
required

string format: uri
<= 500 characters

events

Array<string>
>= 1 items
Allowed values: verdict.created submission.replay_detected indicator.new campaign.detected

description

string
<= 200 characters

##
Responses

### 201

Endpoint with secret

application/json

object

id
required

string

url
required

string

events
required

Array<string>

status
required

string

description
required

string | null

last_delivery_at
required

string | null

last_status
required

integer | null

created_at
required

string

secret
required

string
Examplegenerated

```json
{
  "id": "example",
  "url": "example",
  "events": [
    "example"
  ],
  "status": "example",
  "description": "example",
  "last_delivery_at": "example",
  "last_status": 1,
  "created_at": "example",
  "secret": "example"
}
```

---

Page: Delete an endpoint
URL: https://docs.fromenance.com/api/operations/v1webhook-endpointsid/delete

# Delete an endpoint

DELETE
/v1/webhook-endpoints/{id}FetchcURL

```sh
curl --request DELETE \
  --url https://api.fromenance.com/v1/webhook-endpoints/whe_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^whe_[0-9A-Z]{26}$/
Example

```plaintext
whe_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Deleted

application/json

object

ok
required

boolean
Example

```json
{
  "ok": true
}
```

---

Page: Update an endpoint
URL: https://docs.fromenance.com/api/operations/v1webhook-endpointsid/patch

# Update an endpoint

PATCH
/v1/webhook-endpoints/{id}FetchcURL

```sh
curl --request PATCH \
  --url https://api.fromenance.com/v1/webhook-endpoints/whe_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "url": "https://example.com", "events": [ "verdict.created" ], "status": "active", "description": "example" }'
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^whe_[0-9A-Z]{26}$/
Example

```plaintext
whe_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

## Request Body

application/json

object

url

string format: uri
<= 500 characters

events

Array<string>
>= 1 items
Allowed values: verdict.created submission.replay_detected indicator.new campaign.detected

status

string
Allowed values: active paused

description

string | null
<= 200 characters

##
Responses

### 200

Endpoint

application/json

object

id
required

string

url
required

string

events
required

Array<string>

status
required

string

description
required

string | null

last_delivery_at
required

string | null

last_status
required

integer | null

created_at
required

string
Examplegenerated

```json
{
  "id": "example",
  "url": "example",
  "events": [
    "example"
  ],
  "status": "example",
  "description": "example",
  "last_delivery_at": "example",
  "last_status": 1,
  "created_at": "example"
}
```

---

Page: Delivery log
URL: https://docs.fromenance.com/api/operations/v1webhook-endpointsiddeliveries

# Delivery log

GET
/v1/webhook-endpoints/{id}/deliveriesFetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/webhook-endpoints/whe_01J8Z9X0Q3K4M5N6P7R8S9T0V1/deliveries \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^whe_[0-9A-Z]{26}$/
Example

```plaintext
whe_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Deliveries

application/json

object

data
required

Array<object>

object

id
required

string

endpoint_id
required

string

event
required

string

status
required

string

attempts
required

integer

last_status_code
required

integer | null

last_error
required

string | null

next_attempt_at
required

string | null

delivered_at
required

string | null

replay_of
required

string | null

payload
required

object

key
additional properties

created_at
required

string
Examplegenerated

```json
{
  "data": [
    {
      "id": "example",
      "endpoint_id": "example",
      "event": "example",
      "status": "example",
      "attempts": 1,
      "last_status_code": 1,
      "last_error": "example",
      "next_attempt_at": "example",
      "delivered_at": "example",
      "replay_of": "example",
      "payload": {
        "additionalProperty": "example"
      },
      "created_at": "example"
    }
  ]
}
```

---

Page: Replay a delivery
URL: https://docs.fromenance.com/api/operations/v1webhook-endpointsiddeliveriesdelivery_idreplay

# Replay a delivery

POST
/v1/webhook-endpoints/{id}/deliveries/{delivery_id}/replayFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/webhook-endpoints/example/deliveries/example/replay \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string

delivery_id
required

string

##
Responses

### 200

New delivery

application/json

object

id
required

string

endpoint_id
required

string

event
required

string

status
required

string

attempts
required

integer

last_status_code
required

integer | null

last_error
required

string | null

next_attempt_at
required

string | null

delivered_at
required

string | null

replay_of
required

string | null

payload
required

object

key
additional properties

created_at
required

string
Examplegenerated

```json
{
  "id": "example",
  "endpoint_id": "example",
  "event": "example",
  "status": "example",
  "attempts": 1,
  "last_status_code": 1,
  "last_error": "example",
  "next_attempt_at": "example",
  "delivered_at": "example",
  "replay_of": "example",
  "payload": {
    "additionalProperty": "example"
  },
  "created_at": "example"
}
```

---

Page: Send a test verdict.created event
URL: https://docs.fromenance.com/api/operations/v1webhook-endpointsidtest

# Send a test verdict.created event

POST
/v1/webhook-endpoints/{id}/testFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/webhook-endpoints/whe_01J8Z9X0Q3K4M5N6P7R8S9T0V1/test \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^whe_[0-9A-Z]{26}$/
Example

```plaintext
whe_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Delivery ids

application/json

object

delivery_ids
required

Array<string>
Examplegenerated

```json
{
  "delivery_ids": [
    "example"
  ]
}
```

---

Page: Daily counts: registered, submitted, by outcome, by source, reply p95
URL: https://docs.fromenance.com/api/operations/v1stats

# Daily counts: registered, submitted, by outcome, by source, reply p95

GET
/v1/statsFetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/stats \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey
read

##
Parameters

### Query Parameters

days

1 to 365, default 30

string

1 to 365, default 30

##
Responses

### 200

Stats

application/json

object

range
required

object

from
required

string

to
required

string

days
required

integer

totals
required

object

registered
required

integer

submitted
required

integer

verified
required

integer

not_verified
required

integer

known_fraud
required

integer

replays
required

integer

forwards
required

integer

web
required

integer

reply_p95_ms
required

integer | null

reply_avg_ms
required

integer | null

coverage_gaps
required

integer

code_found_rate
required

number | null

today
required

object

day
required

string

registered
required

integer

submitted
required

integer

verified
required

integer

not_verified
required

integer

known_fraud
required

integer

replays
required

integer

forwards
required

integer

web
required

integer

reply_p95_ms
required

integer | null

by_source
required

object

key
additional properties

number

days
required

Array<object>

object

day
required

string

registered
required

integer

submitted
required

integer

verified
required

integer

not_verified
required

integer

known_fraud
required

integer

replays
required

integer

forwards
required

integer

web
required

integer

reply_p95_ms
required

integer | null

by_source
required

object

key
additional properties

number

coverage
required

Array<object>

object

source_id
required

string

name
required

string

kind
required

string

registered
required

integer

expected
required

integer | null

coverage
required

number | null

top_indicators
required

Array<object>

object

kind
required

string

value
required

string

submission_count
required

integer

last_seen
required

string

marked_fraud
required

boolean

authoritative_mode
required

boolean
Examplegenerated

```json
{
  "range": {
    "from": "example",
    "to": "example",
    "days": 1
  },
  "totals": {
    "registered": 1,
    "submitted": 1,
    "verified": 1,
    "not_verified": 1,
    "known_fraud": 1,
    "replays": 1,
    "forwards": 1,
    "web": 1,
    "reply_p95_ms": 1,
    "reply_avg_ms": 1,
    "coverage_gaps": 1,
    "code_found_rate": 1
  },
  "today": {
    "day": "example",
    "registered": 1,
    "submitted": 1,
    "verified": 1,
    "not_verified": 1,
    "known_fraud": 1,
    "replays": 1,
    "forwards": 1,
    "web": 1,
    "reply_p95_ms": 1,
    "by_source": {
      "additionalProperty": 1
    }
  },
  "days": [
    {
      "day": "example",
      "registered": 1,
      "submitted": 1,
      "verified": 1,
      "not_verified": 1,
      "known_fraud": 1,
      "replays": 1,
      "forwards": 1,
      "web": 1,
      "reply_p95_ms": 1,
      "by_source": {
        "additionalProperty": 1
      }
    }
  ],
  "coverage": [
    {
      "source_id": "example",
      "name": "example",
      "kind": "example",
      "registered": 1,
      "expected": 1,
      "coverage": 1
    }
  ],
  "top_indicators": [
    {
      "kind": "example",
      "value": "example",
      "submission_count": 1,
      "last_seen": "example",
      "marked_fraud": true
    }
  ],
  "authoritative_mode": true
}
```

---

Page: Current user and tenant memberships
URL: https://docs.fromenance.com/api/operations/v1me

# Current user and tenant memberships

GET
/v1/meFetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/me \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session

##
Responses

### 200

Me

application/json

object

user
required

object

id
required

string

email
required

string

name
required

string | null

platform
required

boolean

memberships
required

Array<object>

object

membership_id
required

string

tenant_id
required

string

tenant_slug
required

string

tenant_name
required

string

role
required

string
Examplegenerated

```json
{
  "user": {
    "id": "example",
    "email": "example",
    "name": "example"
  },
  "platform": true,
  "memberships": [
    {
      "membership_id": "example",
      "tenant_id": "example",
      "tenant_slug": "example",
      "tenant_name": "example",
      "role": "example"
    }
  ]
}
```

---

Page: Current tenant
URL: https://docs.fromenance.com/api/operations/v1tenant/get

# Current tenant

GET
/v1/tenantFetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/tenant \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Responses

### 200

Tenant

application/json

object

id
required

string

slug
required

string

name
required

string

plan
required

string

status
required

string

authoritative_mode
required

boolean

authoritative_since
required

string | null

retention_days
required

integer

reply_mode
required

Any of:

- string
- string

string
Allowed values: minimal branded

reply_from_name
required

string | null

reply_domain_id
required

string | null

fraud_contact
required

string | null

verify_page_url
required

string | null

verify_address
required

string

journal_address
required

string

minimal_reply_address
required

string

branding
required

object

key
additional properties

match_threshold
required

integer

sandbox
required

boolean

expected_daily_volume
required

integer | null

created_at
required

string
Example

```json
{
  "reply_mode": "minimal"
}
```

### 401

Unauthorized

application/problem+json

object

type
required

string

title
required

string

status
required

integer

detail

string

instance

string

errors

Present on validation problems.

Array<object>

object

path
required

string

message
required

string

request_id

string
Example

```json
{
  "type": "https://docs.fromenance.com/api/errors#validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "recipient_hash must start with hmac-sha256:",
  "instance": "/v1/communications"
}
```

---

Page: Update tenant settings
URL: https://docs.fromenance.com/api/operations/v1tenant/patch

# Update tenant settings

PATCH
/v1/tenantFetchcURL

```sh
curl --request PATCH \
  --url https://api.fromenance.com/v1/tenant \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "name": "example", "reply_mode": "minimal", "reply_from_name": "example", "reply_domain_id": "example", "fraud_contact": "example", "verify_page_url": "https://example.com", "branding": { "logoUrl": "https://example.com", "accent": "example", "displayName": "example", "supportUrl": "https://example.com" }, "match_threshold": 1, "retention_days": 1, "expected_daily_volume": 1 }'
```

- Production

Authoritative Mode and plan are read only here; a backoffice operator sets them.

## Authorizations

- Session
- ApiKey

## Request Body

application/json

object

name

string
>= 2 characters <= 120 characters

reply_mode

string
Allowed values: minimal branded

reply_from_name

string
<= 120 characters

reply_domain_id

string | null

fraud_contact

string
<= 200 characters

verify_page_url

string format: uri
<= 300 characters

branding

object

logoUrl

string format: uri

accent

string
<= 20 characters

displayName

string
<= 120 characters

supportUrl

string format: uri

match_threshold

integer
<= 20

retention_days

integer
>= 7 <= 730

expected_daily_volume

integer | null

##
Responses

### 200

Tenant

application/json

object

id
required

string

slug
required

string

name
required

string

plan
required

string

status
required

string

authoritative_mode
required

boolean

authoritative_since
required

string | null

retention_days
required

integer

reply_mode
required

Any of:

- string
- string

string
Allowed values: minimal branded

reply_from_name
required

string | null

reply_domain_id
required

string | null

fraud_contact
required

string | null

verify_page_url
required

string | null

verify_address
required

string

journal_address
required

string

minimal_reply_address
required

string

branding
required

object

key
additional properties

match_threshold
required

integer

sandbox
required

boolean

expected_daily_volume
required

integer | null

created_at
required

string
Example

```json
{
  "reply_mode": "minimal"
}
```

### 403

Forbidden

application/problem+json

object

type
required

string

title
required

string

status
required

integer

detail

string

instance

string

errors

Present on validation problems.

Array<object>

object

path
required

string

message
required

string

request_id

string
Example

```json
{
  "type": "https://docs.fromenance.com/api/errors#validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "recipient_hash must start with hmac-sha256:",
  "instance": "/v1/communications"
}
```

---

Page: List tenant users
URL: https://docs.fromenance.com/api/operations/v1users/get

# List tenant users

GET
/v1/usersFetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/users \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Responses

### 200

Users

application/json

object

data
required

Array<object>

object

id
required

string

email
required

string

name
required

string | null

role
required

string
Allowed values: owner admin analyst integrator viewer

status
required

string

invited_at
required

string | null

accepted_at
required

string | null

last_seen_at
required

string | null

created_at
required

string
Example

```json
{
  "data": [
    {
      "role": "owner"
    }
  ]
}
```

---

Page: Invite a user
URL: https://docs.fromenance.com/api/operations/v1users/post

# Invite a user

POST
/v1/usersFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/users \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "email": "hello@example.com", "role": "owner", "name": "example" }'
```

- Production

Creates the membership and emails a sign in link. The invitee signs in with a magic link or passkey.

## Authorizations

- Session
- ApiKey

## Request Body

application/json

object

email
required

string format: email
<= 320 characters

role

string
Allowed values: owner admin analyst integrator viewer

name

string
<= 120 characters

##
Responses

### 201

Invited

application/json

object

id
required

string

email
required

string

name
required

string | null

role
required

string
Allowed values: owner admin analyst integrator viewer

status
required

string

invited_at
required

string | null

accepted_at
required

string | null

last_seen_at
required

string | null

created_at
required

string
Example

```json
{
  "role": "owner"
}
```

### 409

Already a member

application/problem+json

object

type
required

string

title
required

string

status
required

integer

detail

string

instance

string

errors

Present on validation problems.

Array<object>

object

path
required

string

message
required

string

request_id

string
Example

```json
{
  "type": "https://docs.fromenance.com/api/errors#validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "recipient_hash must start with hmac-sha256:",
  "instance": "/v1/communications"
}
```

---

Page: Remove a user from the tenant
URL: https://docs.fromenance.com/api/operations/v1usersid/delete

# Remove a user from the tenant

DELETE
/v1/users/{id}FetchcURL

```sh
curl --request DELETE \
  --url https://api.fromenance.com/v1/users/usr_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^usr_[0-9A-Z]{26}$/
Example

```plaintext
usr_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Removed

application/json

object

ok
required

boolean
Example

```json
{
  "ok": true
}
```

---

Page: Change a user's role
URL: https://docs.fromenance.com/api/operations/v1usersid/patch

# Change a user's role

PATCH
/v1/users/{id}FetchcURL

```sh
curl --request PATCH \
  --url https://api.fromenance.com/v1/users/usr_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "role": "owner" }'
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^usr_[0-9A-Z]{26}$/
Example

```plaintext
usr_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

## Request Body

application/json

object

role
required

string
Allowed values: owner admin analyst integrator viewer

##
Responses

### 200

User

application/json

object

id
required

string

email
required

string

name
required

string | null

role
required

string
Allowed values: owner admin analyst integrator viewer

status
required

string

invited_at
required

string | null

accepted_at
required

string | null

last_seen_at
required

string | null

created_at
required

string
Example

```json
{
  "role": "owner"
}
```

---

Page: List API keys
URL: https://docs.fromenance.com/api/operations/v1api-keys/get

# List API keys

GET
/v1/api-keysFetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/api-keys \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Responses

### 200

Keys

application/json

object

data
required

Array<object>

object

id
required

string

name
required

string

prefix
required

string

mode
required

string
Allowed values: live test

scopes
required

Array<string>
Allowed values: register read admin

last_used_at
required

string | null

revoked_at
required

string | null

created_at
required

string
Example

```json
{
  "data": [
    {
      "mode": "live",
      "scopes": [
        "register"
      ]
    }
  ]
}
```

---

Page: Mint an API key
URL: https://docs.fromenance.com/api/operations/v1api-keys/post

# Mint an API key

POST
/v1/api-keysFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/api-keys \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "name": "example", "mode": "live", "scopes": [ "register" ] }'
```

- Production

The secret is returned once and never stored. Test keys write to a sandbox partition and never send replies to real addresses.

## Authorizations

- Session
- ApiKey

## Request Body

application/json

object

name
required

string
>= 1 characters <= 80 characters

mode

string
Allowed values: live test

scopes

Array<string>
>= 1 items
Allowed values: register read admin

##
Responses

### 201

Key

application/json

object

id
required

string

name
required

string

prefix
required

string

mode
required

string
Allowed values: live test

scopes
required

Array<string>
Allowed values: register read admin

last_used_at
required

string | null

revoked_at
required

string | null

created_at
required

string

secret
required

string
Example

```json
{
  "mode": "live",
  "scopes": [
    "register"
  ]
}
```

---

Page: Revoke an API key
URL: https://docs.fromenance.com/api/operations/v1api-keysid

# Revoke an API key

DELETE
/v1/api-keys/{id}FetchcURL

```sh
curl --request DELETE \
  --url https://api.fromenance.com/v1/api-keys/key_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^key_[0-9A-Z]{26}$/
Example

```plaintext
key_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Revoked

application/json

object

id
required

string

name
required

string

prefix
required

string

mode
required

string
Allowed values: live test

scopes
required

Array<string>
Allowed values: register read admin

last_used_at
required

string | null

revoked_at
required

string | null

created_at
required

string
Example

```json
{
  "mode": "live",
  "scopes": [
    "register"
  ]
}
```

---

Page: Audit log
URL: https://docs.fromenance.com/api/operations/v1audit

# Audit log

GET
/v1/auditFetchcURL

```sh
curl --request GET \
  --url 'https://api.fromenance.com/v1/audit?limit=50' \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Query Parameters

cursor

Opaque cursor from a previous response.

string

Opaque cursor from a previous response.

limit

Page size, 1 to 200, default 50.

string
Example

```json
50
```

Page size, 1 to 200, default 50.

action

string

##
Responses

### 200

Entries

application/json

object

data
required

Array<object>

object

id
required

string

actor_id
required

string | null

actor_email
required

string | null

actor_kind
required

string

action
required

string

target
required

string | null

target_id
required

string | null

before

after

impersonating
required

boolean

at
required

string

next_cursor
required

string | null
Examplegenerated

```json
{
  "data": [
    {
      "id": "example",
      "actor_id": "example",
      "actor_email": "example",
      "actor_kind": "example",
      "action": "example",
      "target": "example",
      "target_id": "example",
      "before": "example",
      "after": "example",
      "impersonating": true,
      "at": "example"
    }
  ],
  "next_cursor": "example"
}
```

---

Page: List site keys with embed snippets
URL: https://docs.fromenance.com/api/operations/v1site-keys/get

# List site keys with embed snippets

GET
/v1/site-keysFetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/site-keys \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Responses

### 200

Site keys

application/json

object

data
required

Array<object>

object

id
required

string

name
required

string

public_key
required

string

allowed_origins
required

Array<string>

theme
required

object

key
additional properties

string

turnstile_required
required

boolean

normal_rate_per_minute
required

integer

revoked_at
required

string | null

embed
required

object

script
required

string

iframe
required

string

created_at
required

string
Examplegenerated

```json
{
  "data": [
    {
      "id": "example",
      "name": "example",
      "public_key": "example",
      "allowed_origins": [
        "example"
      ],
      "theme": {
        "additionalProperty": "example"
      },
      "turnstile_required": true,
      "normal_rate_per_minute": 1,
      "revoked_at": "example",
      "embed": {
        "script": "example",
        "iframe": "example"
      },
      "created_at": "example"
    }
  ]
}
```

---

Page: Create a site key
URL: https://docs.fromenance.com/api/operations/v1site-keys/post

# Create a site key

POST
/v1/site-keysFetchcURL

```sh
curl --request POST \
  --url https://api.fromenance.com/v1/site-keys \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "name": "example", "allowed_origins": [ "https://example.com" ], "theme": { "additionalProperty": "example" }, "turnstile_required": true, "normal_rate_per_minute": 1 }'
```

- Production

## Authorizations

- Session
- ApiKey

## Request Body

application/json

object

name

string
>= 1 characters <= 80 characters

allowed_origins

Array<string>
<= 20 items

theme

object

key
additional properties

string

turnstile_required

boolean

normal_rate_per_minute

integer
>= 5 <= 6000
Examplegenerated

```json
{
  "name": "example",
  "allowed_origins": [
    "https://example.com"
  ],
  "theme": {
    "additionalProperty": "example"
  },
  "turnstile_required": true,
  "normal_rate_per_minute": 1
}
```

##
Responses

### 201

Site key

application/json

object

id
required

string

name
required

string

public_key
required

string

allowed_origins
required

Array<string>

theme
required

object

key
additional properties

string

turnstile_required
required

boolean

normal_rate_per_minute
required

integer

revoked_at
required

string | null

embed
required

object

script
required

string

iframe
required

string

created_at
required

string
Examplegenerated

```json
{
  "id": "example",
  "name": "example",
  "public_key": "example",
  "allowed_origins": [
    "example"
  ],
  "theme": {
    "additionalProperty": "example"
  },
  "turnstile_required": true,
  "normal_rate_per_minute": 1,
  "revoked_at": "example",
  "embed": {
    "script": "example",
    "iframe": "example"
  },
  "created_at": "example"
}
```

---

Page: Revoke a site key
URL: https://docs.fromenance.com/api/operations/v1site-keysid/delete

# Revoke a site key

DELETE
/v1/site-keys/{id}FetchcURL

```sh
curl --request DELETE \
  --url https://api.fromenance.com/v1/site-keys/sk_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^sk_[0-9A-Z]{26}$/
Example

```plaintext
sk_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

##
Responses

### 200

Revoked

application/json

object

ok
required

boolean
Example

```json
{
  "ok": true
}
```

---

Page: Update a site key
URL: https://docs.fromenance.com/api/operations/v1site-keysid/patch

# Update a site key

PATCH
/v1/site-keys/{id}FetchcURL

```sh
curl --request PATCH \
  --url https://api.fromenance.com/v1/site-keys/sk_01J8Z9X0Q3K4M5N6P7R8S9T0V1 \
  --header 'Content-Type: application/json' \
  --cookie fromenance.session_token=<fromenance.session_token> \
  --data '{ "name": "example", "allowed_origins": [ "https://example.com" ], "theme": { "additionalProperty": "example" }, "turnstile_required": true, "normal_rate_per_minute": 1 }'
```

- Production

## Authorizations

- Session
- ApiKey

##
Parameters

### Path Parameters

id
required

string
/^sk_[0-9A-Z]{26}$/
Example

```plaintext
sk_01J8Z9X0Q3K4M5N6P7R8S9T0V1
```

## Request Body

application/json

object

name

string
>= 1 characters <= 80 characters

allowed_origins

Array<string>
<= 20 items

theme

object

key
additional properties

string

turnstile_required

boolean

normal_rate_per_minute

integer
>= 5 <= 6000
Examplegenerated

```json
{
  "name": "example",
  "allowed_origins": [
    "https://example.com"
  ],
  "theme": {
    "additionalProperty": "example"
  },
  "turnstile_required": true,
  "normal_rate_per_minute": 1
}
```

##
Responses

### 200

Site key

application/json

object

id
required

string

name
required

string

public_key
required

string

allowed_origins
required

Array<string>

theme
required

object

key
additional properties

string

turnstile_required
required

boolean

normal_rate_per_minute
required

integer

revoked_at
required

string | null

embed
required

object

script
required

string

iframe
required

string

created_at
required

string
Examplegenerated

```json
{
  "id": "example",
  "name": "example",
  "public_key": "example",
  "allowed_origins": [
    "example"
  ],
  "theme": {
    "additionalProperty": "example"
  },
  "turnstile_required": true,
  "normal_rate_per_minute": 1,
  "revoked_at": "example",
  "embed": {
    "script": "example",
    "iframe": "example"
  },
  "created_at": "example"
}
```

---

Page: Search submissions, registrations, and indicators
URL: https://docs.fromenance.com/api/operations/v1search

# Search submissions, registrations, and indicators

GET
/v1/searchFetchcURL

```sh
curl --request GET \
  --url 'https://api.fromenance.com/v1/search?q=example' \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey
read

##
Parameters

### Query Parameters

q
required

string
>= 2 characters <= 200 characters

##
Responses

### 200

Hits

application/json

object

hits
required

Array<object>

object

kind
required

string
Allowed values: submission communication indicator

id
required

string

title
required

string

subtitle
required

string

href
required

string
Example

```json
{
  "hits": [
    {
      "kind": "submission"
    }
  ]
}
```

---

Page: Onboarding progress derived from tenant state
URL: https://docs.fromenance.com/api/operations/v1setup

# Onboarding progress derived from tenant state

GET
/v1/setupFetchcURL

```sh
curl --request GET \
  --url https://api.fromenance.com/v1/setup \
  --cookie fromenance.session_token=<fromenance.session_token>
```

- Production

## Authorizations

- Session
- ApiKey

##
Responses

### 200

Progress

application/json

object

steps
required

object

tenant
required

boolean

domain_verified
required

boolean

forwarding_working
required

boolean

reply_identity
required

boolean

first_stream
required

boolean

footer_deployed
required

boolean

live
required

boolean

domains
required

Array<object>

object

id
required

string

domain
required

string

status
required

string

forwarding
required

object

status
required

string
Allowed values: not_started sent working failed

sent_at
required

string | null

passed_at
required

string | null

result
required

string | null

to
required

string
Example

```json
{
  "domains": [
    {
      "forwarding": {
        "status": "not_started"
      }
    }
  ]
}
```

---

Page: Security
URL: https://docs.fromenance.com/security

# Security

Fromenance is a communication provenance platform that asks institutions to route customer mail through it, so the security posture has to be finished before the first pilot rather than after. This page is the public overview; a DPA and answers to a full vendor questionnaire are available from your Fromenance contact.

By the end you will know how tenants are isolated, what is encrypted with which key, why the verdict path is deterministic, who the subprocessors are, and how to report a vulnerability.

## Threat model in one paragraph

The customer facing question is “did my institution send this?”. The attacker’s goals are to make a lure verify, to make a real message fail, to learn who a message was sent to, or to read other institutions’ data. The design answers each: verify codes are recipient bound and checksummed, so a copied footer resolves to Not verified and is flagged as a replay; matching is deterministic, so there is no model to prompt; recipients exist only as keyed hashes; and every tenant owned row carries a tenant id enforced in the data layer.

## Tenant isolation

- Every tenant owned table has tenant_id , and every query runs through a scoped repository that requires it. Route handlers cannot build cross tenant queries.

- Object storage keys are prefixed per tenant. API keys and site keys are bound to one tenant.

- An automated suite asserts no cross tenant read on every endpoint on every change.

- Fromenance operators can see per tenant health, rejected inbound reasons, and cross tenant indicator counts. They cannot see submissions or raw mail through those views.

## Encryption and keys

| Data
| Protection
|

| Submitter addresses, subjects, source configuration, webhook and source secrets, the recipient hashing secret
| AES-256-GCM under a per tenant data key
|

| Raw MIME and screenshots
| AES-256-GCM under the tenant data key, stored in Cloudflare R2 under a per tenant prefix, deleted at the end of the retention window with an audit record
|

| Per tenant data keys
| Wrapped by a master key that exists only in the Worker runtime’s secret store, never in code or configuration files
|

| API keys
| SHA-256 hashed at rest, shown once, scoped, revocable, with last use tracking
|

| Recipient addresses
| Never stored. Registrations carry hmac-sha256:<hex> computed with a per tenant secret; the raw address is hashed in your process before the call and rejected by the API if sent in clear
|

| Content
| Never stored in normalized form. A 64 bit SimHash and a SHA-256 are one way
|

| Transport
| TLS everywhere; the API is served only over HTTPS
|

Secrets rotate: the master key yearly, database and object storage credentials quarterly. There are no long lived credentials in the repository or in CI configuration.

## No model on the verdict path

Extraction and matching are regular expressions, MIME parsing, SimHash, and HMAC comparison. Where a vision model is used to read a screenshot, its output is treated as untrusted text that only feeds those same deterministic extractors; it cannot change a verdict. If a language model is added later for lure classification, its output will be a label in a fixed schema that can never change a verdict from Verified. Prompt injection through a forwarded message has no target.

## Inbound trust

Mail to a tenant inbox is processed only when it authenticates for a domain the tenant owns: a DKIM signature that verifies for the domain or an ARC chain whose last seal is by it, checked by Fromenance itself on the raw message, and a _fromenance.<domain> TXT record whose token matches the tenant. Anything else is held for 24 hours for diagnosis and never answered. Details in Domains and mail .

Replies never quote the forwarded message, never include its links or its sender, state only whether a registered communication matches, and are sent only to the customer who asked, from the tenant’s reply identity.

## Abuse handling

- The verify page is rate limited per IP and per site key, requires an allowed origin, and escalates to Cloudflare Turnstile when a key exceeds its normal rate.

- Anyone can forward anything through a tenant’s rule, including attempts to poison the fraud list. Fraud list entries come only from analyst action or confirmed campaign clustering, never from a single submission.

- Footer replay is reported to the customer as Not verified and flagged internally with high priority.

- Provider webhook signatures are verified on every request with a 5 minute replay window where the provider supplies a timestamp. Outbound webhooks are HMAC-SHA256 signed with a per endpoint secret.

## Platform

| Layer
| Provider
|

| API, inbound processing, queues, cron, edge lookups, object storage, OCR
| Cloudflare Workers, Queues, D1, R2, Workers AI
|

| System of record
| Neon Postgres
|

| Email in and out
| Resend
|

| Billing
| Stripe
|

| Error monitoring
| Sentry
|

Admin sign in is by magic link or passkey through Better Auth. Operator access sits behind Cloudflare Access with a hardware key requirement on top of application auth, and every operator action is audited. Deployments run only from CI on the main branch, with dependency scanning.

## Subprocessors

Cloudflare (compute, storage, queues, edge network), Neon (Postgres), Resend (email delivery and inbound), Stripe (billing). Sentry receives error events that contain request ids and stack traces, not message content. The DPA lists each with its role and region.

## Data residency and retention

All storage and processing is in the United States. Retention defaults to 90 days and is tenant configurable from 7 to 730 days; submitter addresses are purged 30 days after the reply; rejected inbound is deleted after 24 hours. Full detail on Retention and privacy .

## Compliance roadmap

SOC 2 Type 1 is targeted within 12 months of the first paying tenant. Until then the controls above, the DPA, and the tenant isolation test suite results are available for review.

## Responsible disclosure

Report vulnerabilities to security@fromenance.com . Include the request id or URL, steps to reproduce, and the impact you believe it has. You will get an acknowledgement within two business days and a status update when the issue is triaged. Please do not test against tenants you do not own, do not access data that is not yours, and give us reasonable time to fix before disclosing publicly. We do not pursue legal action against good faith research that follows these rules.

---

Page: Changelog
URL: https://docs.fromenance.com/changelog

# Changelog

Fromenance is a communication provenance platform, and this changelog records what shipped in each release of the API, the verify widget, and the admin app. Dates are the month the release went live.

By the end you will know what the current release contains and where breaking changes will be announced.

## 2026-09: initial release

The whole of Phase 1, verification, in one release.

Foundation and core

- Bun monorepo with the API, admin app, marketing site, docs site, and the shared core, database, UI, and verify widget packages.

- Deterministic normalization, 64 bit SimHash over word 3-gram shingles, Hamming distance matching, checksummed Crockford verify codes, recipient HMAC, and indicator extraction, producing identical results in Node, Bun, and Cloudflare Workers.

- Drizzle schema for every table with tenant_id on every tenant owned table and no raw recipient column; tenant scoped repository; migrations; demo tenant seed.

API and registry (Gate 1)

- API keys with fr_live_ and fr_test_ prefixes and register , read , admin scopes; site keys with origin checks; magic link and passkey sessions.

- Tenants, users, five roles, audit log on every write.

- Domains with the _fromenance.<domain> TXT record, one minute polling, daily re-check, suspension on a missing record, and the roles trust , sender , reply .

- POST /v1/communications , /batch (1,000 items), /reserve , PATCH complete, Idempotency-Key stored 24 hours, per key rate limits.

- Edge mirror of tenants, domains, keys, and active verify codes for sub 150 ms registration and lookups.

- Dependency free reference implementations of recipient hashing and content fingerprinting, published in the docs and tested against the API on every build.

Inbound and verdicts (Gate 2)

- Inbound mail on verify.fromenance.com and ingest.fromenance.com , raw MIME encrypted in object storage under a tenant prefix.

- DKIM, ARC, and SPF verification in the Worker; the trust check with eight rejection reasons and a 24 hour holding area.

- Queue pipeline for ingest, match, reply, and intelligence with dead letter handling.

- Extraction of code, recipient, fingerprint, headers, and indicators; the pure decide() verdict function covering every row of the matching table including footer replay; idempotent repeat submissions.

- MJML reply templates with the locked verdict block, branded reply identities through Resend with DNS records returned to the tenant, and the minimal reply identity for pilots.

- Analyst overrides, fraud list, fraud fingerprints, retro registration with coverage gap flagging.

- Journal and BCC ingestion at journal-<slug>@ingest.fromenance.com .

Web verify and adapters (Gate 3)

- POST /v1/public/submit with site key and origin checks, per IP and per key rate limits, and Turnstile escalation; synchronous verdicts for text and .eml , poll tokens for screenshots.

- Screenshot OCR feeding the same deterministic extractors.

- The embeddable widget on cdn.fromenance.com/verify.js and embed.html , with tenant theming, script and iframe modes.

- ESP adapters behind one interface: Resend, SendGrid, Amazon SES, Postmark, Mailgun, Salesforce Marketing Cloud, Braze, and a generic signed webhook; reserve flow with 24 hour expiry; source health with silence alerts.

- Outbound webhooks verdict.created , submission.replay_detected , indicator.new , HMAC-SHA256 signed, retried with backoff for about a day, replayable.

Admin app (Gate 4)

- App shell with dark and light themes, tenant switcher, global search, dense tables with column pick, sort, saved filters, and CSV export.

- Six step setup wizard with the forwarding test.

- Overview, Submissions with detail drawer and override, Indicators with STIX 2.1 and CSV export, Fraud list, Campaigns placeholder, Registrations with coverage, Sources with health and test event, Domains, Verify page with live preview, Reply templates with preview and send test, Webhooks with delivery log and replay, Settings.

Docs (Gate 5)

- This site: quickstart, concepts, mail platform guides, one page per adapter, verify page, verifications, webhooks with signature samples in TypeScript, Python, and Go, admin, generated API reference, security, and this changelog. Every TypeScript sample is compiled in CI and executed against a sandbox tenant.

## Versioning

The API is versioned in the path (/v1 ). Additive changes (new fields, new events, new optional parameters) ship without notice here beyond a changelog entry. Anything that removes or renames a field, changes a status code, or changes signature schemes will be announced on this page at least 90 days ahead and shipped under a new version prefix.