API Keys

API Keys provide secure programmatic access to MinuteMail services. This page explains how to create, configure, and manage API keys through the web interface.

Overview

API keys enable you to:

• Programmatically create mailboxes via REST API or SDK
• Retrieve messages without logging into the web interface
• Automate workflows for testing and development
• Integrate MinuteMail into your applications

For detailed API usage, see the API Documentation.

Accessing API Key Management

1. Click the profile menu in the top-right corner
2. Select API Keys
3. You’ll see the API Keys management page (https://minutemail.co/app/manage-api-keys)

Creating an API Key

Step 1: Configure Key Settings

In the “Create a new API key” section, configure:

Key Name (Required)

• Purpose - Helps identify the key’s purpose
• Examples:
  • “Production API Key”
  • “Testing Environment”
  • “GitHub Actions CI/CD”
  • “Customer Portal Integration”
• Best Practice - Use descriptive names for easy management

Expiry Date (Optional)

• Default - Leave empty for a key that never expires
• Set Expiration - Click the date picker to choose an expiry date
• Use Cases for Expiration:
  • Temporary access for contractors
  • Short-term testing periods
  • Security compliance requirements
  • Rotating keys on schedule

Security Tip: Set expiration dates for enhanced security, especially for shared or temporary keys.

Scopes (Required)

Each key is granted a set of scopes that define exactly what it can do. You can either:

• Enable All Access - the key receives the * scope and can do everything you can do, or
• Select individual scopes from the available groups:

Group	Scope	What it allows
Mailboxes	mailboxes:read	List and view mailboxes, emails, and attachments
Mailboxes	mailboxes:write	Create and delete mailboxes, delete emails
Domains	domains:read	List custom domains
Domains	domains:write	Register, verify, and delete domains
Team	team:read	List team members and invitations
Team	team:write	Add/remove members, manage invitations
Identities	identities:read	List OAuth clients and mock identities
Identities	identities:write	Create and delete OAuth clients and identities

You can only grant scopes you hold yourself — the form prevents privilege escalation.

Step 2: Create the Key

1. Ensure Key Name is filled in
2. Enable All Access or select at least one scope
3. Click Create API Key
4. The plaintext key is returned once and shown to you

Step 3: Save Your API Key

⚠️ CRITICAL: The API key is displayed only once.

1. Copy the full API key immediately
2. Store it in a secure location:
   • Password manager (recommended)
   • Environment variables
   • Secure key management service
3. Never commit keys to version control

Example key format (keys are prefixed with mmak_):

mmak_YOUR_API_KEY

If you lose the key, you must:

• Delete the old key
• Create a new one
• Update all applications using it

Managing API Keys

Viewing API Keys

The key list displays all created keys. Each key shows:

• Key Name - Identifier you provided
• Key Suffix - The last characters of the key (e.g., ••••abcd)
• Scopes - Badges such as “All Access”, “Mailboxes Read”, “Domains Write”
• Created Date - When the key was generated
• Expiry - When it expires, or “Never expires”; keys past their expiry date are shown as Expired

Key Actions

Edit Scopes

• Click Edit on a key to change its granted scopes
• You can only grant scopes you hold yourself
• Changes apply immediately after saving

Delete Key

• Click Delete to permanently revoke the key
• All API calls using this key will fail immediately
• Cannot be undone

API Key Permissions

What API Keys Can Do

Depending on the granted scopes, API keys can:

• Create and manage mailboxes (mailboxes:write)
• List mailboxes and retrieve messages/attachments (mailboxes:read)
• Manage custom domains (domains:write)
• Manage team members and invitations (team:write)
• Manage OAuth clients and mock identities (identities:write)

What API Keys Cannot Do

API keys are restricted from:

• Anything outside their granted scopes
• Managing billing or subscriptions
• Creating other API keys beyond what your own scopes allow (must use the web interface for full management)

Scope-Based Restrictions

If a key is limited to specific scopes, any API call requiring an ungranted scope is rejected.

Example:

# Key with only mailboxes:read and mailboxes:write scopes
# ✅ Allowed
POST /v1/mailboxes

# ❌ Forbidden
POST /v1/domains

Using API Keys

Authentication Header

Include the API key in all requests:

curl -X GET https://api.minutemail.co/v1/mailboxes \
  -H "Authorization: Bearer mmak_YOUR_API_KEY"

SDK Usage

With the official Python SDK:

from minutemail import MinuteMailClient

client = MinuteMailClient(api_key="mmak_YOUR_API_KEY")

# Create a mailbox
mailbox = client.create_mailbox(
    domain="minutemail.cc",
    recoverable=True,
    tag="onboarding",
    expires_in=15,
)

For complete examples, see the SDK Documentation.

Security Best Practices

Key Storage

• Never hardcode API keys in source code
• Use environment variables for configuration
• Encrypt secrets at rest in production
• Use secret managers (AWS Secrets Manager, HashiCorp Vault)

Key Rotation

• Rotate regularly - Every 90 days recommended
• Rotate immediately if key may be compromised
• Create the replacement first, update all systems, then delete the old key
• Update all systems before deleting old keys

Access Control

• Principle of least privilege - Only grant the scopes an integration needs
• One key per application - Isolate systems
• Set expiration dates - Especially for temporary access
• Prefer scoped keys over All Access (*) keys for production integrations

Team Environment

• Individual keys - Each team member creates their own
• Shared keys - Only for team-owned integrations
• Document owners - Track who created which keys
• Revoke on departure - Delete keys when members leave

Monitoring API Key Usage

• Check the Usage page for your overall API call consumption
• Review your integration logs for per-key activity
• Delete keys you no longer use

Quota and Limits

API calls count toward your daily quota:

• Free: 50 calls/day
• Hobbyist: 1,000 calls/day
• Pro: 10,000 calls/day
• Team: 50,000 calls/day (shared)

Check current usage on the Usage page.

When Quota Exceeded

• API returns 429 Too Many Requests
• Quota resets at 00:00 UTC daily
• Upgrade plan for higher limits

Troubleshooting

“Invalid API key” error

• Verify key copied correctly (no extra spaces)
• Check if key was deleted or expired
• Ensure using correct environment (test vs production)

“Forbidden” errors

• Check whether your key has the required scope for the endpoint
• Verify the key hasn’t expired

Keys not appearing

• Refresh the page
• Check if you’re logged into the correct account

Cannot create key

• Verify “Key Name” field is filled
• Enable All Access or select at least one scope
• Check browser console for errors

API Key Limits

• Maximum Keys - No hard limit (reasonable usage)
• Scopes - Cannot exceed your own permissions
• Expiration Range - Any future date

Advanced Use Cases

Separate Keys for Environments

Development: "Dev Environment API Key" (scopes: mailboxes:read/write, expires monthly)
Staging: "Staging Environment API Key" (scopes: mailboxes + domains:read, expires quarterly)
Production: "Production API Key" (All Access, rotated regularly)

Least-Privilege Contractor Access

Name: "Q1 Contractor - John Doe"
Expiry: March 31, 2027
Scopes: mailboxes:read, mailboxes:write

API Documentation

For detailed API endpoint documentation:

• Getting Started with API
• Mailbox Endpoints
• Message Endpoints
• Archiving Endpoints

For SDK usage:

• SDK Getting Started
• SDK Mailbox Management
• SDK Message Retrieval