Skip to content

Latest commit

 

History

History
169 lines (137 loc) · 5.68 KB

README_bpmailer.md

File metadata and controls

169 lines (137 loc) · 5.68 KB

bpmailer

The bpmailer tool, part of the bpbroker suite, facilitates easily adding emailing customers and support personnel as part of an application installation. As with all items in the bpbroker toolset, this is cross-platform and designed as a drop-in tool to decrease the complexity of deployments by providing a standard set of success oriented tools.

Contents

Installing

See bpbroker installation.

Usage

> bpmailer
usage: bpmailer [-h] --config CONFIG --to TO_ADDR --subject SUBJECT
                --template TEMPLATE [--from FROM_ADDR] [--css CSS]
                [--variables VARIABLES] [--html]

> bpmailer --help
usage: bpmailer.py [-h] --config CONFIG --to TO_ADDR --subject SUBJECT
                   --template TEMPLATE [--from FROM_ADDR] [--css CSS]
                   [--variables VARIABLES] [--html]

bpmailer tool

optional arguments:
  -h, --help            show this help message and exit
  --config CONFIG, -c CONFIG
                        Path to non-default configuration file
  --to TO_ADDR          Destination email address
  --subject SUBJECT     Email subject
  --template TEMPLATE   Path to mail template file
  --from FROM_ADDR      Source email address
  --css CSS             Path to optional css files not referenced in template
  --variables VARIABLES
                        Path to optional key=value variables files or '-' for
                        stdin.
  --html                Instead of mailing write HTML to stdout

Configuration

Configuration can be made through any combination of the following methods in increasing order of priority.

  • Hardcoded defaults
  • json configuration file
  • Environment variables
  • Command line options

Hardcoded Defaults

The following defaults are embedded within the tool:

{
    "_bpmailer":  {
		"mail_from_address": "bpmailer@`hostname`",
        "smptp_server": "127.0.0.1",
        "smtp_port": 25,
        "smtp_user": "",
        "smtp_password": ""
    }
}

Configuration File

This format is compatible with the bpbroker configuration file and both tools can use the same configuration. See Example bpmailer_config.json also shown below:

{
	"_bpmailer":  {
		"mail_from_address": "[email protected]",
		"mail_cc_addresses": ["[email protected]","[email protected]"],

		"smtp_server": "127.0.0.1",
		"smtp_port": 25,
		"smtp_user": "",
		"smtp_password": ""
	}
}

Disable SMTP authentication by removing or unsetting the smtp_user key.

Available environment variables

The following environment variables are interpreted:

  • MAIL_FROM_ADDRESS
  • MAIL_CC_ADDRESSES
  • SMTP_SERVER
  • SMTP_PORT
  • SMTP_USER
  • SMTP_PASSWORD
  • MAIL_FROM_ADDRESS

Variable Substitution

Key/Value pairs passed into the bpmailer tool are substituted for variable placeholders within the html message file to support content customization.

Variable input via either stdin (specified as -) or a file specified in the --variables parameter.

Variables formated as key/value pairs with a newline seperating each. A single value can span multiple lines but the next variable must start on a new line. For example:

# correct
foo=bar

# correct
foo=bar
foo2=bar2
extra line

# incorrect
foo=barr foo2=bar2

Quickstart Example

Example execution by passing variables through stdin on Linux using a HERE document. Variables can be read via a file or specify - for stdin (as shown below).

> bpmailer --config bpmailer.json  --to [email protected] --subject "Test Message" \
           --template examples/bpmailer_example_message_template \
           --css examples/bpmailer_example_css --from "John Smith <[email protected]>" --variables - <<HERE
NAME=xxxx
foo=bar
HERE

Results in the following email:

example_email

Starting from the email message and css inside the examples directory will deliver a good multi-client experience. This template is based on the ZURB responsive email templates. bpmailer includes a css inliner to easy flexibility and decrease time to implement.

Using bpmailer inside your CenturyLink Cloud Blueprints

Assume the following scenario

You are an ISV distributing a new database engine. You have developed a CenturyLink Cloud Blueprint package and a demo application so potential customers can easily test your application.

Your application takes a few minutes to populate with data which means an "application ready state" and the initial automated installation occur asynchronously. To make using this demo application as easy as possible you want to tell the customer how to access it (the IP address and any initial credentials) and provide some example test queries. To increase conversion rate you want to send this tailored message exactly when the application is ready to test.

Include a bpmailer configuration file with your installation package that points towards your SMTP relay:

{
	"_bpmailer":  {
		"smtp_server": "relay.t3mx.com",
		"smtp_user": "username",
		"smtp_password": "password"
	}
}

After the data load is complete append the following lines to the end of your bash installation script:

> echo IP_ADDRESS=192.168.1.1 | bpmailer --config isv_custom.json  --to [email protected] \
                                         --subject "Database Ready for Testing" \
                                         --template isv_message_template \
										 --from "ISV Inc <[email protected]>" --variables -