Skip to main content

Configure an SMTP Server for Email Notifications

Zuora

Configure an SMTP Server for Email Notifications

  1. Last updated
  2. Save as PDF

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.

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 Administration Settings > Manage SMTP Settings.
  2. Click Edit in the Advanced SMTP Server Configuration Settings section. 
  3. 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.
  4. Click Save.
  5. Verify the identity. For more information, see Verifying identities in Amazon SES.
  6. Click Edit in the first section of the page.
  7. In the Deliver E-Mail Notifications Using dropdown list, select Advanced SMTP Server.
  8. Click Save.

Verify a domain identity

To verify a domain identity:

  1. Click View in the DKIM Status column of the Identities table. The DKIM Settings window pops up.
    DKIM CNAMEs.png
  2. Add the three CNAME records in the pop-up window to your domain’s DNS settings. 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.

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.

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.

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.