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.

Quick Start

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.

cURL Example

# Step 1: Create email
curl -X POST https://mailwave.dev/api/emails/YOUR_API_KEY

# Step 2: Get messages
curl https://mailwave.dev/api/messages/YOUR_API_KEY/user@example.com

Endpoints

All available API endpoints with parameters and response examples.

GET /domains/{apiKey}/{type} Retrieve available domains

Parameters

Name	Type	Required	Description
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

Name	Type	Required	Description
apiKey	string	Required	Your API key

Response

200 Success 401 Unauthorized

JSON

{
  "status": true,
  "data": {
    "id": 42,
    "email": "abc123@example.com",
    "domain": "example.com",
    "expire_at": "2026-04-08 12:00:00",
    "email_token": "eyJ..."
  }
}

POST /emails/{apiKey}/{email}/{username}/{domain} Change email address

Parameters

Name	Type	Required	Description
apiKey	string	Required	Your API key
email	string	Required	Current email address to replace
username	string	Required	New username (part before @)
domain	string	Required	Domain from the available domains list

Response

200 Success 401 Unauthorized 404 Not Found

JSON

{
  "status": true,
  "data": {
    "email": "newname@example.com",
    "domain": "example.com",
    "expire_at": "2026-04-08 12:00:00"
  }
}

POST /emails/{apiKey}/{email} Delete an email address

Parameters

Name	Type	Required	Description
apiKey	string	Required	Your API key
email	string	Required	Email 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

Name	Type	Required	Description
apiKey	string	Required	Your API key
email	string	Required	Email address to fetch messages for

Response

200 Success 401 Unauthorized

JSON

{
  "status": true,
  "data": [
    {
      "id": "a1b2c3...",
      "subject": "Welcome!",
      "from": "noreply@service.com",
      "from_email": "noreply@service.com",
      "to": "abc123@example.com",
      "receivedAt": "2026-04-06 12:00:00",
      "is_seen": false,
      "attachments": []
    }
  ]
}

GET /messages/{apiKey}/message/{messageId} Get a single message with full content

Parameters

Name	Type	Required	Description
apiKey	string	Required	Your API key
messageId	string	Required	Message 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": "noreply@service.com",
    "content": "<p>Hello...</p>",
    "html": true,
    "receivedAt": "2026-04-06 12:00:00",
    "attachments": []
  }
}

POST /messages/{apiKey}/message/{messageId} Delete a specific message

Parameters

Name	Type	Required	Description
apiKey	string	Required	Your API key
messageId	string	Required	Message hash ID to delete

Response

200 Success 401 Unauthorized 404 Not Found

JSON

{
  "status": true,
  "message": "Message deleted successfully"
}

Error Codes

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