Support Addresses

When you set up Zendesk Support, you have one email address: [email protected]. Emails received at this address become tickets.

You can provide your users with additional email addresses for submitting tickets. The additional addresses are called support addresses. You can add up to 3000 support addresses. They can be Zendesk addresses or external addresses. If adding external addresses, additional steps are required to set up forwarding from your email server to your Zendesk account.

Support addresses allow you to customize the "sender" address for your outgoing notifications. When an email is received at a support address, Zendesk responds from the same address. For example, if an email is sent to [email protected], Zendesk sends a notification from [email protected].

For more information, see Adding support addresses for users to submit tickets.

JSON format

Support Addresses are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
brand_id	integer	false	false	The ID of the brand
cname_status	string	true	false	Whether all of the required CNAME records are set. Possible values: "unknown", "verified", "failed". Allowed values are "unknown", "verified", or "failed".
created_at	string	true	false	When the address was created
default	boolean	false	false	Whether the address is the account's default support address
dns_results	string	true	false	Verification statuses for the domain and CNAME records. Possible types: "verified", "failed". Allowed values are "verified", or "failed".
domain_verification_code	string	true	false	Verification string to be added as a TXT record to the domain. Possible types: string or null.
domain_verification_status	string	true	false	Whether the domain verification record is valid. Possible values: "unknown", "verified", "failed". Allowed values are "unknown", "verified", or "failed".
email	string	false	true	The email address. You can't change the email address of an existing support address.
forwarding_status	string	true	false	Status of email forwarding. Possible values: "unknown", "waiting", "verified", or "failed". Allowed values are "unknown", "waiting", "verified", or "failed".
id	integer	true	false	Automatically assigned when created
name	string	false	false	The name for the address
spf_status	string	true	false	Whether the SPF record is set up correctly. Possible values: "unknown", "verified", "failed". Allowed values are "unknown", "verified", or "failed".
updated_at	string	true	false	When the address was updated

You can also include the brand for each Support address in the JSON objects returned by GET requests by sideloading it. Example: GET /api/v2/recipient_addresses.json?include=brands

Example

{
  "brand_id": 123,
  "cname_status": "verified",
  "created_at": "2015-07-20T22:55:29Z",
  "default": true,
  "domain_verification_status": "verified",
  "email": "[email protected]",
  "forwarding_status": "unknown",
  "id": 35436,
  "name": "all",
  "spf_status": "verified",
  "updated_at": "2016-09-21T20:15:20Z"
}

List Support Addresses

• GET /api/v2/recipient_addresses

Lists all the support addresses for the account.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Admins
• Agents

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/recipient_addresses.json \
  -v -u {email_address}:{password}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/recipient_addresses"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/recipient_addresses")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/recipient_addresses',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/recipient_addresses"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/recipient_addresses")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

{
  "recipient_addresses": [
    {
      "brand_id": 123,
      "cname_status": "verified",
      "created_at": "2015-07-20T22:55:29Z",
      "default": true,
      "domain_verification_status": "verified",
      "email": "[email protected]",
      "forwarding_status": "unknown",
      "id": 33,
      "name": "Sales",
      "spf_status": "verified",
      "updated_at": "2016-09-21T20:15:20Z"
    },
    {
      "brand_id": 123,
      "cname_status": "verified",
      "created_at": "2015-07-20T22:55:29Z",
      "default": false,
      "domain_verification_status": "verified",
      "email": "[email protected]",
      "forwarding_status": "unknown",
      "id": 34,
      "name": "Marketing",
      "spf_status": "verified",
      "updated_at": "2016-09-21T20:15:20Z"
    }
  ]
}

Show Support Address

• GET /api/v2/recipient_addresses/{support_address_id}

Allowed For

• Admins
• Agents

Parameters

Name	Type	In	Required	Description
support_address_id	integer	Path	true	The ID of the support address

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/recipient_addresses/{support_address_id}.json \
  -v -u {email_address}:{password}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/recipient_addresses/33"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/recipient_addresses/33")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/recipient_addresses/33',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/recipient_addresses/33"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/recipient_addresses/33")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

{
  "recipient_address": {
    "brand_id": 123,
    "cname_status": "unknown",
    "created_at": "2017-04-02T22:55:29Z",
    "default": true,
    "email": "[email protected]",
    "forwarding_status": "waiting",
    "id": 33,
    "name": "Sales",
    "spf_status": "unknown",
    "updated_at": "2017-04-02T22:55:29Z"
  }
}

Create Support Address

• POST /api/v2/recipient_addresses

Adds a Zendesk or external support address to your account.

To add a Zendesk address, use the following syntax: {local-part}@{accountname}.zendesk.com. Example: '[email protected]'. The local-part can be anything you like.

To add an external email address such as [email protected], the email must already exist and you must set up forwarding on your email server. The exact steps depend on your mail server. See Forwarding incoming email to Zendesk Support. After setting up forwarding, run the Verify Support Address Forwarding endpoint. The address won't work in Zendesk Support until it's been verified.

Allowed For

• Admins
• Agents with permission to manage channels and extensions. See the system permissions in Creating custom roles and assigning agents (Enterprise) in the Support Help Center

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/recipient_addresses.json \
  -H "Content-Type: application/json" -X POST \
  -d '{"recipient_address": {"name": "Sales", "email": "[email protected]", "default": false, "brand_id": 123 }}' \
  -v -u {email_address}:{password}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/recipient_addresses"
	method := "POST"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/recipient_addresses")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("POST", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'POST',
  url: 'https://example.zendesk.com/api/v2/recipient_addresses',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/recipient_addresses"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"POST",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/recipient_addresses")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

201 Created

// Status 201 Created

{
  "recipient_address": {
    "brand_id": 123,
    "cname_status": "verified",
    "created_at": "2017-04-02T22:55:29Z",
    "default": false,
    "email": "[email protected]",
    "forwarding_status": "waiting",
    "id": 33,
    "name": "Sales",
    "spf_status": "verified",
    "updated_at": "2017-04-02T22:55:29Z"
  }
}

Update Support Address

• PUT /api/v2/recipient_addresses/{support_address_id}

Updates an existing support address for your account.

You can't use this endpoint to update a support address's email property. Instead, you can create a new address using the Create Support Address endpoint.

Allowed For

• Admins
• Agents with permission to manage channels and extensions. See the system permissions in Creating custom roles and assigning agents (Enterprise) in the Support Help Center

Parameters

Name	Type	In	Required	Description
support_address_id	integer	Path	true	The ID of the support address

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/recipient_addresses/{support_address_id}.json \
  -H "Content-Type: application/json" -X PUT \
  -d '{"recipient_address": {"name": "Sales" }}' \
  -v -u {email_address}:{password}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/recipient_addresses/33"
	method := "PUT"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/recipient_addresses/33")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("PUT", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'PUT',
  url: 'https://example.zendesk.com/api/v2/recipient_addresses/33',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/recipient_addresses/33"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"PUT",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/recipient_addresses/33")
request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

{
  "recipient_address": {
    "brand_id": 123,
    "created_at": "2017-04-02T22:55:29Z",
    "default": true,
    "email": "[email protected]",
    "forwarding_status": "verified",
    "id": 33,
    "name": "Sales",
    "updated_at": "2017-05-02T22:55:29Z"
  }
}

Delete Support Address

• DELETE /api/v2/recipient_addresses/{support_address_id}

Deletes a support address.

Allowed For

• Admins
• Agents with permission to manage channels and extensions. See the system permissions in Creating custom roles and assigning agents (Enterprise) in the Support Help Center

Parameters

Name	Type	In	Required	Description
support_address_id	integer	Path	true	The ID of the support address

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/recipient_addresses/{support_address_id}.json \
  -v -u {email_address}:{password} -X DELETE

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/recipient_addresses/33"
	method := "DELETE"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/recipient_addresses/33")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("DELETE", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://example.zendesk.com/api/v2/recipient_addresses/33',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/recipient_addresses/33"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"DELETE",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/recipient_addresses/33")
request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

204 No Content

// Status 204 No Content

null

Verify Support Address Forwarding

• PUT /api/v2/recipient_addresses/{support_address_id}/verify

Sends a test email to the specified support address to verify that email forwarding for the address works. An external support address won't work in Zendesk Support until it's verified.

Note: You don't need to verify Zendesk system support addresses.

The endpoint takes the following body: {"type": "forwarding"}. The value of the type property defaults to "forwarding" if none is specified, but the values "spf" and "dns" are also accepted.

Use this endpoint after adding an external support address to Zendesk Support and setting up forwarding on your email server. See Forwarding incoming email to Zendesk Support.

The endpoint doesn't return the results of the test. Instead, use the Show Support Address endpoint to check that the forwarding_status property is "verified".

Other verification checks can also be performed using this API. These include SPF checks and DNS checks.

When calling the endpoint with type set to "spf", it will queries the DNS records to check that the SPF records for Zendesk are present for outbound emails.

When calling the endpoint with type set to "dns", it runs checks on your CNAME records to make sure they are set up properly in your DNS.

Allowed For

• Admins
• Agents with permission to manage channels and extensions. See the system permissions in Creating custom roles and assigning agents (Enterprise) in the Support Help Center

Parameters

Name	Type	In	Required	Description
support_address_id	integer	Path	true	The ID of the support address

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/recipient_addresses/{support_address_id}/verify.json \
  -H "Content-Type: application/json" -X PUT \
  -d '{"type": "forwarding"}' \
  -v -u {email_address}:{password}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/recipient_addresses/33/verify"
	method := "PUT"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/recipient_addresses/33/verify")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("PUT", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'PUT',
  url: 'https://example.zendesk.com/api/v2/recipient_addresses/33/verify',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/recipient_addresses/33/verify"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"PUT",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/recipient_addresses/33/verify")
request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

null