API Documentation

Integrate TempMail into your application. No authentication required for public endpoints.

Base URL: https://your-domain.com
Format: All responses are JSON.

Email Endpoints

GET/api/mail/messages?to={email}&page=1&limit=20

Retrieve paginated emails for an address.

Parameter	Type	Description
`to`	query string	Email address (e.g. `user@mailmomy.com`)
`page`	query string	Page number, default `1`
`limit`	query string	Items per page, default `20`, max `100`

curl "https://mailmomy.com/api/mail/messages?to=test@mailmomy.com&page=1&limit=20"

const res = await fetch('/api/mail/messages?to=test@mailmomy.com&page=1&limit=20');
const page = await res.json();

import requests
r = requests.get('https://mailmomy.com/api/mail/messages', params={'to': 'test@mailmomy.com', 'page': 1, 'limit': 20})
print(r.json())

Response:

{"emails":[{"id":"uuid","recipient":"test@mailmomy.com","from":"sender@example.com",
"subject":"Welcome","message":"<html>...</html>","receivedAt":"2026-03-08 10:30:00"}],
"total":54,"page":1,"limit":20,"pages":3}

DELETE/api/mail/delete?to={email}

Delete all emails for an address.

curl -X DELETE "https://mailmomy.com/api/mail/delete?to=test@mailmomy.com"

Response:

{"deleted": 5}

DELETE/api/mail/delete?id={uuid}

Delete a single email by its ID.

Parameter	Type	Description
`id`	query string	Email UUID (from the `id` field in messages response)

curl -X DELETE "https://mailmomy.com/api/mail/delete?id=550e8400-e29b-41d4-a716-446655440000"

Response:

{"deleted": 1}

Domain Endpoints

GET/api/domains

List all registered domains.

curl "https://mailmomy.com/api/domains"

GET/api/domains/active

List active domain names only (string array).

["boxmail.store","mailmomy.com"]

POST/api/domains

Add a new domain. MX record must point to our server first.

curl -X POST "https://mailmomy.com/api/domains" \
  -H "Content-Type: application/json" \
  -d '{"domain":"mydomain.com","owner":"John","email":"john@example.com"}'

Important: Your domain's MX record must point to mail.mailmomy.com before submitting. We verify DNS on submission and check daily.

GET/api/domains/check-dns?domain={domain}

Check if a domain's MX record points to our server.

{"ok": true, "message": "MX record points to mail.mailmomy.com"}

Webhooks

Get notified instantly when an email arrives. Register a webhook URL and we'll POST the email data to your server in real-time.

Register Webhook

POST /api/webhooks

curl -X POST "https://mailmomy.com/api/webhooks" \
  -H "Content-Type: application/json" \
  -d '{"recipient":"test@mailmomy.com","url":"https://yourapp.com/hook","secret":"your-secret"}'

Parameter	Type	Description
`recipient`	string	Email address to monitor
`url`	string	Your webhook URL (http:// or https://)
`secret`	string	Optional. Used to sign payloads with HMAC-SHA256

Response:

{"id": "webhook-uuid", "status": "ok"}

Webhook Payload

When an email arrives, we POST this JSON to your URL:

{
  "event": "email.received",
  "email": {
    "id": "uuid",
    "recipient": "test@mailmomy.com",
    "from": "sender@example.com",
    "subject": "Your verification code",
    "message": "<p>Your code is 123456</p>",
    "bodyText": "Your code is 123456",
    "receivedAt": "2026-03-28 15:30:00"
  },
  "timestamp": "2026-03-28T15:30:00Z"
}

Headers:

Header	Description
`Content-Type`	application/json
`User-Agent`	TempMail-Webhook/1.0
`X-Webhook-Signature`	HMAC-SHA256 hex digest (only if secret was set)

Verify Signature

If you set a secret, verify the signature to ensure the request is authentic:

import hmac, hashlib

def verify(payload_bytes, signature, secret):
    expected = hmac.new(secret.encode(), payload_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

List Webhooks

GET /api/webhooks?recipient=test@mailmomy.com

Delete Webhook

DELETE /api/webhooks?id=webhook-uuid

Notes

All emails auto-delete after 24 hours (configurable by admin)
Maximum email size: 300 KB (configurable by admin)
No authentication required for public endpoints
Default page limit: 50 emails per request (max configurable up to 300)
MX records are verified every 12 hours; domains pointing elsewhere are deactivated
Rate limit: 10,000 requests per minute per IP (configurable)