Mailboxes

POST /v1/mailboxes

Create a new temporary email mailbox.

Request Body:

{
  "domain": "minutemail.cc",
  "expiresIn": 30,
  "recoverable": true,
  "tag": "newsletter"
}

Parameters:

Field	Type	Description	Required
domain	string	Domain for the mailbox (e.g., minutemail.cc). Must be your API key’s allowed domain or one of your account’s verified domains. Defaults to minutemail.cc if omitted.	No
expiresIn	integer	Mailbox lifetime in minutes (1-60). Defaults to 15 minutes if omitted.	No
recoverable	boolean	Archive mailbox when it expires (allows reactivation later)	No
tag	string	Tag for organizing archived mailboxes (required if recoverable=true)	Conditional
noExpiration	boolean	Create a mailbox that never expires (expiresAt is null and permanent is true in the response)	No

Response (201 Created):

{
  "id": "ed930b25-dd40-41b3-a712-e502fbcc5565",
  "alias": "cdvk6fxequwd",
  "domain": "minutemail.cc",
  "address": "cdvk6fxequwd@minutemail.cc",
  "recoverable": true,
  "tag": "newsletter",
  "owner": "user_123abc",
  "messageCount": 0,
  "expiresAt": "2024-01-18T00:30:00Z",
  "permanent": false,
  "createdAt": "2024-01-18T00:00:00Z"
}

Response Fields:

Field	Type	Description
id	string	Unique mailbox identifier
alias	string	Mailbox alias (auto-generated)
domain	string	Mailbox domain
address	string	Full email address (alias@domain)
recoverable	boolean	Whether mailbox will be archived on expiration
tag	string	Tag for organizing archived mailboxes (omitted when empty)
owner	string	User ID of the mailbox owner
messageCount	integer	Number of messages in the mailbox
expiresAt	string	ISO 8601 timestamp when mailbox expires (null for permanent mailboxes)
permanent	boolean	Whether the mailbox never expires
createdAt	string	ISO 8601 timestamp when mailbox was created

Status Codes:

• 201 Created: Mailbox created successfully
• 400 Bad Request: Invalid input (missing tag when recoverable=true, invalid expiresIn, unknown fields)
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: Domain not allowed for this API key or account
• 429 Too Many Requests: Quota exceeded (active mailbox limit)

Response Headers:

• X-RateLimit-Remaining: Number of API calls remaining in your daily quota

Note: The request body is validated strictly — unknown or misspelled fields are rejected with a 400 error. Only send the fields listed above (the owner field is assigned automatically from your API key and cannot be set).

Example:

curl -X POST https://api.minutemail.co/v1/mailboxes \
  -H "Authorization: Bearer mmak_FKI5IKBJ4FSZJLUFGJ3IMF4A55W2OZW7YMLWD3JI33IVUGDEJXLQ" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "minutemail.cc",
    "expiresIn": 30,
    "recoverable": true,
    "tag": "testing"
  }'

Example Response Headers:

HTTP/1.1 201 Created
Content-Type: application/json
X-RateLimit-Remaining: 958
...

---

GET /v1/mailboxes

List all active mailboxes for your account.

Query Parameters:

Parameter	Type	Description	Required
address	string	Filter by exact email address (returns an empty list if no mailbox matches)	No

Response (200 OK):

{
  "items": [
    {
      "id": "ed930b25-dd40-41b3-a712-e502fbcc5565",
      "alias": "cdvk6fxequwd",
      "domain": "minutemail.cc",
      "address": "cdvk6fxequwd@minutemail.cc",
      "recoverable": true,
      "tag": "important",
      "owner": "user_123abc",
      "messageCount": 3,
      "expiresAt": "2024-01-18T01:00:00Z",
      "permanent": false,
      "createdAt": "2024-01-18T00:00:00Z"
    }
  ]
}

Status Codes:

• 200 OK: Success
• 401 Unauthorized: Invalid or missing API key

Example:

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

---

GET /v1/mailboxes/{mailboxId}

Retrieve details of a specific mailbox.

Path Parameters:

Parameter	Type	Description
mailboxId	string	Mailbox identifier

Response (200 OK):

{
  "id": "ed930b25-dd40-41b3-a712-e502fbcc5565",
  "alias": "cdvk6fxequwd",
  "domain": "minutemail.cc",
  "address": "cdvk6fxequwd@minutemail.cc",
  "recoverable": true,
  "tag": "important",
  "owner": "user_123abc",
  "messageCount": 3,
  "expiresAt": "2024-01-18T01:00:00Z",
  "permanent": false,
  "createdAt": "2024-01-18T00:00:00Z"
}

Status Codes:

• 200 OK: Success
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: You don’t have access to this mailbox
• 404 Not Found: Mailbox not found or expired

Example:

curl https://api.minutemail.co/v1/mailboxes/ed930b25-dd40-41b3-a712-e502fbcc5565 \
  -H "Authorization: Bearer mmak_FKI5IKBJ4FSZJLUFGJ3IMF4A55W2OZW7YMLWD3JI33IVUGDEJXLQ"

---

DELETE /v1/mailboxes

Delete multiple mailboxes in a single request. Recoverable mailboxes will be archived, others will be permanently deleted.

Request Body:

{
  "ids": [
    "ed930b25-dd40-41b3-a712-e502fbcc5565",
    "f2a3b4c5-d6e7-4321-8765-43210fedcba9",
    "a9b8c7d6-e5f4-9876-5432-10fedcba9876"
  ]
}

Parameters:

Field	Type	Description	Required
ids	array[string]	Array of mailbox identifiers to delete	Yes

Response: No content

Status Codes:

• 204 No Content: All mailboxes successfully deleted or archived
• 400 Bad Request: Invalid input (empty ids array, malformed JSON)
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: You don’t have permission to delete one or more mailboxes
• 404 Not Found: One of the mailboxes was not found or has already expired

Notes:

• All mailboxes are validated for permissions before any deletion occurs
• Recoverable mailboxes are automatically archived before deletion
• All emails and attachments in the mailboxes are also deleted

Example:

curl -X DELETE https://api.minutemail.co/v1/mailboxes \
  -H "Authorization: Bearer mmak_FKI5IKBJ4FSZJLUFGJ3IMF4A55W2OZW7YMLWD3JI33IVUGDEJXLQ" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "ed930b25-dd40-41b3-a712-e502fbcc5565",
      "f2a3b4c5-d6e7-4321-8765-43210fedcba9"
    ]
  }'

---

DELETE /v1/mailboxes/{mailboxId}

Delete a mailbox. If the mailbox was created with recoverable=true, its address is archived and can be reactivated later. Otherwise, it’s permanently deleted.

Path Parameters:

Parameter	Type	Description
mailboxId	string	Mailbox identifier

Response: No content

Status Codes:

• 204 No Content: Successfully deleted or archived
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: You don’t have permission to delete this mailbox
• 404 Not Found: Mailbox not found or expired

Example:

curl -X DELETE https://api.minutemail.co/v1/mailboxes/ed930b25-dd40-41b3-a712-e502fbcc5565 \
  -H "Authorization: Bearer mmak_FKI5IKBJ4FSZJLUFGJ3IMF4A55W2OZW7YMLWD3JI33IVUGDEJXLQ"