# Mail Queue

<a id="delete-api-v1-mail-queue"></a>
#### `DELETE /api/v1/mail-queue`

*Delete ALL queued messages*

Wipe the entire Postfix queue (postsuper -d ALL). Requires the `confirm=ALL` query parameter as an explicit safeguard.

**Query parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `confirm` | string | no | Must be 'ALL' to confirm the server-wide queue wipe. |

**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/mail-queue
```

---

<a id="get-api-v1-mail-queue"></a>
#### `GET /api/v1/mail-queue`

*List the Postfix mail queue*

Return every message currently in the Postfix queue (active/deferred/hold) with sender, recipients and size.

**Responses:**

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

**Response example (200):**

```json
{
  "data": [
    {
      "arrival_time": "...",
      "message_size": "...",
      "queue_id": "...",
      "queue_name": "...",
      "recipients": "...",
      "sender": "...",
      "status": "..."
    }
  ],
  "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/mail-queue
```

---

<a id="post-api-v1-mail-queue-flush"></a>
#### `POST /api/v1/mail-queue/flush`

*Flush the mail queue*

Trigger an immediate delivery retry of every queued message (postqueue -f).

**Responses:**

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

**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)" \
  https://your-server:2000/api/v1/mail-queue/flush
```

---

<a id="get-api-v1-mail-queue-summary"></a>
#### `GET /api/v1/mail-queue/summary`

*Mail queue summary*

Return an aggregate count of queued messages by status plus total size.

**Responses:**

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

**Response example (200):**

```json
{
  "data": {
    "active": 0,
    "deferred": 0,
    "hold": 0,
    "total": 0,
    "total_size": 0
  },
  "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/mail-queue/summary
```

---

<a id="delete-api-v1-mail-queue-queue-id"></a>
#### `DELETE /api/v1/mail-queue/{queue_id}`

*Delete a queued message*

Remove a single message from the Postfix queue (postsuper -d). The queue id must match `^[A-Fa-f0-9]{8,12}$`; an id that is not in the queue answers 404 `MAIL_QUEUE_MESSAGE_NOT_FOUND`.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `queue_id` | 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/mail-queue/{queue_id}
```

---

<a id="post-api-v1-mail-queue-queue-id-hold"></a>
#### `POST /api/v1/mail-queue/{queue_id}/hold`

*Hold a queued message*

Move a message to the hold queue so Postfix stops attempting delivery (postsuper -h).

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `queue_id` | 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 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)" \
  https://your-server:2000/api/v1/mail-queue/{queue_id}/hold
```

---

<a id="post-api-v1-mail-queue-queue-id-release"></a>
#### `POST /api/v1/mail-queue/{queue_id}/release`

*Release a held message*

Return a held message to the deferred queue so Postfix resumes delivery attempts (postsuper -H).

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `queue_id` | 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 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)" \
  https://your-server:2000/api/v1/mail-queue/{queue_id}/release
```

---