API Overview

Introduction to the MailSentinel REST API for programmatic access to your email authentication data.

API Overview

The MailSentinel API provides programmatic access to your email authentication data, allowing you to integrate monitoring into your existing workflows.

Base URL

All API requests are made to:

https://api.mailsentinel.io/api

Authentication

Authenticate requests using Bearer tokens:

curl -X GET "https://api.mailsentinel.io/api/domains" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Obtaining API Tokens

  1. Go to Settings > API Keys
  2. Click Generate New Key
  3. Copy and securely store your token

Security: API tokens have full access to your account. Keep them secret and rotate regularly.

Response Format

All responses are JSON:

{
  "success": true,
  "data": {
    // Response data
  }
}

Error Responses

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Domain name is required"
  }
}

Rate Limiting

PlanRequests/MinuteRequests/Day
Free601,000
Pro30010,000
Enterprise1,000Unlimited

Rate limit headers:

  • X-RateLimit-Limit - Maximum requests
  • X-RateLimit-Remaining - Requests remaining
  • X-RateLimit-Reset - Reset timestamp

Common Endpoints

Health Check

GET /health

Response:

{
  "status": "ok",
  "timestamp": "2024-12-09T10:00:00Z"
}

List Domains

GET /api/organizations/{orgId}/domains

Response:

{
  "domains": [
    {
      "id": "dom_123",
      "domain": "example.com",
      "verified": true,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Get Domain Details

GET /api/domains/{domainId}

Response:

{
  "domain": {
    "id": "dom_123",
    "domain": "example.com",
    "verified": true,
    "dmarcRecords": [...],
    "spfRecords": [...],
    "dkimRecords": [...]
  }
}

Scan Domain

Trigger a DNS scan for a domain:

POST /api/domains/{domainId}/scan

Response:

{
  "dmarc": {
    "found": true,
    "record": "v=DMARC1; p=reject; ...",
    "policy": "reject"
  },
  "spf": {
    "found": true,
    "record": "v=spf1 include:... -all",
    "valid": true,
    "dnsLookups": 5
  }
}

SDKs

JavaScript/TypeScript

import { MailSentinel } from '@mailsentinel/sdk';
 
const client = new MailSentinel({
  apiKey: process.env.MAILSENTINEL_API_KEY
});
 
const domains = await client.domains.list('org_123');

Python

from mailsentinel import MailSentinel
 
client = MailSentinel(api_key=os.environ['MAILSENTINEL_API_KEY'])
 
domains = client.domains.list('org_123')

Webhooks

Receive real-time notifications for events:

Supported Events

EventDescription
domain.verifiedDomain ownership verified
domain.scan.completedDNS scan finished
alert.triggeredAlert condition met
report.receivedDMARC report processed

Webhook Payload

{
  "event": "alert.triggered",
  "timestamp": "2024-12-09T10:00:00Z",
  "data": {
    "alertId": "alert_123",
    "domainId": "dom_456",
    "type": "dmarc_failure",
    "message": "DMARC pass rate dropped below 95%"
  }
}

Configuring Webhooks

  1. Go to Settings > Webhooks
  2. Add your endpoint URL
  3. Select events to receive
  4. Save and test

Error Codes

CodeDescription
UNAUTHORIZEDInvalid or missing API token
FORBIDDENInsufficient permissions
NOT_FOUNDResource doesn't exist
VALIDATION_ERRORInvalid request parameters
RATE_LIMITEDToo many requests
INTERNAL_ERRORServer error

Best Practices

1. Use Pagination

For large datasets, use pagination:

GET /api/reports?page=1&limit=50

2. Cache Responses

Cache infrequently changing data like domain configurations.

3. Handle Rate Limits

Implement exponential backoff when rate limited.

4. Secure Your Tokens

  • Never commit tokens to version control
  • Use environment variables
  • Rotate tokens regularly

Next Steps