# MailRent API Documentation

Machine-readable API reference for integrating MailRent mail OTP rentals.

- **Production base URL:** use the same origin where this document is hosted, for example `https://icloudmail.vercel.app`.
- **API version:** V1 read endpoints use `/api/v1/...`.
- **Rental operations:** use `/api/orders/...`.
- **Format:** JSON responses and JSON request bodies where noted.

## Authentication

All API requests require an API key. Create or rotate the key from the account profile page.

Supported headers:

```http
X-API-Key: mrk_your_api_key
```

or:

```http
Authorization: Bearer mrk_your_api_key
```

For JSON requests, also send:

```http
Content-Type: application/json
Accept: application/json
```

Never put a real API key in browser JavaScript, a public frontend bundle, screenshots, logs, or a source repository. Store it on your server and rotate it if exposed.

## Service Catalog

### GET `/api/services` — Get available services and `service_id`

Returns the service catalog used to create a new mail rental. The value of `services[].id` is the exact `service_id` required by `POST /api/orders/rent`.

The frontend expects this endpoint to return a `services` array. The real backend determines whether the catalog is public or requires an authenticated session/API key; send authentication headers when integrating server-side.

#### cURL

```bash
curl "https://icloudmail.vercel.app/api/services" \
  -H "X-API-Key: mrk_your_api_key" \
  -H "Accept: application/json"
```

#### Successful response — `200`

```json
{
  "services": [
    {
      "id": "icloud-facebook",
      "name": "Facebook",
      "code": "FACEBOOK",
      "price": 500,
      "stock": 12,
      "mailbox_type": "iCloud Mail OTP",
      "available": true,
      "style": "facebook",
      "icon": "f"
    }
  ]
}
```

#### Service fields

- `id` — service identifier. Pass this value unchanged as `service_id` when renting.
- `available` — whether the service can currently be selected.
- `stock` — displayed remaining stock; select a service only when it is positive.
- `name`, `code`, `mailbox_type` — display information about the service.
- `price` — price in coins for a new rental.
- `style`, `icon` — optional presentation fields used by the web interface.

#### Integration flow

1. Call `GET /api/services`.
2. Select an item with `available: true` and `stock > 0`.
3. Read `services[].id`.
4. Send it unchanged in `POST /api/orders/rent`:

```json
{
  "service_id": "icloud-facebook"
}
```

`GET /api/products` is used by a legacy compatibility page in this frontend. It is not documented as a confirmed backend alias for `/api/services`; use `/api/services` for new integrations.

## Rental Operations

### POST `/api/orders/rent` — Rent a new mailbox

Creates a new rental from an available service. Obtain a valid `service_id` from `GET /api/services`.

#### Request body

```json
{
  "service_id": "icloud-facebook"
}
```

#### cURL

```bash
curl -X POST "https://icloudmail.vercel.app/api/orders/rent" \
  -H "X-API-Key: mrk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"service_id":"icloud-facebook"}'
```

Replace the host with your production origin and replace the example service ID with the ID returned by your service catalog.

#### Successful response — `200`

```json
{
  "balance": 4500,
  "order": {
    "id": 15,
    "email": "mail@example.com",
    "price": 500,
    "status": "Pending OTP"
  }
}
```

`balance` is the account balance after the transaction. Use `order.id` to query the rental history and `order.email` to identify the mailbox.

### POST `/api/orders/rerent` — Rerent an existing mailbox

Creates a new rental using the mailbox from an existing rental. The backend determines whether the source rental is eligible.

#### Request body

```json
{
  "rental_id": 15
}
```

#### cURL

```bash
curl -X POST "https://icloudmail.vercel.app/api/orders/rerent" \
  -H "Authorization: Bearer mrk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"rental_id":15}'
```

#### Successful response — `200`

```json
{
  "balance": 4150,
  "order": {
    "id": 16,
    "email": "mail@example.com",
    "price": 350,
    "status": "Pending OTP"
  }
}
```

The rerent price, time window, number of uses, and eligibility rules are controlled by the backend. Do not assume a fixed percentage or time limit in client code.

### POST `/api/orders/alias` — Create an alias

Creates an alias from an existing rental. The backend generates the alias mailbox and validates whether the source rental can be used.

#### Request body

```json
{
  "rental_id": 15
}
```

#### cURL

```bash
curl -X POST "https://icloudmail.vercel.app/api/orders/alias" \
  -H "X-API-Key: mrk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"rental_id":15}'
```

#### Successful response — `200`

```json
{
  "balance": 4100,
  "order": {
    "id": 17,
    "email": "alias@example.com",
    "price": 50,
    "status": "Pending OTP"
  }
}
```

In rental history, an alias may include `source_mailbox` to identify the original mailbox. Alias eligibility and pricing are controlled by the backend.

## Read APIs

### GET `/api/v1/me` — Account information

Returns the authenticated account and current coin balance.

#### cURL

```bash
curl "https://icloudmail.vercel.app/api/v1/me" \
  -H "X-API-Key: mrk_your_api_key" \
  -H "Accept: application/json"
```

#### Successful response — `200`

```json
{
  "user": {
    "username": "phatchau036",
    "email": "user@example.com",
    "full_name": "Phat Chau",
    "balance": 5000
  }
}
```

### GET `/api/v1/mail` — Read mail and OTP

Returns mail messages for a mailbox. Omit the `mailbox` query parameter to request the account's available OTP summary, if supported by the backend.

#### Query parameters

- `mailbox` — optional mailbox address to read.

#### cURL

```bash
curl "https://icloudmail.vercel.app/api/v1/mail?mailbox=mail@example.com" \
  -H "Authorization: Bearer mrk_your_api_key" \
  -H "Accept: application/json"
```

#### Successful response — `200`

```json
{
  "mailbox": "mail@example.com",
  "messages": [
    {
      "uid": "42",
      "subject": "Your verification code",
      "otp": "123456",
      "date": "Fri, 22 Aug 2026 08:23:00 +0000"
    }
  ]
}
```

### GET `/api/v1/mailboxes` — Assigned mailboxes

Returns mailboxes assigned to the authenticated account.

#### cURL

```bash
curl "https://icloudmail.vercel.app/api/v1/mailboxes" \
  -H "X-API-Key: mrk_your_api_key" \
  -H "Accept: application/json"
```

#### Successful response — `200`

```json
{
  "mailboxes": [
    {
      "mailbox": "mail@example.com",
      "note": "iCloud OTP",
      "created_at": "22/08/2026 08:23"
    }
  ]
}
```

### GET `/api/v1/mail-history` — Mailbox history

Returns mailbox and service history for the account. Filter by mailbox with the optional query parameter.

#### Query parameters

- `mailbox` — optional mailbox address.

#### cURL

```bash
curl "https://icloudmail.vercel.app/api/v1/mail-history?mailbox=mail@example.com" \
  -H "X-API-Key: mrk_your_api_key" \
  -H "Accept: application/json"
```

#### Successful response — `200`

```json
{
  "history": [
    {
      "mailbox": "mail@example.com",
      "service_name": "Facebook",
      "status": "completed"
    }
  ]
}
```

### GET `/api/v1/rentals` — Rental history

Returns rental records, status, and OTP when available.

#### cURL

```bash
curl "https://icloudmail.vercel.app/api/v1/rentals" \
  -H "X-API-Key: mrk_your_api_key" \
  -H "Accept: application/json"
```

#### Successful response — `200`

```json
{
  "rentals": [
    {
      "id": 15,
      "service": "Facebook",
      "email": "mail@example.com",
      "otp": "123456",
      "status": "completed"
    }
  ]
}
```

## Errors

Responses are JSON when handled by the Vercel proxy. Read the `error`, `message`, or `code` field and do not rely only on the text of a status page.

Common or backend-dependent statuses:

- `400` — missing or invalid `service_id` or `rental_id`.
- `401` — missing or invalid API key.
- `402` — insufficient balance, if enabled by the backend.
- `404` — mailbox or rental not found, or no IMAP source assigned.
- `409` or `422` — rental/alias operation is not eligible, if used by the backend.
- `502` — backend or upstream service is temporarily unavailable.

Example:

```json
{
  "error": "A human-readable error message"
}
```

The exact validation rules, pricing, eligibility, and additional response fields are defined by the real backend. The Vercel deployment is only a same-origin proxy and does not emulate these operations.