TurboMail 1.0 released!

[Matthew Bevan]

It is my pleasure to announce TurboMail 1.0, a TurboGears extension
to add multi-threaded outbound mail functionality to your TurboGears
application.

What is TurboMail?
------------------

TurboMail is a TurboGears extension - meaning that it starts up and
shuts down alongside TurboGears applications you write in the same
way that visit tracking and identity do. TurboMail uses built-in
Python modules for SMTP communication and MIME e-mail creation, but
greatly simplifies these tasks by performing the grunt-work for you.

Being multi-threaded, TurboMail allows you to enqueue messages to be
sent and then immediately continue with processing, resulting in a
much more fluid user experience. Threads are handled intelligently
(increasing the number of threads as demand increases) and they are
automatically recycled. There is only ever one SMTP connection per
thread.

Installing TurboMail
--------------------

Simply easy_install the package:

easy_install TurboMail

TurboMail installs no external scripts.

Using TurboMail
---------------

Before you can send mail, you must enable TurboMail and configure a
server. This is done from your dev.cfg, prod.cfg, or app.cfg by
placing the following in the general section:

mail.on = True
mail.server = "smtp.myserver.net"
mail.username = None
mail.password = None

Set username and password only if your outgoing mail server require
them. Once TurboMail is configured, import 'turbomail' into your
controller's Python file and use the following code to send a simple
plain-text message:

message = turbomail.Message(
'fr...@server.com',
't...@server.com',
'Subject'
)
message.plain = "Plain text body."
turbomail.enqueue(message)

To send a message using a KID template:

message = turbomail.TemplateMessage(
'fr...@server.com',
't...@server.com',
'Subject',
'application.templates.path',
dict(wanted="An argument.")
)
turbomail.enqueue(message)

The final argument to the TemplateMessage constructor is a dictionary
of arguments to pass to the KID template. Callable values will be
resolved (executed) just prior to being sent.

For additional information, visit the API reference:

http://www.topfloor.ca/turbomail/documentation/reference/

Matthew Bevan, Systems Administrator
Top Floor Computer Systems Ltd.

[Italo Maia]

Hoho, Juicy! Is this already in the tg doc? ^^

[Matthew Bevan]

Hoho, Juicy! Is this already in the tg doc? ^^

Alas, no.  I'm working on the epydoc documentation for a bit, then I'll get set on writing something for the documentation area on TurboGears.  However, the API documentation does have a LOT of information on it, and I keep uploading new versions of the documentation as I work on them.

I'll be describing the important properties and methods first, then work out from there.  I'll take requests.  ;^)

[Matthew Bevan]

A updated 1.0.1 version is now available which includes the following:

* Minor updates to remove unneeded arguments.
* Complete source-level epydoc documentation.

Documentation is viewable in the source code and online at the
following URL:

http://www.topfloor.ca/turbomail/documentation/reference/

To update an existing TurboMail installation, run the following:

easy_install -U TurboMail

If you have not yet installed TurboMail, run the above without the -U
option; the latest version will automatically be used.

Have a great day,

[Jorge Vargas]

great idea I look forward to killll ups wrong line

I look forward of using your extension.

[Richard (koorb)]

Right on cue. Thank you. I think this will be very useful!

[Ksenia Marasanova]

Hi Matthew!

Thank you for releasing the application! The standard mail library
would be a great addition to TG.

1. Question: with one SMTP connection per thread, can it handle large
email volumes?

2. Since I was struggling with mail coding lately, few notes that may
be handy :)

- there should be charset parameter available for specifying different
text encoding. (as a sidenote, when it's utf-8, python email library
will *always* transfer-encode it as base64. Very annoying)

- python email library doesnt care about line length. When using
transfer-encoding other than base64, TurboMail should check that the
line length doesnt exceed 998 characters (RFC 2822). (Some mail
servers just chop it off :D) Format flowed library is handy for this
(and of course for format-flowed part :) :
http://www.zopatista.com/projects/formatflowed

- mail headers doesnt have to be ascii-only, the reason to use Header module:
http://docs.python.org/lib/module-email.header.html

- I think "embed" method of Message class should also check if the
file already embedded and/or if the name is already in use

- the outer part of TurboMail message is always "related". I believe
it should be "alternative" when plain text alternative is available:
0. multipart / alternative
0.1. text / plain
0.2. multipart / related
0.2.1. text / html
0.2.2. attachment 1
0.2.3. attachment 2

- I think TurboMail should take care of creating plain text
alternative for html messages. There are several tools that can do it:
http://userpage.fu-berlin.de/~mbayer/tools/html2text.html
http://www.aaronsw.com/2002/html2text/
http://www.zope.org/Members/chrisw/StripOGram

Just my 2 eurocents :)

--Ksenia

[Ksenia Marasanova]

> (as a sidenote, when it's utf-8, python email library
> will *always* transfer-encode it as base64. Very annoying)

Sorry, I was wrong about this. I've missed Charset module from email
package that gives more control about encoding. utf-8 - base64
dependancy is only default.

Ksenia

[Matthew Bevan]

Thanks for the feedback, Ksenia!

I'll reply to each item in turn:

Thank you for releasing the application! The standard mail library

would be a great addition to TG.

I was actually quite curious why there wasn't even simple e-mail sending in TurboGears.  I think my package would be too much overkill for the average application, though.  It's nice, but the memory and processor requirements of multithreading isn't what everyone will be looking for.

1. Question: with one SMTP connection per thread, can it handle large

email volumes?

I successfully sent 100+ messages in a few seconds.  If you are sending larger batches, reducing the mail.interval to 5, setting mail.threads and mail.jobs to the maximum your SMTP server will support, and increasing the mail.timeout to a few minutes will help send a lot more, a lot faster.  Note that most SMTP servers do not actually complain when a single connection is sending too much mail - mine accepts the message and immediately deletes it, accepting a maximum of 10 messages.

there should be charset parameter available for specifying different

text encoding. (as a sidenote,  when it's utf-8, python email library

will *always* transfer-encode it as base64. Very annoying)

I agree, it's a good option.  The syntax will likely follow kid's configuration directives for assume-encoding and encoding.

python email library doesnt care about line length. When using

transfer-encoding other than base64, TurboMail should  check that the

line length doesnt exceed 998 characters (RFC 2822). (Some mail

servers just chop it off :D)  Format flowed library is handy for this

(and of course for format-flowed part :) :

http://www.zopatista.com/projects/formatflowed

The main idea behind the TurboMail library was zero external dependancies, although that library does look awfully nice.  ;)  I'll investigate optional integration of it in the next (1.1) version.

mail headers doesnt have to be ascii-only, the reason to use Header module:

http://docs.python.org/lib/module-email.header.html

Hmm... I'll have to investigate the use of Header and Message classes instead of using MIMEMultipart directly.

I think "embed" method of Message class should also check if the

file already embedded and/or if the name is already in use

You can, in theory, embed multiple attachments with the same name.  It's not a good idea, but you can do it.

the outer part of TurboMail message is always "related". I believe

it should be "alternative" when plain text alternative is available:

0. multipart / alternative

0.1. text / plain

0.2. multipart / related

0.2.1. text / html

0.2.2. attachment 1

0.2.3. attachment 2

There are four scenarios: Plain text only.  Plain text w/ attachments.  Plain and rich text.  Plain and rich text w/ attachments.  I'll have to make the generator a little more friendly in this respect, then.  ;^)

I think TurboMail should take care of creating plain text

alternative for html messages. There are several tools that can do it:

http://userpage.fu-berlin.de/~mbayer/tools/html2text.html

http://www.aaronsw.com/2002/html2text/

http://www.zope.org/Members/chrisw/StripOGram

It'd be even easier than that with a simple regular expression that removes brackets and everything between them, in a similar style to how KID templates are rendered in plain text.  (Note that the TemplateMessage class does automatically provide the plain text alternative in this way.)

Again, thanks for the input!

[samuraisam]

Very nice! I look forward to using it. Does it work on both 2.3 and
2.4?

-Sam

[Matthew Bevan]

Very nice! I look forward to using it. Does it work on both 2.3 and

2.4?

I have not tested it in 2.3.  After doing a quick browse through the PQR looking for differences related to TurboMail, I can find no reason that it wouldn't work in 2.3.  I am unsure, however, if creating classes as descendants of "object" is new in 2.4.

[Bob Ippolito]

On 10/6/06, Matthew Bevan <matt....@topfloor.ca> wrote:
>
>
> Very nice! I look forward to using it. Does it work on both 2.3 and
> 2.4?
>
> I have not tested it in 2.3. After doing a quick browse through the PQR
> looking for differences related to TurboMail, I can find no reason that it
> wouldn't work in 2.3. I am unsure, however, if creating classes as
> descendants of "object" is new in 2.4.

"object" has been there since 2.2

-bob

[Matthew Bevan]

Very nice! I look forward to using it. Does it work on both 2.3 and

2.4?

I have not tested it in 2.3.  After doing a quick browse through the PQR

looking for differences related to TurboMail, I can find no reason that it

wouldn't work in 2.3.  I am unsure, however, if creating classes as

descendants of "object" is new in 2.4.

"object" has been there since 2.2

Then it should work without problem in 2.3.

[Matthew Bevan]

An updated 1.0.4.1 version is now available which includes the
following:

* Better auto-detection of TLS capability.
* A new configuration directive, mail.tls; True, False, or None to
auto-detect.
* Fixes a bug in TemplateMessage which rendered it non-functional.
* Changed the behavior of a worker dying from old age to spawn a
new process immediately.
* Minor fixes and updates to the documentation.
* Benchmark results in the documentation.

[gasolin]

The TurboMail was put on tg document front
http://docs.turbogears.org/1.0

Below the title "Solving specific problems"

It will be a cool integration if user registration extension could send
email to users/owner after registration.

--
Fred

[Krys]

Matthew Bevan wrote:
> It is my pleasure to announce TurboMail 1.0, a TurboGears extension
> to add multi-threaded outbound mail functionality to your TurboGears
> application.

Very nice! I look forward to using this! Well done!

Thank you
Krys

[Kevin Dangoor]

Still playing catchup on email. This is good stuff Matthew!

Kevin

--
Kevin Dangoor
TurboGears / Zesty News

email: k...@blazingthings.com
company: http://www.BlazingThings.com
blog: http://www.BlueSkyOnMars.com