Create Exchange mailbox

Creates an on-premises Exchange mailbox for a user.

POST ~/api/directoryObjects/exchange/mailbox

Request parameters

This request has no parameters.

Request headers

  • Name

  • Required

  • Description

  • Adm-Authorization

  • True

  • Specify the security token obtained during authentication.

  • Content-Type

  • True

  • Use application/json as the value of this header.

Request body

The request body is a JSON object with the following data structure:

{
    "directoryObject": "<objectId>",
    "mailboxParameters": {
        "alias": "<smtpAlias>",
        "aliasTemplate": "<template>",
        "mailboxStorage": "<databaseId>"
    }
}

directoryObject string

The identifier of the user to create a mailbox for. You can use:

 Distinguished name (DN)
# Example
CN=John Smith,CN=Users,DC=example,DC=com
 Globally unique identifier (GUID)
# Example
7a4267ce-d354-44e7-8bd6-c681f1284a41
 Security identifier (SID)
# Example
S-1-5-21-3635565734-1729062999-1822655016-1627

mailboxParameters

The parameters for creating the mailbox.

 Show attributes

mailboxParameters.alias string

Specify the Exchange alias of the mailbox. This attribute and aliasTemplate are mutually exclusive. If both are specified, alias will take precedence.

mailboxParameters.aliasTemplate string

Specify a template to generate the Exchange alias using value references, for example, %username%. Value references will be replaced with the property values of the user account. This attribute and alias are mutually exclusive. If both are specified, alias will take precedence.

mailboxParameters.mailboxStorage string, optional

The identifier of the database where the mailbox should be created. You can use:

 Distinguished name (DN)
# Example
CN=My Mailbox Database,CN=Databases,CN=Exchange Administrative Group,CN=Administrative Groups,CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=example,DC=com

For details on how to get the distinguished name of the mailbox database, see Get the DN of a mailbox database.

 Globally unique identifier (GUID)
# Example
AFAA697D-345A-4234-973E-B44F4A5E4FD6

If not specified, the database will be automatically selected by Exchange.

Responses

If successful, returns 200 OK status code and an operation result in the response body. Otherwise, returns one of the common HTTP error codes and an error description in the response body.

Examples

 Example 1 – Create a mailbox

The following code sample creates an Exchange mailbox for a user in a database selected by Exchange. The Exchange alias is set to the user's logon name using value references.

Request

PowerShell
$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects/exchange/mailbox"

# Request parameters
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN}
$requestBody = ConvertTo-Json @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "mailboxParameters" = @{"aliasTemplate" = "%username%"}
} 

# Make request
Invoke-RestMethod -Method POST -Headers $requestHeaders -Uri $requestUrl `
    -Body $requestBody -ContentType "application/json"
C#
using System;
using System.Text;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string baseUrl = "https://host.example.com/restApi";
        const string endpoint = "/api/directoryObjects/exchange/mailbox";
        
        // Create JSON request body
        string jsonRequest = @"
        {
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'mailboxParameters': {'aliasTemplate': '%username%'}
        }";
        StringContent requestBody = new(jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN);

        // Make request
        HttpResponseMessage response = await client.PostAsync(
            baseUrl + endpoint, requestBody);
        string responseBody = response.Content.ReadAsStringAsync().Result;
        Console.WriteLine(responseBody);
    }
}
cURL
curl  --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \
--header 'Content-Type: application/json' \
--request POST 'https://host.example.com/restApi/api/directoryObjects/exchange/mailbox' \
--data-raw '{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "mailboxParameters": {
        "aliasTemplate": "%username%"
    }
}'
node.js
var https = require('https');

// Request parameters
var options = {
    'method': 'POST',
    'hostname': 'host.example.com',
    'path': '/restapi/api/directoryObjects/exchange/mailbox',
    'headers': {
        'Adm-Authorization': 'YOUR-SECURITY-TOKEN',
        'Content-Type': 'application/json'
    }
};

// Create JSON request body
var postData = `
{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "mailboxParameters": {"aliasTemplate": "%username%"}
}`;

// Make request
var req = https.request(options, res => {
    var data = [];

    res.on("data", chunk => {
        data.push(chunk);
    });

    res.on("end", () => {
        var body = Buffer.concat(data);
        console.log(body.toString());
    });

    res.on("error", error => {
        console.error(error);
    });
});
req.write(postData);

req.end();
Python
import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects/exchange/mailbox"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": YOUR-SECURITY-TOKEN}
requestBody = {
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "mailboxParameters": {"aliasTemplate": "%username%"}
}

# Make request
request = requests.post(requestUrl, headers=requestHeaders, json=requestBody)
response = json.loads(request.content)
print(response)

Response

HTTP Status code: 200 OK
Response body:

{
    "resultType": 0,
    "innerMessages": [],
    "exception": null,
    "actualObjectDN": "CN=John Smith,CN=Users,DC=example,DC=com",
    "extraInfo": {
        "mailNickname": "jsmith",
        "mail": "jsmith@example.com",
        "homeMDB": "Mailbox Database 3"
    }
}
 Example 2 – Create a mailbox in a specific database

The following code sample creates an Exchange mailbox for a user in the specified database.

Request

PowerShell
$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects/exchange/mailbox"

# Request parameters
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN}
$requestBody = ConvertTo-Json @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "mailboxParameters" = @{
        "alias" = "john.smith";
        "mailboxStorage" = "CN=Mailbox Database 3,CN=Databases,CN=Exchange Administrative Group,CN=Administrative Groups,CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=example,DC=com"
    }
} 

# Make request
Invoke-RestMethod -Method POST -Headers $requestHeaders -Uri $requestUrl `
    -Body $requestBody -ContentType "application/json"
C#
using System;
using System.Text;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string baseUrl = "https://host.example.com/restApi";
        const string endpoint = "/api/directoryObjects/exchange/mailbox";
        
        // Create JSON request body
        string jsonRequest = @"
        {
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'mailboxParameters': {
                'alias': 'john.smith',
                'mailboxStorage': 'CN=Mailbox Database 3,CN=Databases,CN=Exchange Administrative Group,CN=Administrative Groups,CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=example,DC=com'
            }
        }";
        StringContent requestBody = new(jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN);

        // Make request
        HttpResponseMessage response = await client.PostAsync(
            baseUrl + endpoint, requestBody);
        string responseBody = response.Content.ReadAsStringAsync().Result;
        Console.WriteLine(responseBody);
    }
}
cURL
curl  --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \
--header 'Content-Type: application/json' \
--request POST 'https://host.example.com/restApi/api/directoryObjects/exchange/mailbox' \
--data-raw '{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "mailboxParameters": {
        "alias": "john.smith",
        "mailboxStorage": "CN=Mailbox Database 3,CN=Databases,CN=Exchange Administrative Group,CN=Administrative Groups,CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=example,DC=com"
    }
}'
node.js
var https = require('https');

// Request parameters
var options = {
    'method': 'POST',
    'hostname': 'host.example.com',
    'path': '/restapi/api/directoryObjects/exchange/mailbox',
    'headers': {
        'Adm-Authorization': 'YOUR-SECURITY-TOKEN',
        'Content-Type': 'application/json'
    }
};

// Create JSON request body
var postData = `
{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "mailboxParameters": {
        "alias": "john.smith",
        "mailboxStorage": "CN=Mailbox Database 3,CN=Databases,CN=Exchange Administrative Group,CN=Administrative Groups,CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=example,DC=com"
    }
}`;

// Make request
var req = https.request(options, res => {
    var data = [];

    res.on("data", chunk => {
        data.push(chunk);
    });

    res.on("end", () => {
        var body = Buffer.concat(data);
        console.log(body.toString());
    });

    res.on("error", error => {
        console.error(error);
    });
});
req.write(postData);

req.end();
Python
import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects/exchange/mailbox"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": YOUR-SECURITY-TOKEN}
requestBody = {
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "mailboxParameters": {
        "alias": "john.smith",
        "mailboxStorage": "CN=Mailbox Database 3,CN=Databases,CN=Exchange Administrative Group,CN=Administrative Groups,CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=example,DC=com"
    }
}

# Make request
request = requests.post(requestUrl, headers=requestHeaders, json=requestBody)
response = json.loads(request.content)
print(response)

Response

HTTP Status code: 200 OK
Response body:

{
    "resultType": 0,
    "innerMessages": [],
    "exception": null,
    "actualObjectDN": "CN=John Smith,CN=Users,DC=example,DC=com",
    "extraInfo": {
        "mailNickname": "john.smith",
        "mail": "john.smith@example.com",
        "homeMDB": "Mailbox Database 3"
    }
}

See also

© Softerra 2022. All rights reserved.
Send feedback