Email

Type email
Datastore Type application
Supports authorities, permissions, transfer

Configuration

Emails maintain a configuration that you can adjust or consult as you create, update and query for them.

The following table presents you the configuration properties.

Property Type Default Read-Only Description
to text The email addresses of the recipients (comma-delimited)
body text The body of the email.
from text The email address of the sender.
subject text The subject of the email.
cc text The email addresses to be carbon-copied (CC) (comma-delimited)
bcc text The email addresses to be blind carbon-copied (BCC) (comma-delimited)
replyTo text The reply-to email address.
sent boolean Whether the email was sent.
sentBy text Who sent the email.
sentOn timestamp When the email was sent.

In addition, the email service optionally allows you to dispatch emails to Domain Users or Domain Groups. Domain Users have their own email fields which will determine the address to which the email is sent.

If you send to a Domain Group, all direct members of the group will receive the email.

Property Type Default Read-Only Description
toDomainId text If you wish to send this email to a specific domain principal, this points to the principal's domain.
toPrincipalId text If you wish to send this email to a specific domain principal, this points to the principal.

Emails can also utilize the contents of a Repository Node to load its body. This allows you to store and collaborate upon email templates within a Branch.

Property Type Default Read-Only Description
bodyRepositoryId text The _doc ID of the repository.
bodyBranchId text The _doc ID of the branch.
bodyNodeId text The _doc ID of the node.
bodyAttachmentId text The name of the attachment (example: default)

Create an Email

When you create an email, it gets stored within Cloud CMS. You can make adjustments to the email as you see fit. You can then send it at some point in the future.

Here is a simple example where we create a basic email:

// assume we have an application
var application = ...;

// create an email
application.createEmail({
    "to": "axl@gnr.com",
    "body": "Welcome to the Jungle!",
    "from": "slash@gnr.com"
});

Update an Email

You can update properties on an email:

// assume we have an application
var application = ...;

// create an email
application.createEmail({
    "to": "axl@gnr.com",
    "body": "Welcome to the Jungle!",
    "from": "slash@gnr.com"
}).then(function() {

    this.set("title", "My First Email");
    this.update();

});

Delete an Email

You can delete emails just as you would any other object. However, if an email has already been sent, deleting it will not cause the email to be unsent (that much should be obvious).

email.del();

Read an Email

You can read an Email by its _doc ID field.

// assume we have an application
var application = ...;

// email id
var emailId = "4b5b685c980c10f98beb";

application.readEmail(emailId).then(function() {
    console.log("Found an email with id: " + this.getId());
});

List Emails

You can retrieve a list of Emails for your application. The following code hands back the full list.

// assume we have an application
var application = ...;

application.listEmails();

You can then iterate over the list to pick at what you'd like.

// assume we have an application
var application = ...;

application.listEmails().each(function() {
    console.log("Email: " + this.getId());
});

Retrieving the full list is potentially an expensive operation, depending how many items you have. The more your retrieve, the more data goes over the wire and so forth. Thus, you might wish to paginate your call and retrieve a subset of the total list at a time.

Here is an example that retrieves in pages of size 10. It starts on the second page (by skipping to starting index 20). It also sorts by the title field in a descending sequence.

// assume we have an application
var application = ...;

application.listEmails({
    "limit": 10,
    "skip": 20,
    "sort": { "title": -1 }
}).each(function() {
    console.log("Found an email with ID: " + this.getId());
});

You don't have to have all of the pagination parameters (limit, skip and sort). You might only want to include one or two. It's up to you.

Query Emails

You can run custom queries against your Emails to find exactly what you're looking for. Here is a query that looks for Emails which are disabled.

// assume we have an application
var application = ...;

application.queryEmails({
    "from": "dizzy@gnr.com"
});

Here is that same query followed by an iteration over the result map.

// assume we have an application
var application = ...;

application.queryEmails({
    "from": "dizzy@gnr.com"
}).each(function(id) {
    console.log("Found an Email: " + id + " with body: " + this.get("body"));
});

Finally, you can mix queries with pagination to reduce data over the wire and speed up performance. Here is that same query with some pagination thrown in. We limit to pages of size 10 and sort by title.

// assume we have an application
var application = ...;

application.queryEmails({
    "from": "dizzy@gnr.com"
},{
    "limit": 10,
    "skip": 20,
    "sort": {
        "title": -1
    }
}).each(function(id) {
    console.log("Found an Email: " + id + " with body: " + this.get("body"));
});

Send an Email

If you've created an Email Provider and an Email, you can then send the email by identify the email provider.

// assume we have an application
var application = ...;

// assume we have an email provider
var emailProvider = ...;

// create an email
application.createEmail({
    "to": "axl@gnr.com",
    "body": "Welcome to the Jungle!",
    "from": "slash@gnr.com"
}).then(function() {

    // send the email using the email providera
    this.send(emailProvider);

});