Send a electronic mail to a list of recipients.


    @note: Outlook and Gmail leverage the list-unsubscribe option for
        senders with good sending reputations:

        "In order to receive unsubscribe feedback, senders must include an
        RFC2369-compliant List-Unsubscribe header containing a mailto: address.
        Please note that we only enable this feedback via email, so URIs for
        other protocols such as http will be ignored. The sender must also
        have a good reputation, and must act promptly in removing users from
        their lists. We do not provide unsubscribe feedback to senders when a
        user unsubscribes from an untrusted message."
        [https://sendersupport.olc.protection.outlook.com/pm/junkemail.aspx]

        "This only works for some senders right now. We're actively encouraging
        senders to support auto-unsubscribe — we think 100% should.  We won't
        provide the unsubscribe option on messages from spammers: we can't
        trust that they'll actually unsubscribe you, and they might even send
        you more spam.  So you'll only see the unsubscribe option for senders
        that we're pretty sure are not spammers and will actually honor your
        unsubscribe request.  We're being pretty conservative about which
        senders to trust in the beginning; over time, we hope to offer the
        ability to unsubscribe from more email."
        [https://gmail.googleblog.com/2009/07/unsubscribing-made-easy.html]


    @param hostname: Internet address or fully qualified domain name --
        human-readable nickname that corresponds to the address -- of the
        SMTP server is running on.

    @param username: username to authenticate with against the SMTP server.

    @param password: password associate to the username to authenticate
        with against the SMTP server.

    @param author_name: complete name of the originator of the message.

    @param author_email_address: address of the mailbox to which the author
        of the message suggests that replies be sent.

    @param recipient_email_addresses: email address(es) of the primary
        recipient(s) of the message.  A bare string will be treated as a
        list with one address.

    @param subject: a short string identifying the topic of the message.

    @param content: the body of the message.

    @param file_path_names: a list of complete fully qualified path name
        (FQPN) of the files to attach to this message.

    @param port_number: Internet port number on which the remote SMTP
        server is listening at.

        SMTP communication between mail servers uses TCP port 25.  Mail
        clients on the other hand, often submit the outgoing emails to a mail
        server on port 587.  Despite being deprecated, mail providers
        sometimes still permit the use of nonstandard port 465 for this
        purpose.

    @param unsubscribe_mailto_link: an email address to directly
        unsubscribe the recipient who requests to be removed from the
        mailing list (https://tools.ietf.org/html/rfc2369.html).

        In addition to the email address, other information can be provided.
        In fact, any standard mail header fields can be added to the mailto
        link.  The most commonly used of these are "subject", "cc", and "body"
        (which is not a true header field, but allows you to specify a short
        content message for the new email). Each field and its value is
        specified as a query term (https://tools.ietf.org/html/rfc6068).

    @param unsubscribe_url: a link that will take the subscriber to a
        landing page to process the unsubscribe request.  This can be a
        subscription center, or the subscriber is removed from the list
        right away and gets sent to a landing page that confirms the
        unsubscribe.

def send_email(hostname, username, password,
        author_name, author_email_address, recipient_email_addresses,
        subject, content,
        file_path_names=None,
        port_number=587,
        unsubscribe_mailto_link=None,
        unsubscribe_url=None):
    """
    Send a electronic mail to a list of recipients.


    @note: Outlook and Gmail leverage the list-unsubscribe option for
        senders with good sending reputations:

        "In order to receive unsubscribe feedback, senders must include an
        RFC2369-compliant List-Unsubscribe header containing a mailto: address.
        Please note that we only enable this feedback via email, so URIs for
        other protocols such as http will be ignored. The sender must also
        have a good reputation, and must act promptly in removing users from
        their lists. We do not provide unsubscribe feedback to senders when a
        user unsubscribes from an untrusted message."
        [https://sendersupport.olc.protection.outlook.com/pm/junkemail.aspx]

        "This only works for some senders right now. We're actively encouraging
        senders to support auto-unsubscribe — we think 100% should.  We won't
        provide the unsubscribe option on messages from spammers: we can't
        trust that they'll actually unsubscribe you, and they might even send
        you more spam.  So you'll only see the unsubscribe option for senders
        that we're pretty sure are not spammers and will actually honor your
        unsubscribe request.  We're being pretty conservative about which
        senders to trust in the beginning; over time, we hope to offer the
        ability to unsubscribe from more email."
        [https://gmail.googleblog.com/2009/07/unsubscribing-made-easy.html]


    @param hostname: Internet address or fully qualified domain name --
        human-readable nickname that corresponds to the address -- of the
        SMTP server is running on.

    @param username: username to authenticate with against the SMTP server.

    @param password: password associate to the username to authenticate
        with against the SMTP server.

    @param author_name: complete name of the originator of the message.

    @param author_email_address: address of the mailbox to which the author
        of the message suggests that replies be sent.

    @param recipient_email_addresses: email address(es) of the primary
        recipient(s) of the message.  A bare string will be treated as a
        list with one address.

    @param subject: a short string identifying the topic of the message.

    @param content: the body of the message.

    @param file_path_names: a list of complete fully qualified path name
        (FQPN) of the files to attach to this message.

    @param port_number: Internet port number on which the remote SMTP
        server is listening at.

        SMTP communication between mail servers uses TCP port 25.  Mail
        clients on the other hand, often submit the outgoing emails to a mail
        server on port 587.  Despite being deprecated, mail providers
        sometimes still permit the use of nonstandard port 465 for this
        purpose.

    @param unsubscribe_mailto_link: an email address to directly
        unsubscribe the recipient who requests to be removed from the
        mailing list (https://tools.ietf.org/html/rfc2369.html).

        In addition to the email address, other information can be provided.
        In fact, any standard mail header fields can be added to the mailto
        link.  The most commonly used of these are "subject", "cc", and "body"
        (which is not a true header field, but allows you to specify a short
        content message for the new email). Each field and its value is
        specified as a query term (https://tools.ietf.org/html/rfc6068).

    @param unsubscribe_url: a link that will take the subscriber to a
        landing page to process the unsubscribe request.  This can be a
        subscription center, or the subscriber is removed from the list
        right away and gets sent to a landing page that confirms the
        unsubscribe.
    """
    # Convert bare string representing only one email address as a list with
    # this single email address.
    if not isinstance(recipient_email_addresses, (list, set, tuple)):
        recipient_email_addresses = [ recipient_email_addresses ]

    # Build the message to be sent.
    message = MIMEMultipart()
    message['From'] = __build_author_name_expr(author_name, author_email_address)
    message['To'] = COMMASPACE.join(recipient_email_addresses)
    message['Date'] = formatdate(localtime=True)
    message['Subject'] = subject

    if author_email_address:
        message.add_header('Reply-To', author_email_address)

    # Add method(s) to unsubscribe a recipient from a mailing list at his
    # request.
    if unsubscribe_mailto_link or unsubscribe_url:
        unsubscribe_methods = [
            unsubscribe_url and '<%s>' % unsubscribe_url,
            unsubscribe_mailto_link and '<mailto:%s>' % unsubscribe_mailto_link,
        ]

        message.add_header('List-Unsubscribe', ', '.join([ method for method in unsubscribe_methods if method ]))

    # Detect whether the content of the message is a plain text or an HTML
    # content, based on whether the content starts with "<" or not.
    message.attach(MIMEText(content.encode('utf-8'),
            _charset='utf-8',
            _subtype='html' if content and content.strip()[0] == '<' else 'plain'))

    # Attache the specified files to the message.
    for file_path_name in file_path_names or []:
        part = MIMEBase('application', 'octet-stream')

        with open(file_path_name, 'rb') as handle:
            part.set_payload(handle.read())

        encoders.encode_base64(part)
        part.add_header('Content-Disposition', 'attachment', filename=os.path.basename(file_path_name))
        message.attach(part)

    # Connect the remote mail server and send the message.
    smtp_server = smtplib.SMTP_SSL(hostname) if port_number == 465 else smtplib.SMTP(hostname, port_number)
    smtp_server.ehlo()

    if port_number <> 465:
        smtp_server.starttls()
        smtp_server.ehlo()

    smtp_server.login(username, password)
    smtp_server.sendmail(author_email_address, recipient_email_addresses, message.as_string())

    smtp_server.close()