After a long IRC chat with the kind Twisted folks on IRC, I am writing here a post that could easily serve as an overview page of twisted.mail.smtp. In my opinion, Twisted sorely lacks overview pages, with real words and not just links to examples. It also needs some Google love, so I hope this page will help others looking how to send emails with Twisted.

twisted.mail.smtp overview

Twisted mail contains implementations of many email-related protocols, such as POP3, IMAP, SMTP and others. It allows writing email clients and servers.

Twisted mail is not meant to be used by people who do not want to deal with protocol details. For example, it has nothing to do with MIME handling and relevant RFC2822 issues. There's a perfectly fine email library in the stdlib for that.

twisted.mail.smtp is an implementation of the SMTP protocol, client and server. However, here I will only deal with SMTP clients (ie, how to send emails).

How to send an email with SMTP

If you're using an open SMTP server, there's a convenience function you can use:

from twisted.mail.smtp import sendmail
from email.mime.text import MIMEText

host = 'smtp.example.com'
from_addr = 'sender@example.com'
to_addrs = ['recipient@example.com']

msg = MIMEText("This is the message body")
msg['Subject'] = 'This is the message subject'
msg['From'] = from_addr
msg['To'] = ', '.join(to_addrs)

dfr = sendmail(host, from_addr, to_addrs, msg.as_string())
def success(r):
    print r
    reactor.stop()
def error(e):
    print e
    reactor.stop()
dfr.addCallback(success)
dfr.addErrback(error)

reactor.run()

See the API Docs for sendmail for more information.

See the stdlib examples for sending more advanced messages with attachments, alternative versions and so on.

Authentication

Unfortunately, sendmail does not support authentication yet. However, it's very easy to send emails via a server requiring authentication, by using the ESMTPSenderFactory:

dfr = Deferred()
factory = ESMTPSenderFactory(username, password, from_addr, to_addrs,
    msg, dfr)
reactor.connectTCP(smtphost, port, factory)

# attach callbacks to dfr as before

There's a more complete example in the Twisted docs, completely ignored by Google so far, for some reason.

Advanced usage

If you are not covered by the simple sendmail function, or it's secure replacement, you probably know enough about email that you can get by using SMTPSenderFactory and ESMTPSenderFactory directly.

Visit the API Docs for twisted.mail.smtp

Mistakes? Omissions?

I'm not a Twisted dev so perhaps I've misunderstood something. Please send feedback via comments.

License

I don't have an explicit copyright policy for my blog posts, but since I want this to end up in the Twisted docs, I am releasing this post under a Creative Commons Attribution-Share Alike License.

As far as I understand it, it means that I only want an attribution when this documentation is used. If that's not the case, please educate me on licensing in the comments.