All API endpoints require a personal API key. Each user has their own unique key tied to their subscription plan.
{apiKey}.
Keep your key secure — do not expose it in client-side code or share it publicly.
Get up and running in 3 steps.
Get your API Key
Copy your API key from the Authentication section above.
Create a temporary email
Call POST /api/emails/{apiKey} to generate a new random email address instantly.
Fetch incoming messages
Poll GET /api/messages/{apiKey}/{email} to retrieve all messages for that address.
# 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]
// 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);
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())
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());
All available API endpoints with parameters and response examples.
| Name | Type | Required | Description |
|---|---|---|---|
| apiKey | string | Required | Your API key |
| type | string | Required | Filter type: free / premium / all |
{
"status": true,
"data": {
"domains": [
{ "domain": "example.com", "type": "Free" },
{ "domain": "premium.io", "type": "Premium" }
]
}
}
| Name | Type | Required | Description |
|---|---|---|---|
| apiKey | string | Required | Your API key |
{
"status": true,
"data": {
"id": 42,
"email": "[email protected]",
"domain": "example.com",
"expire_at": "2026-04-08 12:00:00",
"email_token": "eyJ..."
}
}
| Name | Type | Required | Description |
|---|---|---|---|
| apiKey | string | Required | Your API key |
| string | Required | Current email address to replace | |
| username | string | Required | New username (part before @) |
| domain | string | Required | Domain from the available domains list |
{
"status": true,
"data": {
"email": "[email protected]",
"domain": "example.com",
"expire_at": "2026-04-08 12:00:00"
}
}
| Name | Type | Required | Description |
|---|---|---|---|
| apiKey | string | Required | Your API key |
| string | Required | Email address to delete |
{
"status": true,
"message": "Email has been successfully deleted."
}
| Name | Type | Required | Description |
|---|---|---|---|
| apiKey | string | Required | Your API key |
| string | Required | Email address to fetch messages for |
{
"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": []
}
]
}
| Name | Type | Required | Description |
|---|---|---|---|
| apiKey | string | Required | Your API key |
| messageId | string | Required | Message hash ID from the messages list |
{
"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": []
}
}
| Name | Type | Required | Description |
|---|---|---|---|
| apiKey | string | Required | Your API key |
| messageId | string | Required | Message hash ID to delete |
{
"status": true,
"message": "Message deleted successfully"
}
Each plan includes a monthly credit allowance. Credits are consumed per billable request and reset automatically at the end of each month.
429 status. Free requests (list, poll, delete message) continue to work. Purchase additional credits to restore access immediately.{
"status": false,
"message": "Monthly API request limit reached.",
"limit": 6000,
"used": 6000,
"resets_at": "2026-05-31"
}
429, stop sending billable requests and notify your application to pause until the reset date or until credits are purchased.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']
Standard HTTP status codes returned by the API.
| Code | Meaning | Description |
|---|---|---|
| 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 |