Package: tgext.mailer
About tgext.mailertgext.mailer is a TurboGears2 extension for sending emails with transaction
manager integration. Whenever the transaction manager provided with TurboGears
commits the transaction all the emails are sent, when the transaction is
abort the mails are discarded.While there are other extensions available for sending emails on TurboGears,
like TurboMail. Those are not bound to the transaction manager, have a more
complex structure or are not actively maintained anymore. This lead to the
birth oftgext.mailer.tgext.mailer code is adapted from thepyramid_mailerproject which usesrepoze.sendmailto perform actual email delivery.Installingtgext.mailer can be installed from pypi:pip install tgext.mailershould just work for most of the users.EnablingTo enable tgext.mailer put inside your applicationconfig/app_cfg.pythe following:import tgext.mailer
tgext.mailer.plugme(base_config)or you can usetgext.pluggablewhen available:from tgext.pluggable import plug
plug(base_config, 'tgext.mailer')tgext.mailer will then load the options from your application
configuration file, refer to theConfiguration File Optionssection for a complete list of available options.Sending EmailsSending emails is performed through the mailer object, each request has its
own mailer object, which is in charge of sending only the emails of that
request. If you don’t pass any request to theget_mailercall, the
application wide mailer is returned (Do not use it inside a request):from tgext.mailer import get_mailer
mailer = get_mailer(request)To send a message, you must first create atgext.mailer.message.Messageinstance:from tgext.mailer import Message

message = Message(subject="hello world",
                  sender="admin@mysite.com",
                  recipients=["john.doe@gmail.com"],
                  body="Hi John!")TheMessageis then passed to theMailerinstance. You can either
send the message right away:mailer.send(message)or add it to your mail queue (a maildir on disk):mailer.send_to_queue(message)If you want to send the email without registering it on the transaction manager,
to make sure it gets sent even in case of transaction failures, use:mailer.send_immediately(message)Configuration File OptionsThe available settings are listed below. Place them under[app:main]in your configuration*.inifile.SettingDefaultDescriptionmail.debugmailerFalseStore emails on disk for debuggingmail.hostlocalhostSMTP hostmail.port25SMTP portmail.usernameNoneSMTP usernamemail.passwordNoneSMTP passwordmail.tlsFalseUse TLSmail.sslFalseUse SSLmail.keyfileNoneSSL key filemail.certfileNoneSSL certificate filemail.queue_pathNoneLocation of maildirmail.default_senderNoneDefault from addressmail.debug0SMTP debug levelIn test units that have to check for sent email, make sure to setmail.debugmailerto"dummy"it will save outgoing emails inmailer.outputinstead of actually sending them.TransactionsIf you are using transaction management thentgext.mailerwill only
send the emails (or add them to the mail queue)
when the transactions are committed.For example:import transaction

from tgext.mailer.mailer import Mailer
from tgext.mailer import Message

mailer = Mailer()
message = Message(subject="hello world",
                  sender="admin@mysite.com",
                  recipients=["john.doe@gmail.com"],
                  body="Hi John!")

mailer.send(message)
transaction.commit()The email is not actually sent until the transaction is committed.Usually TurboGears will automatically commit the transaction for your
at the end of the request so you don’t need to explicitly commit or abort
within code that sends mail.  Instead, if an exception is raised, the
transaction will implicitly be aborted and mail will not be sent; otherwise
it will be committed, and mail will be sent.If you use theApplication wide email managerit is usually best practice
to only usesend_immediatelymethod, to avoid registering the same mail manager
in multiple transactions.AttachmentsAttachments are added using thetgext.mailer.message.Attachmentclass:from tgext.mailer import Attachment
from tgext.mailer import Message

message = Message()

photo_data = open("photo.jpg", "rb").read()
attachment = Attachment("photo.jpg", "image/jpg", photo_data)

message.attach(attachment)You can pass the data either as a string or file object, so the above code
could be rewritten:from tgext.mailer import Attachment
from tgext.mailer import Message

message = Message()

attachment = Attachment("photo.jpg", "image/jpg",
                        open("photo.jpg", "rb"))

message.attach(attachment)A transfer encoding can be specified via thetransfer_encodingoption.
Supported options are currentlybase64(the default) andquoted-printable.You can also pass an attachment as thebodyand/orhtmlarguments to specifyContent-Transfer-Encodingor otherAttachmentattributes:from tgext.mailer import Attachment
from tgext.mailer import Message

body = Attachment(data="hello, arthur",
                  transfer_encoding="quoted-printable")
html = Attachment(data="<p>hello, arthur</p>",
                  transfer_encoding="quoted-printable")
message = Message(body=body, html=html)