Setting up the Authenticated SMTP Connector for two-way email relay

Quick Look: Admin Center > Channels > Talk and email > Email

The Authenticated SMTP Connector lets you connect a non-Zendesk email server to your Zendesk Support instance. It is specifically designed for organizations that prefer to use their own email servers or cannot use third-party email servers due to internal corporate policies, data regulations, or encryption needs.

By establishing a secure connection using authenticated and TLS-encrypted SMTP for both inbound and outbound traffic (each using their own credentials), the connector allows you to run your business in ways that meet both your internal and external security and regulatory requirements. It also gives you more visibility into the flow of your email traffic. This flexibility is essential for industries like healthcare, financial services, and government agencies, which often must adhere to strict security protocols. It also helps to prevent unauthorized use of the email service for spam or other malicious activities.

This article includes the following topics:

• Understanding how email is transmitted with two-way authentication
• Considerations
• Important information about email headers
• Configuring the connector for two-way authenticated email relay
• Signing your outbound email traffic with your DKIM signature
• Rotating or changing credentials
• Disconnecting the connector

Related articles:

• Using ticket triggers to create workflows for unauthenticated email
• Email resources

Understanding how email is transmitted with two-way authentication

SMTP is not new to Zendesk; Zendesk currently uses an SMTP relay for all inbound and outbound emails (except the Gmail and Exchange connectors).

The Authenticated SMTP Connector functions like the current SMTP process for email traffic, except that it relays email to and from your business mail server to Zendesk and passes secure credentials (username and password) as part of those inbound and outbound relays.

Figure 1. Email flow with the Authenticated SMTP Connector

The main advantage of this solution is that it allows you to send and receive email traffic to and from your customers using your domain’s email services while ensuring encrypted and secure relays to and from Zendesk.

Once configured, here’s how the Authenticated SMTP Connector works in a typical email workflow:

1. End user submits support request: When an end user emails a support request to your domain’s support address, the user’s email client establishes a standard SMTP connection to your business mail server.
2. Authentication via your mail server: Your business mail server then establishes an authenticated SMTP connection to Zendesk’s email infrastructure, ensuring that only authorized services can be validated through that workflow.
3. Email sent to Zendesk via SMTP: Once the service is authenticated, your business mail server relays the encrypted email to Zendesk.
4. SMTP Connector: The connector verifies the secure credentials for the incoming traffic (domain, username, and password) and passes it to the inbound Zendesk mail server.
5. Ticket created: The email is received, and a ticket is created in Zendesk with a tag indicating the relay was secure.
6. Ticket notifications: Notifications are sent back using your designated and authenticated SMTP-ready domain for outbound sending to the intended recipients.

Considerations

• The SMTP Connector for two-way email relay is not supported when using Microsoft cloud-based services. However, you can use the connector for outbound-only authenticated email relay and standard auto-forwarding of inbound email traffic to Zendesk.
• CCs and followers must be turned on in your account.
• Because the connector relies on two-way authenticated relays to occur, we recommend testing this feature in your Zendesk sandbox environment before using it in production. This is to give your domain admin, IT team, or email provider time to understand the workflow and relationship between the two resources fully.
• Do not add the same support address in your sandbox and production accounts. This may result in inconsistent behavior with Zendesk or your email server. Use your sandbox environment to test, then delete all the test domains and support addresses before adding them to your production account.
• Email must be sent and received from the same domain. You cannot receive incoming authenticated emails from one domain and send outgoing authenticated emails from a different domain.
• The Authenticated SMTP Connector doesn't allow you to send email on behalf of your Zendesk system support addresses (for example, [e-mail]).
• During initial setup, traffic may leave from the default address for that account or brand. Adding a support address for outbound sending allows Zendesk to send email through the authenticated domain.
• Up to 50 support addresses can be added to Zendesk for outbound sending through a single SMTP domain. You can add up to four domains for a total of 200 addresses, but only 50 support addresses can be added for each domain.
• Graylisting for this traffic is not recommended, particularly for verification emails. These emails complete the forwarding circuit and confirm that traffic is relayed successfully.
• You should add the Zendesk IPs to your network allowlist to ensure a reliable connection.
• If you disconnect the connector and continue to forward traffic to Zendesk, it will create and update tickets, though those updates will not be authenticated.

Important information about email headers

Email headers (such as To, From, CC, and Reply-To) contain important data and metadata about an email message.

Your administrator may want to change email headers for several reasons. However, it’s important to note that some header fields should never be altered since they are critical for ensuring the correct delivery and integrity of the message. Changing standard headers at the account's email domain before outbound sending is not supported. Any issues that emerge as a result of this should be investigated and corrected at the external domain.

The below headers should persist throughout the outbound relay process:

Auto-Submitted: auto-generated
X-Auto-Response-Suppress: All
X-Mailer: Zendesk Mailer
X-Zendesk-From-Account-Id: ******
X-Zendesk-Email-Id: ************************

Changing your email header fields doesn’t change how Zendesk works; it only changes how you send your outbound messages and how you might receive responses. The relationships between the requester, agents, and CCs in the email and subsequent ticket should not change. 

Configuring the connector for two-way authenticated email relay

Share these configuration steps with your domain admin or IT team, as they involve obtaining and providing credentials that must be securely transferred and added to your business email servers and Zendesk account.

There are three steps to configuring the connector:

1. Adding an authenticated domain to Zendesk
2. Adding a support address for outbound sending
3. Verifying the connection

Adding an authenticated domain to Zendesk

Begin by adding the domains for which all inbound and outbound traffic should be authenticated through your business mail server. You should have no existing support addresses currently using the domain, as the connector requires that support addresses be added after the domain has been configured. All incoming traffic should arrive through the authenticated connection.

At the end of this step, Zendesk provides you with credentials to share with your domain administrator or IT team so they can properly configure your business email servers.

To add an authenticated domain to Zendesk

1. In Admin Center, click Channels in the sidebar, then select Talk and email > Email.
2. In the Authenticated SMTP Connectors section, click Add domain.

   The Add domain page appears.

   

3. Add a name for the connection. This can be a purpose-specific name or one that correlates directly to the domain being connected.
4. In the Domain field, enter the inbound domain from which you would like to allow Zendesk to receive incoming email.
5. Leave the default value of PLAIN in the Authentication protocol field.
6. Click Save.

   The New Domain Credentials page appears with your inbound credentials.

   

7. Copy the credentials to a secured location or document and provide them to your domain administrator or IT team. Because these credentials allow secured connections, they must be treated as sensitive and protected information. The credentials will not be displayed again.
8. (Optional) If your email service requires an email address for the username, you can use [e-mail] (replace yoursubdomain with your Zendesk subdomain). You should also create this exact same address ([e-mail]) in your account so that if your email provider sends any emails to the address, they will be received in your Zendesk account.
   Important: These credentials are only displayed once to your Zendesk admin. You must start over or rotate the credentials if they are lost. Zendesk cannot obtain them for you.
9. Click Done.

The connection appears in the Authenticated SMTP Connectors list.

The message To complete setup, add at least one support address appears next to the connection name. To finish setting up the connection, continue to Adding a support address for outbound sending.

Adding a support address for outbound sending

You must add an outbound support address to finish setting up your connection. This means configuring Zendesk with your SMTP server settings, including the domain username and password.

This step is critical, as the Authenticated SMTP Connector requires inbound and outbound connections.

Before beginning this step, note the following:

• You will need to obtain the secured credentials for your domain (host, username, and password) from your domain administrator, IT team, or service provider.
• You will need the intended support address, with the above credentials, at your email service. The address must exist before Zendesk can interact with it. Aliases and distribution groups are not supported.
• Adding unique credentials is recommended for each address or brand so you can track traffic with greater specificity. Although this requires more work and credentials to manage, it can be helpful when rotating credentials or mitigating a possible security issue in which a set of credentials may have become compromised.
• You will want to verify that your email service is signing your outbound traffic with your DKIM signature.
• You cannot use the API to add support addresses for this feature.

To add a support address for outbound sending

1. In Admin Center, click Channels in the sidebar, then select Talk and email > Email.
2. Under Support addresses, navigate to the brand to which you want to add a support address.
3. Click Add address > Connect external address.
4. Choose Select SMTP Domain.
5. Select the domain associated with the address you wish to add, then enter the support address you want to connect. Click Next.

   

6. Add the domain credentials provided to you by your domain administrator or IT team. These credentials must be handled in the most secure manner possible.

   

7. Click Save.

When you’re done, the To complete setup, add at least one support address message no longer appears next to the connection name.

The new support address appears in the list with a warning indicator notifying you that the inbound and outbound SMTP verification check failed.

Next, you’ll verify the connection. The error messages will disappear when that process is complete.

Verifying the connection

After you have successfully added your outbound support address, you must verify both the inbound and outbound SMTP configuration. This will send two verification emails confirming you have successfully completed the connection. These verification emails must be received and forwarded successfully back to Zendesk through an authenticated relay.

To verify the connection

1. Click See details next to the Inbound SMTP verification check failed warning message to expand the message.
2. Click Verify inbound SMTP configuration.

   The message changes to Inbound SMTP verification check waiting.

3. Repeat steps 1-2 for the outbound configuration.

A green check mark displays when the connection is successfully verified.

If you see any warnings, the connection is likely not established, and outbound traffic may be getting sent from a default support address. You may need to re-click the Verify button or work with your domain admin to ensure the forwarding process is completed correctly.

Signing your outbound email traffic with your DKIM signature

As described in Digitally signing your email with DKIM, Zendesk Support allows DKIM authentication. DKIM provides a way to authenticate that an email was sent from the domain it claims to be from. This is done by attaching a digital signature to the outgoing emails, which can be verified against a public cryptographic key published in the domain's DNS records.

When using the Authenticated SMTP Connector, Zendesk will not sign outbound traffic with our d=zendesk.com DKIM tag within the header. If you have enabled digital signatures in Zendesk after adding the required CNAME records to your domain, Zendesk will sign the outbound traffic on your behalf and add the d=yourdomain.com DKIM tag to the outbound header.

Your domain can re-sign with your DKIM signature, if you choose. If you opt not to do this, test and ensure you’re not inadvertently overwriting the signature we’ve added for your domain before sending outbound production traffic.

Your domain may need to ignore SPF authority when we relay outbound traffic from Zendesk to your email service (through this connection), as we will be creating a “trusted sender” relationship with your email service, and you will be doing the final authoritative outbound sending (SPF and/or DKIM) to your users.

Zendesk strongly recommends testing in a sandbox environment with test end users to validate that the SPF/DKIM/DMARC checks are all passing.

Rotating or changing credentials

Rotating allows for the temporary existence of two sets of credentials.

• You can use two sets of inbound credentials to achieve seamless credential rotation. Zendesk does not recommend using two sets in perpetuity, as this will limit what you can do if a sudden need to rotate credentials emerges.
• It's possible to cancel existing credentials immediately. This might be necessary if a security concern arises and your team wants to stop all authorization from the previous credentials.
• It's important to have valid Zendesk admin email addresses associated with your account and not to block traffic from Zendesk default native support addresses. These addresses are where Zendesk will send security and educational or confirmation emails from, so it's essential that key stakeholders can receive them.

Disconnecting the connector

If you want to discontinue use of the connector, consider doing so during a low-traffic time. This is because the process takes a few minutes, and you may need to coordinate with your domain administrator to re-send traffic that had been attempted to be relayed during that time.

Depending on how many connected support addresses you have, you may want to leverage the API’s support addresses endpoint for faster results. Only one address can be deleted at a time, but once you have the list of SMTP-connected address IDs, the calls can be made rapidly. Authenticated SMTP Connector support addresses cannot be added through the API. Credentials must be added in Admin Center to create the necessary connection.