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). Defaults to minutemail.cc if omitted.	No
expiresIn	integer	Mailbox lifetime in minutes (1-60)	No
recoverable	boolean	Archive mailbox when it expires (allows reactivation later)	No
tag	string	Tag for organizing archived mailboxes (required if recoverable=true)	Conditional

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",
  "createdAt": "2024-01-18T00:00:00Z"
}

Response Fields:

Field	Type	Description
id	string	Unique mailbox identifier
alias	string	Mailbox alias (auto-generated or custom)
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
owner	string	User ID of the mailbox owner
messageCount	integer	Number of messages in the mailbox
expiresAt	string	ISO 8601 timestamp when mailbox expires
createdAt	string	ISO 8601 timestamp when mailbox was created

Status Codes:

• 201 Created: Mailbox created successfully
• 400 Bad Request: Invalid input (missing required fields, invalid duration format)
• 401 Unauthorized: Invalid or missing API key
• 409 Conflict: Mailbox alias already exists for this domain
• 429 Too Many Requests: Quota exceeded (active or archived mailbox limit)

Response Headers:

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

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	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",
      "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",
  "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

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, invalid format)
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: You don’t have permission to delete one or more mailboxes
• 404 Not Found: One or more mailboxes not found

Notes:

• All mailboxes are validated for permissions before any deletion occurs
• If any validation fails, the entire operation is rejected (atomic)
• 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, it will be 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

Example:

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