Email Provider

Type emailProvider
Datastore Type application
Supports authorities, permissions, transfer

Configuration

Email Providers 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
host text The host address of the email server.
Example: smtp.gmail.com
port number The connection port on the email server.
Example: 25
username text The username to use for authentication (if required).
password text The password to use for authentication (if required).
smtp_enabled boolean Whether SMTP is enabled.
smtp_requires_auth boolean Whether the mail server requires authentication.
smtp_is_secure boolean Whether to connect to the mail server via secure socket.
smtp_starttls_enabled boolean Wheter START_TLS is enabled.

Create an Email Provider

You can create as many email providers as you'd like. You will need to reference these email providers when you choose to send or receive email.

Here's a simple example where we create an email provider:

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

// create an email provider
application.createEmailProvider();

Here's a full example for Google Mail:

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

// authentication
var username = "user@gmail.com";
var password = "password";

// create an email provider
application.createEmailProvider({
    "host": "smtp.gmail.com",
    "username": username,
    "password": password,
    "smtp_enabled": true,
    "smtp_requires_auth": true,
    "smtp_is_secure": true,
    "smtp_starttls_enabled": true
});

Update an Email Provider

To update, all you have to do is make changes to your Email Provider and fire away.

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

// authentication
var username = "user@gmail.com";
var password = "password";

// create an email provider
application.createEmailProvider({
    "host": "smtp.gmail.com",
    "username": username,
    "password": password,
    "smtp_enabled": true,
    "smtp_requires_auth": true,
    "smtp_is_secure": true,
    "smtp_starttls_enabled": true
}).then(function() {

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

});

Delete an Email Provider

It doesn't get much simpler than this:

emailProvider.del();

Read an Email Provider

You can read a Email Provider by its _doc ID field.

// email provider id
var emailProviderId = "4b5b685c980c10f98beb";

application.readEmailProvider(emailProviderId).then(function() {
    console.log("Found email provider: " + this.getId());
})

List Email Providers

You can retrieve a list of Email Providers for your platform quite easily. The following code hands back the full list.

application.listEmailProviders();

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

application.listEmailProviders().each(function() {
    console.log("Email Provider: " + 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.

application.listEmailProviders({
    "limit": 10,
    "skip": 20,
    "sort": { "title": -1 }
}).each(function() {
    console.log("Email Provider: " + 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 Email Providers

You can run custom queries against your Email Providers to find exactly what you're looking for. Here is a query that looks for Email Providers that point to the host smtp.gmail.com.

application.queryEmailProviders({
    "host": "smtp.gmail.com"
});

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

application.queryEmailProviders({
    "host": "smtp.gmail.com"
}).each(function(id) {
    console.log("Found an Email Provider: " + id);
});

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.

application.queryEmailProviders({
    "host": "smtp.gmail.com"
},{
    "limit": 10,
    "skip": 20,
    "sort": {
        "title": -1
    }
}).each(function(id) {
    console.log("Found an Email Provider: " + id);
});