search
how tos

Configure SMTP Email

You can set up your preferred outgoing (SMTP) email server using the Express console or over REST.

Before You Begin

In the Express console, click Applications > App Name > API Scopes.
For the Resource email-server, enable the following API Scopes:

Activate all email-server-config API scopes

For more information about scopes, see Configure Scopes. You can add these scopes over REST. Add these scopes to the apiScopes data in the REST calls for the your preferred app type (Native/SPA, Web, Service). See the Express Postman Collection.

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

Keeping Your SMTP Servers Secure

When “mandatoryTLS”=false, use OpportunisticTLS (STARTTLS).

Many email providers don’t allow the use of port 25 because it’s associated with transmitting emails in plain text. As an alternative, you can secure your SMTP servers with OpportunisticTLS. See OpportunisticTLS and the STARTTLS command described in RFC 3207.

You should also use Mutual TLS authentication (mTLS) to reduces risk when one-time passcodes are emailed.


To use the Express console: Click Email >Provider.

alt text

  1. Enable “Use my own email provider”.
  2. Enter information for host, port, username, and password.
  3. (Optional) Click to check the Use TLS option. This is highly recommended for security purposes.
  4. Click Save.

To test the result, click 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. See Customize Email Templates.



To use the Express REST APIs:

The following REST call returns 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 use when you configure a connection from Express to your outgoing email server. 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, use the same REST call.

These outgoing email server (SMTP) REST calls are included in the Express Postman Collection.

alt text


For questions or feedback, contact us.