Content Analysis

Analyze your email content for spam triggers, deliverability issues, and best practices before sending.

Overview

The Content Analysis API helps you identify potential deliverability issues in your emails before they're sent. Our analyzer checks for spam triggers, HTML structure problems, suspicious links, and provides an overall deliverability score.

Use this API to validate email templates, test subject lines, and ensure your content follows email best practices.

Analyzing Content

Send a POST request with your email subject and HTML content:

bash

POST /v1/content-analysis/analyze
Authorization: Bearer <your_server_token>
Content-Type: application/json

{
  "subject": "Welcome to our platform!",
  "html": "<html><body><h1>Welcome!</h1><p>Thanks for signing up.</p></body></html>"
}

The API returns a comprehensive analysis with scores and actionable recommendations:

json

{
  "spamScore": 0.12,
  "htmlScore": 0.95,
  "linkScore": 1.0,
  "overallScore": 0.89,
  "issues": [
    {
      "severity": "warning",
      "category": "spam",
      "message": "Subject contains exclamation mark which may trigger spam filters",
      "recommendation": "Consider using a more neutral subject line"
    },
    {
      "severity": "info",
      "category": "html",
      "message": "No plain text alternative provided",
      "recommendation": "Add a text version to improve deliverability"
    }
  ],
  "analysis": {
    "wordCount": 12,
    "linkCount": 0,
    "imageCount": 0,
    "hasUnsubscribeLink": false,
    "spamTriggers": ["exclamation_mark_in_subject"]
  }
}

Scoring System

Content analysis produces four scores, each ranging from 0.0 (worst) to 1.0 (best):

Spam Score (0.0–1.0)

Measures how likely your email is to trigger spam filters. Lower is better.

0.0–0.3

Excellent : Very low spam risk

0.3–0.6

Moderate : Some spam triggers detected

0.6–1.0

High : Likely to be flagged as spam

HTML Score (0.0–1.0)

Evaluates HTML structure and email rendering best practices. Higher is better.

0.8–1.0

Excellent : Well-structured HTML

0.5–0.8

Fair : Some structure improvements needed

0.0–0.5

Poor : Major HTML issues detected

Link Score (0.0–1.0)

Checks for suspicious or malformed links. Higher is better.

1.0

Perfect : All links are valid and safe

0.5–1.0

Some suspicious links detected

0.0–0.5

Many suspicious or malformed links

Overall Score (0.0–1.0)

Weighted average of all scores. Higher is better.

0.8–1.0

Excellent : Ready to send

0.5–0.8

Fair : Review recommendations

0.0–0.5

Poor : Major improvements needed

Common Issues Detected

Spam Triggers

Excessive use of capital letters or exclamation marks
Spam trigger words (FREE, URGENT, ACT NOW, etc.)
Hidden text or suspicious formatting
Overly promotional language
Missing unsubscribe link (for marketing emails)

HTML Structure Issues

Missing or malformed HTML tags
No plain text alternative
Excessive image-to-text ratio (>60% images)
Missing alt text for images
Very long emails (>100KB)
Use of deprecated HTML tags

Link Problems

Shortened URLs (bit.ly, tinyurl, etc.)
IP address URLs instead of domain names
Suspicious TLDs (.xyz, .tk, .ml)
Mismatched link text and destination
Too many links (link-to-text ratio > 3:1)

Using SDKs

Node.js SDK

javascript

import { Postject } from 'postject-sdk';

const client = new Postject({ apiKey: 'pt_live_your_token' });

const analysis = await client.analyzeContent(
  'Welcome to our platform!',
  '<html><body><h1>Welcome!</h1></body></html>'
);

console.log('Spam score:', analysis.spamScore);
console.log('Overall score:', analysis.overallScore);
console.log('Issues:', analysis.issues);

// Only send if score is good
if (analysis.overallScore > 0.7) {
  await client.send({ ... });
} else {
  console.warn('Content needs improvement:', analysis.issues);
}

Python SDK

python

from postject import Postject

client = Postject(api_key="pt_live_your_token")

analysis = client.analyze_content(
    subject="Welcome to our platform!",
    html="<html><body><h1>Welcome!</h1></body></html>"
)

print(f"Spam score: {analysis.spam_score}")
print(f"Overall score: {analysis.overall_score}")
print(f"Issues: {analysis.issues}")

# Only send if score is good
if analysis.overall_score > 0.7:
    client.send({ ... })
else:
    print(f"Content needs improvement: {analysis.issues}")

Best Practices

Do

Test templates before sending campaigns
Include plain text alternatives
Keep image-to-text ratio balanced
Use descriptive, non-promotional subjects
Add unsubscribe links for marketing emails
Use full domain URLs instead of IP addresses

Don't

Use ALL CAPS or excessive !!! marks
Include spam trigger words like FREE or URGENT
Send image-only emails
Use URL shorteners (bit.ly, tinyurl)
Embed forms or JavaScript
Send very large HTML (>100KB)

Automatic Analysis on Send

You can enable automatic content analysis when sending emails by including the analyzeContent: true flag in your send request. If the overall score is below 0.5, the send will be rejected with a 400 Bad Request error.

bash

POST /v1/send
Authorization: Bearer <your_server_token>
Content-Type: application/json

{
  "to": "user@example.com",
  "subject": "Welcome!",
  "html": "<h1>Welcome!</h1>",
  "analyzeContent": true
}

# If score < 0.5, returns:
{
  "error": "Content analysis failed",
  "analysis": {
    "overallScore": 0.45,
    "issues": [ ... ]
  }
}