API Reference

Complete JunkMail API documentation for developers

The API is available exclusively with the Business plan.

Introduction

The JunkMail API allows you to integrate temporary email features into your applications. Create addresses, retrieve emails, configure webhooks, and manage forwarding programmatically.

Base URL

https://api.junkmail.dev/api/v1

Authentication

All API requests require an API key in the Authorization header:

Authorization: Bearer jm_live_xxxxxxxxxxxx

Response Format

The API returns JSON responses:

{
  "data": { ... }
}

In case of an error:

{
  "error": "Error description"
}

Rate Limiting

Plan	Requests/minute
Business	100

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Endpoints

Endpoint	Description
Authentication	API key management and scopes
Addresses	Create/list/delete temporary addresses
Emails	Retrieve/delete received emails
Send Emails	Send emails from a temporary address
Domains	Manage your custom domains
Forwarding	Manage email forwarding
Analytics	Statistics and metrics
Webhooks	Configure webhooks
Errors	Error codes

Audit Logs

All actions performed via the API are recorded in the audit logs. You can access them via:

GET /api/v1/audit-logs

Parameter	Type	Description
limit	number	Number of results (default: 20)
offset	number	Offset for pagination

SDK

SDKs are available to simplify integration:

• JavaScript/TypeScript - npm install @junkmail/sdk
• Python - pip install junkmail

Quick Example

# Create a temporary address
curl -X POST https://api.junkmail.dev/api/v1/addresses \
  -H "Authorization: Bearer jm_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"alias": "test-api"}'

Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "address": "test-api@junkmail.site",
    "alias": "test-api",
    "isActive": true,
    "createdAt": "2024-01-15T10:00:00Z",
    "expiresAt": "2024-01-22T10:00:00Z",
    "forwarding": null
  }
}