Configure an Alternate SMTP Email Relay

The REST APIs provided with Oracle Commerce allows you to use an alternate Simple Mail Transfer Protocol (SMTP) relay to send email messages.

Oracle Commerce provides a default fully managed email service. However, if necessary due to your own corporate policies or needs, you can use an alternative SMTP email relay. When you use your own SMTP Relay, you assume full responsibility for any deliverability concerns. Oracle Commerce’s responsibility in this situation is limited to attempting to deliver the message to your SMTP relay, Deliverability includes making sure your email is not treated as spam as discussed in Ensure emails are not rejected as spam.

When you set up an SMTP email service property, your emailSMTPHost is added to the proxy and SMTP traffic is routed through the proxy so that it can reach your SMTP relay.

Commerce allows you to use the REST API to configure your email service types. For example, if you issue a GET command to the /ccadmin/v1/email endpoint, and you will see the default setting:

GET  /ccadmin/v1/email

"emailServiceProperties":{
    "emailServiceType" : "DEFAULT"
}

The response contains two JSON objects: the emailSerivceProperties that contains the email service settings, and an emailNotificationTypes object, which contains information on the available email types and their site-specific settings. For example:

{
  "emailServiceProperties": {
    "emailServiceType": "DEFAULT"
  },
  "links": [
    {
      "rel": "self",
      "href": "/email"
    }
  ],
  "emailNotificationTypes": {
    "ccadmin_user_password_reset_v1": {
      "recommendationsSupported": false,
      "displayName": "Oracle Commerce Administrator Password Reset",
      "description": null,
      "recommendationsStrategy": null,
      "version": 1,
      "enabled": false,
      "fromEmail": null,
      "recommendationsAllowAnyStrategy": true,
      "recommendationsRestriction": null,
      "fromName": null,
      "recommendationsAllowRestrictions": true,
      "includeRecommendations": false,
      "id": "ccadmin_user_password_reset_v1",
      "recommendationsPermittedStrategies": [],
      "numberOfRecommendations": 12
    },
    "placed_order_v1": {
      "recommendationsSupported": false,
      "displayName": "Order Placed",
      "description": null,
      "recommendationsStrategy": null,
      "version": 1,
      "enabled": false,
      "fromEmail": null,
      "recommendationsAllowAnyStrategy": true,
      "recommendationsRestriction": null,
      "fromName": null,
      "recommendationsAllowRestrictions": true,
      "includeRecommendations": false,
      "id": "placed_order_v1",
      "recommendationsPermittedStrategies": [],
      "numberOfRecommendations": 12
    }
  }
}

Important: Some of the configuration's details are not included in the response for security reasons.

For information on working with email notifications, refer to Enable the types of email your store sends.

Note that the endpoint configuration uses the site context specified using the X-CCSite request header or the occsite query parameter. Omitting the site will display all of the settings for your default site.

To set the SMTP email service type, issue a POST command to the /ccadmin/v1/email endpoint and include the following properties:

• emailSMTPPort - Indicates the port to use when communicating with the SMTP host. The port number should be either 465 or 587 and match the emailSMTPAuthMethod. Note that you can specify an SMTP server in the allowedURLs property by adding its domain name, such as smpt.example.com.
• emailSMTPHost - The SMTP host name.
• emailServiceType - This property is set to either DEFAULT or SMTP.
• emailSMTPAuthMethod - This identifies the authorization method as either SSL or TLS. This property indicates if the authorization method used by your SMTP server uses Secure Sockets Layer (SSL with port 465, legacy) or Transport Layer Security (TLS with port 587, modern).
• emailSMTPUsername - The name used to log into the SMTP server.
• emailSMTPPassword - The user password for the SMTP Server. This field will not be displayed when you issue a GET command.

For example:

"emailServiceProperties":{
        "emailSMTPPort":"587",
        "emailSMTPHost":"smtp.myrelayservice.com",
        "emailServiceType":"SMTP",
        "emailSMTPAuthMethod":"TLS",
        "emailSMTPUsername":"smtpadmin"
        "emailSMTPPassword":"smtpadminpassword"
    }

If you issue a POST command to the /ccadmin/v1/email endpoint without passing in "emailServiceType":"SMTP" an error occurs indicating that you cannot change settings when the email service type is set to DEFAULT. If you do not provide all of the required settings described earlier, you will also get an error.

Once you have issued a POST command to the endpoint with the required properties, all email will switch to use the newly configured SMTP server.

Note that the endpoint configuration uses the site context specified using the X-CCSite request header or the occsite query parameter. Omitting the site applies all of the settings for your default site.

To switch back the email service type to use the default email service, issue a PUT command to the /ccadmin/v1/email endpoint:

PUT  /ccadmin/v1/email

"emailServiceProperties":{
    "emailServiceType" : "DEFAULT"
}

Your SMTP configuration settings will be reset to their default, internal values.