Getting Started

The MinuteMail REST API allows you to programmatically create and manage temporary email mailboxes, receive emails, and integrate privacy-focused email workflows into your applications.

Requirements

To use the MinuteMail API, you’ll need:

1. An API Key: Generate one from your MinuteMail dashboard
2. A Base URL: The API is available at https://api.minutemail.co/v1

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer mmak_FKI5IKBJ4FSZJLUFGJ3IMF4A55W2OZW7YMLWD3JI33IVUGDEJXLQ

Getting an API Key

1. Log in to your MinuteMail dashboard at MinuteMail
2. Click your profile menu → API Keys
3. Click Create API Key
4. Copy and securely store your key (it won’t be shown again)

Security Best Practices

• Never commit API keys to version control
• Use environment variables to store keys in your applications
• Rotate keys regularly and revoke unused keys
• Restrict key permissions if your plan supports it
• Configure domain restrictions to limit where your API keys can be used from

Domain Restrictions

You can configure domain restrictions for each API key to enhance security by limiting which domains can use the key. This is particularly useful for client-side applications.

How It Works

When you configure allowed domains for an API key:

• The API validates the request’s Origin, Referer, or Host header against your allowed domains
• If the request comes from an unauthorized domain, it receives a 403 Forbidden response
• If no domains are configured, the key can be used from any domain (default)

Domain Format

You can specify domains in two formats:

1. Exact domain: example.com - Only allows requests from exactly example.com
2. Wildcard subdomain: *.example.com - Allows requests from any subdomain of example.com (e.g., app.example.com, sub.example.com)

Examples:

example.com           → Matches: example.com
*.example.com         → Matches: app.example.com, sub.example.com, example.com
localhost:3000        → Matches: localhost:3000 (useful for development)

Configuration

To configure domain restrictions:

1. Click your profile menu → API Keys in your MinuteMail dashboard
2. Create a new key or edit an existing one
3. Add allowed domains in the Domain Restrictions field (one per line)
4. Save the configuration

Best Practice: Always configure domain restrictions for API keys used in client-side (browser) applications to prevent unauthorized use if your key is exposed.

Rate Limits & Quotas

Rate Limits

API rate limits depend on your subscription plan:

Plan	Requests per Minute	Burst Limit
Free	60	100
Hobbyist	120	200
Pro	600	1000
Team	1200	2000

When you exceed your rate limit, you’ll receive a 429 Too Many Requests response.

Rate Limit Headers

Every API response includes the X-RateLimit-Remaining header showing how many API calls remain in your current quota:

X-RateLimit-Remaining: 942

• On successful requests, this shows your remaining API calls
• When rate limited (429 response), this will be 0
• Use this header to track your usage and avoid hitting limits

Quotas

Your plan includes daily quotas for:

• API Calls: Total API requests per day (resets daily at midnight UTC)
  • Free: 100 calls/day
  • Hobbyist: 1,000 calls/day
  • Pro: 10,000 calls/day
  • Team: 50,000 calls/day (shared across team)
• Active Mailboxes: Maximum concurrent active mailboxes
  • Free: 3 mailboxes
  • Hobbyist: 10 mailboxes
  • Pro: 50 mailboxes
  • Team: 200 mailboxes (shared across team)
• Archived Mailboxes: Maximum stored archived mailboxes (recoverable mailboxes)
  • Free: 5 archives
  • Hobbyist: 20 archives
  • Pro: 200 archives
  • Team: 1,000 archives

Common Patterns

Duration Format

Duration values (e.g., expiresIn) specify the mailbox lifetime in minutes as an integer value.

Examples:

• 30 - 30 minutes
• 10 - 10 minutes
• 60 - 60 minutes (1 hour)

The duration must be between 1 and 60 minutes.

Timestamps

All timestamps are in ISO 8601 format with UTC timezone:

2024-01-18T00:15:00Z

Error Handling

Most errors return a consistent JSON structure:

{
  "error": "error_code",
  "message": "Human-readable error description"
}

Note: Some errors (particularly authentication and domain restriction errors) may return plain text responses with Content-Type: text/plain. Your application should handle both JSON and plain text error responses.

Common Error Codes

HTTP Status	Error Code	Description
400	bad_request	Invalid request (malformed JSON, missing required fields)
401	unauthorized	Missing or invalid API key
403	forbidden	You don’t have access to this resource or domain restriction failed
404	not_found	Resource not found
429	rate_limit_exceeded	Too many requests (rate limit)
429	quota_exceeded	Usage quota exceeded
500	internal_error	Internal server error

Note: A 403 forbidden error with the message “API key not authorized for this domain” indicates that your API key has domain restrictions configured and the request is coming from an unauthorized domain. Check your API key’s domain configuration in the dashboard.