Python easy mail library Documentation

Transcription

1 Python easy mail library Documentation Release Alain Spineux Oct 31, 2017

2

3 Contents 1 Download and Install 3 2 Support for Python 3.x 5 3 Use pyzmail 7 4 Documentation Articles API documentation Support 11 6 Quick Example Compose an Send an Parse an Tricks Embedding image in HTML Scripts pyzsendmail pyzinfomail License Links 23 i

4 ii

5 Python easy mail library Documentation, Release pyzmail is a high level mail library for Python. It provides functions and classes that help for reading, composing and sending s. pyzmail exists because their is no reasons that handling mails with Python would be more difficult than with popular mail clients like Outlook or Thunderbird. pyzmail hides the complexity of the MIME structure and MIME encoding/decoding. It also make the problems of the internationalization encoding/decoding simpler. Contents 1

6 Python easy mail library Documentation, Release Contents

7 CHAPTER 1 Download and Install pyzmail is available for Python 2.6+ and 3.2+ from pypi and can be easily installed using the easy_install successor named distribute and pip using $ pip install pyzmail to quickly install distribute and pip, use curl -O python distribute_setup.py easy_install pip pyzmail can be installed the old way from sources. Download the archive from pypi and extract its content into a directory. cd into this directory and run: > cd pyzmail-x.x.x > python setup.py install Binary version of the scripts for Windows pyzmail win32.zip can be downloaded from here. pyzmail sources are also available on github 3

8 Python easy mail library Documentation, Release Chapter 1. Download and Install

9 CHAPTER 2 Support for Python 3.x Python 3.2+ supported Python 3.2 is supported and has been tested. Python 3.0 and 3.1 are not supported because none of them provide functions to handle 8bits encoded s like in 3.2 ( .message_from_bytes() & . message_from_binary_file() ) At installation time, pyzmail sources are automatically converted by distribute using 2to3. Unfortunately, scripts are not converted in the process. You can convert them using 2to3 yourself (adapt paths to fit you configuration): /opt/python-3.2.2/bin/2to3 --no-diffs --write --nobackups /opt/python-3.2.2/bin/ pyzinfomail /opt/python-3.2.2/bin/2to3 --no-diffs --write --nobackups /opt/python-3.2.2/bin/ pyzsendmail 5

10 Python easy mail library Documentation, Release Chapter 2. Support for Python 3.x

11 CHAPTER 3 Use pyzmail The package is split into 3 modules: generate: Useful functions to compose and send mail s parse: Useful functions to parse s utils: Various functions used by other modules Most important functions are available from the top of the pyzmail package. usage sample: import pyzmail #access function from top of pyzmail ret=pyzmail.compose_mail('me@foo.com', [ 'him@bar.com'], u'subject', \ 'iso ', ('Hello world', 'us-ascii')) payload=ret[0] print payload msg=pyzmail.pyzmessage.factory(payload) print msg.get_subject() #use more specific function from inside modules print pyzmail.generate.format_addresses([('john', 'john@foo.com') ], \ 'From', 'us-ascii') print pyzmail.parse.decode_mail_header('=?iso ?q?hello?=') More in the Quick Example section. 7

12 Python easy mail library Documentation, Release Chapter 3. Use pyzmail

13 CHAPTER 4 Documentation You can find lots of sample inside the docstrings but also in the tests directory. The documentation, samples, docstring and articles are all fitted for python 2.x. Some occasional hint give some tricks about Python 3.x. Articles To understand how this library works, you will find these 3 articles very useful. They have been written before the first release of pyzmail and the code has changed a little since: Parsing using Python part 1 of 2 : The Header Parsing using Python part 2 of 2 : The content Generate and send mail with python: tutorial API documentation The API documentation in epydoc format contains a lot of samples in doctest string. You will find them very useful too. 9

14 Python easy mail library Documentation, Release Chapter 4. Documentation

15 CHAPTER 5 Support Ask your questions here 11

16 Python easy mail library Documentation, Release Chapter 5. Support

17 CHAPTER 6 Quick Example Lets show you how it works! Compose an import pyzmail sender=(u'me', 'me@foo.com') recipients=[(u'him', 'him@bar.com'), 'just@me.com'] subject=u'the subject' text_content=u'bonjour aux Fran\xe7ais' prefered_encoding='iso ' text_encoding='iso ' payload, mail_from, rcpt_to, msg_id=pyzmail.compose_mail(\ sender, \ recipients, \ subject, \ prefered_encoding, \ (text_content, text_encoding), \ html=none, \ attachments=[('attached content', 'text', 'plain', 'text.txt', \ 'us-ascii')]) print payload Look a the output: Content-Type: multipart/mixed; boundary="=============== ==" MIME-Version: 1.0 From: Me <me@foo.com> To: Him <him@bar.com>, just@me.com Subject: the subject 13

18 Python easy mail library Documentation, Release Date: Fri, 19 Aug :04: =============== == Content-Type: text/plain; charset="iso " MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Bonjour aux Fran=E7ais --=============== == Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="text.txt" attached content --=============== ==-- Send an First take a look at the other values returned by pyzmail.compose_mail(): print 'Sender address:', mail_from print 'Recipients:', rcpt_to Here are the values I can reuse for my SMTP connection: Sender address: me@foo.com Recipients: ['him@bar.com', 'just@me.com'] I want to send my via my Gmail account: smtp_host='smtp.gmail.com' smtp_port=587 smtp_mode='tls' smtp_login='my.gmail.addresse@gmail.com' smtp_password='my.gmail.password' ret=pyzmail.send_mail(payload, mail_from, rcpt_to, smtp_host, \ smtp_port=smtp_port, smtp_mode=smtp_mode, \ smtp_login=smtp_login, smtp_password=smtp_password) if isinstance(ret, dict): if ret: print 'failed recipients:', ', '.join(ret.keys()) else: print 'success' else: print 'error:', ret Here pyzmail.send_mail() combine SSL and authentication. 14 Chapter 6. Quick Example

19 Python easy mail library Documentation, Release Parse an Now lets try to read the we have just composed: msg=pyzmail.pyzmessage.factory(payload) print 'Subject: %r' % (msg.get_subject(), ) print 'From: %r' % (msg.get_address('from'), ) print 'To: %r' % (msg.get_addresses('to'), ) print 'Cc: %r' % (msg.get_addresses('cc'), ) Take a look at the outpout: Subject: u'the subject' From: (u'me', 'me@foo.com') To: [(u'him', 'him@bar.com'), (u'just@me.com', 'just@me.com')] Cc: [] And a little further regarding the mail content and attachment: for mailpart in msg.mailparts: print ' %sfilename=%r alt_filename=%r type=%s charset=%s desc=%s size=%d' % ( \ '*'if mailpart.is_body else ' ', \ mailpart.filename, \ mailpart.sanitized_filename, \ mailpart.type, \ mailpart.charset, \ mailpart.part.get('content-description'), \ len(mailpart.get_payload()) ) if mailpart.type.startswith('text/'): # display first line of the text payload, used_charset=pyzmail.decode_text(mailpart.get_payload(), mailpart. charset, None) print ' >', payload.split('\\n')[0] And the output: *filename=none alt_filename='text.txt' type=text/plain charset=iso desc=none size=20 > Bonjour aux Français filename=u'text.txt' alt_filename='text-01.txt' type=text/plain charset=us-ascii desc=none size=16 > attached content The first one, with a * is the text content, the second one is the attachment. You also have direct access to the text and HTML content using: if msg.text_part!=none: print '-- text --' print msg.text_part.get_payload() if msg.html_part!=none: print '-- html --' print msg.html_part.get_payload() And the output: 6.3. Parse an 15

20 Python easy mail library Documentation, Release text -- Bonjour aux Français Their is no HTML part! 16 Chapter 6. Quick Example

21 CHAPTER 7 Tricks Embedding image in HTML Image embedding differs from linked images in that the image itself is encoded, and included inside the message. Instead of using a normal URL in the IMG tag inside the HTML body, we must use a cid:target reference and assign this target name to the Content-ID of the embedded file. See this sample: import base64 import pyzmail angry_gif=base64.b64decode( """R0lGODlhDgAOALMAAAwMCYAAAACAAKaCIwAAgIAAgACAgPbTfoR/YP8AAAD/AAAA//rMUf8A/wD/ //Tw5CH5BAAAAAAALAAAAAAOAA4AgwwMCYAAAACAAKaCIwAAgIAAgACAgPbTfoR/YP8AAAD/AAAA //rmuf8a/wd///tw5aq28b1gqz3s6jop2sxnayngaghahirquzh6sedgpqgy5/b9ui+ezkakghhg ZPLIbMKcDMwLhIkAADs= """) text_content=u"i'm very angry. See attached document." html_content=u'<html><body>i\'m very angry. ' \ '<img src="cid:angry_gif" />.\n' \ 'See attached document.</body></html>' payload, mail_from, rcpt_to, msg_id=pyzmail.compose_mail(\ (u'me', 'me@foo.com'), \ [(u'him', 'him@bar.com'), 'just@me.com'], \ u'the subject', \ 'iso ', \ (text_content, 'iso '), \ (html_content, 'iso '), \ attachments=[('the price of RAM modules is increasing.', \ 'text', 'plain', 'text.txt', 'us-ascii'), ], embeddeds=[(angry_gif, 'image', 'gif', 'angry_gif', None), ]) 17

22 Python easy mail library Documentation, Release print payload And here is the payload: Content-Type: multipart/mixed; boundary="=============== ==" MIME-Version: 1.0 From: Me To: Him Subject: the subject Date: Fri, 02 Sep :40: =============== == Content-Type: multipart/related; boundary="=============== ==" MIME-Version: =============== == Content-Type: multipart/alternative; boundary="=============== ==" MIME-Version: =============== == Content-Type: text/plain; charset="iso " MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable I'm very angry. See attached document. --=============== == Content-Type: text/html; charset="iso " MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable <html><body>i'm very angry. <img src=3d"cid:angry_gif" />. See attached doc= ument.</body></html> --=============== ==-- --=============== == Content-Type: image/gif MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-ID: <angry_gif> Content-Disposition: inline R0lGODlhDgAOALMAAAwMCYAAAACAAKaCIwAAgIAAgACAgPbTfoR/YP8AAAD/AAAA//rMUf8A/wD/ //Tw5CH5BAAAAAAALAAAAAAOAA4AgwwMCYAAAACAAKaCIwAAgIAAgACAgPbTfoR/YP8AAAD/AAAA //rmuf8a/wd///tw5aq28b1gqz3s6jop2sxnayngaghahirquzh6sedgpqgy5/b9ui+ezkakghhg ZPLIbMKcDMwLhIkAADs= --=============== ==-- --=============== == Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="text.txt" The price of RAM module is increasing. --=============== ==-- 18 Chapter 7. Tricks

23 CHAPTER 8 Scripts Binary executables for Windows of these script are available in the Download _ section below. pyzsendmail pyzsendmail is a command line script to compose and send simple and complex s. Features: SSL, TLS, authentication HTML content and embedded images attachments Internationalisation Read the manual for more. Under Windows pyzsendmail.exe can replace the now old blat.exe and bmail.exe. pyzinfomail pyzinfomail is a command line script reading an from a file and printing most important information. Mostly to show how to use pyzmail library. Read the manual for more. 19

24 Python easy mail library Documentation, Release Chapter 8. Scripts

25 CHAPTER 9 License pyzmail iis released under the GNU Lesser General Public License ( LGPL ). 21

26 Python easy mail library Documentation, Release Chapter 9. License

27 CHAPTER 10 Links More links about parsing and writing mail in python formataddr() and unicode Sending Unicode s in Python Sending with smtplib 23