# Email Accounts

<a id="get-api-v1-accounts-username-emails"></a>
#### `GET /api/v1/accounts/{username}/emails`

*List email accounts*

Returns every mailbox owned by the given hosting account.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_list_EmailResponse__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": [
    {
      "active": "...",
      "address": "...",
      "quota_mb": "...",
      "used_mb": "..."
    }
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/emails
```

---

<a id="post-api-v1-accounts-username-emails"></a>
#### `POST /api/v1/accounts/{username}/emails`

*Create email account*

Provision a new mailbox. The local-part is derived from `address`; the domain must already be registered to this hosting account.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `address` | string | yes | minLength=3; maxLength=254 |
| `password` | string | yes | minLength=8; maxLength=256 |
| `quota_mb` | integer | no | default `250`; minimum=0.0; maximum=51200.0 |

**Request body example:**

```json
{
  "address": "string",
  "password": "REPLACE_ME",
  "quota_mb": 250
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_EmailResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "active": true,
    "address": "string",
    "quota_mb": 0,
    "used_mb": 0.0
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/accounts/{username}/emails
```

---

<a id="delete-api-v1-accounts-username-emails-email"></a>
#### `DELETE /api/v1/accounts/{username}/emails/{email}`

*Delete email account*

Remove the mailbox row and permanently delete its maildir contents. This cannot be undone.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |
| `email` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/emails/{email}
```

---

<a id="put-api-v1-accounts-username-emails-email"></a>
#### `PUT /api/v1/accounts/{username}/emails/{email}`

*Update email account*

Patch the mailbox quota or active flag.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |
| `email` | string | yes | — |

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `active` | boolean | no | — |
| `quota_mb` | integer | no | — |

**Request body example:**

```json
{
  "active": false,
  "quota_mb": 0
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_EmailResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "active": true,
    "address": "string",
    "quota_mb": 0,
    "used_mb": 0.0
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X PUT \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/accounts/{username}/emails/{email}
```

---

<a id="get-api-v1-accounts-username-emails-email-forwarders"></a>
#### `GET /api/v1/accounts/{username}/emails/{email}/forwarders`

*List email forwarders*

Returns every forward destination configured for this mailbox.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |
| `email` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_list_ForwarderResponse__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": [
    {
      "active": "...",
      "destination": "...",
      "id": "...",
      "source": "..."
    }
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/emails/{email}/forwarders
```

---

<a id="post-api-v1-accounts-username-emails-email-forwarders"></a>
#### `POST /api/v1/accounts/{username}/emails/{email}/forwarders`

*Create email forwarder*

Add a destination address that receives a copy of inbound mail.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |
| `email` | string | yes | — |

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `destination` | string | yes | minLength=3; maxLength=254 |

**Request body example:**

```json
{
  "destination": "string"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_ForwarderResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "active": true,
    "destination": "string",
    "id": 0,
    "source": "string"
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/accounts/{username}/emails/{email}/forwarders
```

---

<a id="delete-api-v1-accounts-username-emails-email-forwarders-forwarder-id"></a>
#### `DELETE /api/v1/accounts/{username}/emails/{email}/forwarders/{forwarder_id}`

*Delete email forwarder*

Remove a forwarder by id.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |
| `email` | string | yes | — |
| `forwarder_id` | integer | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/emails/{email}/forwarders/{forwarder_id}
```

---

<a id="post-api-v1-accounts-username-emails-email-password"></a>
#### `POST /api/v1/accounts/{username}/emails/{email}/password`

*Change email password*

Rotate the mailbox login password (stored as a salted SHA-256 hash that Dovecot verifies); open IMAP/POP3 sessions are closed.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |
| `email` | string | yes | — |

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `password` | string | yes | minLength=8; maxLength=256 |

**Request body example:**

```json
{
  "password": "REPLACE_ME"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/accounts/{username}/emails/{email}/password
```

---

<a id="get-api-v1-accounts-username-emails-email-webmail-url"></a>
#### `GET /api/v1/accounts/{username}/emails/{email}/webmail-url`

*Mint Roundcube webmail SSO URL*

Returns a short-lived SSO URL for the panel's embedded Roundcube. Responds 409 `EMAIL_INACTIVE` for a deactivated mailbox and 503 `WEBMAIL_NOT_INSTALLED` when Roundcube is absent.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |
| `email` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_WebmailUrlData_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "login_url": "string"
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/emails/{email}/webmail-url
```

---