Anti-Spam Protection

Anti-Spam Protection

mailiam provides comprehensive built-in spam protection to keep your forms secure and your inbox clean.

Built-in Protection Features

1. Honeypot Fields

Honeypot fields are hidden form inputs that catch automated bots:

<form action="https://api.mailiam.dev/yourdomain.com/contact" method="POST">
  <!-- Visible fields -->
  <input name="name" type="text" placeholder="Your name" required>
  <input name="email" type="email" placeholder="Your email" required>
  <textarea name="message" placeholder="Your message" required></textarea>

  <!-- Hidden honeypot field -->
  <input type="text"
         name="_mailiam_honeypot"
         style="display:none"
         tabindex="-1"
         autocomplete="off">

  <button type="submit">Send Message</button>
</form>

Custom Honeypot Field Names

Configure custom honeypot field names in your configuration:

domains:
  yourdomain.com:
    forms:
      contact:
        name: "Contact Form"
        honeypot: "company_bot_field"  # Custom honeypot name

Or via instant forms:

mailiam instant create \
  --email your@email.com \
  --name "Contact Form" \
  --honeypot "custom_honeypot_field"

2. Rate Limiting

Automatic rate limiting prevents form submission abuse:

domains:
  yourdomain.com:
    forms:
      contact:
        name: "Contact Form"
        rateLimit: 10  # 10 submissions per hour per IP

Rate Limiting Levels

Level	Submissions/Hour	Use Case
Conservative	5	High-security forms
Standard	10	Most contact forms
Relaxed	20	Newsletter signups
Testing	100+	Development/testing

3. Content Filtering

mailiam automatically filters common spam patterns:

• URL Detection: Blocks submissions with excessive links
• Keyword Filtering: Detects spam keywords and phrases
• Language Detection: Filters non-relevant language content
• Pattern Recognition: Identifies bot-like submission patterns

4. Domain Verification

Only verified domains can send emails, preventing domain spoofing:

# Verify domain ownership
mailiam domains verify yourdomain.com

# Check verification status
mailiam domains status

Configuration Options

Global Spam Protection

Configure spam protection globally:

settings:
  spam_protection: true          # Enable/disable globally
  defaultSpamProtection: "normal" # normal, strict, relaxed
  rate_limit: 10                 # Default rate limit

Per-Domain Configuration

domains:
  yourdomain.com:
    spam_protection:
      enabled: true
      level: "strict"              # strict, normal, relaxed
      honeypot: "_mailiam_honeypot"
      rate_limit: 10
      content_filter: true

    forms:
      contact:
        name: "Contact Form"
        spam_protection:
          level: "normal"          # Override domain setting
          rate_limit: 15           # Override rate limit

Per-Form Configuration

forms:
  contact:
    name: "Contact Form"
    spam_protection:
      enabled: true
      level: "strict"
      honeypot: "contact_honeypot"
      rate_limit: 5
      whitelist_ips:
        - "192.168.1.100"         # Allow specific IPs
        - "10.0.0.0/8"            # Allow IP ranges
      blacklist_keywords:
        - "casino"
        - "viagra"
        - "crypto"

Protection Levels

Relaxed Protection

Good for high-volume forms like newsletters:

forms:
  newsletter:
    spam_protection:
      level: "relaxed"
      rate_limit: 50
      content_filter: false
      honeypot: false

Features:

• Basic rate limiting
• Minimal content filtering
• No honeypot requirement
• Suitable for: Newsletter signups, surveys

Normal Protection (Default)

Balanced protection for most contact forms:

forms:
  contact:
    spam_protection:
      level: "normal"
      rate_limit: 10
      content_filter: true
      honeypot: true

Features:

• Standard rate limiting
• Content pattern detection
• Honeypot validation
• Suitable for: Contact forms, feedback forms

Strict Protection

Maximum protection for sensitive forms:

forms:
  support:
    spam_protection:
      level: "strict"
      rate_limit: 5
      content_filter: true
      honeypot: true
      require_js: true           # Require JavaScript execution
      captcha: true             # Enable CAPTCHA (premium feature)

Features:

• Aggressive rate limiting
• Enhanced content filtering
• Required honeypot validation
• JavaScript requirement
• Optional CAPTCHA integration
• Suitable for: Support forms, sales inquiries

Advanced Features

IP Whitelisting

Allow specific IP addresses to bypass protection:

forms:
  internal:
    spam_protection:
      whitelist_ips:
        - "192.168.1.0/24"       # Internal network
        - "203.0.113.1"          # Specific IP
        - "2001:db8::/32"        # IPv6 range

IP Blacklisting

Block specific IP addresses or ranges:

forms:
  contact:
    spam_protection:
      blacklist_ips:
        - "198.51.100.0/24"      # Known spam network
        - "203.0.113.99"         # Specific bad actor

Geographic Filtering

Restrict submissions by country (premium feature):

forms:
  contact:
    spam_protection:
      geo_filter:
        allow_countries: ["US", "CA", "GB", "AU"]
        block_countries: ["CN", "RU"]

Time-Based Restrictions

Limit form submissions to specific time periods:

forms:
  business:
    spam_protection:
      time_restrictions:
        timezone: "America/New_York"
        business_hours_only: true
        allowed_hours:
          start: "09:00"
          end: "17:00"
        allowed_days: ["monday", "tuesday", "wednesday", "thursday", "friday"]

Security Analytics

Form Security Reports

Generate security reports for your forms:

# Get security report for a specific form
mailiam instant security form_abc123

# Get security summary for all forms
mailiam instant list --security

Example report:

Security Report for Contact Form (form_abc123)
=============================================

Last 30 days:
  Total submissions: 150
  Spam blocked: 23 (15.3%)
  Rate limit hits: 5
  Honeypot catches: 18

Top spam sources:
  - 198.51.100.44 (8 attempts)
  - 203.0.113.22 (5 attempts)
  - 192.0.2.88 (3 attempts)

Spam indicators:
  - Excessive URLs: 12 blocked
  - Suspicious keywords: 6 blocked
  - Bot patterns: 5 blocked

Real-time Monitoring

Monitor spam attempts in real-time:

# Monitor form submissions
mailiam instant submissions form_abc123 --live

# Filter for spam attempts only
mailiam instant submissions form_abc123 --spam-only

Integration with External Services

CAPTCHA Integration

Integrate with popular CAPTCHA services:

reCAPTCHA

forms:
  contact:
    spam_protection:
      captcha:
        provider: "recaptcha"
        site_key: "${RECAPTCHA_SITE_KEY}"
        secret_key: "${RECAPTCHA_SECRET_KEY}"
        threshold: 0.5           # Score threshold (0-1)

Frontend integration:

<form action="https://api.mailiam.dev/yourdomain.com/contact" method="POST">
  <!-- Form fields -->
  <input name="name" type="text" required>
  <input name="email" type="email" required>
  <textarea name="message" required></textarea>

  <!-- reCAPTCHA -->
  <div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY"></div>

  <button type="submit">Send</button>
</form>

hCaptcha

forms:
  contact:
    spam_protection:
      captcha:
        provider: "hcaptcha"
        site_key: "${HCAPTCHA_SITE_KEY}"
        secret_key: "${HCAPTCHA_SECRET_KEY}"

External Spam Detection

Integrate with third-party spam detection services:

forms:
  contact:
    spam_protection:
      external_services:
        akismet:
          api_key: "${AKISMET_API_KEY}"
          site_url: "https://yourdomain.com"

        spamhaus:
          enabled: true

        custom_webhook:
          url: "https://yourapi.com/spam-check"
          headers:
            Authorization: "Bearer ${SPAM_API_KEY}"

Testing Spam Protection

Test Honeypot Protection

# This should be blocked (honeypot filled)
curl -X POST https://api.mailiam.dev/yourdomain.com/contact \
  -F "name=Test User" \
  -F "email=test@example.com" \
  -F "message=Test message" \
  -F "_mailiam_honeypot=bot-content"

Test Rate Limiting

# Send multiple rapid requests (should hit rate limit)
for i in {1..15}; do
  curl -X POST https://api.mailiam.dev/yourdomain.com/contact \
    -F "name=Test $i" \
    -F "email=test$i@example.com" \
    -F "message=Test message $i"
done

Test Content Filtering

# This should be blocked (spam content)
curl -X POST https://api.mailiam.dev/yourdomain.com/contact \
  -F "name=Spam Bot" \
  -F "email=spam@bad-domain.com" \
  -F "message=Buy cheap viagra now! Visit casino-winner.com for amazing deals!"

Common Spam Patterns

Bot Signatures

mailiam automatically detects these bot patterns:

• Extremely fast form submission (< 2 seconds)
• Missing common browser headers
• Suspicious user agent strings
• JavaScript disabled (when required)
• Form fields filled in exact order

Content Patterns

Common spam content patterns that are filtered:

• Multiple URLs in message
• All caps text
• Excessive punctuation
• Random character strings
• Common spam keywords
• Email addresses in message body

Submission Patterns

• Multiple submissions from same IP
• Identical messages from different IPs
• Submissions outside business hours (if configured)
• Geographic mismatches (if geo-filtering enabled)

Best Practices

1. Layer Multiple Protections

Don’t rely on a single protection method:

forms:
  contact:
    spam_protection:
      level: "normal"
      honeypot: true
      rate_limit: 10
      content_filter: true
      captcha: true              # For high-risk forms

2. Monitor and Adjust

Regularly review spam reports and adjust settings:

# Weekly security review
mailiam instant security form_abc123

# Adjust rate limits based on legitimate traffic
# Tune content filters based on false positives

3. User Experience Balance

Balance security with user experience:

• Use CAPTCHA only for high-risk forms
• Set reasonable rate limits
• Provide clear error messages
• Allow legitimate users to contact you via alternative means

4. Regular Updates

Keep your spam protection updated:

# Update CLI for latest spam protection features
npm update -g mailiam

# Review and update spam protection settings quarterly

Troubleshooting

False Positives

If legitimate submissions are being blocked:

1. Check rate limits: May be too restrictive
2. Review content filters: Legitimate content may trigger filters
3. Verify honeypot implementation: Ensure it’s properly hidden
4. Check IP restrictions: User may be on blacklisted range

# Debug a specific submission
mailiam instant submissions form_abc123 --debug

# Temporarily reduce protection level
# Then gradually increase back

False Negatives

If spam is getting through:

1. Increase protection level: Move from “relaxed” to “normal” or “strict”
2. Enable missing features: Add honeypot, content filtering
3. Reduce rate limits: Tighten submission frequency
4. Add CAPTCHA: For persistent spam issues

Configuration Issues

# Test spam protection configuration
mailiam test config --validate-spam

# Check form-specific settings
mailiam forms list --security-details

Getting Help

Documentation Resources

• Configuration Schema - Complete configuration reference
• Security Overview - General security practices
• Rate Limiting - Detailed rate limiting guide

Support

If you need help with spam protection:

1. Security Reports: Generate detailed reports first
2. GitHub Issues: Report persistent spam patterns
3. Email Support: Contact support@mailiam.dev
4. Premium Support: Available for enterprise customers

Include in your support request:

• Form configuration
• Spam patterns you’re seeing
• Security reports
• Steps you’ve already tried