API Reference v1.3

SecureStamp API

REST API for trust verification, domain registry, stamp management and plugin analytics. All responses are JSON. Rate limits are per API key unless noted otherwise.

Authentication

Pass your API key in the Authorization header as a Bearer token, or as the X-API-Key header.

# Bearer token
curl -H "Authorization: Bearer sk_live_yourkey..." \
     https://securestamp.online/api/trust/check

# API Key header
curl -H "X-API-Key: sk_live_yourkey..." \
     https://securestamp.online/api/trust/check

API keys are prefixed sk_live_ (production) or sk_test_ (test). Generate them from your dashboard → API Keys.

Public endpoints

No auth — trust check, registry lookup

Authenticated

API key required — quota 1,000–50,000 req/month by plan

Rate limits

60 req/min public · 300 req/min authenticated

Trust Check

POST/api/trust/check

Verify the trust status of an email address or domain. Returns a score (0–100), trust state, and SPF/DKIM/DMARC signal breakdown.

Parameters

Name	Type	Required	Description
target	string	✓	Email address or domain to verify

Request body

{
  "target": "newsletter@example.com"
}

Response

{
  "target": "newsletter@example.com",
  "domain": "example.com",
  "trustState": "CONFIABLE",
  "score": 87,
  "signals": {
    "spf": "pass",
    "dkim": "pass",
    "dmarc": "pass",
    "domainAge": "2y",
    "registrationVerified": true,
    "domainVerifiedInRegistry": true
  },
  "stamp": {
    "stampId": "f47ac10b-...",
    "artworkUrl": "https://securestamp.online/api/stamps/embed?id=f47ac...",
    "collectionTitle": "Classic"
  },
  "checkedAt": "2026-06-02T18:00:00Z"
}

cURL example

curl -X POST https://securestamp.online/api/trust/check \
  -H "Content-Type: application/json" \
  -d '{"target":"newsletter@example.com"}'

Domain Registry

GET/api/registry/lookup

Check whether a domain is registered in the SecureStamp public registry. Returns registration date, score, and stamp status without exposing internal user data.

Parameters

Name	Type	Required	Description
domain	string (query)	✓	Domain to look up, e.g. example.com

Response

{
  "domain": "example.com",
  "registered": true,
  "score": 92,
  "status": "CONFIABLE",
  "registeredAt": "2025-03-14T10:00:00Z",
  "hasActiveStamp": true
}

cURL example

curl "https://securestamp.org/api/registry/lookup?domain=example.com"

Stamps

GET/api/stamps/embedAPI Key

Returns an HTML/SVG stamp widget for embedding in outgoing emails. Accepts the stamp ID. The response is an HTML fragment containing a signed, verified trust stamp.

Parameters

Name	Type	Required	Description
id	string (query)	✓	Stamp ID returned by trust/check
theme	string (query)	—	"light" \| "dark" (default: "dark")

Response

<!-- Signed HTML trust stamp -->
<div class="ss-stamp" data-stamp-id="f47ac10b..." data-score="87">
  <img src="..." alt="SecureStamp verified" />
  <a href="https://securestamp.org/verify/eyJhbG...">Verify</a>
</div>

cURL example

curl "https://securestamp.online/api/stamps/embed?id=f47ac10b..." \
  -H "Authorization: Bearer sk_live_yourkey..."

User & Quota

GET/api/quota/statusAPI Key

Returns the authenticated user's current quota usage, plan tier, and remaining verifications for the current billing period.

Response

{
  "plan": "starter",
  "billingInterval": "monthly",
  "quota": {
    "used": 142,
    "limit": 1000,
    "remaining": 858,
    "resetAt": "2026-07-01T00:00:00Z"
  }
}

cURL example

curl https://securestamp.online/api/quota/status \
  -H "Authorization: Bearer sk_live_yourkey..."

PATCH/api/user/artistAPI Key

Select an artist collection to display on outgoing stamps. A 10% subscription commission will accrue to the selected artist while the user has an active paid plan.

Request body

{
  "artistId": "artist-uuid-or-cognito-sub"
}

Response

{
  "ok": true,
  "selectedArtistId": "artist-uuid",
  "artistSelectedAt": "2026-06-02T18:00:00Z"
}

cURL example

curl -X PATCH https://securestamp.online/api/user/artist \
  -H "Authorization: Bearer sk_live_yourkey..." \
  -H "Content-Type: application/json" \
  -d '{"artistId":"artist-uuid"}'

POST/api/events

Record an anonymous plugin analytics event. No PII — only plan tier, event name, and risk metadata. Events are retained for 90 days.

Parameters

Name	Type	Required	Description
event	string	✓	Snake_case event name, e.g. plugin_signature_inserted
source	enum	✓	gmail \| outlook \| safari \| apple-mail \| cli \| browser-extension
planTier	string	✓	User plan tier at the time of event
riskLevel	enum	—	safe \| suspicious \| dangerous
senderTrustState	enum	—	trusted \| suspicious \| blocked \| unknown
locale	string	—	BCP-47 locale, e.g. es-AR
timestamp	number	✓	Unix timestamp (ms)

Request body

{
  "event": "plugin_signature_inserted",
  "source": "gmail",
  "planTier": "free",
  "locale": "es-AR",
  "timestamp": 1748880000000
}

Response

{
  "ok": true,
  "eventId": "uuid-..."
}

cURL example

curl -X POST https://securestamp.online/api/events \
  -H "Content-Type: application/json" \
  -d '{"event":"plugin_signature_inserted","source":"gmail","planTier":"free","timestamp":1748880000000}'

Error Codes

Status	Code	Meaning
400	BAD_REQUEST	Malformed JSON or missing required field
401	UNAUTHORIZED	Missing or invalid API key
422	VALIDATION_ERROR	Input failed Zod schema validation
429	RATE_LIMITED	Too many requests — back off and retry
503	STORAGE_UNAVAILABLE	Temporary DynamoDB write failure
502	UPSTREAM_ERROR	Upstream Stripe or external service error