sendSESEmailBulk Namespace Reference

Classes
class	CustomArgumentParser

Functions
def	getParser ()
def	get_ith_batch (_iter, batch_i, batch_size)
def	batch_recipients (to, cc, bcc, ses_batch_size=AWS_SES_EMAIL_LIMIT)
def	send_email_batch (email_group, context, args)
def	main (argv)
def	run ()

Variables
tuple	format
	LOGGER = logging.getLogger(__name__)
	logging_handler = logging.StreamHandler()
tuple	USAGE_HELP
string	AWS_REGION = 'us-west-2'
int	AWS_SES_EMAIL_LIMIT = 50

Detailed Description

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.

Function Documentation

batch_recipients()

def sendSESEmailBulk.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

Definition at line 158 of file sendSESEmailBulk.py.

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))

getParser()

def sendSESEmailBulk.getParser

(

)

Prepare argument parser.

Returns:
    parser -- ArgumentParser object

Definition at line 92 of file sendSESEmailBulk.py.

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

main()

def sendSESEmailBulk.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

Definition at line 309 of file sendSESEmailBulk.py.

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

run()

def sendSESEmailBulk.run

(

)

Script entrypoint

Definition at line 397 of file sendSESEmailBulk.py.

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

send_email_batch()

def sendSESEmailBulk.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

Definition at line 213 of file sendSESEmailBulk.py.

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

Variable Documentation

format

tuple sendSESEmailBulk.format

Initial value:

= ("[%(levelname)-5s] %(asctime)-15s ({}|%(funcName)s|%(lineno)d) "
        ":: %(message)s").format(__file__)

Definition at line 47 of file sendSESEmailBulk.py.

USAGE_HELP

tuple sendSESEmailBulk.USAGE_HELP

Initial value:

=  ("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]")

Definition at line 56 of file sendSESEmailBulk.py.