JAMES-2292 Provide documentation for WebAdmin MailQueue endpoints
Project: http://git-wip-us.apache.org/repos/asf/james-project/repo Commit: http://git-wip-us.apache.org/repos/asf/james-project/commit/6f6513df Tree: http://git-wip-us.apache.org/repos/asf/james-project/tree/6f6513df Diff: http://git-wip-us.apache.org/repos/asf/james-project/diff/6f6513df Branch: refs/heads/master Commit: 6f6513dffc90386e3167506301a85431c940e5b5 Parents: 113bb75 Author: Antoine Duprat <[email protected]> Authored: Fri Jan 26 15:30:27 2018 +0100 Committer: benwa <[email protected]> Committed: Tue Jan 30 16:51:42 2018 +0700 ---------------------------------------------------------------------- src/site/markdown/server/manage-webadmin.md | 111 +++++++++++++++++++++++ 1 file changed, 111 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/james-project/blob/6f6513df/src/site/markdown/server/manage-webadmin.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/server/manage-webadmin.md b/src/site/markdown/server/manage-webadmin.md index b99c794..e7cc226 100644 --- a/src/site/markdown/server/manage-webadmin.md +++ b/src/site/markdown/server/manage-webadmin.md @@ -915,6 +915,117 @@ The scheduled task will have the following type `reprocessingOneTask` and the fo } ``` +## Administrating mail queues + +### Listing mail queues + +``` +curl -XGET http://ip:port/mailQueues +``` + +The answer looks like: + +``` +["outgoing","spool"] +``` + +Response codes: + + - 200: The list of mail queuess + - 500: Internal error + +### Getting a mail queue details + +``` +curl -XGET http://ip:port/mailQueues/mailQueueName +``` + +Resource name mailQueueName is the name of a mail queue, this command will return the details of the given mail queue. For instance: + +``` +{"name":"outgoing","size":0} +``` + +Response codes: + + - 200: Success + - 400: Mail queue is not valid + - 404: The mail queue does not exist + - 500: Internal error + +### Listing the mails of a mail queue + +``` +curl -XGET http://ip:port/mailQueues/mailQueueName/mails +``` + +Additional URL query parameters: + + - `limit`: Maximum number of mails returned in a single call. Only strictly positive integer values are accepted. Example: + +``` +curl -XGET http://ip:port/mailQueues/mailQueueName/mails?limit=100 +``` + +The answer looks like: + +``` +[{ + "name": "Mail1516976156284-8b3093b9-eebf-4c40-9c26-1450f4fcdc3c-to-test.com", + "sender": "[email protected]", + "recipients": ["[email protected]"], + "nextDelivery": "1969-12-31T23:59:59.999Z" +}] +``` + +Response codes: + + - 200: Success + - 400: Mail queue is not valid or limit is invalid + - 404: The mail queue does not exist + - 500: Internal error + +### Deleting mails from a mail queue + +``` +curl -XDELETE http://ip:port/mailQueues/mailQueueName/mails?sender=senderMailAddress +``` + +This request should have exactly one query parameter from the following list: +* sender: which is a mail address (i.e. [email protected]) +* name: which is a string +* recipient: which is a mail address (i.e. [email protected]) + +The mails from the given mail queue matching the query parameter will be deleted. + + +Response codes: + + - 204: Success (No content) + - 400: Invalid request + - 404: The mail queue does not exist + - 500: Internal error + +### Flushing mails from a mail queue + +``` +curl -XPATCH http://ip:port/mailQueues/mailQueueName?delayed=true \ + -d '{"delayed": false}' +``` + +This request should have the query parameter *delayed* set to *true*, in order to indicate only delayed mails are affected. +The payload should set the `delayed` field to false inorder to remove the delay. This is the only supported combination, +and it performs a flush. + +The mails delayed in the given mail queue will be flushed. + +Response codes: + + - 204: Success (No content) + - 400: Invalid request + - 404: The mail queue does not exist + - 500: Internal error + ## Task management Some webadmin features schedules tasks. The task management API allow to monitor and manage the execution of the following tasks. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
