Dashboard API Docs
REST API v1

Mail Wave API

Build powerful applications with temporary email addresses. Generate, manage, and receive emails programmatically.

REST API
JSON Responses
API Key Auth
Base URL https://mailwave.dev/api
Authentication

All API endpoints require a personal API key. Each user has their own unique key tied to their subscription plan.

API Key Required
Your personal API key must be included in every request as a URL parameter {apiKey}. Keep your key secure — do not expose it in client-side code or share it publicly.
Sign In to View Your API Key
Log in to your account to access your personal API key. API access is available on paid plans.
Quick Start

Get up and running in 3 steps.

1

Get your API Key

Copy your API key from the Authentication section above.

2

Create a temporary email

Call POST /api/emails/{apiKey} to generate a new random email address instantly.

3

Fetch incoming messages

Poll GET /api/messages/{apiKey}/{email} to retrieve all messages for that address.

cURL
PHP
Python
Node.js
cURL
# Step 1: Create a random email
curl -X POST https://mailwave.dev/api/emails/YOUR_API_KEY

# Step 2: Get messages for that email
curl https://mailwave.dev/api/messages/YOUR_API_KEY/[email protected]
PHP
// Step 1: Create a random email
$apiKey = 'YOUR_API_KEY';

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => 'https://mailwave.dev/api/emails/' . $apiKey,
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
$email    = $response['data']['email'];

// Step 2: Get messages for that email
curl_setopt($ch, CURLOPT_URL, 'https://mailwave.dev/api/messages/' . $apiKey . '/' . $email);
curl_setopt($ch, CURLOPT_POST, false);
$messages = json_decode(curl_exec($ch), true);
curl_close($ch);

var_dump($messages);
Python
import requests

API_KEY  = 'YOUR_API_KEY'
BASE_URL = 'https://mailwave.dev/api'

# Step 1: Create a random email
res   = requests.post(f'{BASE_URL}/emails/{API_KEY}')
email = res.json()['data']['email']
print(f'Created: {email}')

# Step 2: Poll for incoming messages
msgs = requests.get(f'{BASE_URL}/messages/{API_KEY}/{email}')
print(msgs.json())
Node.js
const API_KEY  = 'YOUR_API_KEY';
const BASE_URL = 'https://mailwave.dev/api';

// Step 1: Create a random email
const res   = await fetch(`${BASE_URL}/emails/${API_KEY}`, { method: 'POST' });
const data  = await res.json();
const email = data.data.email;
console.log('Created:', email);

// Step 2: Poll for incoming messages
const msgs = await fetch(`${BASE_URL}/messages/${API_KEY}/${email}`);
console.log(await msgs.json());
Endpoints

All available API endpoints with parameters and response examples.

GET /domains/{apiKey}/{type} Retrieve available domains
Parameters
NameTypeRequiredDescription
apiKey string Required Your API key
type string Required Filter type: free / premium / all
Response
200 Success 401 Unauthorized 404 Not Found
JSON
{
  "status": true,
  "data": {
    "domains": [
      { "domain": "example.com", "type": "Free" },
      { "domain": "premium.io", "type": "Premium" }
    ]
  }
}
POST /emails/{apiKey} Generate a new random email
Parameters
NameTypeRequiredDescription
apiKey string Required Your API key
Response
200 Success 401 Unauthorized
JSON
{
  "status": true,
  "data": {
    "id": 42,
    "email": "[email protected]",
    "domain": "example.com",
    "expire_at": "2026-04-08 12:00:00",
    "email_token": "eyJ..."
  }
}
POST /emails/{apiKey}/{email}/{username}/{domain} Change email address
Parameters
NameTypeRequiredDescription
apiKeystringRequiredYour API key
emailstringRequiredCurrent email address to replace
usernamestringRequiredNew username (part before @)
domainstringRequiredDomain from the available domains list
Response
200 Success 401 Unauthorized 404 Not Found
JSON
{
  "status": true,
  "data": {
    "email": "[email protected]",
    "domain": "example.com",
    "expire_at": "2026-04-08 12:00:00"
  }
}
POST /emails/{apiKey}/{email} Delete an email address
Parameters
NameTypeRequiredDescription
apiKeystringRequiredYour API key
emailstringRequiredEmail address to delete
Response
200 Success 401 Unauthorized 404 Not Found
JSON
{
  "status": true,
  "message": "Email has been successfully deleted."
}
GET /messages/{apiKey}/{email} Get all messages for an email
Parameters
NameTypeRequiredDescription
apiKeystringRequiredYour API key
emailstringRequiredEmail address to fetch messages for
Response
200 Success 401 Unauthorized
JSON
{
  "status": true,
  "data": [
    {
      "id": "a1b2c3...",
      "subject": "Welcome!",
      "from": "[email protected]",
      "from_email": "[email protected]",
      "to": "[email protected]",
      "receivedAt": "2026-04-06 12:00:00",
      "is_seen": false,
      "attachments": []
    }
  ]
}
GET /messages/{apiKey}/message/{messageId} Get a single message with full content
Parameters
NameTypeRequiredDescription
apiKeystringRequiredYour API key
messageIdstringRequiredMessage hash ID from the messages list
Response
200 Success 401 Unauthorized 404 Not Found
JSON
{
  "status": true,
  "data": {
    "id": "a1b2c3...",
    "subject": "Welcome!",
    "from": "Service",
    "from_email": "[email protected]",
    "content": "<p>Hello...</p>",
    "html": true,
    "receivedAt": "2026-04-06 12:00:00",
    "attachments": []
  }
}
POST /messages/{apiKey}/message/{messageId} Delete a specific message
Parameters
NameTypeRequiredDescription
apiKeystringRequiredYour API key
messageIdstringRequiredMessage hash ID to delete
Response
200 Success 401 Unauthorized 404 Not Found
JSON
{
  "status": true,
  "message": "Message deleted successfully"
}
Rate Limiting

Each plan includes a monthly credit allowance. Credits are consumed per billable request and reset automatically at the end of each month.

Free Requests
List domains
Poll messages
Delete message
Billable (1 credit each)
Create email
Update email
Delete email
Read message
Reset Cycle
Credits reset on the last day of each month. Unused plan credits do not carry over, but purchased bonus credits never expire.
429 Too Many Requests — Credits Exhausted
When your monthly credit limit is reached, all billable API requests return a 429 status. Free requests (list, poll, delete message) continue to work. Purchase additional credits to restore access immediately.
429 Response
{
  "status": false,
  "message": "Monthly API request limit reached.",
  "limit": 6000,
  "used": 6000,
  "resets_at": "2026-05-31"
}
Best Practice
Always check the HTTP status code before processing the response. If you receive a 429, stop sending billable requests and notify your application to pause until the reset date or until credits are purchased.
Python — Handling 429
import requests

res = requests.post('https://mailwave.dev/api/emails/YOUR_KEY')

if res.status_code == 429:
    data = res.json()
    print(f"Limit reached. Resets: {data['resets_at']}")
elif res.status_code == 200:
    email = res.json()['data']['email']
Error Codes

Standard HTTP status codes returned by the API.

CodeMeaningDescription
200 Success Request completed successfully
401 Unauthorized Invalid or missing API key
404 Not Found Resource not found or invalid parameter
429 Too Many Requests Monthly credit limit reached — purchase credits or wait for reset