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 scopes to only the operations your application needs (e.g. mailboxes:read only)
• Configure domain restrictions to limit which mailbox domains a key can use

API Key Scopes

Each API key can be limited to a set of scopes. When no scopes are configured (or * is used), the key has full access. Available scopes:

• mailboxes:read, mailboxes:write — mailbox and message operations
• domains:read, domains:write — custom domain operations
• team:read, team:write — team operations
• identities:read, identities:write — identity operations

Read operations (GET) require the :read scope; write operations (POST, DELETE) require the :write scope. A key with insufficient scopes receives a 403 Forbidden response.

Domain Restrictions

You can configure allowed domains for each API key to limit which mailbox domains the key can create mailboxes on. This is useful when you want a key restricted to your own verified custom domains.

When allowed domains are configured for a key:

• POST /v1/mailboxes requests using a domain outside the allowed list receive a 403 Forbidden response
• If no domains are configured, the key can use the default domain (minutemail.cc) and your tenant’s verified custom domains (default)

Domain Format

You can specify domains in two formats:

1. Exact domain: example.com - Only allows mailboxes on exactly example.com
2. Wildcard subdomain: *.example.com - Allows mailboxes on any subdomain of example.com (e.g., app.example.com, sub.example.com) as well as example.com itself

Rate Limits & Quotas

Daily API Call Quota

API usage is subject to a daily quota that depends on your subscription plan (resets daily at midnight UTC):

Plan	API Calls per Day
Free	50
Hobbyist	1,000
Pro	10,000
Team	50,000 (shared across team)

When you exceed your daily quota, you’ll receive a 429 Too Many Requests response and the X-RateLimit-Remaining header will be 0.

Rate Limit Headers

API responses include the X-RateLimit-Remaining header showing how many API calls remain in your daily quota:

X-RateLimit-Remaining: 42

• On successful requests, this shows your remaining API calls for the current UTC day
• When quota is exceeded (429 response), this will be 0
• Use this header to track your usage and avoid hitting limits

Quotas

Your plan also includes limits for:

• Active Mailboxes: Maximum concurrent active mailboxes
  • Free: 2 mailboxes
  • Hobbyist: 10 mailboxes
  • Pro: 50 mailboxes
  • Team: 200 mailboxes (shared across team)
• Archived Mailboxes: Maximum stored archived mailboxes (recoverable mailboxes)
  • Free: 3 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. If omitted, the mailbox uses the platform default lifetime of 15 minutes. Mailboxes can also be created with noExpiration: true to never expire (see Mailboxes).

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: Authentication errors from the API gateway (missing or invalid API key) and usage-limit errors are returned as plain text with Content-Type: text/plain. Errors produced by the mailbox service (validation, not found, conflicts) are JSON. Your application should handle both JSON and plain text error responses.

Common Error Codes

HTTP Status	Error Code	Description
400	invalid_request	Invalid request (malformed JSON, missing required fields, unknown fields)
401	unauthorized	Missing or invalid API key
403	forbidden	You don’t have access to this resource, key lacks the required scope, or the mailbox domain is not allowed for your key
404	mailbox_not_found, mail_not_found, archived_mailbox_not_found, attachment_not_found	Resource not found
409	mailbox_alias_conflict	Mailbox alias is already in use
429	mailbox_limit_reached	Mailbox quota exceeded (active or archived mailbox limit)

A 403 Forbidden response with the message “domain not allowed for this tenant” indicates that the domain requested in POST /v1/mailboxes is not in your API key’s allowed domains or your account’s verified domains. Check the API key’s domain configuration in the dashboard.