Python examples for Mailoverse using the requests library. Learn to retrieve emails, implement polling, and create a reusable client class for email testing in Python.

Python

Examples for Python using the requests library.

Using requests 

import os
import requests

MAILOVERSE_DOMAIN = os.environ['MAILOVERSE_DOMAIN']
MAILOVERSE_API_KEY = os.environ['MAILOVERSE_API_KEY']

def get_email(address: str) -> dict | None:
    response = requests.get(
        'https://api.mailoverse.com/email',
        params={'address': address},
        headers={'Authorization': f'Bearer {MAILOVERSE_API_KEY}'}
    )
    response.raise_for_status()
    return response.json()['email']

# Usage
email = get_email(f'test@{MAILOVERSE_DOMAIN}')
if email:
    print(f"Subject: {email['subject']}")
    print(f"Links: {email['parsedHtml']['links']}")

With Polling 

import os
import time
import requests

def wait_for_email(address: str, timeout: int = 30, interval: int = 1) -> dict:
    """Poll for an email until it arrives or timeout is reached."""
    start_time = time.time()
    headers = {'Authorization': f"Bearer {os.environ['MAILOVERSE_API_KEY']}"}

    while time.time() - start_time < timeout:
        response = requests.get(
            'https://api.mailoverse.com/email',
            params={'address': address},
            headers=headers
        )
        response.raise_for_status()
        data = response.json()

        if data['email']:
            return data['email']

        time.sleep(interval)

    raise TimeoutError(f'Timeout waiting for email to {address}')

# Usage
email = wait_for_email('test@yoursubdomain.mailoverse.com')
print(f"Received: {email['subject']}")

Client Class

A full-featured client class with type hints and dataclasses: 

import os
import time
from typing import Optional
from dataclasses import dataclass
import requests

@dataclass
class ParsedContent:
    links: list[dict[str, str]]
    images: list[str]
    body: str

@dataclass
class Email:
    id: str
    from_addresses: list[str]
    to_addresses: list[str]
    subject: Optional[str]
    body: Optional[str]
    html_body: Optional[str]
    parsed_html: Optional[ParsedContent]
    parsed_text: Optional[ParsedContent]
    received_at: str

    @classmethod
    def from_dict(cls, data: dict) -> 'Email':
        return cls(
            id=data['id'],
            from_addresses=data['from'],
            to_addresses=data['to'],
            subject=data.get('subject'),
            body=data.get('body'),
            html_body=data.get('htmlBody'),
            parsed_html=ParsedContent(**data['parsedHtml']) if data.get('parsedHtml') else None,
            parsed_text=ParsedContent(**data['parsedText']) if data.get('parsedText') else None,
            received_at=data['receivedAt'],
        )

class MailoverseClient:
    def __init__(self, api_key: Optional[str] = None, domain: Optional[str] = None):
        self.api_key = api_key or os.environ['MAILOVERSE_API_KEY']
        self.domain = domain or os.environ['MAILOVERSE_DOMAIN']
        self.base_url = 'https://api.mailoverse.com'

    def get_email(self, address: str) -> Optional[Email]:
        response = requests.get(
            f'{self.base_url}/email',
            params={'address': address},
            headers={'Authorization': f'Bearer {self.api_key}'}
        )
        response.raise_for_status()
        data = response.json()['email']
        return Email.from_dict(data) if data else None

    def wait_for_email(
        self,
        address: str,
        timeout: int = 30,
        interval: int = 1
    ) -> Email:
        start_time = time.time()
        while time.time() - start_time < timeout:
            email = self.get_email(address)
            if email:
                return email
            time.sleep(interval)
        raise TimeoutError(f'Timeout waiting for email to {address}')

    def generate_test_email(self, prefix: str = 'test') -> str:
        import random
        import string
        suffix = ''.join(random.choices(string.ascii_lowercase + string.digits, k=8))
        return f'{prefix}-{int(time.time())}-{suffix}@{self.domain}'

# Usage
client = MailoverseClient()
test_email = client.generate_test_email('signup')
email = client.wait_for_email(test_email)
print(f"Received: {email.subject}")

Using with pytest 

import pytest
from mailoverse import MailoverseClient

@pytest.fixture
def mailoverse():
    return MailoverseClient()

def test_signup_sends_verification_email(mailoverse, app_client):
    test_email = mailoverse.generate_test_email('signup')

    # Trigger signup in your app
    app_client.post('/signup', json={
        'email': test_email,
        'password': 'SecurePass123!'
    })

    # Wait for verification email
    email = mailoverse.wait_for_email(test_email)

    assert 'Verify' in email.subject
    assert email.parsed_html is not None
    assert len(email.parsed_html.links) == 1
    assert '/verify?token=' in email.parsed_html.links[0]['href']

See Also