# Client — Email

<a id="get-api-v1-client-emails"></a>
#### `GET /api/v1/client/emails`

*List email accounts (client)*

Return all email accounts owned by the authenticated client account.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_list_EmailResponse__` | Successful Response |

**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/client/emails
```

---

<a id="post-api-v1-client-emails"></a>
#### `POST /api/v1/client/emails`

*Create email account (client)*

Create an email account on a domain owned by the authenticated client account. The plan's mailbox count is enforced, and the quota must be 1 MB to the plan's disk with the account's mailboxes together not exceeding it (422 VALIDATION_ERROR / 403 EMAIL_LIMIT).

**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/client/emails
```

---

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

*Delete email account (client)*

Delete an email account owned by the authenticated client account.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `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/client/emails/{email}
```

---

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

*Update email account (client)*

Update an email account (quota, active flag) owned by the authenticated client account. A changed quota must be 1 MB to the plan's disk with the account's mailboxes together not exceeding it (422 VALIDATION_ERROR / 403 EMAIL_LIMIT).

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `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/client/emails/{email}
```

---

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

*List email forwarders (client)*

Return all forwarders configured for an email account owned by the authenticated client account.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `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/client/emails/{email}/forwarders
```

---

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

*Create email forwarder (client)*

Create a forwarder routing mail from an email account to an external destination.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `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/client/emails/{email}/forwarders
```

---

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

*Delete email forwarder (client)*

Delete a forwarder for an email account owned by the authenticated client account.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `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/client/emails/{email}/forwarders/{forwarder_id}
```

---

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

*Change email password (client)*

Change the password of an email account owned by the authenticated client account.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `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/client/emails/{email}/password
```

---

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

*Get webmail SSO URL (client)*

Mint a short-lived SSO token for the Roundcube webmail interface, scoped to the given email account.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `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/client/emails/{email}/webmail-url
```

---