Hosted authentication

Let EmailEngine handle the email setup flow.

While you can always register new accounts using the EmailEngine's API, you could also let EmailEngine handle the entire email setup flow.

In that case, you would redirect your users to your EmailEngine installation, where they'd see an email server setup form. Once they have completed that form and EmailEngine has registered their settings, that user will be redirected back to your application.

How does it work?

Your application generates a signed URL against your EmailEngine's installation that includes the general account information (account id, name) about the user to be added.

Then you redirect your user to that URL, and EmailEngine takes over by showing the forms you can see above.

Once the user has finished setting up their email account, EmailEngine redirects that user back to your application. You can start making API requests against the user's email account.

Example

The following Node.js example script generates a URL for the authentication form.

const crypto = require('crypto');

// The "Service secret" value from the Service configuration page
const serviceSecret = 'eb1824b36ac5e133edd86993bbbc55dc';
// Some random unique string that matches the account in your system
const accountId     = 'account_id';
// The name of the user
const accountName   = 'Full Name';
// Where to redirect once email account is registered
const redirectUrl   = 'https://my.app.example.com/account/added';
// URL to EmailEngine
const emailEngineBaseUrl = 'http://127.0.0.1:3000';

// Set up payload for signing
let data = Buffer.from(
    JSON.stringify({
        account: accountName,
        name: accountName,
        redirectUrl
    })
);

// Sign the payload
let hmac = crypto.createHmac('sha256', serviceSecret);
hmac.update(data);
let signature = hmac.digest('base64url');

// Build the URL
let url = new URL(`accounts/new`, emailEngineBaseUrl);
url.searchParams.append('data', data.toString('base64url'));
url.searchParams.append('sig', signature);

// Form URL is now ready to be used
console.log(url.href);