TurboMail Documentation
***********************

TurboMail is a Python library to ease sending emails from your application.

By using TurboMail you can:

* Easily construct plain text and HTML emails
* Make your code  which sends mails testable
* Use different mail delivery strategies (e.g. your app should not block if your mail server is slow)
* Switch the transport (e.g. SMTP, mailbox) by just changing some values in a config file

TurboMail 3.x was rebuilt from scratch so that you don't have dependencies 
on `TurboGears <http://www.turbogears.org>`_ any longer. Therefore TurboMail
is usable with all Python applications including `Django <http://www.djangoproject.com>`_,
`Pylons <http://pylonshq.com>`_, `Trac <http://trac.edgewall.org>`_,
`web.py <http://webpy.org>`_ and plain CGI scripts. All versions of Python 2.3-2.6
are supported and there are no other dependencies on external packages for 
normal operation [#]_.


Using TurboMail is meant to be simple::

  from turbomail import Message
  message = Message("from@example.com", "to@example.com", "Hello World")
  message.plain = "TurboMail is really easy to use."
  message.send()

This would send a plain text email with the subject "Hello World" and the
author (:mailheader:`From:` header) "from@example.com" to "to@example.com". The 
body just contains "TurboMail is really easy to use.". The code assumes that you 
use TurboMail inside of a "supported" framework [#]_ which sets up TurboMail on 
startup. We'll show you how to start TurboMail manually (e.g. for plain CGI 
scripts) later (see :ref:`TurboMail from Scratch <turbomail_from_scratch>`).


This documentation is an effort of the TurboMail developers to show you the full
potential of TurboMail. But we need your help! If you find mistakes in this docs,
please notify us. If you think some parts should be clarified or documented
differently, please notify us. We really need your input (and your time :-) to
make TurboMail a software everyone likes to use.


.. [#] In order to run the full test suite you need to install 
       `pymta <http://www.schwarz.eu/opensource/projects/pymta/>`_ and its 
       dependencies.

.. [#] TurboMail 3 comes with adapters for TurboGears 1 and Pylons/TurboGears 2 
       (see :ref:`TurboMail Adapters <adapters>`) but supporting a new framework 
       should only be a matter of 4-10 lines of code if the framework uses 
       setuptools (see :ref:`Writing Custom Adapters <custom_adapters>` 
       for more information). 


High Level Overview
*******************

.. toctree::
    :maxdepth: 2

    chapters/overview


Using TurboMail
***************

.. toctree::
    :maxdepth: 2

    chapters/using


Detailed TurboMail
******************

.. toctree::
    :maxdepth: 2

    chapters/detailed


Extending TurboMail
********************

.. toctree::
    :maxdepth: 2

    chapters/extending


TurboMail Community
*******************

.. toctree::
    :maxdepth: 2

    chapters/community