Developer resources

You can set up your custom email domain to verify that Zendesk can send email on behalf of your email server.

For example, if you receive email from your customers at help@mycompany.com, and you’ve set up an automatic redirect to forward all email received there to Support, you can authorize Zendesk to send out notifications as if it originated from your own email address (for example: help@mycompany.com).

Setting up records for your domain can be confusing because it’s something most of us rarely do. Consult your system administrator, if you have one, before proceeding.

You don’t have to configure your email domain this way, but it’s recommended if you use your own custom email domain and have set up forwarding to an external email address. If you use a non-custom domain, such as addresses ending in @gmail.com or @yahoo.com, you can’t use this feature, as you won’t have access to the account DNS settings.

The advantages of this configuration

When Zendesk sends an email message using your email address (which is what happens if you’ve set up a support address with forwarding) the message identifies the sender as zendesk.com to avoid getting rejected. However, if you allow Zendesk to send email on behalf of your email domain, Zendesk stops sending messages from zendesk.com, and sends them from your domain, preserving your branding.

If you don’t complete the tasks described in this article, your customers might see something like this:

The following warning will also appear in the agent interface next to your external support addresses:

Setting up records for your domain

You will need to set up an SPF record and several CNAME records. Make sure you do both.

Setting up an SPF record

If this is the first time doing this task, keep in mind that you should also set up your CNAME records when you’re done.

The process of setting up an SPF record is different for different domain registrars. For example, here are the instructions for GoDaddy, Namecheap, 1&1, Network Solutions, and Google Domains.

Don’t forget to set up your CNAME records when you’re done.

To create or edit an SPF record to reference Zendesk

• Edit your domain’s DNS settings to add a TXT record. The steps vary depending on your domain registrar. A TXT record is required for your SPF record to be validated.

Zendesk recommends using the following SPF record:

v=spf1 include:mail.zendesk.com ?all

While we recommend using ?all because it’s the least intrusive qualifier, you can use whichever qualifier you are comfortable with.

If you’ve already set up an SPF record for another purpose, you can simply add a reference to Zendesk to it. The SPF specification requires that you only have one SPF record on your domain, if you have multiple records, it may cause issues, and cause rejections of your email.

For example, instead of having two separate records, such as v=spf1 include:\_spf.google.com ~all and v=spf1 include:mail.zendesk.com ~all you can combine them into one, like this:

v=spf1 include:\_spf.google.com include:mail.zendesk.com ~all

In the past, Zendesk suggested alternate formulations for SPF records, including include:smtp.zendesk.com and include:support.zendesk.com. These are both outdated SPF records. While they might still work, they’re not the best option. If you’re still using them, you’ll see a warning flag indicating you’ve set up an outdated record.

Setting up CNAME records

In order for Zendesk to send email on your behalf, you must add four CNAME (Canonical Name) records to your DNS server that give Zendesk domain-level email authorization.

The CNAME records redirect SPF checks to mail*.zendesk.com, which is a Zendesk server that includes an SPF record that is maintained by Zendesk. This SPF record is used for mail sent from zendesk*.customer.com. This means that Zendesk maintains SPF records for a subset of mail delivered from your domain, and ensures they are always up-to-date.

To authorize Zendesk to deliver your email using CNAME records

• Edit your domain’s DNS settings and add each of these CNAME records:

  Type	Name/Host/Domain	Value/Target/Destination	TTL
  CNAME	zendesk1	mail1.zendesk.com	3600 or use default
  CNAME	zendesk2	mail2.zendesk.com	3600 or use default
  CNAME	zendesk3	mail3.zendesk.com	3600 or use default
  CNAME	zendesk4	mail4.zendesk.com	3600 or use default

If you’re unsure about any of the above, consult with your DNS provider.

Consider making an additional update to digitally sign outbound email from Zendesk to prevent your customers’ email clients from blocking email. Digitally signing email provide that an email actually came from your organization and not someone pretending to be your organization. For instructions, see Digitally signing your email with DKIM or DMARC.

Verifying your domain

In order for Zendesk Support to send emails on your behalf, you must verify that you own the domain that you want Support to use. This is done by adding a TXT record (a domain verification record) to your DNS server that Support will check. The domain verification record is unique for each Support account and domain combination.

If you don’t add the domain verification record, Support sends emails from a Zendesk-provided email address. If you want to give your customers a white label experience, hiding all Zendesk branding, you must add this record.

To verify that a domain belongs to you

1. After you have finished setting up your CNAME records, go to Support and click the Admin icon () in the sidebar, and then navigate to Channels > Email.

2. Locate the DNS records (located outside of Zendesk) for your Support address, then click See details to see the domain verification value.

   If you are an agent with permissions to manage support addresses, you can use the Support Addresses API endpoint to find the domain verification code for your support address instead, if you prefer. Look for the domain_verification_code value.

3. Edit your domain’s DNS settings and add this TXT record:

   Type	Name/Host/Domain	Value	TTL
   TXT	zendeskverification		3600 or use default

   You can find the value next to the Domain verification TXT record check. In this example, the value is abcdef123456:

   

4. After you add the TXT record, click the Verify DNS records button to confirm that all of your records are now valid. If they are, the red error messages will be gone.

   After your domain is verified, leave the domain verification record in-place.

If you decide to change your Support subdomain or host mapping later, you don’t need to update your domain verification records.

Understanding SPF checks

Sender Policy Framework (SPF) is a domain level email authorization protocol that allows you to declare which IP addresses are allowed to send email as if it originated from your domain.

This is accomplished by adding Domain Name System (DNS), TXT, or CNAME records. Think of DNS as a publicly accessible record for the internet. These records enable you to state publicly that Zendesk is an authorized sender for your domain.

When an email client receives a message, it performs an SPF check on the sending domain to verify that the email came from who it says it did. If this check fails, or there isn’t a DNS record that says that Zendesk is a permitted sender, some receivers might consider that email spam or a phishing attempt, and flag it as untrustworthy or not display it to your customers at all.

Zendesk avoids this by sending email using our own domain when we’re not authorized to use your domain, and by using your domain only when you authorize Zendesk with a proper SPF record. Either way, email sent from Zendesk should never be marked as spam.

If you have multiple Help Centers, you can enable users to search across multiple Help Centers. You can decide which Help Centers to include in the search results. You can also decide if you want to include community content from those Help Centers.

You must have Guide Enterprise and Support Enterprise to support multiple Help Centers. You must be a Guide Manager to enable search for multiple Help Centers.

All of our themes support sidebar filters and results for multiple Help Centers on the Search Results page, introduced on September 25, 2019

To enable users to search across multiple Help Centers

1. In Guide, click the Settings icon () icon in the sidebar, then click Search settings.
2. Under Search across multiple Help Centers, click Show results from other Help Centers.

3. Click the Show community posts from selected Help Centers in search results if you’d like to include community posts from the selected Help Centers in the search results.

   Knowledge base articles are included by default and cannot be excluded.

   

4. Select the name of each Help Center you want to include in the search results.

   The name of each Help Center that’s been activated for a brand appears in the list. You might not have a corresponding Help Center for each of your brands.

5. Click Save in the Help Center Search settings page when you are finished.

The GitHub integration enables you to develop and maintain a theme collaboratively in GitHub, then preview or publish it in Guide. To set up the integration, make sure your theme is stored in GitHub, then set up the integration in Guide.

You must be a Guide Manager to set up the GitHub integration in Guide.

Preparing your theme in GitHub

You need to ensure that your theme is in GitHub before you set up the integration in Guide. If you’re new to Git and GitHub check out this tutorial. If your theme is already in GitHub, and it meets the following requirements, see Setting up the integration in Guide.

The integration has the following requirements for your GitHub repo:

• The manifest file must be at the root of the GitHub repo

  The file manifest.json should be placed at the root of your GitHub repository for Guide to be able to fetch your theme. You can still include extra files, such as tooling, which are ignored when importing to Guide.

• The GitHub repo can have only one theme

  You should only manage one theme in each repository. You can use the branch option during theme import to try out variations of your theme.

To get your theme into a GitHub repo

• If your theme is in Guide, export your theme from Guide and create a GitHub repo (if you don’t already have one) and push your theme to the GitHub repo.

• If your theme is not in Guide or GitHub, create a GitHub repo (if you don’t already have one) and push your theme to the GitHub repo.

After you’ve prepared your theme in GitHub, you are ready to set up the integration in Guide.

Setting up the integration

To set up the GitHub integration you need to make sure your theme is stored in GitHub, then fetch your theme from GitHub to Guide. This one-time fetch establishes the connection between your theme and GitHub.

After you set up the integration, you will work on the theme in GitHub, then update the theme in Guide when you’re ready. In Guide you can then preview or publish the theme live.

To set up the GitHub integration with your Guide theme

1. In GitHub, ensure that you have prepared your theme.

2. In Guide, click the Customize design icon () in the sidebar.

   The Themes page opens.

3. Click Add new theme in the upper-right corner.

4. Click Fetch from GitHub.

   

5. Enter the URL for the repo and, optionally, enter a branch name if you want to fetch from a branch other than the default branch, then click Import.
6. Log in to GitHub if prompted, then click Authorize Zendesk.

The theme thumbnail appears on the Themes page when the import is complete. If you have problems, see Troubleshooting the GitHub integration for Guide themes.

Once you’ve established the connection between your theme in Guide and GitHub, you will manage your theme in GitHub and update the theme in Guide as needed.

SSL (Secure Socket Layer) is an encryption protocol that ensures secure communications with your website. You must configure an SNI-based SSL certificate for a host-mapped domain using one of the two methods below:

• Use the free SNI-based SSL certificate from Zendesk (recommended)
• Use your own SNI-based certificate

If you don’t upload a certificate when you use a host-mapped domain, all help center traffic will be redirected to your default zendesk.com subdomain.

Using a Zendesk-provisioned SSL certificate

We recommend using the Zendesk-provisioned SNI-based SSL certificate for your host-mapped domain or domains if you’re on the Team, Professional, or Enterprise plans. This is included for free with your Zendesk plan. The SSL certificate covers all your host-mapped domains. Zendesk automatically renews the SSL certificate before it expires.

Your host mapping must be set up correctly before you start.

1. In Zendesk Support, click the Admin icon () in the sidebar, select Settings > Security, then click the SSL tab at the top of the Security page.
2. In the Hosted SSL section of the page, click Enable Zendesk-provisioned SSL.

3. Click Save.

   Zendesk requests a SSL certificate from Let’s Encrypt, a third-party certificate service. It can take up to an hour to complete the request. If you have any issues, contact support@zendesk.com.

   When you add, update, or delete a host-mapped domain, Zendesk removes your current certificate and replaces it with a new certificate that covers the new host-mapped routes.

Providing your own SSL certificate

If you prefer not using Zendesk-provisioned SSL, you can get and upload your own SNI-based SSL certificate as described in this section. If you use your own certificate, Zendesk will not automatically renew it when it expires.

Because of potentially long lead times, consider your SSL options early in the process of setting up your Zendesk Support.

Getting your own SSL certificate

If you already have a SNI-based certificate for your host-mapped address, skip to Uploading the certificate below.

You can purchase a SSL certificate from a certificate authority such as DigiCert or Symantec, or from resellers such as Namecheap. You need to give the certificate authority a certificate signing request file (CSR) to create the certificate. You can generate the CSR, as described below.

Make sure any SSL certificate you purchase supports Server Name Indication (SNI) technology.

IP-based SSL certificates are not supported.

If you have multiple host-mapped brands, you only need one certificate for all of them – you don’t need a SSL certificate for each brand. However, if you add a host-mapped brand, you need to replace your existing certificate with a new one. Generate the new certificate as described in the procedure below. For more information on host-mapped brands, see Generating an SSL certificate for host-mapped brands.

To get a SSL certificate

1. In Zendesk Support, click the Admin icon () in the sidebar, select Settings > Security, then click the SSL tab at the top of the Security page.

2. In the Hosted SSL section of the page, click I do not have a certificate, and then Generate a request. A certificate signing request file (CSR) is created and downloaded to your computer.

   

3. Provide the CSR file to the certificate authority.

   The certificate authority generates a SSL certificate and gives it to you so that it can be installed on our servers.

   Certificate authorities charge a fee for each request so keep the following tips in mind:

   • Before you buy, make sure your certificate authority supports SHA-2 encryption. The CSR file generated uses SHA-2 encryption
   • Make sure the certificate supports Server Name Indication (SNI) technology
   • If prompted, specify “Nginx”, “Apache” or “Apache + mod_ssl” as the desired web server
   • After the certificate authority generates the certificate file, save it so you don’t have to make another request

   We strongly discourage using wildcard certificates. If your certificate is compromised anywhere on any of the services you use, the information on all your services is at risk. You also have to replace the certificate everywhere it’s used.

Once you have a SSL certificate, the next step is to upload it as described below.

Uploading the certificate

After purchasing the SSL certificate, the certificate authority will send you an email or direct you to a page where you can download the certificate. The instructions are often unclear about what files you really need or if you should prepare them before uploading them. For guidance, see Identifying and preparing your SSL certificate.

After obtaining or preparing the SSL certificate as a PEM file as described above, upload it to our servers as follows.

1. In Zendesk Support, click the Admin icon () in the sidebar, select Settings > Security, then click the SSL tab at the top of the Security page.

2. In the Hosted SSL section of the page, click I have a certificate, then Upload certificate.

   

3. Navigate to the PEM file and select it.
4. If you have a private key associated with the certificate, click Upload private key and enter your passphrase if any. You don’t need a key if you generated the CSR file in Zendesk Support. For more information, see Getting a key file for upload.

5. Click Save.

   The certificate will be installed on our servers.

Update the CNAME record

For either SSL option – you provide your own SSL certificate or you use Zendesk-provisioned SSL – Zendesk requires that the DNS record be a CNAME record that points to subdomain.zendesk.com. DNS “A” records are not supported.

You must configure the DNS, refer to Changing the URL of your Help Center. If there is an error in the DNS, we will remove the invalid host mapping.

Reviewing the SSL status of a certificate

You can review the SSL status (CNAME check) of your host-mapped, SSL-enabled brands in the Zendesk Support interface.

1. In Zendesk Support, click the Admin icon () in the sidebar, select Settings > Security, then click the SSL tab at the top of the Security page. The SSL page displays information about your certificates:

   

   This view of the SSL page is only displayed if you have a host-mapped, SSL-enabled domain.

2. Refresh the page to run the SSL status check again.

Replacing a certificate

You can replace a certificate installed on Zendesk Support.

Zendesk will notify you when the certificate you provided is about the expire. If it expires before you can replace it, Zendesk will automatically replace it with a free, SNI-based SSL certificate from Let’s Encrypt, a third-party certificate service. See Getting a Zendesk-provisioned SSL certificate. You can keep the certificate or replace it with your own.

1. In Zendesk Support, click the Admin icon () in the sidebar, select Settings > Security, then click the SSL tab at the top of the Security page.

2. Click I already have a certificate and follow the steps in Uploading the certificate above.

   

   This view of the SSL page is only displayed if you have a host-mapped, SSL-enabled domain.

3. If you don’t have a replacement certificate yet, click I do not have a certificate and follow the steps in Getting a SSL certificate above.

Extending HTTP Strict Transport Security (HSTS) to one year

HTTP Strict Transport Security (HSTS) is enabled by default for host-mapped, SSL-enabled domains in Zendesk Support. HSTS instructs users’ browsers to access your host-mapped domain only over SSL.

When a user types http://shop.example.com or just shop.example.com to access a SSL-enabled site that doesn’t have HSTS, the user’s browser briefly accesses the non-encrypted version of the site before being redirected to the encrypted HTTPS version. The redirect makes the user vulnerable to a man-in-the-middle attack, where a hacker exploits the redirect to redirect the user to a malicious site.

When HSTS is enabled, the site instructs the user’s browser to never load the site using HTTP. The browser automatically converts all such attempts to HTTPS requests, skipping the redirect that hackers can exploit for man-in-the-middle attacks. As long as the user accessed the site once using HTTPS, the user’s browser will know to only use HTTPS to access it.

The browser remembers the site only for a specified period. By default for Zendesk SSL-enabled domains, the period is 1 day. You can increase the period to 1 year.

This feature is only available if you have a host-mapped, SSL-enabled domain.

To extend the period the browser remembers your site to one year

1. In Zendesk Support, click the Admin icon () in the sidebar, select Settings > Security, then click the SSL tab at the top of the Security page.
2. Select the HSTS option to instruct browsers to remember the site for up to one year.
3. Click Save.

After setting up a host-mapped, SSL-enabled domain, you can perform any of the following management tasks:

• Reviewing the SSL status of a certificate
• Replacing a certificate
• Extending HTTP Strict Transport Security (HSTS) to one year

You can use Google Analytics to track Help Center traffic. Enabling it involves getting the tracking ID from Google Analytics and then adding it to the Help Center.

If you previously obtained the JavaScript snippet from Google Analytics and added it to your Help Center pages manually, you should remove the snippet before enabling the setting described in this article.

Adding your Help Center to Google Analytics

To track traffic via Google Analytics, you’ll need a Google Analytics account.

To create a new Google Analytics account

1. Go to www.google.com/analytics and create an account.
2. On the New Account page, click Website.

3. Use your Help Center information to fill out the account options. For example, if you’re creating an account for your company, Mondocam, you’d enter the following:

   • Account Name: Mondocam
   • Website Name: Mondocam Help Center
   • Website URL: (Select https:// from the drop-down menu) mondocam.zendesk.com/hc

   Set the remaining options according to your preferences.

4. Click Get Tracking ID and accept the Terms and Conditions.
5. Copy and add the tracking ID to the Help Center as described in Adding the tracking ID to the Help Center, below.

Once you have a Google Analytics account, you can add your Help Center.

To add your Help Center to your Google Analytics account

1. Sign in to your Google Analytics account.

2. If this is the first website associated with this Google Analytics account, click Sign Up.

   If you have other websites associated with this Google Analytics account, click Admin at the top of the page, and in the Account column, click the existing account name and select Create new account.

3. Use your Help Center information to fill out the account options. For example, if you’re creating an account for your company, Mondocam, you’d enter the following:

   • Account Name: My Company
   • Website Name: My Company Help Center
   • Website URL: (Select https:// from the drop-down menu) mycompany.zendesk.com/hc

   Set the remaining options according to your preferences.

4. Click Get Tracking ID and accept the Terms and Conditions.
5. Copy and add the tracking ID to the Help Center as described below.

Adding the tracking ID to the Help Center

Once you have your Help Center added to your Google Analytics account, you need to update your settings with the tracking ID you generated in the previous section.

To add the tracking ID to the Help Center

1. In Guide, click the Settings () icon in the sidebar.

2. Under Integrations, select the option to enable the Google Analytics and enter your tracking ID.

   

3. Click Update on the upper-right side of the page.

Using Google Analytics with Help Center

See the following resources on using Google Analytics to create the best self-service experience possible for your customers:

• Google Analytics and Help Center - Part 1: Asking the right questions
• Google Analytics and Help Center - Part 2: Measuring the effectiveness of search
• Google Analytics and Help Center - Part 3: Tracking customers’ actions
• Google Analytics and Help Center - Part 4: Fine-tuning Help Center
• Google Analytics and Help Center - Part 5: Capturing Help Center user data

An API, or Application Programming Interface, is a tool for software applications that acts as an intermediary and allows them to talk to one another. Each time you use an app like Zendesk, send an instant message, or check the weather on your phone, you’re using an API.

An example of this in the API would be the List Users endpoint. It returns a list of all users in your Zendesk Support account. Some endpoints like the Show User endpoint are more focused and just return a single thing. You can also use the API to make changes to things in Zendesk.

The API is a powerful resource that many of our customers use to bulk-import resources, create apps, pull data to external sources, and more.

Most of the reference documentation for the Zendesk API is available in the Rest API section of the Zendesk Developer Portal, which describes all the available endpoints.

Why use the API?

You can use the API to add functionality that’s not available in the UI (either natively or at your plan level) at a much faster pace than attempting to do it all by hand.

For accounts currently on the Essential or Team plans, using the API allows you to have a direct method for exporting your data without needing to upgrade to Professional (which allows for automated data exports). Similarly, you may use the API to get ticket data for reporting purposes. The API can return all information related to a ticket, so you may use the API output to pass data into a third party reporting application.

The ability to quickly update many records is another benefit of using the API. For example, while you’re only able to create a single organization at a time in the agent interface, you could create up to 100 organizations at a time with the API. In the same vein, the restrictions on how many items you can update at a time is higher with the API. The interface allows for 60 tickets to be edited at once, while the API allows up to 100 tickets.

Other common tasks include:

• Creating tickets
• Migrating ticket data into Zendesk from another system
• Editing users in bulk
• Searching records
• And many more!

Now that we’ve outlined why you’d want to use the API, let’s look at how to make an API request.

Format

The Zendesk API returns data in a lightweight format called JSON, whichlooks like this:

{
  "posts": [
    {
      "id": 35467,
      "title": "How do I open the safe"
    },
    {
      "id": 35468,
      "title": "How do I reset the combination?"
    },
    ...
  ]
}

A typical endpoint looks like this:

subdomain.zendesk.com/api/v2/users/me.json

Endpoints can perform the following actions:

• GET - Retrieve items
• POST - Create items that didn’t exist before
• PUT - Update existing items
• DELETE - Remove items

In a browser, you can only make GET requests. You can perform the other actions using tools like cURL or the API console on the Zendesk Developer Portal.

cURL

The reference documentation uses cURL in all the endpoint examples. cURL is a command-line tool that lets you try API commands without a browser. For more information, see Installing and Using cURL in the Zendesk Help Center. You can use cURL for any of the 4 types of calls. It comes pre-installed on a Mac, but you’ll need to install it in Windows. For instructions, see Installing cURL in the Zendesk Help Center.

Status of your requests

For every API request you make, you receive a response that lets you know if it worked or not. If not, the response will provide clues as to why the request didn’t work. These responses are called status codes. Some of the most common ones are as follows:

• 200 - The request was successful
• 400 - Request was unsuccessful
• 409 - Merge or constraint error, try the call again
• 422 - Un-processible Entity
• 429 - Rate limit has been exceeded
• 500 - Warning or temporary state, contact support if it persists

See Response Codes in the API docs for more details about the status codes.