Hosted Authentication

While you can always add new email accounts directly via EmailEngine's API, you also have the option to let EmailEngine take care of the entire setup process. This approach simplifies user interactions and reduces complexity in your application.

With hosted authentication, you direct your users to EmailEngine’s web-based form, where they provide their email server credentials. After successful configuration, EmailEngine stores the account settings and redirects the user back to your application, ready for use.

Note: If you prefer not to use the hosted authentication form but need to manage OAuth2 flows, consider the alternative authentication server feature.

Your application generates a signed URL that links to your EmailEngine installation. This URL includes basic account details (such as account ID and user name) that EmailEngine will use during the setup process.

Once your user is redirected to this URL, EmailEngine handles the rest by displaying the appropriate forms. After successful configuration, the user is redirected back to your application’s designated URL, and you can begin making API calls to interact with their email account.

Important: To display options for Gmail or Outlook accounts, you need to configure these services ahead of time. Follow the specific guides for Outlook OAuth2 and Gmail OAuth2 integration.

The most efficient way to generate a link to the hosted authentication form is by using EmailEngine's API. Here's an example:

curl -X 'POST' \
  'https://ee.example.com/v1/authentication/form' \
  -H 'Content-Type: application/json' \
  -d '{
  "account": "example",
  "name": "My Email Account",
  "email": "user@example.com",
  "redirectUrl": "https://myapp/account/settings.php"
}'

This API request returns a JSON object containing the url field:

{
  "url": "https://ee.example.com/accounts/new?data=eyJhY2NvdW50IjoiZXhh...L0W_BkFH5HW6Krwmr7c"
}

You should then redirect your user to this URL (url value) to display the authentication form.

Redirect URL

Once authentication is successful, EmailEngine redirects the user back to the redirectUrl you provided. It appends two query parameters to this URL:

1. account: The account ID of the registered account. If you provided an account value in the original request, this ID will match it; otherwise, EmailEngine will generate one.
2. state: Indicates whether the account is new ("new") or if an existing account was updated ("existing"). If an existing account was used, its settings are updated, and no new account is created.