.. django-postman documentation master file, created by
sphinx-quickstart on Fri Nov 26 09:32:49 2010.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to django-postman's documentation!
==========================================
This is an application for `Django <https://www.djangoproject.com>`_-powered websites.
A list of available translations is maintained in the `Wiki <https://bitbucket.org/psam/django-postman/wiki/>`_.
Your contribution to the translations is welcomed `here <https://www.transifex.com/psam/django-postman/>`_.
Basically, the purpose is to allow authenticated users of a site to exchange private **messages**
within the site. In this documentation, the word *user* is to be understood as an instance of a User,
in the django.contrib.auth context.
So it is mainly for a User-to-User exchange.
But it may be beneficial for a subscriber to receive inquiries from any visitor, ie even if non authenticated.
For instance, a subscriber as a service provider wants an ask-me-details form on a presentation page
to facilitate possible business contacts.
In this case, the visitor is presented a compose message form with an additional field to give
an email address for the reply. The email is obfuscated to the recipient.
What is a message ? Roughly a piece of text, about a subject, sent by a sender to a recipient.
Each user has access to a collection of messages, stored in folders:
* **Inbox** for incoming messages
* **Sent** for sent messages
* **Archives** for archived messages
* **Trash** for messages marked as deleted
In folders, messages can be presented in two modes:
* by **conversation**, for a compact view: the original message and its replies are grouped in a set
to constitute one sole entry.
The lastest message (based on the time) is the representative of the set.
* by **message**, for an expanded view: each message is considered by itself.
Here is a summary of features:
* A non-User (email is undisclosed) can write to a User and get a reply
(can be disabled by configuration)
* Exchanges can be moderated (with auto-accept and auto-reject plug-ins)
* Optional recipient filter plug-ins
* Optional exchange filtering plug-ins (blacklists)
* Multi-recipient writing is possible (can be disabled by configuration)
with min/max constraints
* Messages are managed by conversations
* Messages in folders are sortable by sender|recipient|subject|date
* 'Archives' folder in addition to classic Inbox, Sent and Trash folders
* A Quick-Reply form to only ask for a response text
* A cleanup management command to clear the old deleted messages
It has support for optional additional applications:
* Autocomplete recipient field (default is 'django-ajax-selects'),
with multiple recipient management
* New message notification (default is `pinax-notifications`_)
* Asynchronous mailer (default is `django-mailer`_)
.. _`pinax-notifications`: https://github.com/pinax/pinax-notifications/
.. _`django-mailer`: https://github.com/pinax/django-mailer/
Moderation
----------
As an option, messages may need to be validated by a moderator before to be visible
to the recipient. Possible usages are:
* to control there is no unwanted words in the text fields.
* to make sure that no direct contact informations are exchanged when the site is an intermediary
and delivers services based on subscription fees.
Messages are first created in a *pending* state. A moderator is in charge to change them to
a *rejected* or *accepted* state. This operation can be done in two ways:
* By a person, through the Admin site. A specially simplified change view is provided,
with one-click buttons to accept or reject the message.
* Automatically, through one or more auto-moderator functions.
Filters
-------
As options, custom filters can disallow messages, in two ways:
* **user filter**: a user is not in a state to act as a recipient
* **exchange filter**: criteria for a message between a specific sender
and a specific recipient are not fulfilled