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

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 Platform > Events & Notifications in the left navigation menu.
  2. Click the Settings tab.
  3. In the Email Settings section, click Edit in the External SMTP section.
  4. Configure the required fields. See External SMTP Configuration Fields for more information.
  5. 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.
  6. Click Edit in the Email Settings section.
  7. In the Deliver E-Mail Notifications Using dropdown list, select External SMTP Server.
  8. 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.

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

  1. Navigate to Platform > Events & Notifications in the left navigation menu.
  2. Click the Settings tab.
  3. In the Email Settings section, click the Advanced SMTP tab and then click Edit.
  4. Create an identity.
    • To create a domain identity:
      1. From the New Identity Type list, select Domain Identity.
      2. 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, then yourcompany.com and en.yourcompany.com are both valid domain names.
    • To create an email identity:
      1. From the New Identity Type list, select Email Identity.
      2. 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, then contact@yourcompany.com, employee@yourcompany.com, and noreply@en.yourcompany.com are all valid email addresses.
  5. Click Save.
  6. Verify the identity. For more information, see Verifying identities in Amazon SES.
  7. Click Edit in the Email Settings section.
  8. In the Deliver E-Mail Notifications Using dropdown list, select Advanced SMTP Server.
  9. 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:

  1. Click View in the DKIM Status column of the Identities table. The DKIM Settings dialog pops up.
    DKIM CNAMEs.png
  2. 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 is ctoy2wj55u._domainkey, specify ctoy2wj55u._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.
  3. 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 to Success. 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 to  Failed. You need to verify the domain identity again:
      1. Repeat steps 1 and 2 to add the three CNAME records to your domain's DNS settings.
      2. 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.

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:

  1. Open the verification email sent from Amazon SES to your identity’s email address.
  2. Click the link in the email to complete the verification process. Note that the verification link expires in 24 hours.
  3. 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 to Success. You have finished the verification.
    • If the verification fails, the value in the Verification Status column changes from Pending to  Failed. You need to verify the email identity again:
      1. Click Retry in the Verification Status column to send a verification email.
      2. Repeat steps 1 to 3.

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 from contact@yourcompany.com, but not employee@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 from contact@yourcompany.com, employee@yourcompany.com, or noreply@en.yourcompany.com.
  • 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.