API Documentation

Welcome to the SpamKiller API. Our AI-powered spam detection service helps you identify and filter spam submissions from contact forms, comments, and user-generated content.

Authentication

All API requests require authentication using an API key. You can obtain your API key from your project dashboard.

Authentication Methods

Include your API key in one of the following headers:

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY

Rate Limits

Rate limits are based on your subscription plan. When you exceed your limit, you'll receive a 429 Too Many Requests response.

Retrieve information about your project's subscription, plan details, and usage statistics.

Request Example

curl -X GET https://spamkiller.io/api/v1/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "data": {
    "project": {
      "id": 1,
      "name": "My First Project",
      "slug": "my-first-project",
      "active": true
    },
    "subscription": {
      "status": "active",
      "plan": {
        "name": "Free",
        "slug": "free",
        "price": "0.00",
        "currency": "USD",
        "validations_per_month": 100
      },
      "usage": {
        "validations_used": 3,
        "validations_remaining": 97,
        "validations_limit": 100,
        "usage_percentage": 3
      },
      "billing": {
        "starts_at": "2025-10-28T09:48:35+00:00",
        "ends_at": null,
        "validations_reset_at": "2025-11-28T09:48:35+00:00",
        "payment_method": "manual"
      }
    }
  }
}

Analyze content for spam detection using AI. This is the main endpoint for validating user submissions.

Request Parameters

Request Example

curl -X POST https://spamkiller.io/api/v1/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context": "E-commerce website selling outdoor equipment. Customer support contact form.",
    "email": "john.smith@company.com",
    "body": {
      "name": "John Smith",
      "phone": "+1234567890",
      "message": "Hello, I would like to schedule a meeting next week to discuss hiking boots."
    }
  }'

Response Example

{
  "success": true,
  "data": {
    "validation_id": 123,
    "is_spam": false,
    "spam_score": 5,
    "confidence": 95,
    "reasons": [
      "Message is professional, coherent, and grammatically correct.",
      "Clear intent to discuss product offerings.",
      "Email address format is professional and plausible."
    ],
    "red_flags": [],
    "recommendation": "Treat as a legitimate inquiry.",
    "processing_time_ms": 8140
  }
}

Response Fields

Report a validation result as a false positive. This helps our AI model improve accuracy and learn from incorrect classifications. Your feedback is valuable for training and refining spam detection.

Path Parameters

Request Body Parameters

Request Example

curl -X POST https://spamkiller.io/api/v1/validations/12345/report-false-positive \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Legitimate customer inquiry",
    "feedback": "This was a real customer asking about product availability. The AI incorrectly flagged it as spam because of the phrase ''limited time offer'' which the customer was referring to."
  }'

Response Example (Success)

{
  "success": true,
  "message": "Thank you for your feedback. Our team will review this validation.",
  "data": {
    "validation_id": 12345,
    "false_positive": true,
    "reported_at": "2025-11-06T12:34:56+00:00"
  }
}

Response Example (Already Reported)

{
  "success": false,
  "error": "This validation has already been reported as a false positive"
}

Submit a rating and optional comment for a validation result. This helps us understand overall satisfaction with the API accuracy and identify areas for improvement.

Path Parameters

Request Body Parameters

Request Example

curl -X POST https://spamkiller.io/api/v1/validations/12345/feedback \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5,
    "comment": "Perfect detection! Caught a sophisticated spam attempt that other services missed."
  }'

Response Example (Success)

{
  "success": true,
  "message": "Thank you for your feedback!",
  "data": {
    "validation_id": 12345,
    "rating": 5,
    "submitted_at": "2025-11-06T12:34:56+00:00"
  }
}

Response Example (Already Submitted)

{
  "success": false,
  "error": "Feedback has already been submitted for this validation or rating is invalid"
}

Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur in your SpamKiller account. Instead of polling for changes, webhooks push data to your server instantly.

Available Events

Create Webhook

Request Body

{
  "url": "https://your-domain.com/webhooks/spam-analyzer",
  "events": [
    "validation.spam_detected",
    "credits.low"
  ]
}

Response

{
  "success": true,
  "message": "Webhook created successfully",
  "data": {
    "id": 1,
    "url": "https://your-domain.com/webhooks/spam-analyzer",
    "events": ["validation.spam_detected", "credits.low"],
    "secret": "wh_sec_abc123xyz789...",
    "active": true,
    "created_at": "2025-11-04T10:30:00Z"
  }
}

List Webhooks

Returns all webhooks for your project with delivery statistics (success rate, last delivery time, etc.).

Example Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "url": "https://your-domain.com/webhooks/spam-analyzer",
      "events": ["validation.spam_detected", "credits.low"],
      "active": true,
      "successful_deliveries": 150,
      "failed_deliveries": 3,
      "success_rate": 98.04,
      "last_delivered_at": "2025-11-04T10:30:00Z",
      "created_at": "2025-11-01T09:00:00Z"
    }
  ]
}

Update Webhook

Update webhook URL, events, or enable/disable it. All fields are optional.

Request Body

{
  "events": ["validation.spam_detected", "validation.legitimate_detected"],
  "active": true
}

Delete Webhook

Permanently delete a webhook subscription. This cannot be undone.

Response

{
  "success": true,
  "message": "Webhook deleted successfully"
}

Signature Verification

All webhooks include an HMAC SHA256 signature in the X-Webhook-Signature header. Always verify this signature to ensure the webhook is from SpamKiller.

PHP Example

<?php

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secret = 'wh_sec_abc123xyz789...'; // Your webhook secret

$expectedSignature = hash_hmac('sha256', $payload, $secret);

if (hash_equals($expectedSignature, $signature)) {
    // Signature is valid
    $data = json_decode($payload, true);
    // Process webhook...
    http_response_code(200);
} else {
    http_response_code(401);
    die('Invalid signature');
}

Webhook Payload Format

{
  "event": "validation.spam_detected",
  "timestamp": "2025-11-04T10:30:00Z",
  "webhook_id": 1,
  "data": {
    "id": 123,
    "is_spam": true,
    "spam_score": 85,
    "confidence": 92,
    "email": "spammer@example.com",
    "project_id": 1,
    "created_at": "2025-11-04T10:30:00Z"
  }
}

Retry Logic

Error Handling

All error responses follow the same format with a success: false flag.

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or inactive"
}

{
  "success": false,
  "error": "No active subscription",
  "message": "This project does not have an active subscription"
}

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "email": ["The email field must be a valid email address."]
  }
}

{
  "success": false,
  "error": "Validation limit exceeded",
  "message": "You have reached your monthly validation limit.",
  "details": {
    "limit": 100,
    "used": 100,
    "resets_at": "2025-11-28T09:48:35+00:00"
  }
}

Code Examples

<?php

$apiKey = 'YOUR_API_KEY';
$apiUrl = 'https://spamkiller.io/api/v1/validate';

$data = [
    'context' => 'E-commerce website selling electronics. Contact form for customer support.',
    'email' => 'customer@example.com',
    'body' => [
        'name' => 'John Doe',
        'subject' => 'Product inquiry',
        'message' => 'Hello, I would like more information about your products.'
    ]
];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($httpCode === 200 && $result['success']) {
    if ($result['data']['is_spam']) {
        echo "Spam detected! Score: " . $result['data']['spam_score'];
    } else {
        echo "Content is legitimate!";
    }
} else {
    echo "Error: " . ($result['message'] ?? 'Unknown error');
}

const fetch = require('node-fetch');

const apiKey = 'YOUR_API_KEY';
const apiUrl = 'https://spamkiller.io/api/v1/validate';

const data = {
  context: 'SaaS application for project management. User registration form.',
  email: 'newuser@example.com',
  body: {
    username: 'johndoe',
    company: 'Acme Corp',
    phone: '+1234567890'
  }
};

fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => {
  if (result.success) {
    if (result.data.is_spam) {
      console.log(`Spam detected! Score: ${result.data.spam_score}`);
    } else {
      console.log('Content is legitimate!');
    }
  } else {
    console.error(`Error: ${result.message}`);
  }
})
.catch(error => console.error('Request failed:', error));

import requests

api_key = 'YOUR_API_KEY'
api_url = 'https://spamkiller.io/api/v1/validate'

data = {
    'context': 'Blog about technology and AI. Comment form on article pages.',
    'email': 'reader@example.com',
    'body': {
        'author_name': 'Jane Smith',
        'comment': 'Great article! Very informative and well-written.'
    }
}

headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {api_key}'
}

response = requests.post(api_url, json=data, headers=headers)
result = response.json()

if response.status_code == 200 and result['success']:
    if result['data']['is_spam']:
        print(f"Spam detected! Score: {result['data']['spam_score']}")
    else:
        print('Content is legitimate!')
else:
    print(f"Error: {result.get('message', 'Unknown error')}")