Get started with Mailoverse in under 5 minutes. Create your account, get your API key, and send your first test email. Step-by-step setup guide with code examples.

Getting Started

1. Create an Account

Sign up for a free account using GitHub or Google. No credit card required — the free plan includes 100 emails per month, which is perfect for getting started.

2. Get Your Credentials

After signing in, go to your Dashboard. You'll find two important pieces of information:

Domain
abc123xyz.mailoverse.com
Your unique subdomain. Send emails to any address at this domain.
API Key
a1b2c3d4e5f6789012345678abcdef01
Your secret key for API authentication. Keep this secure.

3. Send a Test Email

Configure your application to send an email to your Mailoverse subdomain. You can use any local part you want — they're all valid:

  • test@yoursubdomain.mailoverse.com
  • user123@yoursubdomain.mailoverse.com
  • signup-flow@yoursubdomain.mailoverse.com
  • anything-you-want@yoursubdomain.mailoverse.com

For testing, you can use any SMTP service, email API, or even send from your own mail server. See the Sending Emails guide for detailed configuration options.

4. Retrieve via API

Once you've sent an email, retrieve it using the API: 

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

If an email exists for that address, you'll get a response like this: 

{
  "email": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "from": ["noreply@yourapp.com"],
    "to": ["test@yoursubdomain.mailoverse.com"],
    "subject": "Welcome to Our App",
    "body": "Thanks for signing up! Click here to verify: https://yourapp.com/verify?token=abc123",
    "htmlBody": "<html>...</html>",
    "parsedHtml": {
      "links": [
        { "href": "https://yourapp.com/verify?token=abc123", "text": "Verify your email" }
      ],
      "images": ["https://yourapp.com/logo.png"]
    },
    "parsedText": {
      "links": [
        { "href": "https://yourapp.com/verify?token=abc123", "text": "https://yourapp.com/verify?token=abc123" }
      ],
      "images": []
    },
    "receivedAt": "2025-12-31T10:30:00.000Z"
  }
}

If no email exists yet, you'll receive { "email": null }. In your tests, you can poll the endpoint until an email arrives.

5. Use in Your Tests

Here's a simple example of using Mailoverse in a Playwright test: 

import { test, expect } from '@playwright/test';

const MAILOVERSE_DOMAIN = 'yoursubdomain.mailoverse.com';
const MAILOVERSE_API_KEY = process.env.MAILOVERSE_API_KEY;

test('user can sign up and verify email', async ({ page }) => {
  const testEmail = `test-${Date.now()}@${MAILOVERSE_DOMAIN}`;

  // Fill out signup form
  await page.goto('/signup');
  await page.fill('[name="email"]', testEmail);
  await page.fill('[name="password"]', 'SecurePass123!');
  await page.click('button[type="submit"]');

  // Wait for and retrieve the verification email
  let email = null;
  for (let i = 0; i < 10; i++) {
    const response = await fetch(
      `https://api.mailoverse.com/email?address=${testEmail}`,
      { headers: { 'Authorization': `Bearer ${MAILOVERSE_API_KEY}` } }
    );
    const data = await response.json();
    if (data.email) {
      email = data.email;
      break;
    }
    await page.waitForTimeout(1000);
  }

  expect(email).not.toBeNull();
  expect(email.subject).toContain('Verify');

  // Extract verification link and visit it
  const verifyLink = email.parsedHtml.links.find(
    link => link.href.includes('/verify')
  );
  await page.goto(verifyLink.href);

  // Assert verification succeeded
  await expect(page.locator('h1')).toContainText('Email Verified');
});

Next Steps

  • Sending Emails — Learn about SMTP configuration and sending emails from various providers.
  • API Reference — Complete documentation of the email retrieval endpoint.
  • Code Examples — Ready-to-use examples for cURL, JavaScript, Python, and testing frameworks.