Account

Generate authentication link

Generates a redirect link to the hosted authentication form<br/><br/>An IMAP setup completes without asking the user for mail server settings whenever EmailEngine can discover and verify them from the address and password alone. Set skipServerSettings to false to always show that step.<br/><br/>If expectedEmail is set and the user completes the form as a different identity, the setup is rejected before any credentials are stored. The user stays on EmailEngine, which names both addresses and offers to restart the setup, so the browser is never redirected to redirectUrl.

post/v1/authentication/form

Request

  • Base URL: https://your-emailengine-host
  • URL: https://your-emailengine-host/v1/authentication/form
  • Auth: HTTP bearer

Headers

x-ee-timeoutinteger

Request timeout in milliseconds. Raises the command timeout above the EENGINE_TIMEOUT default for a long-running request; a value below the default has no effect

Example:30000

Request body

accountstring nullable

Account ID. If set to null, a unique ID will be generated automatically

namestring

Display name for the account

emailstring

Specifies the default email address for this account. Users can change it if needed.

expectedEmailstring

Pins the account to an email address

delegatedboolean

If true, configures this account as a shared mailbox. Currently supported by MS365 OAuth2 accounts

skipServerSettingsboolean

If true, the mail server settings step is skipped whenever the IMAP and SMTP settings for the address can both be discovered and verified with the password the user enters. The step is still shown if discovery or verification does not fully succeed. Set to false to always ask the user for the server settings. Applies to the IMAP setup path only.

notifyFromstring date-time nullable

Only send webhooks for messages received after this date. Defaults to account creation time. IMAP only.

subconnectionsstring[]

Additional mailbox paths to monitor with dedicated IMAP connections for faster change detection. Use sparingly as connection limits are strict.

pathstring[] nullable

Mailbox folders to monitor for changes (IMAP only). Use "*" to monitor all folders (default)

redirectUrlstring required

After the authentication process is completed, the user is redirected to this URL

Example request

{
  "account": "example",
  "name": "My Email Account",
  "email": "user@example.com",
  "expectedEmail": "user@example.com",
  "notifyFrom": "2021-07-08T07:06:34.336Z",
  "subconnections": [
    "[Gmail]/Spam",
    "\\Sent"
  ],
  "path": [
    "*"
  ],
  "redirectUrl": "https://myapp/account/settings.php",
  "type": "imap"
}

Response

Returns a single-use URL for the hosted authentication form.

urlstring required

Generated URL to the hosted authentication form

Example response

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

Changes

No recorded changes to this operation across all 1 revision of this API.