Skip to content

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.

    from_address= "[email protected]"
    username= "wso2iamtest"
    password= "Wso2@iam70"
    hostname= ""
    port= 587
    enable_start_tls= true
    enable_authentication= true
    signature = ""
    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.


    For information about the SMTP, see here.


    • 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.


    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.


    • 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


    mail.smtp.user User Name for the sender smtp server

    Password for the sender smtp server


    Port of the sender smtp server

    mail.smtp.from From email address of the smtp server 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="">
        <from streamName="id_gov_notify_stream" version="1.0.0"/>
        <mapping customMapping="enable" type="text">
        <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>
  6. Since these configurations will be applicable during the tenant loading process, configure tenant loading and unloading for your tenant.