search
how tos

Configure SMTP Email

ForgeRock lets you set up the outgoing (SMTP) email server of your choice through the Express console or over REST.

Prerequisites

Before you can configure an SMTP server, you’ll need to enable the following API Scopes, through the Express console:

Activate all email-server-config API scopes

You can add these scopes over REST. Add these scopes to the apiScopes data in the REST calls for the desired app (Native/SPA, Web, Service), as described in our API Documentation.

For more information, see our discussion on Scopes.

You’ll also need the following information to set up a connection between ForgeRock Identity Cloud Express and your SMTP server:

Property Description
Host The hostname or fully-qualified domain name (FQDN) of your SMTP server; an IP address is acceptable
Port The port number associated with your SMTP server
Username The username required to authenticate with the SMTP server
Password The password required to authenticate with the SMTP email server
mandatoryTLS If true, requires TLS; if false, defaults to Opportunistic TLS

When “mandatoryTLS”=false, Use OpportunisticTLS (STARTTLS)

Many email providers don’t allow the use of port 25, as that port is associated with transmission of emails in plain text. However, you can secure your SMTP servers with OpportunisticTLS. Many administrators implement OpportunisticTLS with the STARTTLS command described in RFC 3207.

We strongly encourage the use of Mutual TLS authentication (mTLS). This reduces risk when one-time passcodes are emailed.

Configuring An Outgoing Email Server Through the Express Console

To configure an outgoing SMTP server through the Express console, follow these steps:

  1. Sign-in as a team member.
  2. Navigate to Email > Provider.
  3. Activate the Use my own email provider option.
  4. Enter information as described earlier in this page for host, port, username, and password.

For security, we also strongly encourage you to activate the Use TLS option. When you’ve made your entries, select Save.

To test the result, select the Send Test Email button, or run the following REST call:

content_copy COPY

curl 'https://api-{tenant_name}.forgeblocks.com/v1/email' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d '{
    "templateId":"{template_id}",
    "userId":"{user_id}"
}'

The button sends an email with the Welcome template described in the section on Email Templates.

Configuring An Outgoing Email Server Over REST

The following REST call will return details of all configured outgoing email servers.

content_copy COPY

curl -X GET \
https://api-{tenantName}.forgeblocks.com/v1/email-server \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' 

If there’s an existing custom SMTP server, you’ll see output in the following format:

{
    "host": "hostnameOrIPAddress",
    "port": somePortNumber,
    "username": "someUsername",
    "mandatoryTLS": true
}

You can use the same properties that you can use when configuring a connection from Express to your outgoing email server. Of course, when including SMTP account information, you’ll need to include a password. Express does not include the password in the REST output.

content_copy COPY

curl -X PUT \
https://api-{tenantName}.forgeblocks.com/v1/email-server \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' 
-d {
    "host": "hostnameOrIPAddress",
    "port": somePortNumber,
    "username": "someUsername",
    "password": "correspondingPassword",
    "mandatoryTLS": true
}

To modify the outgoing email server, you’d use the same REST call.

We’ve included these outgoing email server (SMTP) REST calls in our Postman collection, available at https://developer-api.forgerock.com.


If you have questions email [email protected].