Setting up your Email Provider

The public application services often need to send emails as part of their respective flows. To do this, a public email provider must be configured for the application. This is email provider that the public services will use when dispatching emails as part of a public flow.

On this page, we cover a few convenience methods that are available to test your email provider as well as send emails straight away. This page assumes that you are already familiar with email providers. If you'd like to read more about email providers, please read up on Email Provider

To work with these methods, you first need to have an Create new Application Keys data store instantiated that will be used to store data for your mobile/web application. You can instantiate this through the Cloud CMS console or you can do so programmatically. Once you've done so, you will need to configure the application instance to have the following property:

public.emailProviderId - The ID of one of your platform's email providers that should be used to send emails.

Sample configuration

The following JSON can be appended into your Application JSON (which you can edit within the Cloud CMS console). Or you can edit your application and enter these values via a form.

{
    "public": {
        "userDomainId": "primary", // either "primary" or a domain ID
        "emailProviderId": "{Email Provider GUID}"
    }
}

API Methods

Below we cover step-by-step how to use the API methods to complete a "forgot username" flow. For technical details on using the public application services API, please see the Public Application Services API.

Test your Email Provider

Once you've created your email provider and configured it with connectivity information to your email server, you will want to test to ensure that it is properly set up. Cloud CMS can perform a test connection to your email server and send a test email. If you receive this email, then you know your email provider is working.

To test your email provider, you make a call to Cloud CMS:

POST /pub/applications/{applicationId}/emailprovider/test?from={from}&to={to}

You need to specify the ID of your Application instance (applicationId) in the path to the method. You also need to provide the email address that the email will come (from) as well as specify the recipient that the email will be sent (to).

Here is an example that uses jQuery:

// the application
var applicationId = "GUID1";

// from and to
var from = "tom@tom.com";
var to = "jerry@jerry.com";

// test the email provider
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "url": "/pub/applications/" + applicationId + "/emailprovider/test?from=" + from + "&to=" + to
});

If the email provider is configured correctly, the recipient will receive a test email. If there is some kind of problem, you will receive back an error code with some JSON messages that should help you to figure things out.

If you don't get an error and you also don't get an email, then you should check with your email server administrator. This often means that the connectivity to the email server is fine but that something on the email server end prevented the email from being sent. For example, the email server administrator may have rules configured within their server that quarantined your email (based on a non-trusted IP, spam filter, or a scan of the contents of your email).

Finally, you should check your own "spam" or "junk" folders within your email client to ensure that the email wasn't received and then moved based on a filter. If this is the case, you should work with your email server administrator to determine how their spam rules work and optimize your email accordingly.

Send an Email

At times, you will want to send an ad-hoc email that isn't part of a flow. The Cloud CMS public application services let you send either a pre-saved email or create a new email and send it all at once.

To first create an email, you should follow the instructions provided on our section on Send Email. Emails are saved objects. You can create them, edit them, permission them and collaborate on their authorship.

Once you have an email, you can send it like this:

POST /pub/applications/{applicationId}/emailprovider/send?id={emailId}

The email will be sent using the public email provider.

If you want to create and send an email all at once, you can do so by posting the JSON payload for the email definition like this:

POST /pub/applications/{applicationId}/emailprovider/send

The email will be created and then sent right away using the public email provider.

Here is an example of using some straightforward jQuery to create and send an email:

// the application
var applicationId = "GUID1";

// the email definition
var email = {
    "to": "axl@gnr.com",
    "body": "Welcome to the Jungle!",
    "from": "slash@gnr.com"
};

// create and send the email
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "data": email,
    "url": "/pub/applications/" + applicationId + "/emailprovider/send"
});

In either case, be sure to test your email provider ahead of time to ensure that you have it properly configured.

Attachments

You can also include attachments in your emails from cloudcms content. To do this, you must include an _attachments property as part of the payload containing an array of node References. For each of these references, their default attachment will be attached to the resulting email.

// the application
var applicationId = "GUID1";

// from and to
var from = "tom@tom.com";
var to = "jerry@jerry.com";

var body = {
    "_attachments": [
        "node://ref/for/node1",
        "node://ref/for/node2"
    ]
};

// test the email provider
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "url": "/pub/applications/" + applicationId + "/emailprovider/test?from=" + from + "&to=" + to,
    "data": body
});