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
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 > Manage SMTP Settings.
- 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.
Emails are sent from Zuora using Zuora’s Amazon Simple Email Service account, which alleviates any need for you to directly partner with Amazon. When your subscribers trigger an event, Zuora sends emails to recipients according to the configured notification definition through Amazon's SendRawEmail API operation.
Prerequisites
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 identities or domain identities 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 > Manage SMTP Settings.
- Click Edit in the Advanced SMTP Server Configuration Settings section.
- Create an identity.
- To create a domain identity:
- From the New Identity Type list, select Domain Identity.
- Enter a valid domain name in the Add New Identity field. A domain name is valid only if it matches an active user’s work email domain in your Zuora tenant. For example, if an active user’s email address is
employee@yourcompany.com
, thenyourcompany.com
anden.yourcompany.com
are both valid domain names.
- To create an email identity:
- From the New Identity Type list, select Email Identity.
- Enter a valid email address in the Add New Identity field. An email address is valid only if it matches an active user’s work email domain in your Zuora tenant, regardless of the local-part. For example, if an active user’s email address is
employee@yourcompany.com
, thencontact@yourcompany.com
,employee@yourcompany.com
, andnoreply@en.yourcompany.com
are all valid email addresses.
- To create a domain identity:
- Click Save.
- Verify the identity. For more information, see Verifying identities in Amazon SES.
- To verify a domain identity, see Verify a domain identity.
- To verify an email identity, see Verity an email identity.
- Click Edit in the first section of the page.
- In the Deliver E-Mail Notifications Using dropdown list, select Advanced SMTP Server.
- Click Save.
Note that Zuora also utilizes Amazon SES for Workflow email notifications. You do not need to perform the above steps if you want to verify an identity for Workflow. For more information about how to use your own email address in Workflow, see Email notifications in Workflow.
Verify a domain identity
To verify a domain identity:
- Click View in the DKIM Status column of the Identities table. The DKIM Settings dialog pops up.
- Add the three CNAME records in the pop-up dialog to your domain’s DNS settings.
If the name in the DKIM settings ends with_domainkey
, append your domain name that is being verified to the end of that name. For example, if the name isctoy2wj55u._domainkey
, specifyctoy2wj55u._domainkey.yourcompany.com
in your DNS settings. Note that some DNS service providers might automatically add the domain name. In this case, to avoid duplication of the domain name, you should not add it.
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. - Wait for the verification to take effect and check the verification status:
- If the verification succeeds, the values in the Verification Status and DKIM Status columns change from
Pending
toSuccess
. You have finished the verification.
Note that verification of these settings might take up to 72 hours to take effect in Zuora. - If the verification fails, the values in the Verification Status and DKIM Status columns change from
Pending
toFailed
. You need to verify the domain identity again:- Repeat steps 1 and 2 to add the three CNAME records to your domain's DNS settings.
- Click Retry in the Verification Status column.
- If the
Pending
status lasts more than 72 hours, delete the domain identity and add it again to initiate re-verification.
- If the verification succeeds, the values in the Verification Status and DKIM Status columns change from
Note that if you click View in the Verification Status column, you can see a TXT record in the pop-up window. You do not need to add this TXT record to your domain’s DNS settings to verify a domain identity.
Verify an email identity
To verify an email identity:
- Open the verification email sent from Amazon SES to your identity’s email address.
- Click the link in the email to complete the verification process. Note that the verification link expires in 24 hours.
- Wait for the verification to take effect and check the verification status:
- If the verification succeeds, the value in the Verification Status column changes from
Pending
toSuccess
. You have finished the verification. - If the verification fails, the value in the Verification Status column changes from
Pending
toFailed
. You need to verify the email identity again:- Click Retry in the Verification Status column to send a verification email.
- Repeat steps 1 to 3.
- If the verification succeeds, the value in the Verification Status column changes from
Identity verifications across different Zuora environments
Zuora Production and API Sandbox environments share verifications of email and domain identities for the advanced SMTP server. If you have verified an email or domain identity in one environment, you can use this verified identity in the other environment without the need to verify it again.
However, the verification-sharing strategy does not apply to Zuora Developer or Central Sandbox environment. For example, if you want to verify a domain identity in Zuora API Sandbox, Developer Sandbox, Central Sandbox, and Production environments, you need to add six CNAME records to that domain’s DNS settings: three for the Production and API Sandbox environments and three for the Developer and Central Sandbox environments.
Configure SPF records for advanced SMTP server
To prevent your emails from being blocked or sent to spam or junk filters, ensure to add include:amazonses.com
to the SPF record in your domain’s DNS settings.
Here is an SPF record example when using advanced SMTP server:
v=spf1 mx include:amazonses.com ~all
For more information about SPF records for Amazon SES, see Authenticating email with SPF in Amazon SES.
Test email bounces and complaints
Bounce and complaint rates are important metrics for Amazon SES and email service providers. High bounce and complaint rates may lead to a negative impact on your company.
However, sometimes you need to test your product in different scenarios, including when an email bounce occurs. In this circumstance, you can leverage the Amazon SES mailbox simulator to simulate email bounces or complaints, without affecting your company’s reputation.
For more information about the Amazon SES mailbox simulator, see Mailbox simulator for the Amazon Simple Email Service.
Notes and limitations
- You can create at most one domain identity for your Zuora tenant.
- You can create up to three email identities for your Zuora tenant.
- You cannot create a domain identity and an email identity with the same domain.
- With advanced SMTP server, you can only send emails from verified email addresses.
- For a verified email identity, the same email address is allowed. For example, if you have
contact@yourcompany.com
as a verified email identity, you can send emails fromcontact@yourcompany.com
, but notemployee@yourcompany.com
. - For a verified domain identity, all email addresses with the same domain and subdomains are allowed. For example, if you have
yourcompany.com
as a verified domain identity, you can send emails fromcontact@yourcompany.com
,employee@yourcompany.com
, ornoreply@en.yourcompany.com
.
- For a verified email identity, the same email address is allowed. For example, if you have
- Every email you send with the Advanced SMTP server contains a DKIM signature for
amazonses.com
in the email header. To comply with the DMARC authentication protocol by including another DKIM signature for your own domain, you must verify a domain identity for your domain and send emails with email addresses from that domain.