Skip to content

Risk Assessment

Pre-send risk assessment API for Professional and Enterprise plans. Preview risk scores before sending emails to reduce bounce rates, improve deliverability, and maintain sender reputation. Get detailed risk analysis with actionable recommendations and enforcement policy insights.

Operations

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"
  }
}