Skip to content

Preview risk score before sending (advisory)

Request

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
Security
ApiKeyAuth
Bodyapplication/jsonrequired
tostring, (email)required

Recipient email address

Example:"user@example.com"
subjectstringrequired

Email subject line

Example:"Welcome to our platform"
htmlstring

HTML content (optional)

Example:"<p>Welcome to our platform!</p>"
textstring

Plain text content (optional)

Example:"Welcome to our platform!"
is_bulkboolean

Whether this is bulk/marketing email

Default:false
curl -i -X POST \
  https://api.mailerlogic.net/api/v1/risk/preview \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "to": "user@example.com",
    "subject": "Welcome to our platform",
    "html": "<p>Welcome to our platform!</p>",
    "text": "Welcome to our platform!",
    "is_bulk": false
  }'

Responses

Risk score calculated successfully

Bodyapplication/json
risk_scoreinteger, [ 0 .. 100 ]required

Overall risk score (0-100)

Example:15
risk_levelstringrequired

Risk level category

Enum:"safe""low""medium""high"
Example:"safe"
would_blockbooleanrequired

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.

Example:false
actionstringrequired

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"
Example:"allow"
reason_codestring or 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"
Example:null
block_reasonstring or null

Human-readable explanation (null if allowed)

Example:null
risk_factorsArray of objects

Detailed breakdown of risk factors that contributed to score

breakdownobject

Risk score breakdown by category

recommendationsArray of strings

Actionable recommendations to reduce risk

Example:
[
  "Consider verifying sender domain with DKIM/SPF",
  "Review content for spam triggers"
]
policy_snapshotobject

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

engine_versionstring

Risk scoring engine version for tracking/debugging

Example:"risk-v3.2"
quotaobject

Current Risk API quota status

Response
{
  "risk_score": 15,
  "risk_level": "safe",
  "would_block": false,
  "action": "allow",
  "reason_code": null,
  "block_reason": null,
  "risk_factors": [
    { … }
  ],
  "breakdown": {
    "recipient": 5,
    "content": 5,
    "sender": 0,
    "behavior": 0
  },
  "recommendations": [],
  "policy_snapshot": {
    "block_disposable_emails": true,
    "enforce_sender_verification": true,
    "disposable_confidence_threshold": 0.85,
    "customer_plan": "professional"
  },
  "engine_version": "risk-v3.2",
  "quota": {
    "used": 43,
    "limit": 1000,
    "remaining": 957,
    "reset_at": "2025-02-01T00:00:00Z"
  }
}