Skip to content
ALTCHA ALTCHA ALTCHA

How to Classify Data with Sentinel

Sentinel’s Classifier provides a powerful, flexible way to evaluate and categorize data across multiple dimensions—including text, email addresses, IP addresses, geolocation, and device metadata. By leveraging natural language processing (NLP), rule-based detection, and machine learning models, the Classifier helps identify spam, fraud, abuse, and other unwanted behavior with precision.

Whether you’re filtering user-generated content, validating sign-ups, or detecting suspicious activity, the Classifier API delivers actionable insights through a unified interface. It returns detailed scores and classifications that enable fine-grained decision-making tailored to your specific business needs.

This guide walks you through how to use the Classifier effectively for different data types and scenarios.

Setup

  1. Ensure you have Sentinel installed.
  2. Create a new API key and assign it to a Security Group with Restricted access level (the Classifier API is non-public).

How It Works

The Classifier API evaluates input data — such as text, form fields, email addresses, or IP addresses — against built-in rules and returns a score for each rule. The total overall score and resulting classification indicate how likely the input is to be spam or unwanted content.

Text Classification

The primary use case for the Classifier is to detect common spam or harmful patterns in text. To classify text, submit it using the text parameter.

curl -X POST http://localhost:8080/v1/classifier \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}" \
  -d '{
    "text": "Example text to classify"
  }'

Key Response Fields

  • classification – Can be GOOD (score < 1), NEUTRAL (score 1–2), or BAD (score > 2).
  • score – A numeric score; scores greater than 2 typically indicate spam.
  • triggeredRules – An array of matched rules, sorted by score.

Additional text-related response fields include:

  • text.classifier – The language classifier used (based on detected language).
  • text.language – The ISO code of the detected language (two-letter format).
  • text.rules – A list of evaluated rules with corresponding scores and metadata.

Commonly Used Rules

  • CAPITALIZATION – Detects capitalized words; excessive capitalization may suggest unsolicited messaging.
  • EXCLAMATION – Identifies exclamation marks; excessive use may be flagged as suspicious.
  • HTML – Detects HTML tags; presence of HTML may be considered suspicious.
  • PROFANITY – Identifies commonly used profane language.
  • SPAM_WORDS – Detects known spam-related words.
  • EMOJI – Flags excessive emoji usage.

For a complete list of supported rules, refer to the API Documentation.

Rule Filtering

You can customize classification behavior by disabling specific rules or enabling only certain ones:

  • Use "disableRules": ["CAPITALIZATION"] to skip specific rules.
  • Alternatively, use "enableRules": ["PROFANITY"] to allow only selected rules.

Form Fields Classification

To classify data submitted through website forms, use the fields parameter to send one or more form fields for evaluation.

When form fields are provided, the Classifier automatically identifies email addresses and text content within the submitted values, applying appropriate classification rules to each. This allows you to detect spam, fake submissions, or suspicious patterns directly from user input forms.

curl -X POST http://localhost:8080/v1/classifier \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}" \
  -d '{
    "fields": {
      "email": "text@example.com",
      "name": "John Doe",
      "message": "Hello, I need help with checkout on your website."
    }
  }'

This method simplifies integration with contact forms, registration pages, and other user-input interfaces by allowing you to submit raw field values without preprocessing.

Similarity Classification

In addition to rule-based classification, you can evaluate text using Similarity Detection, which compares the provided text (or text fields) against pre-configured training data to identify matches or near-matches.

This feature is particularly useful for identifying spam or abuse patterns that may vary slightly in wording but share structural or semantic similarity with known examples.

curl -X POST http://localhost:8080/v1/classifier \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}" \
  -d '{
    "similarity": [{
      "groups": ["chat_spam"],
      "partial": true,
      "stopOnMatch": 0.7
    }],
    "text": "Example text to classify"
  }'

If a match is found, the response will include a triggered rule such as SIMILARITY:chat_spam, allowing you to take action based on similarity to known undesirable content.

Email Classification

Email address classification helps identify disposable, free, or poorly configured email domains. This can reveal whether an email is temporary, from a free provider, or has poor deliverability settings.

Tip: For privacy compliance, consider sending only the domain portion of the email address (e.g., gmail.com) instead of the full email.

curl -X POST http://localhost:8080/v1/classifier \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}" \
  -d '{
    "email": "gmail.com"
  }'

Email-Specific Rules

  • DISPOSABLE – Matches if the domain is recognized as a disposable email service (e.g., 10MinuteMail).
  • DMARC – Checks for the presence of a _dmarc. DNS record; triggers if missing.
  • FREE_PROVIDER – Matches if the domain is associated with a known free email provider (e.g., Gmail). A score of 0 indicates a custom business domain, while 0.5 indicates a popular free provider.
  • MX – Verifies the existence of MX records; triggers if none are found, indicating potential invalidity.

IP Address Classification

IP addresses can be resolved to geolocation data and classified based on network-related risk factors. The Classifier identifies whether the IP belongs to a proxy, TOR node, or known malicious source.

Note: This feature requires IP Resolver to be configured.

curl -X POST http://localhost:8080/v1/classifier \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}" \
  -d '{
    "ip": "127.0.0.1"
  }'

IP-Specific Rules

  • HOSTING – Matches if the IP is associated with a datacenter.
  • MALICIOUS – Matches if the IP appears in blocklists of known malicious actors.
  • PROXY – Matches if the IP is associated with a proxy or VPN service.
  • TOR – Matches if the IP is identified as a TOR exit node.

When geo-location data is available, location-based rules are also applied.

Location Classification

Location classification evaluates the geo-location derived from an IP address or time zone for potential risk indicators.

Location Rules

  • HIGH_RISK_COUNTRY – Matches if the location corresponds to a high-risk or sanctioned country.
  • LOCATION_DISTANCE – Matches if the current location is far from a previously recorded location (lastKnownLocation).
  • TIMEZONE_MISMATCH – Matches if the geo-location derived from the IP does not match the country inferred from the provided time zone.

Fast Traveler Detection

A common use case is detecting suspicious login activity. If you store a user’s previous location, provide it via the lastKnownLocation parameter (latitude and longitude). The Classifier calculates the distance between locations and assigns a score between 0 and 5.

  • Minimum threshold: 100 km
  • Maximum score: 5 (for distances up to ~3,000 km)

Use this feature only with recent location data (e.g., within a few hours), as users may travel long distances via air travel.

Time Zone-Based Location

Modern operating systems synchronize time zones based on device location. Using the time zone for location detection can be more accurate than IP-based methods, especially when users employ proxies or dynamic IPs.

Send the user’s time zone alongside the IP address. The system compares both location sources (countries) and triggers TIMEZONE_MISMATCH if they differ.

Device Classification

Device classification analyzes HTTP headers to determine whether the request originated from a bot, AI agent, or automated script. Automated systems often omit standard headers.

curl -X POST http://localhost:8080/v1/classifier \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}" \
  -d '{
    "headers": {
      "Accept": "...",
      "Accept-Language": "...",
      "User-Agent": "..."
    }
  }'

Device Rules

  • BOT – Matches if the User-Agent header identifies the device as a bot, crawler, or AI agent.
  • ACCEPT_HEADER_MISSING – Triggers if the Accept header is absent.
  • ACCEPT_LANGUAGE_HEADER_MISSING – Triggers if the Accept-Language header is missing.
  • USER_AGENT_HEADER_MISSING – Triggers if the User-Agent header is missing.

Rate Limiting

You can integrate rate limiting directly into your classification requests using the rateLimit parameter. This allows you to control request frequency for your users without implementing complex backend logic.

curl -X POST http://localhost:8080/v1/classifier \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}" \
  -d '{
    "rateLimit": {
      "customKey": "{USER_ID}",
      "limit": "10/1h",
      "memory": true
    }
  }'
  • customKey – A unique identifier such as a user ID.
  • limit – Defines the number of allowed requests per duration (e.g., 10/1h = 10 requests per hour).
  • memory – When set to true, uses in-memory storage for faster processing (without Redis).

For more information, see Rate Limiters documentation.

Put It All Together

For optimal results, submit multiple indicators in a single request. Combining different data points reduces false positives caused by individual negative classifications.

curl -X POST http://localhost:8080/v1/classifier \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}" \
  -d '{
    "email": "live.com",
    "ip": "127.0.0.1",
    "timeZone": "Europe/London"
  }'

Evaluating Classification Scores

The Classifier returns both a classification (GOOD, NEUTRAL, or BAD) and an overall score. While these provide a general assessment, you’re not limited to default thresholds. You can evaluate individual rules and apply custom scoring logic tailored to your specific use case.