StormGTM API

Quickstart

export STORMGTM_API_KEY=sgtm_live_...

curl https://stormgtm.com/v1/check \
  -H "authorization: Bearer $STORMGTM_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "email": "jane.doe@acme.io",
    "context": { "name": "Jane Doe", "company": "Acme" }
  }'

npm install @stormgtm/client

import { StormGTM } from "@stormgtm/client";

const stormgtm = new StormGTM({
  apiKey: process.env.STORMGTM_API_KEY!,
  baseUrl: "https://stormgtm.com",
});

const result = await stormgtm.check({
  email: "jane.doe@acme.io",
  tier: "deep",
  context: { name: "Jane Doe", company: "Acme", githubLogin: "janedoe" },
});

const send = result.verdict === "deliverable" && result.policy.allowed;
console.log(send ? "send" : "skip", result.score, result.reasons);

await stormgtm.reportOutcome({ email: "jane.doe@acme.io", kind: "delivered" });

npm install -g @stormgtm/client

export STORMGTM_API_KEY=sgtm_live_...
export STORMGTM_API_URL=https://stormgtm.com

stormgtm me
stormgtm check jane.doe@acme.io --name "Jane Doe" --company Acme
stormgtm check jane.doe@acme.io --github janedoe --deep --json
stormgtm batch leads.csv --wait
stormgtm outcome jane.doe@acme.io bounced

{
  "mcpServers": {
    "stormgtm": {
      "command": "npx",
      "args": ["-y", "@stormgtm/mcp"],
      "env": {
        "STORMGTM_API_KEY": "sgtm_live_...",
        "STORMGTM_API_URL": "https://stormgtm.com"
      }
    }
  }
}

claude mcp add stormgtm \
  --env STORMGTM_API_KEY=sgtm_live_... \
  --env STORMGTM_API_URL=https://stormgtm.com \
  -- npx -y @stormgtm/mcp

Authentication

Send Authorization: Bearer sgtm_live_… on every request. Create and revoke keys in the dashboard; a key is shown once, when you create it. All request and response bodies are JSON.

POST /v1/check

Check one lead synchronously. Fast checks usually finish in 1–4 seconds; SMTP servers that stall can take up to ~25 seconds.

{
  "email": "jane@acme.io",            // required
  "tier": "fast" | "deep",            // default fast (1 credit); deep = 5 credits
  "smtp": true,                       // set false to skip the SMTP probe
  "context": {                        // all optional; more context, better verdicts
    "name": "Jane Doe", "firstName": "Jane", "lastName": "Doe",
    "company": "Acme", "companyDomain": "acme.io", "title": "CTO",
    "source": "github", "sourceUrl": "https://github.com/acme/api",
    "githubLogin": "janedoe", "linkedinUrl": "…", "notes": "…"
  },
  "policy": { … }                     // optional; overrides your account default
}

{
  "id": "chk_…",
  "email": "Jane@Acme.io", "normalized": "jane@acme.io",
  "verdict": "deliverable" | "risky" | "undeliverable" | "unknown",
  "score": 0-100,
  "tier": "fast",
  "reasons": [{ "code": "smtp_accepted", "impact": "positive", "weight": 45, "detail": "RCPT accepted by aspmx.l.google.com" }],
  "facts": { "mx": "yes", "provider": "google", "smtp": "accepted", "catchAll": false, "spf": true, "dmarc": true, … },
  "policy": { "allowed": true, "violations": [] },
  "billable": true,
  "credits": 1
}

Verdicts

policy.allowed is separate from the verdict: a lead can be deliverable and still outside your policy. Gate sends on both.

Reasons

The score starts at 50 and each reason adds its weight. A fatal reason makes the lead undeliverable regardless of the rest.

Policy

Set a default policy on your account, or send policy with a check or batch to override it. Violations come back in policy.violations and never change the score.

"policy": {
  "blockTlds": ["ru", "cn"],
  "blockDomains": ["qq.com"],
  "blockLocals": ["npm"],
  "blockRoleAccounts": true,
  "blockFreeMail": false,
  "blockAnonymous": true,
  "blockSocialHosts": true,
  "blockCatchAll": false
}

POST /v1/batches

Queue up to 10,000 leads. Greylisted or silent servers are retried after 5, 15, and 45 minutes before settling as unknown.

{
  "leads": [{ "email": "jane@acme.io", "context": { "name": "Jane Doe" } }, …],
  "tier": "fast",
  "policy": { … },
  "webhookUrl": "https://you.example/hooks/leads"   // optional, HTTPS only
}
→ 202 { "id": "bat_…", "status": "queued", "total": 2, "maxCredits": 2 }

Poll GET /v1/batches/:id?offset=0&limit=100 for status and results. When done we POST {"event":"batch.completed","batch":{"id","total","completedAt","summary"}} to your webhook.

POST /v1/outcomes

Report what happened after you sent. Bounces make future checks of that address undeliverable; replies and deliveries raise confidence. Addresses are stored hashed.

{ "email": "jane@acme.io", "kind": "bounced" | "delivered" | "replied" | "opened" | "complained",
  "occurredAt": "2026-10-01T12:00:00Z", "detail": "550 5.1.1" }

// or many at once
{ "outcomes": [ … up to 1000 … ] }

Other endpoints

Errors

Errors look like {"error":{"code":"insufficient_credits","message":"…"}}. Codes: missing_api_key, invalid_api_key (401), insufficient_credits (402), invalid_request (422, with issues), batch_too_large (413).

Agents and MCP

Give your agent the MCP server (stormgtm-mcp) with STORMGTM_API_KEY set, and it gets check_lead, check_batch, batch_status, report_outcome, and credits tools. Setup is in the Quickstart.

The rule we recommend agents follow:

• Send only when verdict is deliverable and policy.allowed is true.
• risky: enrich with more context and tier: "deep", or ask a human.
• unknown is free: retry later or use a batch.
• Report bounces and replies to /v1/outcomes.