Complete API documentation for Mailoverse. Learn about authentication, endpoints, request/response formats, error handling, and best practices for the email retrieval API.

API Reference

The Mailoverse API allows you to retrieve emails sent to your subdomain. All requests must be authenticated with your API key.

Base URL
https://api.mailoverse.com

Authentication

All API requests require authentication using a Bearer token. Include your API key in the Authorization header: 

Authorization: Bearer your-api-key

You can find your API key in the Dashboard. Keep your API key secure and never expose it in client-side code.

Get Email

Retrieve the oldest unread email for a specific address. Once retrieved, the email is marked as read and won't be returned again on subsequent requests.

GET /email

Query Parameters

Parameter Type Required Description
address string Yes The full email address to check, e.g., test@yoursubdomain.mailoverse.com

Request Example 

curl -X GET 'https://api.mailoverse.com/email?address=test@yoursubdomain.mailoverse.com' \
  -H 'Authorization: Bearer your-api-key'

Response Format

The response is a JSON object containing the email data or null if no unread email exists for that address.

Success Response (Email Found) 

{
  "email": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "from": ["sender@example.com"],
    "to": ["test@yoursubdomain.mailoverse.com"],
    "subject": "Welcome to Our App",
    "body": "Plain text version of the email...",
    "htmlBody": "<html><body>HTML version...</body></html>",
    "parsedHtml": {
      "links": [
        { "href": "https://example.com/verify?token=abc123", "text": "Verify Email" },
        { "href": "https://example.com/help", "text": "Help Center" }
      ],
      "images": [
        "https://example.com/logo.png",
        "https://example.com/banner.jpg"
      ],
      "body": "<html><body>HTML version...</body></html>"
    },
    "parsedText": {
      "links": [
        { "href": "https://example.com/verify?token=abc123", "text": "https://example.com/verify?token=abc123" }
      ],
      "images": [],
      "body": "Plain text version of the email..."
    },
    "receivedAt": "2025-12-31T10:30:00.000Z"
  }
}

Success Response (No Email) 

{
  "email": null
}

Response Fields

Field Type Description
email object | null The email object, or null if no unread email exists
email.id string Unique identifier for the email (UUID)
email.from string[] Array of sender email addresses
email.to string[] Array of recipient email addresses
email.subject string Email subject line (optional)
email.body string Plain text body of the email (optional)
email.htmlBody string HTML body of the email (optional)
email.parsedHtml object Parsed content from HTML body (optional)
email.parsedText object Parsed content from plain text body (optional)
email.receivedAt string ISO 8601 timestamp when the email was received

Parsed Content Structure

Both parsedHtml and parsedText contain automatically extracted data to make testing easier:

Field Type Description
links Link[] Array of extracted links with href and text
links[].href string The URL of the link
links[].text string The visible text of the link (or image src if link wraps an image)
images string[] Array of image URLs found in the email
body string The original body content

Error Responses

Status Description Response Body
400 Missing or invalid address parameter { "error": "Missing 'address' query parameter" }
400 Invalid email address format { "error": "Invalid 'address' format" }
401 Missing Authorization header { "error": "Invalid authorization header" }
401 Invalid API key or domain mismatch { "error": "Invalid domain or key" }
404 Endpoint not found Not found

Rate Limits & Quotas

Each plan has a monthly email quota. Emails are counted when received, not when retrieved. Check your current usage in the Dashboard.

The API itself does not have strict rate limits, but we recommend implementing reasonable polling intervals (e.g., 1 second between requests) to avoid unnecessary load.

For plan details and quotas, see our Pricing page.

Next Steps

  • Code Examples — Ready-to-use examples for various languages and testing frameworks.
  • Sending Emails — Learn how to send emails to your Mailoverse subdomain.