sendSESEmailBulk.py

#!/usr/bin/env python

"""Send bulk emails through AWS SES.
This script is an extension (and eventually a replacement) to sendSESEmail.py,
and a more generalized version of it's functionalities. Eventually, we want
to validate the funtionalities of this script in use cases where
sendSESEmail.py is being used, and make the email sending implementation in
this script default.

This attempts to simplify the grouping of email recipients
(to, cc and bcc) by respecting the limit of number of recipients that can be
used in a single aws ses send_email api call.

Uses the AWS SES call send-mail.
Has the following important parameters:

Body contents: (at least one of the following has to be specified.)
- text -- the plain text version of the email.
- html -- the HTML-formatted version of the email.

- subject -- the subject of the email.  This is required.
- efrom -- the from email.  This is required.
The efrom requires verification by AWS SES (either by email address or by domain.)
- replyto -- the reply to email.  (submitform.pl & submitsecure.pl)

IMPORTANT: Please inspect the batch_recipients function to see how email
groups are constructed.

Email destinations: (at least one of the following has to be specified.)
Destinations are space-separated like a@comp.dom b@comp.dom ...
- to -- a list of to recipients.  (Who the email is actually addressed to.)
- bcc -- a list of bcc recipients. (List isn't visible in email.)
- cc -- the cc for the email.  (Visible list in email.)

Amazon requires the from email to be verified or the domain verified.
"""

import sys
import boto3
import os
import json
import argparse
from botocore.exceptions import ClientError
import textwrap
import logging

format=("[%(levelname)-5s] %(asctime)-15s ({}|%(funcName)s|%(lineno)d) "
        ":: %(message)s").format(__file__)
LOGGER = logging.getLogger(__name__)
LOGGER.setLevel(logging.DEBUG)
logging_handler = logging.StreamHandler()
logging_handler.setFormatter(logging.Formatter(format))
LOGGER.addHandler(logging_handler)

# Global settings
USAGE_HELP = ("Usage: sendSESEmailBulk.py [-h] [--to TO [TO ...]] "
              "[--bcc BCC [BCC ...]] [--cc CC [CC ...]] --efrom EFROM"
              "[--replyto REPLYTO [REPLYTO ...]] --subject SUBJECT"
              "[--plaintext PLAINTEXT] [--htmltext HTMLTEXT]"
              "[--quiet] [--context CONTEXT]")

# aws ses is only available and configured in 'us-west-2'
AWS_REGION = 'us-west-2'

# The message may not include more than 50 recipients, across
# the To:, CC: and BCC: fields.
# See: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ses.html
AWS_SES_EMAIL_LIMIT = 50


class CustomArgumentParser(argparse.ArgumentParser):
    """Custom ArgumentParser class

    Extends:
        argparse.ArgumentParser
    """

    def error(self, message):
        """Suppressing default error method

        Return custom error message on ArgumentParser.error.

        Arguments:
            message -- error message

        Raises:
            BaseException
        """
        raise BaseException(message)


def getParser():
    """Prepare argument parser.

    Returns:
        parser -- ArgumentParser object
    """
    parser = CustomArgumentParser (
        description = "Send emails through AWS SES.",
        formatter_class = argparse.RawDescriptionHelpFormatter,
        epilog = textwrap.dedent('''\
            additional information:
                One of --to, --bcc, or --cc has to be defined.
                One of --plaintext or --htmltext has to be defined.
                --efrom and --subject are required.
            '''))

    parser.add_argument ("--to", nargs = "+",
                        help = "Space-separated list of to email addresses",
                        required = False)

    parser.add_argument ("--bcc", nargs = "+",
                        help = "Space-separated list of bcc email addresses",
                        required = False)

    parser.add_argument ("--cc", nargs = "+",
                         help = "Space-separated list of cc email addresses",
                         required = False)

    parser.add_argument ("--efrom",
                        help = "From email address",
                        required = True)

    parser.add_argument ("--replyto", nargs = "+",
                        help = "Reply to email address",
                        required = False)

    parser.add_argument ("--subject",
                         help = "Subject of the email",
                         required = True)

    parser.add_argument ("--plaintext",
                        help = "Email body in plaintext",
                        required = False)

    parser.add_argument ("--htmltext",
                        help = "Html body in HTML",
                        required = False)

    parser.add_argument("--quiet", action = "store_true",
                        help = "Suppress success message",
                        required = False)

    parser.add_argument("--context",
                        help = ("Json string for logging application"
                                "context for the email messages being sent."),
                        required = False)

    return parser


def get_ith_batch(_iter, batch_i, batch_size):
    start = batch_i * batch_size
    end = min(batch_i * batch_size + batch_size, len(_iter))
    return _iter[start:end]


def batch_recipients(to, cc, bcc, ses_batch_size=AWS_SES_EMAIL_LIMIT):
    """
    This function constructs a collective (to, cc, bcc) batch of email
    recipients to be used for aws ses send_email destination argument.

    NOTE: there are varions use cases that need detailed conversation:
    - What if the total of cc + to recipients is greater than the
      AWS_SES_EMAIL_LIMIT? How do we construct the appropriate
      destination object? How do we divide cc's? How many cc's do
      do we want to allow?
    - Similar concerns with cc + bcc.

    Args:
        to: list of to recipients
        cc: list of cc recipients
        bcc: list of bcc recipients

    Returns:
        Generator that iterator of email group recipients

    """
    bcc_count = len(bcc)
    to_count = len(to)
    cc_count = len(cc)

    # list of all recipients under batch size
    if to_count + cc_count + bcc_count <= ses_batch_size:
        yield (to, cc, bcc)

    else:
        # total of to and cc list can be processed
        if to_count + cc_count <= ses_batch_size:
            yield(to, cc, [])

        # TODO: any combination of to, cc and bcc: this needs to be
        # further discussed to cover other possible use cases
        else:
            # admin broadcast email uses only `to:` recipients
            if to_count > 0:
                for ith_to in range(int(to_count/ses_batch_size)+1):
                    yield (get_ith_batch(to, ith_to, ses_batch_size), [], [])

            # admin broadcast email uses only 'cc:' recipients
            # this means that this would only send emails as cc
            # for all the recipients in this group
            if cc_count > 0:
                for ith_cc in range(int(cc_count/ses_batch_size)+1):
                    yield ([], get_ith_batch(cc, ith_cc, ses_batch_size), [])

        # broadcast email uses only 'bcc:' recipients
        if bcc_count > 0:
            for ith_bcc in range(int(bcc_count/ses_batch_size)+1):
                yield ([], [], get_ith_batch(bcc, ith_bcc, ses_batch_size))


def send_email_batch(email_group, context, args):
    """
    This sends emails to a batch of to, cc and bcc recipients.

    Args:
        email_group: group of to, cc and bcc email recipients; total
                 should be less than or equal to AWS_SES_EMAIL_LIMIT
    Returns:
        batch_return: a dictionary of status, error and response force
                      each email group

    """
    success = True
    response = {}

    batch_return = {
        'status': '000',
        'error': [],
        'response': {},
        'context': context
    }

    try:

        # Create boto3 client object
        client = boto3.client('ses', region_name=AWS_REGION)

        # Construct destination
        destination = {}

        if email_group[0]: destination["ToAddresses"] = email_group[0]
        if email_group[1]: destination["CcAddresses"] = email_group[1]
        if email_group[2]: destination["BccAddresses"] = email_group[2]

        # Construct message
        charset = "UTF-8"
        message = {}
        message["Subject"] = {}
        message["Subject"]["Data"] = args.subject
        message["Subject"]["Charset"] = charset

        if (args.plaintext != None):
            message["Body"] = {}
            message["Body"]["Text"] = {}
            message["Body"]["Text"] ["Data"] = args.plaintext
            message["Body"]["Text"] ["Charset"] = charset

        if (args.htmltext != None):
            if "Body" not in message:
                message ["Body"] = {}

            message["Body"]["Html"] = {}
            message["Body"]["Html"]["Data"] = args.htmltext
            message["Body"]["Html"]["Charset"] = charset

        if (args.replyto != None):
            # Call AWS SES
            response = client.send_email (
                Source = args.efrom,
                Destination = destination,
                Message = message,
                ReplyToAddresses = args.replyto,
                ConfigurationSetName='ses-detail-logging',
            )
        else:
            # Call AWS SES
            response = client.send_email (
                Source = args.efrom,
                Destination = destination,
                Message = message,
                ConfigurationSetName='ses-detail-logging',
            )

    except ClientError as e:
        success = False
        batch_return["status"] = 902
        batch_return["error"] = str(e)

    except Exception as e:
        success = False
        batch_return['status'] = 903
        batch_return['error'] = e


    batch_return['response'] = response

    # log response with requestId, messageId and calling context for each batch
    # AWS S3 store AWS Kinesis Data Firehose events regarding SES send-email
    if success:
        LOGGER.info(batch_return)
    else:
        LOGGER.error(batch_return)

    return success


def main(argv):
    """Main method to execute operations on email verification.

    Arguments:
        argv {list} -- list of script arguments

    Returns:
        validation_response <dictionary>: if any arguments validation error,
                                          return a json error: code is non zero
        OR
        respons_list <list>: list of json response for each batch
                             of email recipients

    Raises:
        SystemExit
        BaseException
    """

    return_code = 0
    sender_context = {}
    validation_response = {
        'status': '000',
        'error': [],
        'response': {},
        'context': sender_context
    }

    recipient_to = []
    recipient_cc = []
    recipient_bcc = []

    # Get argument parser
    parser = getParser()

    try:
        args = parser.parse_args(argv)
        sender_context = args.context

        # Validation
        if (args.to == None and args.bcc == None and args.cc == None):
            raise BaseException ("Destination has to be specified. One of"
                                 " the --to, --bcc or --cc options need"
                                 " to be provided.")
        else:
            if args.to != None: recipient_to = args.to
            if args.cc != None: recipient_cc = args.cc
            if args.bcc != None: recipient_bcc = args.bcc

        if (args.plaintext == None and args.htmltext == None):
            raise BaseException ("Email body has to be specified")

    except (BaseException) as e:
        return_code = 102
        evalue = str(e)
        if (evalue != "0"): # If it is empty, it is a help message
            validation_response["status"] = return_code
            validation_response["error"].append(USAGE_HELP)
            validation_response["error"].append(str(e))
            validation_response["context"] = sender_context
            LOGGER.error(json.dumps(validation_response))

    except (Exception) as e:
        return_code = 103
        validation_response["status"] = return_code
        validation_response["error"] = str(e)
        validation_response["context"] = sender_context
        LOGGER.error(json.dumps(validation_response))

    # exit if validation error
    if return_code > 0:
        return return_code

    # prepare email groups and send emails
    recipient_generator = batch_recipients(recipient_to,
                                           recipient_cc,
                                           recipient_bcc)

    for email_group in recipient_generator:
        if sum(map(len, email_group)) > 0:
            batch_success = send_email_batch(email_group, sender_context, args)
            # mark that aws ses failed to process some batches or all messages
            # only used for script exit code
            if not batch_success:
                return_code = 1

    return return_code


def run():
    """Script entrypoint"""
    sys.exit(main(sys.argv[1:]))


if __name__ == "__main__":
    run()