Vision
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
- Navigate to Administration Settings > External SMTP.
- Click edit in the External SMTP Server Configuration Settings section and complete the configuration fields.
- Configure the required fields. See External SMTP Configuration Fields for more information.
- 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. - Click edit in the first section of the page.
- In the Deliver E-Mail Notifications Using dropdown list, select External SMTP Server.
- 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:
|
|
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:
|
|
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
- Navigate to Administration Settings > External SMTP.
- Click edit in the Advanced SMTP Server Configuration Settings section.
- Configure the required fields. See Advanced SMTP Configuration Fields for more information.
- Click save.
- Click edit in the first section of the page.
- In the Deliver E-Mail Notifications Using dropdown list, select Advanced SMTP Server.
- 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:
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, If you selected Email Identity, specify an email address. For example, For more information, see Verifying identities in Amazon SES. |