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/rdb2-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.util.column(column_name)
Rdbhost.util.fixed(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 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 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.util.fixed('special title'),
              Rdbhost.util.column('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.

Demo

A working demo is at JsDemos

Supporting Files

If you write the emailing functions into your JavaScript and test, the JavaScript module should create and populate all necessary tables and other resources interactively as you test. If you want to manually create them, here is the apikeys definition:

--
-- Name: apikeys; Type: TABLE; Schema: auth; Owner: s0000000014; Tablespace:
--

CREATE TABLE auth.apikeys (
  service character varying(10),
  apikey character varying(100),
  webmaster_email character varying(150),
  account_email character varying(150)
);

ALTER TABLE auth.apikeys OWNER TO <super role>;
				

Relevant Blog Posts