# # pyzmail/generate.py # (c) Alain Spineux # http://www.magiksys.net/pyzmail # Released under LGPL """ Useful functions to compose and send emails. For short: >>> payload, mail_from, rcpt_to, msg_id=compose_mail((u'Me', 'me@foo.com'), ... [(u'Him', 'him@bar.com')], u'the subject', 'iso-8859-1', ('Hello world', 'us-ascii'), ... attachments=[('attached', 'text', 'plain', 'text.txt', 'us-ascii')]) ... #doctest: +SKIP >>> error=send_mail(payload, mail_from, rcpt_to, 'localhost', smtp_port=25) ... #doctest: +SKIP """ import os, sys import time import base64 import smtplib, socket import email import email.encoders import email.header import email.utils import email.mime import email.mime.base import email.mime.text import email.mime.image import email.mime.multipart from . import utils def format_addresses(addresses, header_name=None, charset=None): """ Convert a list of addresses into a MIME-compliant header for a From, To, Cc, or any other I{address} related field. This mixes the use of email.utils.formataddr() and email.header.Header(). @type addresses: list @param addresses: list of addresses, can be a mix of string a tuple of the form C{[ 'address@domain', (u'Name', 'name@domain'), ...]}. If C{u'Name'} contains non us-ascii characters, it must be a unicode string or encoded using the I{charset} argument. @type header_name: string or None @keyword header_name: the name of the header. Its length is used to limit the length of the first line of the header according the RFC's requirements. (not very important, but it's better to match the requirements when possible) @type charset: str @keyword charset: the encoding charset for non unicode I{name} and a B{hint} for encoding of unicode string. In other words, if the I{name} of an address in a byte string containing non I{us-ascii} characters, then C{name.decode(charset)} must generate the expected result. If a unicode string is used instead, charset will be tried to encode the string, if it fail, I{utf-8} will be used. With B{Python 3.x} I{charset} is no more a hint and an exception will be raised instead of using I{utf-8} has a fall back. @rtype: str @return: the encoded list of formated addresses separated by commas, ready to use as I{Header} value. >>> print format_addresses([('John', 'john@foo.com') ], 'From', 'us-ascii').encode() John >>> print format_addresses([(u'l\\xe9o', 'leo@foo.com') ], 'To', 'iso-8859-1').encode() =?iso-8859-1?q?l=E9o?= >>> print format_addresses([(u'l\\xe9o', 'leo@foo.com') ], 'To', 'us-ascii').encode() ... # don't work in 3.X because charset is more than a hint ... #doctest: +SKIP =?utf-8?q?l=C3=A9o?= >>> # because u'l\xe9o' cannot be encoded into us-ascii, utf8 is used instead >>> print format_addresses([('No\\xe9', 'noe@f.com'), (u'M\\u0101ori', 'maori@b.com') ], 'Cc', 'iso-8859-1').encode() ... # don't work in 3.X because charset is more than a hint ... #doctest: +SKIP =?iso-8859-1?q?No=E9?= , =?utf-8?b?TcSBb3Jp?= >>> # 'No\xe9' is already encoded into iso-8859-1, but u'M\\u0101ori' cannot be encoded into iso-8859-1 >>> # then utf8 is used here >>> print format_addresses(['a@bar.com', ('John', 'john@foo.com') ], 'From', 'us-ascii').encode() a@bar.com , John """ header=email.header.Header(charset=charset, header_name=header_name) for i, address in enumerate(addresses): if i!=0: # add separator between addresses header.append(',', charset='us-ascii') try: name, addr=address except ValueError: # address is not a tuple, their is no name, only email address header.append(address, charset='us-ascii') else: # check if address name is a unicode or byte string in "pure" us-ascii if utils.is_usascii(name): # name is a us-ascii byte string, i can use formataddr formated_addr=email.utils.formataddr((name, addr)) # us-ascii must be used and not default 'charset' header.append(formated_addr, charset='us-ascii') else: # this is not as "pure" us-ascii string # Header will use "RFC2047" to encode the address name # if name is byte string, charset will be used to decode it first header.append(name) # here us-ascii must be used and not default 'charset' header.append('<%s>' % (addr,), charset='us-ascii') return header def build_mail(text, html=None, attachments=None, embeddeds=None): """ Generate the core of the email message regarding the parameters. The structure of the MIME email may vary, but the general one is as follow:: multipart/mixed (only if attachments are included) | +-- multipart/related (only if embedded contents are included) | | | +-- multipart/alternative (only if text AND html are available) | | | | | +-- text/plain (text version of the message) | | +-- text/html (html version of the message) | | | +-- image/gif (where to include embedded contents) | +-- application/msword (where to add attachments) @param text: the text version of the message, under the form of a tuple: C{(encoded_content, encoding)} where I{encoded_content} is a byte string encoded using I{encoding}. I{text} can be None if the message has no text version. @type text: tuple or None @keyword html: the HTML version of the message, under the form of a tuple: C{(encoded_content, encoding)} where I{encoded_content} is a byte string encoded using I{encoding} I{html} can be None if the message has no HTML version. @type html: tuple or None @keyword attachments: the list of attachments to include into the mail, in the form [(data, maintype, subtype, filename, charset), ..] where : - I{data} : is the raw data, or a I{charset} encoded string for 'text' content. - I{maintype} : is a MIME main type like : 'text', 'image', 'application' .... - I{subtype} : is a MIME sub type of the above I{maintype} for example : 'plain', 'png', 'msword' for respectively 'text/plain', 'image/png', 'application/msword'. - I{filename} this is the filename of the attachment, it must be a 'us-ascii' string or a tuple of the form C{(encoding, language, encoded_filename)} following the RFC2231 requirement, for example C{('iso-8859-1', 'fr', u'r\\xe9pertoir.png'.encode('iso-8859-1'))} - I{charset} : if I{maintype} is 'text', then I{data} must be encoded using this I{charset}. It can be None for non 'text' content. @type attachments: list @keyword embeddeds: is a list of documents embedded inside the HTML or text version of the message. It is similar to the I{attachments} list, but I{filename} is replaced by I{content_id} that is related to the B{cid} reference into the HTML or text version of the message. @type embeddeds: list @rtype: inherit from email.Message @return: the message in a MIME object >>> mail=build_mail(('Hello world', 'us-ascii'), attachments=[('attached', 'text', 'plain', 'text.txt', 'us-ascii')]) >>> mail.set_boundary('===limit1==') >>> print mail.as_string(unixfrom=False) Content-Type: multipart/mixed; boundary="===limit1==" MIME-Version: 1.0 --===limit1== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Hello world --===limit1== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="text.txt" attached --===limit1==-- """ if attachments is None: attachments = [] if embeddeds is None: embeddeds = [] main=text_part=html_part=None if text: content, charset=text main=text_part=email.mime.text.MIMEText(content, 'plain', charset) if html: content, charset=html main=html_part=email.mime.text.MIMEText(content, 'html', charset) if not text_part and not html_part: main=text_part=email.mime.text.MIMEText('', 'plain', 'us-ascii') elif text_part and html_part: # need to create a multipart/alternative to include text and html version main=email.mime.multipart.MIMEMultipart('alternative', None, [text_part, html_part]) if embeddeds: related=email.mime.multipart.MIMEMultipart('related') related.attach(main) for part in embeddeds: if not isinstance(part, email.mime.base.MIMEBase): data, maintype, subtype, content_id, charset=part if (maintype=='text'): part=email.mime.text.MIMEText(data, subtype, charset) else: part=email.mime.base.MIMEBase(maintype, subtype) part.set_payload(data) email.encoders.encode_base64(part) part.add_header('Content-ID', '<'+content_id+'>') part.add_header('Content-Disposition', 'inline') related.attach(part) main=related if attachments: mixed=email.mime.multipart.MIMEMultipart('mixed') mixed.attach(main) for part in attachments: if not isinstance(part, email.mime.base.MIMEBase): data, maintype, subtype, filename, charset=part if (maintype=='text'): part=email.mime.text.MIMEText(data, subtype, charset) else: part=email.mime.base.MIMEBase(maintype, subtype) part.set_payload(data) email.encoders.encode_base64(part) part.add_header('Content-Disposition', 'attachment', filename=filename) mixed.attach(part) main=mixed return main def complete_mail(message, sender, recipients, subject, default_charset, cc=None, bcc=None, message_id_string=None, date=None, headers=None): """ Fill in the From, To, Cc, Subject, Date and Message-Id I{headers} of one existing message regarding the parameters. @type message:email.Message @param message: the message to fill in @type sender: tuple @param sender: a tuple of the form (u'Sender Name', 'sender.address@domain.com') @type recipients: list @param recipients: a list of addresses. Address can be tuple or string like expected by L{format_addresses()}, for example: C{[ 'address@dmain.com', (u'Recipient Name', 'recipient.address@domain.com'), ... ]} @type subject: str @param subject: The subject of the message, can be a unicode string or a string encoded using I{default_charset} encoding. Prefert unicode to byte string here. @type default_charset: str @param default_charset: The default charset for this email. Arguments that are non unicode string are supposed to be encoded using this charset. This I{charset} will be used has an hint when encoding mail content. @type cc: list @keyword cc: The I{carbone copy} addresses. Same format as the I{recipients} argument. @type bcc: list @keyword bcc: The I{blind carbone copy} addresses. Same format as the I{recipients} argument. @type message_id_string: str or None @keyword message_id_string: if None, don't append any I{Message-ID} to the mail, let the SMTP do the job, else use the string to generate a unique I{ID} using C{email.utils.make_msgid()}. The generated value is returned as last argument. For example use the name of your application. @type date: int or None @keyword date: utc time in second from the epoch or None. If None then use curent time C{time.time()} instead. @type headers: list of tuple @keyword headers: a list of C{(field, value)} tuples to fill in the mail header fields. Values are encoded using I{default_charset}. @rtype: tuple @return: B{(payload, mail_from, rcpt_to, msg_id)} - I{payload} (str) is the content of the email, generated from the message - I{mail_from} (str) is the address of the sender to pass to the SMTP host - I{rcpt_to} (list) is a list of the recipients addresses to pass to the SMTP host of the form C{[ 'a@b.com', c@d.com', ]}. This combine all recipients, I{carbone copy} addresses and I{blind carbone copy} addresses. - I{msg_id} (None or str) None if message_id_string==None else the generated value for the message-id. If not None, this I{Message-ID} is already written into the payload. >>> import email.mime.text >>> msg=email.mime.text.MIMEText('The text.', 'plain', 'us-ascii') >>> # I could use build_mail() instead >>> payload, mail_from, rcpt_to, msg_id=complete_mail(msg, ('Me', 'me@foo.com'), ... [ ('Him', 'him@bar.com'), ], 'Non unicode subject', 'iso-8859-1', ... cc=['her@bar.com',], date=1313558269, headers=[('User-Agent', u'pyzmail'), ]) >>> print payload ... # 3.X encode User-Agent: using 'iso-8859-1' even if it contains only us-asccii ... # doctest: +ELLIPSIS Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: Me To: Him Cc: her@bar.com Subject: =?iso-8859-1?q?Non_unicode_subject?= Date: ... User-Agent: ...pyzmail... The text. >>> print 'mail_from=%r rcpt_to=%r' % (mail_from, rcpt_to) mail_from='me@foo.com' rcpt_to=['him@bar.com', 'her@bar.com'] """ def getaddr(address): if isinstance(address, tuple): return address[1] else: return address if cc is None: cc=[] if bcc is None: bcc=[] if headers is None: headers=[] mail_from=getaddr(sender[1]) rcpt_to=list(map(getaddr, recipients)) rcpt_to.extend(list(map(getaddr, cc))) rcpt_to.extend(list(map(getaddr, bcc))) message['From'] = format_addresses([ sender, ], header_name='from', charset=default_charset) if recipients: message['To'] = format_addresses(recipients, header_name='to', charset=default_charset) if cc: message['Cc'] = format_addresses(cc, header_name='cc', charset=default_charset) message['Subject'] = email.header.Header(subject, default_charset) if date: utc_from_epoch=date else: utc_from_epoch=time.time() message['Date'] = email.utils.formatdate(utc_from_epoch, localtime=True) if message_id_string: msg_id=message['Message-Id']=email.utils.make_msgid(message_id_string) else: msg_id=None for field, value in headers: message[field]=email.header.Header(value, default_charset) payload=message.as_string() return payload, mail_from, rcpt_to, msg_id def compose_mail(sender, recipients, subject, default_charset, text, html=None, attachments=None, embeddeds=None, cc=None, bcc=None, message_id_string=None, date=None, headers=None): """ Compose an email regarding the arguments. Call L{build_mail()} and L{complete_mail()} at once. Read the B{parameters} descriptions of both functions L{build_mail()} and L{complete_mail()}. Returned value is the same as for L{build_mail()} and L{complete_mail()}. You can pass the returned values to L{send_mail()} or L{send_mail2()}. @rtype: tuple @return: B{(payload, mail_from, rcpt_to, msg_id)} >>> payload, mail_from, rcpt_to, msg_id=compose_mail((u'Me', 'me@foo.com'), [(u'Him', 'him@bar.com')], u'the subject', 'iso-8859-1', ('Hello world', 'us-ascii'), attachments=[('attached', 'text', 'plain', 'text.txt', 'us-ascii')]) """ if attachments is None: attachments=[] if embeddeds is None: embeddeds=[] if cc is None: cc=[] if bcc is None: bcc = [] if headers is None: headers=[] message=build_mail(text, html, attachments, embeddeds) return complete_mail(message, sender, recipients, subject, default_charset, cc, bcc, message_id_string, date, headers) def send_mail2(payload, mail_from, rcpt_to, smtp_host, smtp_port=25, smtp_mode='normal', smtp_login=None, smtp_password=None): """ Send the message to a SMTP host. Look at the L{send_mail()} documentation. L{send_mail()} call this function and catch all exceptions to convert them into a user friendly error message. The returned value is always a dictionary. It can be empty if all recipients have been accepted. @rtype: dict @return: This function return the value returnd by C{smtplib.SMTP.sendmail()} or raise the same exceptions. This method will return normally if the mail is accepted for at least one recipient. Otherwise it will raise an exception. That is, if this method does not raise an exception, then someone should get your mail. If this method does not raise an exception, it returns a dictionary, with one entry for each recipient that was refused. Each entry contains a tuple of the SMTP error code and the accompanying error message sent by the server. @raise smtplib.SMTPException: Look at the standard C{smtplib.SMTP.sendmail()} documentation. """ if smtp_mode=='ssl': smtp=smtplib.SMTP_SSL(smtp_host, smtp_port) else: smtp=smtplib.SMTP(smtp_host, smtp_port) if smtp_mode=='tls': smtp.starttls() if smtp_login and smtp_password: if sys.version_info<(3, 0): # python 2.x # login and password must be encoded # because HMAC used in CRAM_MD5 require non unicode string smtp.login(smtp_login.encode('utf-8'), smtp_password.encode('utf-8')) else: #python 3.x smtp.login(smtp_login, smtp_password) try: ret=smtp.sendmail(mail_from, rcpt_to, payload) finally: try: smtp.quit() except Exception as e: pass return ret def send_mail(payload, mail_from, rcpt_to, smtp_host, smtp_port=25, smtp_mode='normal', smtp_login=None, smtp_password=None): """ Send the message to a SMTP host. Handle SSL, TLS and authentication. I{payload}, I{mail_from} and I{rcpt_to} can come from values returned by L{complete_mail()}. This function call L{send_mail2()} but catch all exceptions and return friendly error message instead. @type payload: str @param payload: the mail content. @type mail_from: str @param mail_from: the sender address, for example: C{'me@domain.com'}. @type rcpt_to: list @param rcpt_to: The list of the recipient addresses in the form C{[ 'a@b.com', c@d.com', ]}. No names here, only email addresses. @type smtp_host: str @param smtp_host: the IP address or the name of the SMTP host. @type smtp_port: int @keyword smtp_port: the port to connect to on the SMTP host. Default is C{25}. @type smtp_mode: str @keyword smtp_mode: the way to connect to the SMTP host, can be: C{'normal'}, C{'ssl'} or C{'tls'}. default is C{'normal'} @type smtp_login: str or None @keyword smtp_login: If authentication is required, this is the login. Be carefull to I{UTF8} encode your login if it contains non I{us-ascii} characters. @type smtp_password: str or None @keyword smtp_password: If authentication is required, this is the password. Be carefull to I{UTF8} encode your password if it contains non I{us-ascii} characters. @rtype: dict or str @return: This function return a dictionary of failed recipients or a string with an error message. If all recipients have been accepted the dictionary is empty. If the returned value is a string, none of the recipients will get the message. The dictionary is exactly of the same sort as smtplib.SMTP.sendmail() returns with one entry for each recipient that was refused. Each entry contains a tuple of the SMTP error code and the accompanying error message sent by the server. Example: >>> send_mail('Subject: hello\\n\\nmessage', 'a@foo.com', [ 'b@bar.com', ], 'localhost') #doctest: +SKIP {} Here is how to use the returned value:: if isinstance(ret, dict): if ret: print 'failed' recipients: for recipient, (code, msg) in ret.iteritems(): print 'code=%d recipient=%s\terror=%s' % (code, recipient, msg) else: print 'success' else: print 'Error:', ret To use your GMail account to send your mail:: smtp_host='smtp.gmail.com' smtp_port=587 smtp_mode='tls' smtp_login='your.gmail.addresse@gmail.com' smtp_password='your.gmail.password' Use your GMail address for the sender ! """ error=dict() try: ret=send_mail2(payload, mail_from, rcpt_to, smtp_host, smtp_port, smtp_mode, smtp_login, smtp_password) except (socket.error, ) as e: error='server %s:%s not responding: %s' % (smtp_host, smtp_port, e) except smtplib.SMTPAuthenticationError as e: error='authentication error: %s' % (e, ) except smtplib.SMTPRecipientsRefused as e: # code, error=e.recipients[recipient_addr] error='all recipients refused: '+', '.join(list(e.recipients.keys())) except smtplib.SMTPSenderRefused as e: # e.sender, e.smtp_code, e.smtp_error error='sender refused: %s' % (e.sender, ) except smtplib.SMTPDataError as e: error='SMTP protocol mismatch: %s' % (e, ) except smtplib.SMTPHeloError as e: error="server didn't reply properly to the HELO greeting: %s" % (e, ) except smtplib.SMTPException as e: error='SMTP error: %s' % (e, ) # except Exception, e: # raise # unknown error else: # failed addresses and error messages error=ret return error