API Documentation

Authentication

Send an API key in the Authorization header.

Authorization: Bearer sk_live_your_api_key_here

POST /v1/preflight/email

The primary endpoint. Pass sender, recipient, message, and policy context. The response returns a firewall decision, risk score, reason codes, optional approval metadata, and billing details.

Request

curl -X POST https://api.sendguard.ai/v1/preflight/email \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws_demo",
    "agent_id": "sdr-agent-01",
    "campaign_id": "camp_q2_pipeline",
    "policy": "balanced",
    "from": {
      "email": "lisa@tryacme.com",
      "domain": "tryacme.com",
      "mailbox_age_days": 18,
      "domain_age_days": 90
    },
    "to": {
      "email": "cfo@hospital.com",
      "company": "Northshore Hospital",
      "industry": "healthcare",
      "country": "US",
      "source": "apollo"
    },
    "message": {
      "subject": "Quick question",
      "body": "Hi there, we can reduce admin overhead by 30%. Reply unsubscribe to opt out."
    },
    "context": {
      "intent": "cold_outbound",
      "relationship": "new_prospect",
      "crm_stage": "prospect",
      "sequence_step": 1
    }
  }'

Response

{
  "id": "8a13d8bc-9bf0-4d11-a5b9-2cf92eb9dbee",
  "workspace_id": "ws_demo",
  "agent_id": "sdr-agent-01",
  "campaign_id": "camp_q2_pipeline",
  "recipient_email": "cfo@hospital.com",
  "decision": "requires_approval",
  "risk_score": 86,
  "confidence": 0.94,
  "delay_seconds": 0,
  "reasons": [
    {
      "code": "SENSITIVE_INDUSTRY",
      "severity": "high",
      "message": "Recipient industry \"healthcare\" requires human review before autonomous outreach"
    },
    {
      "code": "PRICING_CLAIM_DETECTED",
      "severity": "high",
      "message": "Pricing or discount claims require human approval before sending"
    }
  ],
  "recommendations": [
    "Route this outbound action to a human approver before sending."
  ],
  "approval": {
    "queue": "sales_manager",
    "reason": "Pricing or discount claims require human approval before sending"
  },
  "status": "deliverable",
  "billing": {
    "charged": true,
    "units": 1,
    "reason": "full_verification",
    "balance_remaining": 4832
  }
}

Decision Actions

Billing Notes

Examples

Node.js

const res = await fetch("https://api.sendguard.ai/v1/preflight/email", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_xxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    workspace_id: "ws_demo",
    agent_id: "my-agent",
    policy: "balanced",
    from: { email: "lisa@tryacme.com", mailbox_age_days: 18, domain_age_days: 90 },
    to: { email: "cfo@hospital.com", company: "Northshore Hospital", industry: "healthcare", country: "US" },
    message: { subject: "Quick question", body: "Reply unsubscribe to opt out." },
    context: { intent: "cold_outbound", relationship: "new_prospect", sequence_step: 1 }
  })
});

const data = await res.json();
if (data.decision !== "allow") {
  console.log(data.reasons);
}

Python

import requests

resp = requests.post(
    "https://api.sendguard.ai/v1/preflight/email",
    headers={"Authorization": "Bearer sk_live_xxx"},
    json={
        "workspace_id": "ws_demo",
        "agent_id": "my-agent",
        "policy": "balanced",
        "from": {"email": "lisa@tryacme.com", "mailbox_age_days": 18, "domain_age_days": 90},
        "to": {"email": "cfo@hospital.com", "company": "Northshore Hospital", "industry": "healthcare", "country": "US"},
        "message": {"subject": "Quick question", "body": "Reply unsubscribe to opt out."},
        "context": {"intent": "cold_outbound", "relationship": "new_prospect", "sequence_step": 1}
    }
)

print(resp.json())

Approval and Feedback APIs