Suppression List API

Overview

The Suppression List API allows your applications to check email addresses against your suppression lists in real-time. Instead of downloading static files, you can make API requests to instantly verify if an email should be suppressed.

Getting Started

1. Create an API Key

1. Navigate to your campaign's affiliate details
2. Scroll to the "API Keys" section
3. Click "Create API Key"
4. Give your key a descriptive name (e.g., "Production Server", "Staging Environment")
5. Copy the key immediately — you won't be able to see it again

API Endpoints

Check Email Suppression

Endpoint: POST /api/v1/suppression/check

Authentication: Bearer token in Authorization header

Request Example

curl -X POST https://app.listarmor.com/api/v1/suppression/check \
  -H "Authorization: Bearer slm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "user1@example.com",
      "user2@example.com"
    ]
  }'

Response Example

{
  "results": {
    "user1@example.com": {
      "suppressed": true,
      "reason": "user_optout",
      "date_added": "2025-10-01T12:34:56Z"
    },
    "user2@example.com": {
      "suppressed": false
    }
  },
  "summary": {
    "total_checked": 2,
    "suppressed": 1,
    "clean": 1
  }
}

Request Parameters

Response Fields

API Usage Statistics

Endpoint: GET /api/v1/stats

View your API key usage statistics including request counts, hit rates, and recent activity.

Request Example

curl https://app.listarmor.com/api/v1/stats \
  -H "Authorization: Bearer slm_your_api_key_here"

Rate Limits

Each API key has a default rate limit of 10,000 requests per hour.

If you exceed the rate limit, you'll receive a 429 Too Many Requests response with a Retry-After header indicating when you can try again.

Best Practices

• Batch requests: Check multiple emails in a single request (up to 1,000) instead of making individual requests
• Implement caching: Cache suppression results for a short period to reduce API calls
• Handle errors gracefully: Implement retry logic with exponential backoff for transient errors
• Monitor usage: Check your API stats regularly to understand usage patterns
• Rotate keys: Periodically create new API keys and revoke old ones for security
• Use environment variables: Store API keys in environment variables, never in source code

Error Codes