Configure the Email Sending Module¶

This document explains the steps to configure WSO2 Identity Server to send emails during multiple email-related customer identity and access management tasks such as email OTP, email notifications, and account recovery.

Configure the email sender (globally)¶

Follow the steps given below to enable the email sender globally for all tenants in your WSO2 IS.

1. Shut down the server if it is running.

2. Add the following properties to the deployment.toml file in the IS_HOME/repository/conf folder to configure the email server.

   [output_adapter.email]
   from_address= "[email protected]"
   username= "wso2iamtest"
   password= "Wso2@iam70"
   hostname= "smtp.gmail.com"
   port= 587
   enable_start_tls= true
   enable_authentication= true
   signature = "ABC.com"

   Property	Description
   from_address	This is the mail address from where you want to send the notification. It can be any working mail address.
   username	Provide the username of the SMTP account. Username of the mail you have provided in from_address.
   password	Provide the password of the SMTP account. Password of the mail you have provided in from_address.
   host	The SMTP server to connect to.
   port	This is the SMTP server port to connect to if the connect() method does not explicitly specify one. Defaults to 25.
   enable_start_tls	If true, this enables using the STARTTLS command (if enabled before issuing any login commands. Note that an appropriate trust store must be configured so that the client will trust the server's certificate. Defaults to false.
   enable_authentication	If true, attempt to authenticate the user using the AUTH command. Defaults to false.
   signature	Signature of the sender account.

   Tip

   For information about the SMTP, see here.

   Info

   • If you use a Gmail account as the from_address, you must create an App Password. After you get an App Password from Google, update the password.
   • If your password contains special characters (example: <, >, &), you will run into errors when running the server. To avoid errors, update the password parameter as follows:

     password= "<![CDATA[xxxx]]>"

3. Save the configurations and start the server.

Configure the email sender (per tenant)¶

Follow the steps given below to enable the email sender per tenant.

1. Configure the Configuration Management REST API.

2. Execute the following curl command to create a resource type named Publisher.

   Sample Request

   curl -X POST "https://localhost:9443/t/{tenant-domain}/api/identity/config-mgt/v1.0/resource-type" -H "accept: 
   application/json" -H 
   "Content-Type: application/json" -H 'Authorization: Basic YWRtaW46YWRtaW4=' -d "{ \"name\": \"Publisher\", \"description\": \"Publisher Configurations\"}"

3. Execute the following curl command for creating a resource named EmailPublisher.

   Sample Request

   curl -X POST "https://localhost:9443/t/{tenant-domain}/api/identity/config-mgt/v1.0/resource/Publisher" -H "accept: 
   application/json" -H "Content-Type: application/json" -H 'Authorization: Basic YWRtaW46YWRtaW4=' -d "{ \"name\": \"EmailPublisher\", \"attributes\": [ { \"key\": \"email\", \"value\": \"string\" } ]}"

4. Execute the following curl command for creating a file named EmailPublisher.

   Info

   This EmailPublisher.xml file will be used as the tenant's email publisher file. Configure the tenant-wise email configurations in the EmailPublisher.xml file.

   Sample Request

   curl -X POST "https://localhost:9443/t/{tenant-domain}/api/identity/config-mgt/v1
   .0/resource/Publisher/EmailPublisher/file" -H "accept: application/json" -H 
   "Content-Type: multipart/form-data" -H 'Authorization: Basic YWRtaW46YWRtaW4=' -F "[email protected];type=text/xml" -F "fileName=EmailPublisher"

5. Open the EmailPublisher.xml file and configure the parameters given below.

   Note

   • Only one EmailPublisher.xml file with the name EmailPublisher should be added to a tenant.
   • You do not need to configure all the configurable parameters. If a parameter has not been configured in the EmailPublisher.xml file, configurations in the output-event-adapters.xml will be used instead.

   Property name	Description
   mail.smtp.user	User Name for the sender smtp server
   mail.smtp.password	Password for the sender smtp server
   mail.smtp.port	Port of the sender smtp server
   mail.smtp.from	From email address of the smtp server
   mail.smtp.host	Host name of the smtp server
   mail.smtp.auth	Password hash method to use when storing user entries in the user store.
   mail.smtp.starttls.enable	Property to enable STARTTLS support for JavaMail
   mail.smtp.replyTo	Reply to address of smtp server
   mail.smtp.signature	Signature for the sender account

   Following is a sample configuration for the EmailPublisher.xml file.

   <?xml version="1.0" encoding="UTF-8"?>
   <eventPublisher name="EmailPublisher" statistics="disable"
       trace="disable" xmlns="http://wso2.org/carbon/eventpublisher">
       <from streamName="id_gov_notify_stream" version="1.0.0"/>
       <mapping customMapping="enable" type="text">
       <inline>{{body}}{{footer}}</inline>
       </mapping>
       <to eventAdapterType="email">
       <property name="email.address">{{send-to}}</property>
       <property name="email.type">{{content-type}}</property>
       <property name="email.subject">{{subject}}</property>
       <property name="mail.smtp.password">xxxxx</property>
       <property name="mail.smtp.from">[email protected]</property>
       <property name="mail.smtp.user">resourcesiam</property>
       </to>
   </eventPublisher>

6. Since these configurations will be applicable during the tenant loading process, configure tenant loading and unloading for your tenant.