API documentation

Use the suppression check API to see which recipients should be excluded from a campaign before you send. No secrets are exposed in this documentation—you use your own API key in requests.

Overview

Before sending a campaign, send us the hashed email addresses of recipients and the campaign tags that describe the campaign (e.g. Mother's Day, pregnancy). We return allow or block for each hash. Suppress any block result from your send.

We never receive plain email addresses—only SHA256 hashes.
One campaign can have multiple tags for accurate matching (e.g. Mother's Day + family).
If a user has opted out of an umbrella category (e.g. "sensitive mode"), they are blocked for any tag under that umbrella.

Authentication

Every request must include your API key in the x-api-key header. You receive the key when you register your company (it is shown once at onboarding). Keep it secret and use it only from your backend or trusted systems.

x-api-key: your_api_key_here

Endpoint

POST /api/v1/check

Base URL: your deployment URL (e.g. https://inboxconsent.com).

Request headers

Header	Required	Description
x-api-key	Yes	Your API key (plain text).
Content-Type	Yes	application/json

Request body

{
  "hashes": ["64-char-hex-sha256-of-normalised-email", "..."],
  "campaign_tags": ["mothers_day", "family_parenting"]
}

hashes: Array of SHA256 hashes (64 hex characters). Use our normalisation (Gmail dots removed, +alias stripped); see Hashing below.
campaign_tags: One or more category codes. Use multiple tags when a campaign fits several (e.g. Mother's Day flowers = mothers_day + family_parenting).

Limits: up to 1000 hashes and 50 tags per request.

Response (200)

{
  "results": {
    "abc123...": { "allowed": true },
    "def456...": { "allowed": false }
  }
}

results: For each requested hash, { "allowed": true } or { "allowed": false }. Suppress recipients where allowed is false. No explanation is returned (privacy).
Audience required: All hashes must be in your verified audience. Sync via POST /api/v1/audience/sync first.

Example (curl)

curl -X POST https://your-domain.com/api/v1/check \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "hashes": ["e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"],
    "campaign_tags": ["mothers_day"]
  }'

Error responses

Status	Meaning
401	Missing or invalid x-api-key.
400	Invalid JSON, missing hashes, or limits exceeded.
429	Monthly consent check limit reached for your plan.

Email hashing

Hashes must match how we store preferences. Use this process so results are consistent:

Normalise: Lowercase, trim. For Gmail/GoogleMail: remove dots from local part; strip +alias.
Optional pepper: If agreed, toHash = pepper + ":" + email.
Hash: SHA256(toHash) as 64-char hex.

We do not publish a pepper in this doc. If one is in use for your integration, we will provide it to you separately.

Category codes

Use these codes in campaign_tags. Users can opt out of specific categories or umbrella categories; if they opt out of an umbrella, they are blocked for any tag under it.

Seasonal

mothers_day
fathers_day
valentines_day
christmas_family
baby_shower
back_to_school_family

Life events

pregnancy_baby
fertility_ivf
bereavement_services
divorce_separation
dating_relationships
family_parenting

Lifestyle / health

alcohol
gambling
weight_loss
cosmetic_surgery

Umbrellas

sensitive_mode
seasonal_sensitive
life_event_sensitive
lifestyle_sensitive

Code examples

Replace YOUR_API_KEY and the hash with your values. Base URL: your deployment (e.g. https://inboxconsent.com).

cURL

curl -X POST https://inboxconsent.com/api/v1/check \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"hashes": ["SHA256_HASH"], "campaign_tags": ["mothers_day"]}'

Node.js

const res = await fetch("https://inboxconsent.com/api/v1/check", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.INBOXCONSENT_API_KEY,
  },
  body: JSON.stringify({
    hashes: ["sha256HashOfNormalisedEmail"],
    campaign_tags: ["mothers_day"],
  }),
});
const { results } = await res.json();

Python

import os, requests
r = requests.post(
    "https://inboxconsent.com/api/v1/check",
    headers={"x-api-key": os.environ["INBOXCONSENT_API_KEY"]},
    json={"hashes": ["sha256_hash"], "campaign_tags": ["mothers_day"]},
)
results = r.json()["results"]

Integrations (Klaviyo, Mailchimp, Shopify)

Use the same POST /api/v1/check endpoint from any platform. Store your API key in environment variables or secret manager; call the API from a server-side action, workflow, or cron before sending.

Klaviyo: Flow webhook sends to your endpoint; your endpoint calls InboxConsent and updates a Klaviyo profile property; use a conditional split on that property so only "allow" profiles receive the email.
Mailchimp: Connect in Dashboard; we run a hosted sync that tags blocked members. Exclude that tag when creating campaigns.
Shopify: In Shopify Flow use Send HTTP request (with API key in secure secrets) and Run code to parse the response; branch on allow/block to send marketing email or update customer only when allowed.

For step-by-step setup, platform prerequisites, and checklists for each integration, see the Integration guide in the repo: docs/integrations.md.

If you're building a public integration (e.g. Klaviyo app), contact us for partnership and listing.

Need an API key? Register your company to get one. For technical support, contact us through your account.