Messages

GET /v1/mailboxes/{mailboxId}/mails

List all emails in a mailbox.

Path Parameters:

Parameter	Type	Description
mailboxId	string	Mailbox identifier

Response (200 OK):

{
  "items": [
    {
      "id": "f1e2d3c4-b5a6-9876-5432-10fedcba9876",
      "mailboxId": "ed930b25-dd40-41b3-a712-e502fbcc5565",
      "sender": "sender@example.com",
      "subject": "Welcome!",
      "body": "This is a test email.",
      "hasAttachments": true,
      "attachments": [
        {
          "id": "12345678-1234-1234-1234-123456789abc",
          "name": "document.pdf",
          "sizeBytes": 102400
        }
      ],
      "receivedAt": "2024-01-18T00:15:00Z"
    }
  ]
}

Response Fields:

Field	Type	Description
id	string	Unique email identifier
mailboxId	string	Parent mailbox identifier
sender	string	Email sender address
subject	string	Email subject line
body	string	Email body content (plain text or HTML)
hasAttachments	boolean	Whether email has attachments
attachments	array	List of attachment metadata (if any)
receivedAt	string	ISO 8601 timestamp when email was received

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/mails \
  -H "Authorization: Bearer mmak_FKI5IKBJ4FSZJLUFGJ3IMF4A55W2OZW7YMLWD3JI33IVUGDEJXLQ"

---

GET /v1/mailboxes/{mailboxId}/mails/{mailId}

Retrieve a specific email.

Path Parameters:

Parameter	Type	Description
mailboxId	string	Mailbox identifier
mailId	string	Email identifier

Response (200 OK):

{
  "id": "f1e2d3c4-b5a6-9876-5432-10fedcba9876",
  "mailboxId": "ed930b25-dd40-41b3-a712-e502fbcc5565",
  "sender": "sender@example.com",
  "subject": "Welcome!",
  "body": "This is a test email.",
  "hasAttachments": true,
  "attachments": [
    {
      "id": "12345678-1234-1234-1234-123456789abc",
      "name": "document.pdf",
      "sizeBytes": 102400
    }
  ],
  "receivedAt": "2024-01-18T00:15: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 or email not found

Example:

curl https://api.minutemail.co/v1/mailboxes/ed930b25-dd40-41b3-a712-e502fbcc5565/mails/f1e2d3c4-b5a6-9876-5432-10fedcba9876 \
  -H "Authorization: Bearer mmak_FKI5IKBJ4FSZJLUFGJ3IMF4A55W2OZW7YMLWD3JI33IVUGDEJXLQ"

---

DELETE /v1/mailboxes/{mailboxId}/mails

Delete multiple emails from a mailbox in a single request. All attachments are also deleted.

Path Parameters:

Parameter	Type	Description
mailboxId	string	Mailbox identifier

Request Body:

{
  "ids": [
    "f1e2d3c4-b5a6-9876-5432-10fedcba9876",
    "a2b3c4d5-e6f7-8765-4321-0fedcba98765",
    "b3c4d5e6-f7a8-7654-3210-fedcba987654"
  ]
}

Parameters:

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

Response: No content

Status Codes:

• 204 No Content: All emails successfully deleted
• 400 Bad Request: Invalid input (empty ids array, invalid format)
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: You don’t have access to this mailbox
• 404 Not Found: Mailbox not found

Notes:

• Mailbox ownership is validated before processing
• All attachments associated with the emails are also deleted
• Operation is atomic - either all emails are deleted or none
• Silently skips non-existent email IDs

Example:

curl -X DELETE https://api.minutemail.co/v1/mailboxes/ed930b25-dd40-41b3-a712-e502fbcc5565/mails \
  -H "Authorization: Bearer mmak_FKI5IKBJ4FSZJLUFGJ3IMF4A55W2OZW7YMLWD3JI33IVUGDEJXLQ" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "f1e2d3c4-b5a6-9876-5432-10fedcba9876",
      "a2b3c4d5-e6f7-8765-4321-0fedcba98765"
    ]
  }'

---

DELETE /v1/mailboxes/{mailboxId}/mails/{mailId}

Delete a specific email.

Path Parameters:

Parameter	Type	Description
mailboxId	string	Mailbox identifier
mailId	string	Email identifier

Response: No content

Status Codes:

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

Example:

curl -X DELETE https://api.minutemail.co/v1/mailboxes/ed930b25-dd40-41b3-a712-e502fbcc5565/mails/f1e2d3c4-b5a6-9876-5432-10fedcba9876 \
  -H "Authorization: Bearer mmak_FKI5IKBJ4FSZJLUFGJ3IMF4A55W2OZW7YMLWD3JI33IVUGDEJXLQ"

---

Attachments

GET /v1/mailboxes/{mailboxId}/mails/{mailId}/attachments

List all attachments for an email.

Path Parameters:

Parameter	Type	Description
mailboxId	string	Mailbox identifier
mailId	string	Email identifier

Response (200 OK):

{
  "items": [
    {
      "id": "12345678-1234-1234-1234-123456789abc",
      "mailId": "f1e2d3c4-b5a6-9876-5432-10fedcba9876",
      "name": "document.pdf",
      "contentType": "application/pdf",
      "sizeBytes": 102400
    }
  ]
}

Response Fields:

Field	Type	Description
id	string	Unique attachment identifier
mailId	string	Parent email identifier
name	string	Attachment filename
contentType	string	MIME type (e.g., application/pdf, image/png)
sizeBytes	number	File size in bytes

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 or email not found

Example:

curl https://api.minutemail.co/v1/mailboxes/ed930b25-dd40-41b3-a712-e502fbcc5565/mails/f1e2d3c4-b5a6-9876-5432-10fedcba9876/attachments \
  -H "Authorization: Bearer mmak_FKI5IKBJ4FSZJLUFGJ3IMF4A55W2OZW7YMLWD3JI33IVUGDEJXLQ"

---

GET /v1/mailboxes/{mailboxId}/mails/{mailId}/attachments/{attachmentId}

Download a specific attachment.

Path Parameters:

Parameter	Type	Description
mailboxId	string	Mailbox identifier
mailId	string	Email identifier
attachmentId	string	Attachment identifier

Response (200 OK):

{
  "id": "12345678-1234-1234-1234-123456789abc",
  "name": "document.pdf",
  "contentType": "application/pdf",
  "data": "JVBERi0xLjQKJ...",
  "sizeBytes": 102400
}

Response Fields:

Field	Type	Description
id	string	Unique attachment identifier
name	string	Attachment filename
contentType	string	MIME type
data	string	Base64-encoded file content
sizeBytes	number	File size in bytes

Note: The attachment content is returned as a base64-encoded string in the data field. Decode it before saving to disk.

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, email, or attachment not found

Example:

# Download and save attachment
curl https://api.minutemail.co/v1/mailboxes/ed930b25-dd40-41b3-a712-e502fbcc5565/mails/f1e2d3c4-b5a6-9876-5432-10fedcba9876/attachments/12345678-1234-1234-1234-123456789abc \
  -H "Authorization: Bearer mmak_FKI5IKBJ4FSZJLUFGJ3IMF4A55W2OZW7YMLWD3JI33IVUGDEJXLQ" \
  | jq -r '.data' | base64 -d > document.pdf

---

DELETE /v1/mailboxes/{mailboxId}/mails/{mailId}/attachments

Delete multiple attachments from an email in a single request.

Path Parameters:

Parameter	Type	Description
mailboxId	string	Mailbox identifier
mailId	string	Email identifier

Request Body:

{
  "ids": [
    "12345678-1234-1234-1234-123456789abc",
    "23456789-2345-2345-2345-234567890bcd",
    "34567890-3456-3456-3456-345678901cde"
  ]
}

Parameters:

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

Response: No content

Status Codes:

• 204 No Content: All attachments successfully deleted
• 400 Bad Request: Invalid input (empty ids array, invalid format)
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: You don’t have access to this mailbox
• 404 Not Found: Mailbox or email not found

Notes:

• Mailbox ownership is validated before processing
• Attachment summaries are automatically refreshed after deletion
• Silently skips non-existent attachment IDs

Example:

curl -X DELETE https://api.minutemail.co/v1/mailboxes/ed930b25-dd40-41b3-a712-e502fbcc5565/mails/f1e2d3c4-b5a6-9876-5432-10fedcba9876/attachments \
  -H "Authorization: Bearer mmak_FKI5IKBJ4FSZJLUFGJ3IMF4A55W2OZW7YMLWD3JI33IVUGDEJXLQ" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "12345678-1234-1234-1234-123456789abc",
      "23456789-2345-2345-2345-234567890bcd"
    ]
  }'

---

DELETE /v1/mailboxes/{mailboxId}/mails/{mailId}/attachments/{attachmentId}

Delete a specific attachment.

Path Parameters:

Parameter	Type	Description
mailboxId	string	Mailbox identifier
mailId	string	Email identifier
attachmentId	string	Attachment identifier

Response: No content

Status Codes:

• 204 No Content: Successfully deleted
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: You don’t have access to this mailbox
• 404 Not Found: Mailbox, email, or attachment not found

Example:

curl -X DELETE https://api.minutemail.co/v1/mailboxes/ed930b25-dd40-41b3-a712-e502fbcc5565/mails/f1e2d3c4-b5a6-9876-5432-10fedcba9876/attachments/12345678-1234-1234-1234-123456789abc \
  -H "Authorization: Bearer mmak_FKI5IKBJ4FSZJLUFGJ3IMF4A55W2OZW7YMLWD3JI33IVUGDEJXLQ"