The Authenticated SMTP Connector allows you to 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:
- About the Authenticated SMTP Connector
- Considerations
- Configuring the Authenticated SMTP Connector
- Signing your outbound email traffic with your DKIM signature
- Important information about email headers
- Using triggers and views to create workflows for authenticated and unauthenticated email
- Rotating or changing credentials
- Disconnecting the Authenticated SMTP Connector
About the Authenticated SMTP Connector
SMTP is not new to Zendesk; Zendesk currently uses an SMTP relay for all inbound and outbound emails (except Gmail connector).
The Authenticated SMTP Connector functions like the current SMTP process for email traffic, except that it relays email to and from your company’s mail server to Zendesk and passes/receives 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:
- End user submits support request: When an end user emails a support request to your domain’s support address, the user’s email client very likely establishes a standard SMTP connection to your business mail server.
- 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.
- Email sent to Zendesk via SMTP: Once the service is authenticated, your business mail server relays the encrypted email to Zendesk.
- 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.
- Ticket created: The email is received, and a ticket is created in Zendesk with a Tag indicating the relay was secure.
- Ticket notifications: Notifications are sent back using your designated and authenticated SMTP-ready domain for outbound sending to the intended recipients.
Considerations
- Because the Authenticated SMTP Connector feature 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, either with Zendesk or your email server. It is recommended that you 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 when using this integration. You cannot receive incoming auth'd emails from one domain, and send outgoing auth'd emails from a different domain as part of this feature.
- During initial setup there may be some traffic leaving from the default address for that account or brand. Adding a support address for outbound sending is what completes the integration and allows us to send through the authenticated address/domain.
- Up to fifty 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 fifty support addresses can be added for each domain.
- It is advised that you do not employ graylisting for this traffic, particularly for the verification emails, as these emails completing the forwarding circuit are what will allow the feature to function and confirm to us that traffic is being successfully relayed.
- You should allowlist the Zendesk hosts/IPs to ensure a robust connection.
- If you disable the feature and continue to forward traffic to us it will create and update tickets, though those updates will not be authenticated.
Configuring the Authenticated SMTP Connector
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:
- Adding an authenticated domain to Zendesk
- Adding a support address for outbound sending
- 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. To do this you must have no existing support addresses which use that domain, as this integration requires that support addresses be added after the domain has been configured. Once you’ve added the authenticated domain, any unauthenticated traffic from that domain will be dropped. All incoming traffic must 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
- In Admin Center, click Channels in the sidebar, then select Talk and email > Email.
- In the Authenticated SMTP Connectors section, click Add domain.
The Add domain page appears.
- Add a Name for the connection. This can be a purpose-specific name or one that correlates directly to the domain being connected.
- In the Domain field, enter the inbound domain from which you would like to allow Zendesk to receive incoming email.
- For Authentication protocol, leave the default value of PLAIN.
- Click Save.
The New Domain Credentials page appears with your inbound credentials.
- 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.
- (Optional) If your email service requires an email address for the username you can use accountname@accountname.zendesk.com (replace accountname with your Zendesk subdomain.)
Important: These credentials are only displayed to your Zendesk admin once. If they are lost, then you must start over or rotate the credentials. Do not open a support request asking Zendesk to provide them to you because Zendesk won’t be able to obtain them. - Click Done.
The connection appears in the Authenticated SMTP Connectors list.
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 need to 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 crucial, as inbound and outbound connections are required by the Authenticated SMTP Connector.
Before beginning this step, note the following:
- You will need the secured credentials for your domain (host, username, and password), obtained 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. This can be helpful in rotating credentials or in mitigating a possible security issue in which a set of credentials may have become compromised.
- You will want to sign 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
- In Admin Center, click Channels in the sidebar, then select Talk and email > Email.
- Under Support addresses, navigate to the brand to which you would like to add a support address.
- Click Add address > Connect external address.
- Choose Select SMTP Domain.
- Select the domain associated with the address you wish to add, then enter the support address you want to connect. Click Next.
- 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.
- 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 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 that verify that you have successfully completed the connection. These verification emails must be received and forwarded successfully back to Zendesk through an authenticated relay for the integration to function.
To verify the connection
- Click See details next to the Inbound SMTP verification check failed warning message to expand the message.
- Click Verify inbound SMTP configuration.
The message changes to Inbound SMTP verification check waiting. - Repeat steps 1-2 for the outbound configuration.
When the connection is successfully verified, a green check mark displays.
If you see any warnings, the connection was likely not established, and outbound traffic may be getting sent from a default support address.
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 indeed 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 at your domain, we 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 over-writing the signature we’ve added for your domain before sending the traffic outbound.
Your domain may need to ignore SPF authority when we relay traffic to you, as we will be creating a “trusted sender” relationship with your email service and you will be doing the authoritative outbound sending (SPF and/or DKIM).
We strongly recommend testing in a sandbox environment with test end-users to validate that the SPF/DKIM/DMARC checks are all passing.
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 might want to change or manipulate headers for several reasons. However, it’s important to note that some header fields should never be altered since some are critical for ensuring the correct delivery and to ensure the integrity of the message. Changing standard headers at the account's email domain before outbound sending is not a currently supported aspect of this feature. Any issues that emerge as a result of this should be investigated and corrected at the external domain.
Changing your email header fields doesn’t change how Zendesk works, it only changes how you do your outbound sending and how you might receive responses. The relationships between requester, agents and CCs in the email and subsequent ticket should not change.
This feature does not give you the ability to send email on behalf of your Zendesk system support addresses (example: support@subdomain.zendesk.com).
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: ************************
Using triggers and views to create workflows for authenticated and unauthenticated email
If you enable ticket tagging, you can use views and triggers in Zendesk Support to provide visibility into whether tickets were created by the SMTP Connector. This can help you route, troubleshoot, or examine your workflow to decide whether you need to make changes.
Two ticket tags are automatically added to tickets when automatic ticket tagging is enabled:
- system_authenticated_email_ticket - Automatically added to newly created tickets through the SMTP Connector.
- system_unauthenticated_email_update - Automatically added to tickets when an update is made to a previously authenticated ticket through an unauthenticated email update.
For more information on the benefits of ticket tags and how they work, see Working with ticket tags and Managing ticket tags.
Important: you do not want to have Automatic Ticket Tagging enabled. This may add often used Tags on your tickets and may interact poorly with the Tags designed to surface authentication information to your account (above).
Example 1: Route new tickets created through unauthenticated email to a group
You might want a special group of agents to review tickets that have been created through unauthenticated email. This ensures the right people can examine how these tickets are being created and determine whether additional configuration is needed.
For this scenario, you can create a trigger that routes all tickets that don’t contain the system_authenticated_email_ticket tag to a group (the Auditors group is used in this example). You can also optionally apply a tag to these tickets (such as admin_unauthenticated) so you can create a view with tickets containing that tag.
Example 2: Route tickets updated through unauthenticated email to a group
If tickets are created through an authenticated workflow via the SMTP Connector, then they should also be updated through an authenticated workflow. This example shows how to send unauthenticated updated tickets to a special group of agents so they can take steps to understand how the workflow is resulting in a loss of authentication.
For this scenario, you can create a trigger that routes all tickets that contain the system_unauthenticated_email_update tag to a group (the Auditors group is used in this example). You can also optionally use the trigger to set the ticket priority to High.
Rotating or changing credentials
- Two sets of credentials - We will allow you to use two sets of inbound credentials for the purpose of seamless credential rotation. We do not recommend using two sets in perpetuity, as this will limit what you are able to do in the event a sudden need to rotate credentials emerges
- Rotating - allows for the temporary existence of two sets of credentials
- Sudden cancellation of existing credentials - it is also 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 immediately.
- Security Emails - It is important to have valid Zendesk Admin email addresses associated with your account, and not to block traffic from Zendesk default native support addresses - these are where we will send security and educational/confirmation emails from, so it is important that they can be received by the key stakeholders.
Disconnecting the Authenticated SMTP Connector
- The process - in the event that you wish to discontinue use of the feature you may want to consider doing so during a low-traffic time, as the process will take a few minutes and you may need to coordinate with your domain administrator to re-send any traffic that had been attempted to be relayed during that time
- The API - 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 then the calls can be made in a very rapid sequence. It is worth noting that Authenticated SMTP Connector support addresses can not be added via the API at this time, as credentials must be added within the UI to create the necessary connection