RDB2JS Emailing

Emailing module for the RdbHost JavaScript V2 library.
The library can be loaded with a script tag, like:

<script src="https://www.rdbhost.com/vendor/rdbhost/2.1/lib/js/rdbhost-bundle.js"></script>
<script src="https://www.rdbhost.com/vendor/rdbhost/2.1/lib/js/rdb2-emailing.js"></script>

A more performant way is to include it in the LAB.JS config:

<script> var $L = $LAB.script('/vendor/rdbhost/2.1/lib/js/rdb2-emailing.js')</script>

To send an email, you need an account on one of the emailing web services.

The Rdbhost.Email object

This module extends the Rdbhost global with an object Rdbhost.Email, which is an extension of the Rdbhost object, containing all of its methods, plus a few for Emailing functionality.

Where you would have used Rdbhost.preauth(), use Rdbhost.Email.preauth() instead.

Emailing

To send an email, you use one of the email methods, and optionally the query method. The email methods are email, email_host, and email_user.

Emailing Methods:

email(from, from_email, to, to_email, subject, body, body_html,  attachments);

email_host(from, from_email, subject, body, body_html, attachments);

email_user(to, to_email, subject, body, body_html, attachments);

These methods are on the request object, as returned by Rdbhost.Email.preauth(), or any of the other request object constructors.

attachments is undefined or an object, where attribute names are file names, and attribute bodies are the file bodies. The other parameters are strings or undefined. The to_email, from_email, subject fields are required.

Configuration Methods

Rdbhost.Email.email_config(host, host_email, service)

service is postmark, or mailgun for the webservice you are using. The host and host_email are a name and email-address (yours, perhaps) for the email_host method.

Parameter Methods:

Rdbhost.Email.column_wrapper(column_name)
Rdbhost.Email.fixed_wrapper(string)

Explaining these parameter methods takes some context: If you just pass strings as parameters to the emailing methods, the email method creates an SQL query with each value parameterized. The query gets a substitution-token inlined, and the value is passed as an argument.

Sometimes you want the value itself inlined, so the value itself becomes part of the whitelisted query. If you wrap the value in the fixed_wrapper method, the value gets interpolated into the query instead of being parameterized.

Sometimes the values for the fields come from a database, rather than as literals. The SQL passed in the query method will retrieve the values, and each value included in the email using column_wrapper method wrapping the column name.

When using the query method, the query can return multiple records, which will result in multiple emails. Each record must include an idx field. The idx field should be unique per record, so you can identify which result row results from each record.

The Emailing functionality is in the Email element of Rdbhost.

Look at an example:

// registers name and email as recipients of email_host email
Rdbhost.Email.email_config('President', 'pres@example.net', 'postmark');

// The subject line is hard coded into the query, and the email body comes from a table.
var spr = Rdbhost.Email.preauth()
  .query("SELECT 1 AS idx, body FROM lookup.emails; ")
  .email_host('David', 'dkeeney@rdbhost.com',
              Rdbhost.fixed_wrapper('special title'),
              Rdbhost.column_wrapper('body'));

spr.then(function(d) {
    alert('email sent successfully');
});

The server sends one email for each row returned by the query.

The email methods return promises. Each promise resolves with a list of rows that indcate 'SUCCESS' or error for each email attempt.

The first time you run each query as preauth, the library will have you confirm the white-listing of the query.