Mailscr API Documentation

🚀 Welcome to Mailscr API

Our API allows you to integrate temporary email functionality into your applications. Create disposable email addresses, receive emails, and manage domains programmatically.

Base URL: https://mailscr.us/api

📧 Email Management

GET List Emails

Endpoint: /email/{domain}/{user}/

Retrieve all emails for a specific user with pagination support.

Parameters:

Parameter Type Description Default
domain string Email domain Required
user string Username part of email Required
page integer Page number 1
limit integer Items per page (1-100) 20

Example Request:

curl -X GET "https://mailscr.us/api/email/example.com/john/?page=1&limit=20"

Response:

{ "emails": [ { "id": 123, "subject": "Welcome to our service", "sender": "noreply@service.com", "date": "2025-07-11T10:30:00Z", "body": "Plain text content", "html_body": "<h1>HTML content</h1>", "has_attachments": false } ], "total": 5, "page": 1, "limit": 20, "has_more": false }

GET Read Single Email

Endpoint: /email/{domain}/{user}/{email_id}

Retrieve a specific email by ID.

Example Request:

curl -X GET "https://mailscr.us/api/email/example.com/john/123"

DELETE Delete Email

Endpoint: /email/{domain}/{user}/{email_id}

Delete a specific email.

Example Request:

curl -X DELETE "https://mailscr.us/api/email/example.com/john/123"

POST Save Email

Endpoint: /save-email/{domain}/{user}/

Save a new email (typically used by mail server).

Request Body:

{ "subject": "Email subject", "sender": "sender@example.com", "date": "2025-07-11T10:30:00Z", "body": "Plain text content", "html_body": "<h1>HTML content</h1>", "has_attachments": false }

🌐 Domain Management

GET List All Domains

Endpoint: /domains/

Get a list of all available domains.

Example Response:

["example.com", "temp-mail.io", "disposable.email"]

GET Get Random Domains

Endpoint: /random-domains/

Get a random selection of online domains.

Parameters:

Parameter Type Description Default
page integer Page number 1
limit integer Number of domains (1-50) 20

Example Response:

{ "domains": ["example.com", "temp-mail.io"], "total": 2 }

POST Add Domain

Endpoint: /add-domain/{domain}

Add a new domain to the system.

Example Request:

curl -X POST "https://mailscr.us/api/add-domain/mydomain.com"

Response:

{ "status": "added", "domain": "mydomain.com", "is_online": true }

GET Check Domain MX Records

Endpoint: /check-mx/{domain}

Check if a domain has valid MX records pointing to our mail server.

Example Response:

{ "result": "online" }

🔧 Utility Endpoints

POST Refresh Domain Status

Endpoint: /refresh-domains/

Force refresh all domain statuses.

DELETE Cleanup Old Emails

Endpoint: /cleanup-old-emails/

Remove emails older than 7 days.

📝 Response Codes

Code Description
200 Success
400 Bad Request - Invalid parameters
404 Not Found - Resource doesn't exist
500 Internal Server Error

💡 Usage Examples

JavaScript Example

// Get emails for user async function getEmails(domain, user) { const response = await fetch(`https://mailscr.us/api/email/${domain}/${user}/`); const data = await response.json(); return data.emails; } // Add a new domain async function addDomain(domain) { const response = await fetch(`https://mailscr.us/api/add-domain/${domain}`, { method: 'POST' }); return await response.json(); }

Python Example

import requests # Get emails def get_emails(domain, user): response = requests.get(f'https://mailscr.us/api/email/{domain}/{user}/') return response.json() # Add domain def add_domain(domain): response = requests.post(f'https://mailscr.us/api/add-domain/{domain}') return response.json()

🔐 Rate Limiting

API requests are rate limited to prevent abuse. Current limits:

📞 Support

For API support, please contact us or email: support@mailscr.us