Accounts-account-email-domain-usernames:GET

GET /accounts/{account}/email/{domain}/usernames

Retrieves a list of mailboxes for a specific account and domain

Request

GET /accounts/{account}/email/{domain}/usernames

Request Parameters

account - string

The user account owning the domain and the mailboxes

domain - string

The specific domain for which the call will retrieve the list

URI Parameters

filterUsername - string

Only mailboxes with username matching the value of the parameter will be returned. The values used could be specified as a partial match with a wildcard(*).

page - integer

Specifies which page should be displayed. Requires a pageSize parameter to also be provided

pageSize - integer

Specifies the number of entries to be displayed on a page. Requires a page parameter to also be provided

sortField - string

Specifies if the resulting list is to be sorted by a given field. Allowed values are username and quota

sortOrder - string

The order in which the sorting is to be done. Allowed values are asc and desc

details - integer

If set to 1 the type of mailbox users will be displayed for each mailbox

Response

Status Code

200 OK

Success

401 Unauthorized

The supplied credentials are invalid or do not provide permissions for this operation.

404 Not Found

The domain name or account does not exist.

Response Body

{
    "totalCount": "{count}",
    "list": [
        {
            "username": "{username}", 
            "webmailAccess": "{webmailAccess}",
            "links": [
                {
                    "href": "{href}",
                    "rel": "{rel}"
                }
            ],
            "type": {type},
            "quota": {quota}, 
            "master": {master}, 
            "trialType": "{trialType}",
            "trialExpiration": "{trialExpiration}",
            "allowUpgrade": {allowUpgrade}
        }
    ],

}
 

Parameters

total count - integer

The total number of mailboxes under the domain

username - string

The username of an individual mailbox

master - integer

Allowed values are 0 or 1

quota - integer

The quota of the mailbox in Megabytes

webmailAccess - string

(OPTIONAL)

The type of webmail of the mailbox. Allowed values can be obtained from the webmailNames API endpoint. Will only be displayed if the user passed the details URI parameter

trialType - string

Trial account type set for a given period of time. Supported values can be obtained from the webmailNames API endpoint.

trialExpiration - date - YYYY-mm-dd

Expiration date of trial period formatted as YYYY-mm-dd.

href - string

Link to other resources relevant to the mailboxes lists

rel - string

Type of relation to the resource for the provided link

Examples

Success scenario

Request

GET accounts/test-account123/email/test.com/usernames
 

Response

{
    "totalCount": 1,
    "list": [
        {
            "username": "test", 
            "links": [
                {
                    "href": "{{APIBaseURL}}/accounts/test-account123/email/test.com/usernames/test/mailbox/",
                    "rel": "self"
                }
            ],
            "type": "imap"
            "quota": 10,
            "master": false, 
            "trialType": "premium",
            "trialExpiration": "2018-10-28",
            "allowUpgrade": true
        }
    ]    
}
 

Request with webmailAccess

Request

GET accounts/test-account123/email/test.com/usernames?details=1
 

Response

{
    "totalCount": 1,
    "list": [
        {
            "username": "test", 
            "webmailAccess": "standard",
            "links": [
                {
                    "href": "{{APIBaseURL}}/accounts/test-account123/email/test.com/usernames/test/mailbox/",
                    "rel": "self"
                }
            ],
            "type": "imap"
            "quota": 10,
            "master": false, 
            "trialType": "premium",
            "trialExpiration": "2018-10-28",
            "allowUpgrade": true
        }
    ]    
}
 

Paginated request with sort order

Request

GET accounts/test-account123/email/test.com/usernames?page=2&pageSize=2&sortField=username&sortOrder=desc
 

Response

{   
    "totalCount": 6,
    "list": [
        {
            "username": "test2", 
            "links": [
                {
                    "href": "{{APIBaseURL}}/accounts/test-account123/email/test.com/usernames/test2/mailbox/",
                    "rel": "self"
                }
            ],
            "type": "imap",
            "quota": 10,
            "master": true, 
            "trialType": "premium",
            "trialExpiration": "2018-10-28",
            "allowUpgrade": true
        },
        {
            "username": "test1", 
            "links": [
                {
                    "href": "{{APIBaseURL}}/accounts/test-account123/email/test.com/usernames/test1/mailbox/",
                    "rel": "self"
                }
            ],
            "type": "imap",
            "quota": 10,
            "master": false, 
            "trialType": "premium",
            "trialExpiration": "2018-10-28",
            "allowUpgrade": true
        }
    ],
    "links": [
        {
            "href": "{{APIBaseURL}}/accounts/test-account123/email/test.com/usernames?page=1&pageSize=2",
            "rel": "first"
        },
        {
            "href": "{{APIBaseURL}}/accounts/test-account123/email/test.com/usernames?page=1&pageSize=2",
            "rel": "previous"
        },
        {
            "href": "{{APIBaseURL}}/accounts/test-account123/email/test.com/usernames?page=3&pageSize=2",
            "rel": "next"
        },
        {
            "href": "{{APIBaseURL}}/accounts/test-account123/email/test.com/usernames?page=3&pageSize=2",
            "rel": "last"
        },
        {
            "href": "{{APIBaseURL}}/accounts/test-account123/email/test.com/usernames?page=2&pageSize=2",
            "rel": "self"
        }
    ]
}
 

See also

• Email API

blog comments powered by Disqus