diff options
Diffstat (limited to 'src/mailman/rest/docs/queues.rst')
| -rw-r--r-- | src/mailman/rest/docs/queues.rst | 174 |
1 files changed, 174 insertions, 0 deletions
diff --git a/src/mailman/rest/docs/queues.rst b/src/mailman/rest/docs/queues.rst new file mode 100644 index 000000000..861b6806f --- /dev/null +++ b/src/mailman/rest/docs/queues.rst @@ -0,0 +1,174 @@ +====== +Queues +====== + +You can get information about what messages are currently in the Mailman +queues by querying the top-level ``queues`` resource. Of course, this +information may be out-of-date by the time you receive a response, since queue +management is asynchronous, but the information will be as current as +possible. + +You can get the list of all queue names. + + >>> dump_json('http://localhost:9001/3.0/queues') + entry 0: + count: 0 + directory: .../queue/archive + files: [] + http_etag: ... + name: archive + self_link: http://localhost:9001/3.0/queues/archive + entry 1: + count: 0 + directory: .../queue/bad + files: [] + http_etag: ... + name: bad + self_link: http://localhost:9001/3.0/queues/bad + entry 2: + count: 0 + directory: .../queue/bounces + files: [] + http_etag: ... + name: bounces + self_link: http://localhost:9001/3.0/queues/bounces + entry 3: + count: 0 + directory: .../queue/command + files: [] + http_etag: ... + name: command + self_link: http://localhost:9001/3.0/queues/command + entry 4: + count: 0 + directory: .../queue/digest + files: [] + http_etag: ... + name: digest + self_link: http://localhost:9001/3.0/queues/digest + entry 5: + count: 0 + directory: .../queue/in + files: [] + http_etag: ... + name: in + self_link: http://localhost:9001/3.0/queues/in + entry 6: + count: 0 + directory: .../queue/nntp + files: [] + http_etag: ... + name: nntp + self_link: http://localhost:9001/3.0/queues/nntp + entry 7: + count: 0 + directory: .../queue/out + files: [] + http_etag: ... + name: out + self_link: http://localhost:9001/3.0/queues/out + entry 8: + count: 0 + directory: .../queue/pipeline + files: [] + http_etag: ... + name: pipeline + self_link: http://localhost:9001/3.0/queues/pipeline + entry 9: + count: 0 + directory: .../queue/retry + files: [] + http_etag: ... + name: retry + self_link: http://localhost:9001/3.0/queues/retry + entry 10: + count: 0 + directory: .../queue/shunt + files: [] + http_etag: ... + name: shunt + self_link: http://localhost:9001/3.0/queues/shunt + entry 11: + count: 0 + directory: .../queue/virgin + files: [] + http_etag: ... + name: virgin + self_link: http://localhost:9001/3.0/queues/virgin + http_etag: ... + self_link: http://localhost:9001/3.0/queues + start: 0 + total_size: 12 + +Query an individual queue to get a count of, and the list of file base names +in the queue. There are currently no files in the ``bad`` queue. + + >>> dump_json('http://localhost:9001/3.0/queues/bad') + count: 0 + directory: .../queue/bad + files: [] + http_etag: ... + name: bad + self_link: http://localhost:9001/3.0/queues/bad + +We can inject a message into the ``bad`` queue. It must be destined for an +existing mailing list. + + >>> dump_json('http://localhost:9001/3.0/lists', { + ... 'fqdn_listname': 'ant@example.com', + ... }) + content-length: 0 + date: ... + location: http://localhost:9001/3.0/lists/ant.example.com + server: WSGIServer/0.2 CPython/3.4.2 + status: 201 + +While list creation takes an FQDN list name, injecting a message to the queue +requires a List ID. + + >>> dump_json('http://localhost:9001/3.0/queues/bad', { + ... 'list_id': 'ant.example.com', + ... 'text': """\ + ... From: anne@example.com + ... To: ant@example.com + ... Subject: Testing + ... + ... """}) + content-length: 0 + date: ... + location: http://localhost:9001/3.0/queues/bad/... + server: ... + status: 201 + +And now the ``bad`` queue has at least one message in it. + + >>> dump_json('http://localhost:9001/3.0/queues/bad') + count: 1 + directory: .../queue/bad + files: ['...'] + http_etag: ... + name: bad + self_link: http://localhost:9001/3.0/queues/bad + +We can delete the injected message. + + >>> json = call_http('http://localhost:9001/3.0/queues/bad') + >>> len(json['files']) + 1 + >>> dump_json('http://localhost:9001/3.0/queues/bad/{}'.format( + ... json['files'][0]), + ... method='DELETE') + content-length: 0 + date: ... + server: ... + status: 204 + +And now the queue has no files. + + >>> dump_json('http://localhost:9001/3.0/queues/bad') + count: 0 + directory: .../queue/bad + files: [] + http_etag: ... + name: bad + self_link: http://localhost:9001/3.0/queues/bad |