API Documentation

Welcome to the leveragers.xyz API documentation. Our RESTful API provides programmatic access to temporary email infrastructure, perfect for automated testing, development workflows, and secure messaging.

BASE URL: https://leveragers.xyz/api

Key Features

  • Instant Email Generation - Create temporary mailboxes in milliseconds
  • Real-time Inbox Access - Retrieve emails as they arrive
  • Custom Domain Support - Use your own domains for email generation
  • RESTful Architecture - Simple, predictable HTTP endpoints
  • JSON Responses - All responses in standard JSON format

Quick Start Guide

Get up and running with the leveragers.xyz API in just a few steps.

1 Create an Account

Sign up at leveragers.xyz/register to get your API key.

2 Get Your API Key

Navigate to your Profile page and copy your API key from the "API Credentials" section.

Keep it Secret

Your API key is like a password. Never share it publicly or commit it to version control.

3 Make Your First Request

Generate your first temporary email address:

CURL
curl -X POST https://leveragers.xyz/api/mail/generate \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json"
PYTHON
import requests

url = "https://leveragers.xyz/api/mail/generate"
headers = {"X-API-KEY": "your_api_key_here"}

response = requests.post(url, headers=headers)
email = response.json()["email"]
print(f"Generated: {email}")
JAVASCRIPT
const response = await fetch('https://leveragers.xyz/api/mail/generate', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your_api_key_here'
  }
});

const data = await response.json();
console.log('Generated:', data.email);

4 Check Your Inbox

Retrieve emails sent to your generated address:

CURL
curl https://leveragers.xyz/api/mail/list \
  -H "X-API-KEY: your_api_key_here"

Authentication

All API requests require authentication using your API key passed in the X-API-KEY header.

How It Works

Every request to the API must include your API key in the request headers. The server validates this key before processing your request.

AUTHENTICATION HEADER
X-API-KEY: your_api_key_here
Security Best Practices
  • Never expose your API key in client-side code
  • Use environment variables to store your key
  • Rotate your key regularly from the Profile page
  • Use HTTPS for all API requests

Email Generation

POST /mail/generate

Creates a new temporary email address. You can optionally specify a domain and custom prefix.

Request Parameters

Parameter Type Required Description
domain string No Target domain (defaults to leveragers.xyz)
prefix string No Custom email prefix (auto-generated if not provided)
REQUEST
curl -X POST https://leveragers.xyz/api/mail/generate \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "leveragers.xyz", "prefix": "test"}'
REQUEST
import requests

url = "https://leveragers.xyz/api/mail/generate"
headers = {"X-API-KEY": "your_api_key_here"}
data = {"domain": "leveragers.xyz", "prefix": "test"}

response = requests.post(url, headers=headers, json=data)
print(response.json())
REQUEST
const response = await fetch('https://leveragers.xyz/api/mail/generate', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    domain: 'leveragers.xyz',
    prefix: 'test'
  })
});

const data = await response.json();
console.log(data);
RESPONSE - 201 CREATED
{
  "email": "test@leveragers.xyz",
  "created_at": "2026-02-15T04:40:00Z"
}

List Emails

GET /mail/list

Retrieves all emails for the authenticated user. Supports pagination.

Query Parameters

Parameter Type Default Description
page integer 1 Page number for pagination
per_page integer 10 Number of results per page (max: 100)
REQUEST
curl https://leveragers.xyz/api/mail/list?page=1&per_page=10 \
  -H "X-API-KEY: your_api_key_here"
RESPONSE - 200 OK
{
  "emails": [
    {
      "id": 1,
      "email_address": "test@leveragers.xyz",
      "domain_id": 2,
      "created_at": "2026-02-15T04:40:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 10
}

Get Email Details

GET /mail/{email_address}/messages

Retrieves all messages received for a specific email address.

REQUEST
curl https://leveragers.xyz/api/mail/test@leveragers.xyz/messages \
  -H "X-API-KEY: your_api_key_here"
RESPONSE - 200 OK
{
  "messages": [
    {
      "id": 42,
      "from_address": "noreply@example.com",
      "subject": "Welcome to our service",
      "body": "Thank you for signing up...",
      "html_content": "<html>...</html>",
      "received_at": "2026-02-15T04:41:00Z"
    }
  ],
  "total": 1
}

Domain Management

GET /domains/user

Lists all domains owned by the authenticated user.

RESPONSE - 200 OK
{
  "domains": [
    {
      "id": 1,
      "domain_name": "example.com",
      "status": "active",
      "verified_at": "2026-02-14T10:00:00Z",
      "created_at": "2026-02-14T09:00:00Z"
    }
  ],
  "total": 1
}

Add Domain

POST /domains/add

Registers a new custom domain for email generation.

Parameter Type Required Description
domain string REQUIRED The domain name to register
REQUEST
curl -X POST https://leveragers.xyz/api/domains/add \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'
RESPONSE - 201 CREATED
{
  "message": "Domain added successfully",
  "domain_id": 1,
  "domain": {
    "id": 1,
    "domain_name": "example.com",
    "mx_record": "mail.leveragers.xyz",
    "status": "pending"
  }
}

Verify Domain

POST /domains/{domain_id}/verify

Verifies DNS configuration for a registered domain.

DNS Configuration Required

Before verifying, ensure you've added the required MX and TXT records to your domain's DNS settings. You can find these records in the domain details on the Domains page.

REQUEST
curl -X POST https://leveragers.xyz/api/domains/1/verify \
  -H "X-API-KEY: your_api_key_here"
RESPONSE - 200 OK
{
  "status": "active",
  "message": "Domain verified successfully",
  "verified_at": "2026-02-15T04:42:00Z"
}

Error Codes

The API uses standard HTTP status codes to indicate success or failure.

Code Status Description
200 OK Request successful
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
404 Not Found Resource not found
500 Server Error Internal server error

Error Response Format

ERROR RESPONSE
{
  "error": "Invalid API key",
  "status": 401
}

Rate Limits

To ensure fair usage and system stability, API requests are rate-limited.

Free Tier

100

requests per hour

Pro Tier

1,000

requests per hour

Rate Limit Headers

All responses include X-RateLimit-Remaining and X-RateLimit-Reset headers to help you track your usage.