API Reference

Complete Aliasify API documentation for developers

The API is available exclusively with the Business plan.

Introduction

The Aliasify API lets you integrate email-alias features into your applications. Create aliases, retrieve emails, configure webhooks, and manage forwarding programmatically.

Naming note: the REST endpoints are mounted at /api/v1/addresses and /api/v1/emails for backward compatibility with installed clients. The product concept they manage is what we now call an alias in the dashboard. The JSON address field contains the email string itself; the JSON alias field is the optional friendly label you can attach.

Base URL

https://api.aliasify.app/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
Aliases	Create/list/delete aliases
Emails	Retrieve/delete received emails
Send Emails	Send emails from one of your aliases
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 an alias (the JSON `alias` field is the label, not a prefix)
curl -X POST https://api.aliasify.app/api/v1/addresses \
  -H "Authorization: Bearer jm_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"alias": "Test fixture"}'

Response:

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