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

Click the profile menu in the top-right corner
Select API Keys
You’ll see the API Keys management page

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 infinite/non-expiring key
Set Expiration - Click the date picker to choose 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.

Domain Restrictions (Required)

Purpose - Limit which domains this key can manage
Security - Prevents unauthorized access to all mailboxes
Configuration:
- All available domains shown with checkboxes
- minutemail.cc (default platform domain)
- Your verified custom domains

Default Behavior: By default, minutemail.cc is selected and cannot be removed if it’s your only domain.

Step 2: Add Domains to Key

View the “Domains” section showing currently selected domains
Each domain displays:
- Domain name (e.g., minutemail.cc)
- Remove button (✕) to exclude it
To add more domains:
- Click the Add Domain dropdown
- Select a domain from available options
- Click Add Domain button

Note: “All available domains have been added to this key” appears when no domains remain to add.

Step 3: Create the Key

Ensure Key Name is filled in
Verify domain selections
Click Create API Key
A success modal appears with your new key

Step 4: Save Your API Key

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

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

Example key format:

mm_sk_live_1234567890abcdefghijklmnopqrstuvwxyz

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 “API Keys” section displays all created keys:

Each key shows:

Key Name - Identifier you provided
Partial Key - Last 8 characters (e.g., ••••••wx yz)
Created Date - When the key was generated
Expiry Date - When it expires (or “Never expires”)
Domain Count - Number of domains accessible
Last Used - Most recent API call timestamp
Status:
- Active - Working normally
- Expired - No longer valid (past expiry date)
- Revoked - Manually disabled

Key Actions

For each API key, you can:

View Domains

Click View Domains to see which domains this key can access
Useful for auditing permissions

Regenerate Key

Click Regenerate to create a new secret
Old secret becomes invalid immediately
Use Case: Rotate keys periodically for security

Edit Configuration

Click Edit to modify:
- Key name
- Expiry date
- Domain restrictions
Cannot change existing key secret (must regenerate)

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

API keys grant access to:

Create mailboxes on allowed domains
List mailboxes you own
Retrieve messages from your mailboxes
Delete mailboxes you created
Archive and restore mailboxes
Download attachments

What API Keys Cannot Do

API keys are restricted from:

Viewing other users’ mailboxes (team members or other accounts)
Managing billing or subscriptions
Creating API keys (must use web interface)
Inviting team members
Adding custom domains (requires DNS verification)

Domain-Based Restrictions

If a key is limited to specific domains:

Can only create mailboxes on those domains
Cannot list mailboxes from other domains
API calls for unauthorized domains return 403 Forbidden

Example:

# Key allowed only for: example.com
# ✅ Allowed
POST /api/mailboxes
{ "domain": "example.com" }

# ❌ Forbidden
POST /api/mailboxes
{ "domain": "other-domain.com" }

Using API Keys

Authentication Header

Include the API key in all requests:

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

SDK Usage

With the official SDK:

import { MinuteMailClient } from '@minutemail/sdk';

const client = new MinuteMailClient({
  apiKey: process.env.MINUTEMAIL_API_KEY
});

// Create a mailbox
const mailbox = await client.mailboxes.create({
  domain: 'minutemail.cc',
  expiresIn: 900 // 15 minutes
});

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
Keep old keys briefly during transitions
Update all systems before deleting old keys

Access Control

Principle of least privilege - Only grant needed domains
One key per application - Isolate systems
Set expiration dates - Especially for temporary access
Monitor usage - Check “Last Used” timestamps

Team Environment

Individual keys - Each team member gets 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

Last Used Timestamp

Shows when key last made an API call
Helps identify:
- Inactive keys (candidates for deletion)
- Unexpected usage patterns
- Keys to rotate

Audit Logs

Access logs via Usage page or API:

Track all API calls per key
Monitor for suspicious activity
Debug integration issues

Quota and Limits

API calls count toward your daily quota:

Free: 100 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 if domain is included in key configuration
Verify you own the mailbox you’re accessing
Ensure key hasn’t expired

Keys not appearing

Refresh the page
Check if you’re logged into the correct account
Verify your plan supports API access

Cannot create key

Verify “Key Name” field is filled
Ensure at least one domain is selected
Check browser console for errors

API Key Limits

Maximum Keys - No hard limit (reasonable usage)
Key Length - Fixed at 64 characters
Domain Restrictions - Can include all available domains
Expiration Range - Any future date

Advanced Use Cases

Separate Keys for Environments

Development: "Dev Environment API Key" (expires monthly)
Staging: "Staging Environment API Key" (expires quarterly)
Production: "Production API Key" (never expires, rotated quarterly)

Domain-Specific Keys

Customer Portal: domains = [customer-portal.example.com]
Internal Tools: domains = [minutemail.cc, testing.example.com]
Public API: domains = [api.example.com]

Temporary Contractor Access

Name: "Q1 Contractor - John Doe"
Expiry: March 31, 2026
Domains: [contractor-temp.example.com]

API Documentation

For detailed API endpoint documentation:

For SDK usage: