Skip to main content

Configure an SMTP Server for Email Notifications

Zuora

Configure an SMTP Server for Email Notifications

Zuora offers the following methods to sending email notifications to your subscribers

  • Zuora default email server
  • External SMTP server
  • Advanced SMTP server

See the following sections for more information about each method.

Zuora default email server

It is the out-of-the-box, quick, and scalable solution allowing Zuora to send emails on behalf of your organization. 

Ensure that a valid email address is entered in the Email field in your tenant profile (Administration Settings > Manage Tenant Profile). The email address is used as the mail.from value for notifications.

External SMTP server

You can use your own SMTP server to send email notifications instead of using Zuora's default email server. The benefits for using your own SMTP server include:

  • More control over emails delivered to your customers because messages are sent through your own server
  • Ability to access sent email records through your SMTP server logs
  • No need to whitelist Zuora email servers because messages are sent through your own server

Note: Zuora recommends systems like Pendula (Zuora partner), Amazon SES, Sendgrid, MailJet or Zuora's provided email relay solution that offer larger throughputs on email relay. If you use Google or Microsoft email relay service, you might reach their service limits with Zuora's bulk invoice, payment and account statement processed notification events. Refer to Gmail sending limits and Microsoft 365 message rate limits and throttling for details.

Prerequisites

  • Ensure that your SMTP server relay feature is turned on. Otherwise, any emails sent with a mail.from address in the notification that is different from your SMTP server default will fail.
  • If you use the Gmail SMTP server, you might need to generate an application-specific password for your account. Otherwise, you will get an error against the invalid password.

Configure external SMTP server

  1. Navigate to Administration Settings > External SMTP.
  2. Click edit in the External SMTP Server Configuration Settings section and complete the configuration fields.
  3. Configure the required fields. See External SMTP Configuration Fields for more information.
  4. Click test connection and save when the fields are complete.
    The data is saved if the connection is successful. If an error occurs, the configuration information is not valid and an error message appears.
  5. Click edit in the first section of the page.
  6. In the Deliver E-Mail Notifications Using dropdown list, select External SMTP Server.
  7. Click save.

External SMTP Configuration Fields

The following table provides descriptions of the configuration fields and indicates whether they are required when you are setting up an external SMTP server (without DKIM authentication). The section that follows this table provides example configurations.

Field Required? Description

SMTP Server Name

Required

Host name of your SMTP server.

SMTP Port

Required

The port that Zuora uses to connect to the SMTP server.

Authentication Required

The authentication scheme for the SMTP server. The following schemes are available:

  • Username/Password
  • OAuth 2.0

SMTP Enable StartTLS

Optional

Set to true if the SMTP server attempts to upgrade to an encrypted connection (TLS or SSL) before authentication.

Default is false.

SMTP User Name

Required

The email address of the sender.

Password

Required only if Authentication is set to Username/Password

Your password for the SMTP server.

OAuth2.0 Provider Required only if Authentication is set to OAuth 2.0

The OAuth 2. 0 provider you created in Administration Settings > Manage OAuth 2.0 Providers

To create a new OAuth 2.0 provider, see Add an OAuth 2.0 provider for more information.

SMTP SocketFactory Port

Required only if you specify the SMTP SocketFactory Class

If specified, Zuora uses this port to send email to the SMTP server. Otherwise, Zuora uses the SMTP Port.

SMTP SocketFactory Class

Optional

Set to javax.net.ssl.SSLSocketFactory if the SMTP server uses this class to create SSL sockets.

SMTP SocketFactory Fallback

Optional

Set to true if the SMTP server tries to create a socket using a different class if the specified SMTP SocketFactory Class fails.

Default is true.

Common error messages

After entering your SMTP server configuration details and clicking test connection and save, you may get an error message. The following table provides some common error messages and actions you can take to resolve the issue.

Error Message Recommended Action

Unknown SMTP host

Check that the SMTP Server Name is correct.

Could not connect to SMTP host

Check that the SMTP Port is correct. If the port is correct, the SMTP server might be experiencing a temporary issue. Wait a few minutes and try again.

Connect timed out

Authentication failed: Bad username / password

Check whether your username and password are correct.

Authentication failed

Check whether your username and password, or OAuth 2.0 provider configuration are correct.

Authentication required

Check if you have configured the Authentication field.

Read timed out

Check that you have entered the correct values for the following fields:

  • SMTP SocketFactory Port
  • SMTP SocketFactory Class
  • SMTP SocketFactory Fallback

Could not convert socket to TLS

Advanced SMTP server

Zuora also supports sending emails using DomainKeys Identified Mail (DKIM) through Amazon Simple Email Service (SES), allowing you to comply with Domain-based Message Authentication, Reporting and Conformance (DMARC). You must set up an advanced SMTP server in Zuora and go through the verification processes. For more information about DKIM in Amazon SES, see Authenticating Email with DKIM in Amazon SES.

Prerequisites

  • Ensure that the corresponding CNAME records are added to your domain's DNS records. How you update the DNS settings depends on who provides your DNS service. If your DNS service is provided by a domain name registrar, contact that registrar to update your DNS records. Note that verification of these settings might take up to 72 hours to take effect in Zuora.
  • For security purposes, Zuora only allows for identity types that can be actively identified in your Zuora tenant. For example, an email identity must exist as an active user in your Zuora tenant, and a domain identity must match a domain of an active user in your Zuora tenant. Therefore, if the intended email entities or domain entities do not have the corresponding active users in Zuora, you must set up the users and activate them before configuring the advanced SMTP server.

Configure advanced SMTP server

  1. Navigate to Administration Settings > External SMTP.
  2. Click edit in the Advanced SMTP Server Configuration Settings section. 
  3. Configure the required fields. See Advanced SMTP Configuration Fields for more information.
  4. Click save.
  5. Click edit in the first section of the page.
  6. In the Deliver E-Mail Notifications Using dropdown list, select Advanced SMTP Server.
  7. Click save.

Advanced SMTP Configuration Fields

The following table provides descriptions of the configuration fields and indicates whether they are required when you are setting up an advanced SMTP server.

Field Required? Description

New Entity Type

Required

The entity type of the SMTP server. The following types are available:

  • Domain Identity
  • Email Identity

For security purposes, Zuora only allows for identity types that can be actively identified in your Zuora tenant. For example, a defined email identity must exist as an active user in your Zuora tenant, and a domain identity must match a domain of an active user in your Zuora tenant.

Add New Identity Required

If you selected Domain Identity, enter the domain that needs to be verified. For example, subscriptioncompany.com. With a domain verified, all email addresses from this domain are verified and you do not need to verify individual email addresses from this domain.

If you selected Email Identity, specify an email address. For example, dummyname@subscriptioncompany.com. Up to 3 individual email addresses are allowed. Amazon SES requires that you verify your identities (the domains or email addresses that you send email from). Therefore, you or specified users will go through a verification process after you have saved the configuration. After you or specified users complete the verification process, the Verification Status and DKIM Status are updated for the corresponding identity in the Advanced SMTP Server Configuration Settings section.

For more information, see Verifying identities in Amazon SES.