Skip to content

API Overview

The Smailander API provides programmatic access to all platform features, including honeypot management, email analysis, threat detection, and reporting.

API Base URL

Production: https://api.smailander.com/v1
Staging: https://api-staging.smailander.com/v1

Authentication

Smailander uses API keys for authentication.

API Key in Header

curl -X GET https://api.smailander.com/v1/emails \
  -H "Authorization: Bearer YOUR_API_KEY"

API Key in Query Parameter

curl -X GET https://api.smailander.com/v1/emails?api_key=YOUR_API_KEY

Security

Never expose your API key in client-side code. Always use server-side requests.

Rate Limiting

Plan Requests per Minute Requests per Hour Requests per Day
Free 60 1,000 10,000
Pro 300 5,000 50,000
Enterprise Unlimited Unlimited Unlimited

Rate Limit Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1647120000

Rate Limit Error

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 60 seconds."
}

API Key Permissions

API keys can be scoped to specific endpoints:

{
  "key_id": "key_abc123",
  "name": "Production Key",
  "permissions": [
    "emails:read",
    "emails:write",
    "honeypots:read",
    "honeypots:write",
    "reports:read",
    "webhooks:manage"
  ],
  "rate_limit": {
    "per_minute": 300,
    "per_hour": 5000,
    "per_day": 50000
  }
}

Response Format

All API responses follow a consistent format:

Success Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-12T14:30:15Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Invalid email address",
    "details": {
      "field": "email",
      "value": "invalid-email"
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-12T14:30:15Z"
  }
}

HTTP Status Codes

Code Meaning Description
200 OK Request successful
201 Created Resource created successfully
204 No Content Request successful, no content returned
400 Bad Request Invalid request parameters
401 Unauthorized Authentication required or failed
403 Forbidden Insufficient permissions
404 Not Found Resource not found
409 Conflict Resource already exists
422 Unprocessable Entity Validation error
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error
503 Service Unavailable Service temporarily unavailable

Pagination

List endpoints support pagination:

GET /v1/emails?page=1&limit=25

Pagination Response

{
  "success": true,
  "data": [
    // Array of items
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 12847,
    "total_pages": 514,
    "has_next": true,
    "has_prev": false
  }
}

Pagination Parameters

Parameter Type Default Max Description
page integer 1 - Page number
limit integer 25 100 Items per page

Filtering

List endpoints support filtering:

GET /v1/emails?threat_score=gt:50&date_range=2026-03-01:2026-03-12

Filter Operators

Operator Description Example
eq: Equals threat_score=eq:80
ne: Not equals threat_score=ne:0
gt: Greater than threat_score=gt:50
gte: Greater than or equal threat_score=gte:50
lt: Less than threat_score=lt:100
lte: Less than or equal threat_score=lte:100
in: In list status=in:active,inactive
nin: Not in list status=nin:deleted
contains: Contains subject=contains:urgent
regex: Regular expression from=regex:.*@malicious.com

Sorting

List endpoints support sorting:

GET /v1/emails?sort=received_at:desc

Sort Parameters

Parameter Type Default Description
sort string id:asc Sort by field
sort_direction string asc Sort direction (asc/desc)

Sortable Fields

Common sortable fields include: - id, created_at, updated_at - received_at, sent_at - threat_score, malware_score, spam_score, phishing_score - name, email, subject

Field Selection

Select specific fields to reduce response size:

GET /v1/emails?fields=id,subject,threat_score,received_at

Field Selection Response

{
  "success": true,
  "data": [
    {
      "id": "email_abc123",
      "subject": "Urgent: Account compromised",
      "threat_score": 85,
      "received_at": "2026-03-12T14:30:15Z"
    }
  ]
}

Bulk Operations

Bulk Create

POST /v1/honeypots/bulk
Content-Type: application/json

[
  {
    "email_address": "honeypot1@company.com",
    "purpose": "monitoring"
  },
  {
    "email_address": "honeypot2@company.com",
    "purpose": "leak-detection"
  }
]

Bulk Update

PATCH /v1/honeypots/bulk
Content-Type: application/json

{
  "ids": ["honeypot_1", "honeypot_2"],
  "updates": {
    "status": "active"
  }
}

Bulk Delete

DELETE /v1/honeypots/bulk?ids=honeypot_1,honeypot_2

Webhooks

Webhooks allow real-time notifications:

{
  "webhook_id": "webhook_abc123",
  "url": "https://your-server.com/webhook",
  "events": [
    "email.received",
    "threat.detected",
    "pattern.detected"
  ],
  "secret": "webhook-secret-key",
  "status": "active"
}

See Webhooks for more details.

SDKs

Official SDKs are available:

Language Package Documentation
JavaScript @smailander/sdk GitHub
Python smailander-python GitHub
Go github.com/smailander/go-sdk GitHub
Java com.smailander:java-sdk GitHub

JavaScript SDK Example

import Smailander from '@smailander/sdk';

const client = new Smailander({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://api.smailander.com/v1'
});

// List emails
const emails = await client.emails.list({
  threat_score: 'gt:50',
  limit: 10
});

// Create honeypot
const honeypot = await client.honeypots.create({
  email_address: 'test@company.com',
  purpose: 'monitoring'
});

Python SDK Example

from smailander import Smailander

client = Smailander(api_key='YOUR_API_KEY')

# List emails
emails = client.emails.list(
    threat_score='gt:50',
    limit=10
)

# Create honeypot
honeypot = client.honeypots.create(
    email_address='test@company.com',
    purpose='monitoring'
)

API Endpoints

Authentication

Method Endpoint Description
POST /auth/login Login with magic link
POST /auth/verify Verify magic link token
POST /auth/refresh Refresh access token

Honeypots

Method Endpoint Description
GET /honeypots List all honeypots
POST /honeypots Create honeypot
GET /honeypots/:id Get honeypot details
PATCH /honeypots/:id Update honeypot
DELETE /honeypots/:id Delete honeypot
POST /honeypots/bulk Bulk create honeypots
PATCH /honeypots/bulk Bulk update honeypots
DELETE /honeypots/bulk Bulk delete honeypots

Emails

Method Endpoint Description
GET /emails List all emails
GET /emails/:id Get email details
DELETE /emails/:id Delete email
GET /emails/:id/attachments List email attachments
GET /emails/:id/attachments/:attachment_id Download attachment

Webhooks

Method Endpoint Description
GET /webhooks List all webhooks
POST /webhooks Create webhook
GET /webhooks/:id Get webhook details
PATCH /webhooks/:id Update webhook
DELETE /webhooks/:id Delete webhook
POST /webhooks/:id/test Test webhook
POST /webhooks/:id/disable Disable webhook
POST /webhooks/:id/enable Enable webhook

API Keys

Method Endpoint Description
GET /api-keys List all API keys
POST /api-keys Create API key
GET /api-keys/:id Get API key details
PATCH /api-keys/:id Update API key
DELETE /api-keys/:id Delete API key
POST /api-keys/:id/regenerate Regenerate API key

Users

Method Endpoint Description
GET /users/me Get current user
PATCH /users/me Update current user
GET /users/:id Get user details
DELETE /users/:id Delete user account

Reports

Method Endpoint Description
GET /reports List all reports
POST /reports Create report
GET /reports/:id Get report details
GET /reports/:id/download Download report
DELETE /reports/:id Delete report
POST /reports/:id/generate Generate report

OpenAPI Specification

The complete OpenAPI 3.0 specification is available:

  • Swagger UI: https://api.smailander.com/v1/swagger
  • OpenAPI JSON: https://api.smailander.com/v1/openapi.json

Testing

Test Environment

Use the staging environment for testing:

# Staging API
curl -X GET https://api-staging.smailander.com/v1/emails \
  -H "Authorization: Bearer STAGING_API_KEY"

Test Data

The staging environment includes sample test data: - 100 sample emails - 10 sample honeypots - Various threat types

Best Practices

1. Authentication

  • Use API keys: Don't embed credentials in code
  • Scope permissions: Limit API key permissions to minimum required
  • Rotate keys: Regularly rotate API keys
  • Secure storage: Store API keys securely (environment variables)

2. Rate Limiting

  • Handle 429 errors: Implement exponential backoff
  • Cache responses: Cache frequently accessed data
  • Batch requests: Use bulk operations when possible
  • Monitor usage: Track API usage to avoid limits

3. Error Handling

  • Check status codes: Always check HTTP status codes
  • Handle errors gracefully: Implement proper error handling
  • Log errors: Log errors for debugging
  • Retry transient failures: Retry on 5xx errors

4. Performance

  • Use pagination: Don't fetch all data at once
  • Select fields: Only request needed fields
  • Filter early: Apply filters to reduce result size
  • Use async processing: For long-running operations

Support

Changelog

v1.0.0 (2026-03-12)

  • Initial API release
  • Full CRUD operations for honeypots and emails
  • Webhook support
  • Report generation
  • Bulk operations support

Next Steps