# Preview risk score before sending (advisory)

Pre-send guidance to help you decide whether to send an email.

Returns a risk assessment with a would_block boolean that indicates whether the platform will block this email if you attempt to send it.

Important Contract:
- This is advisory - you make the decision
- If would_block = true, calling /api/v1/send will also block for the same reason
- If would_block = false but risk is medium/high, you can still choose to send
- Platform may throttle/warn on high risk sends depending on your plan

Risk Score Ranges:
- 0-29: Safe (send)
- 30-49: Low risk (warn)
- 50-69: Medium risk (soft block - customer can override)
- 70-100: High/Critical risk (hard block)

Hard Blocks (would_block = true):
- Known spamtraps (spamtrap_detected)
- Previous spam complaints (previous_complaint)
- High-confidence disposable domains > 0.85 (disposable_high_confidence)
- Sender verification failure if enabled (sender_not_verified)
- Risk score >= 70 (risk_score_critical)

Stable Reason Codes (for programmatic handling):
- disposable_high_confidence - Disposable domain with 90%+ confidence
- disposable_medium_confidence - Disposable domain with 50-89% confidence
- sender_not_verified - DKIM/SPF not verified
- spamtrap_detected - Known spamtrap address
- previous_complaint - Recipient marked previous email as spam
- previous_hard_bounce - Hard bounce on previous send
- content_risk_high - High spam content score
- velocity_first_send_bulk - First send attempt is bulk email
- volume_spike - Unusual sending volume increase

Quota:
- Available on Professional and Enterprise plans
- Check /api/v1/risk/stats for usage and remaining quota

Endpoint: POST /api/v1/risk/preview
Version: 1.0.0
Security: ApiKeyAuth

## Request fields (application/json):

  - `to` (string, required)
    Recipient email address
    Example: "user@example.com"

  - `subject` (string, required)
    Email subject line
    Example: "Welcome to our platform"

  - `html` (string)
    HTML content (optional)
    Example: "<p>Welcome to our platform!</p>"

  - `text` (string)
    Plain text content (optional)
    Example: "Welcome to our platform!"

  - `is_bulk` (boolean)
    Whether this is bulk/marketing email

## Response 200 fields (application/json):

  - `risk_score` (integer, required)
    Overall risk score (0-100)
    Example: 15

  - `risk_level` (string, required)
    Risk level category
    Enum: "safe", "low", "medium", "high"

  - `would_block` (boolean, required)
    Critical field: Indicates if /api/v1/send will block this email.
If true, calling /send will result in the same block with the same reason_code.

  - `action` (string, required)
    Platform decision on this send:
- allow: Will send without warnings
- warn: Will send but risk warning shown in logs/dashboard
- soft_block: Platform will block /send unless customer takes explicit corrective action (verify domain, remove recipient, fix content). Not the same as "warn" - this requires action.
- block: Hard block - cannot send under any circumstances
    Enum: "allow", "warn", "soft_block", "block"

  - `reason_code` (string,null)
    Stable machine-readable reason code (null if allowed).
Use this for programmatic decision-making.
    Enum: null, "disposable_high_confidence", "disposable_medium_confidence", "sender_not_verified", "spamtrap_detected", "previous_complaint", "previous_hard_bounce", "content_risk_high", "velocity_first_send_bulk", "volume_spike", "risk_score_critical"

  - `block_reason` (string,null)
    Human-readable explanation (null if allowed)

  - `risk_factors` (array)
    Detailed breakdown of risk factors that contributed to score

  - `risk_factors.type` (string)
    Stable factor type code
    Example: "free_email_provider"

  - `risk_factors.points` (integer)
    Points contributed by this factor
    Example: 5

  - `risk_factors.message` (string)
    Human-readable explanation
    Example: "Sending to free email provider"

  - `breakdown` (object)
    Risk score breakdown by category

  - `breakdown.recipient` (integer)
    Recipient risk score (0-40)
    Example: 5

  - `breakdown.content` (integer)
    Content risk score (0-30)
    Example: 5

  - `breakdown.sender` (integer)
    Sender risk score (0-20)

  - `breakdown.behavior` (integer)
    Behavior/velocity risk score (0-10)

  - `recommendations` (array)
    Actionable recommendations to reduce risk
    Example: ["Consider verifying sender domain with DKIM/SPF","Review content for spam triggers"]

  - `policy_snapshot` (object)
    Enforcement policy settings at time of preview.
Use this to correlate why an old preview doesn't match a later /send if settings changed.

  - `policy_snapshot.block_disposable_emails` (boolean)
    Whether disposable emails are blocked
    Example: true

  - `policy_snapshot.enforce_sender_verification` (boolean)
    Whether sender verification is required
    Example: true

  - `policy_snapshot.disposable_confidence_threshold` (number)
    Confidence threshold for disposable blocking (0.0-1.0)
    Example: 0.85

  - `policy_snapshot.customer_plan` (string)
    Customer plan tier (affects soft blocks and throttling)
    Example: "professional"

  - `engine_version` (string)
    Risk scoring engine version for tracking/debugging
    Example: "risk-v3.2"

  - `quota` (object)
    Current Risk API quota status

  - `quota.used` (integer)
    Example: 43

  - `quota.limit` (integer)
    Example: 1000

  - `quota.remaining` (integer)
    Example: 957

  - `quota.reset_at` (string)
    When quota resets (typically start of next month)
    Example: "2025-02-01T00:00:00Z"

## Response 400 fields (application/json):

  - `error` (string)
    Example: "validation_error"

  - `message` (string)
    Example: "Invalid email address"

## Response 401 fields (application/json):

  - `error` (string)
    Error code or message

## Response 403 fields (application/json):

  - `error` (string)
    Example: "feature_not_available"

  - `message` (string)
    Example: "Risk Score API is not available for your account. Please upgrade to a Professional or Enterprise plan."

  - `upgrade_info` (object)

  - `upgrade_info.feature` (string)
    Example: "Risk Score API"

  - `upgrade_info.available_on` (array)
    Example: ["Professional","Enterprise"]

  - `upgrade_info.benefits` (array)
    Example: ["Preview risk scores before sending","Reduce bounce rates proactively","Comply with sending policies","Improve delivery reputation"]

## Response 429 fields (application/json):

  - `error` (string)
    Example: "quota_exceeded"

  - `message` (string)
    Example: "Monthly risk API quota exceeded (1000/1000). Resets on 2025-02-01."

  - `quota` (object)

  - `quota.used` (integer)
    Example: 1000

  - `quota.limit` (integer)
    Example: 1000

  - `quota.resets_at` (string)
    Example: "2025-02-01T00:00:00Z"