Mail Queue

Updated Oct 4, 2026 Markdown

`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:

shell

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

`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:

shell

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

`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:

shell

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

`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:

shell

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

`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:

shell

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}

`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:

shell

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

`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:

shell

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

Still Need Help?

Our support team is here around the clock for anything you can't find above.