Revision as of 11:08, 20 August 2014

POST accounts/{account}/email/{domain}/usernames/{mailbox}/forwards

Sets forwarding for specified mailbox,domain and account.

Request

POST accounts/{account}/email/{domain}/usernames/{mailbox}/forwards

URI Parameters

account - string

domain - string

mailbox - string

Request Headers

Authorization - HTTP Authorization header [1]

The Authentication credentials of the client application.

Content-Type

Required. Set this header to application/json; charset=UTF-8

Request Body

{
    "targets": [
        {"target": "{target-email}"},
        {"target": "{target-email1}"},
    ]
}
 

Parameters

targets - list

List of target objects.

target - string

The target mailbox to forward to.

Response

Status Code

204 No Content

Success

400 Bad Request

The format of the request body is invalid or the username does not meet the requirements.

401 Unauthorized

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

404 Not Found

The domain name does not exist.

409 Conflict

The request parameters creates resource conflict.

Examples

Failure when creating a forwarding with missing required parameter

Request

POST accounts/{account}/email/test.com/usernames/test/forwards

{empty request body}
 

Response

400 Bad Request

{"targets":"Required"}
 

Failure when creating a forwarding with an empty list of targets

Request

POST accounts/{account}/email/test.com/usernames/test/forwards

{"targets":[]}
 

Response

400 Bad Request

{"targets": "Shorter than minimum length 1"}
 

Success when creating a forwarding

Request

POST accounts/{account}/email/test.com/usernames/test/forwards

{
    "targets": [
        {"target": "test-fwd@example.com"}
    ]
}
 

Response

204 No Content

Success setting multiple forwarding targets (distribution list)

Request

POST accounts/{account}/email/test.com/usernames/test/forwards

{
    "targets": [
        {"target": "test-fwd@test.com"},
        {"target": "test-fwd1@example.com"}
    ]
}
 

Response

204 No Content

Creating local forwarding or distribution list that contains mailboxes in the source domain

Local forwarding is created when some or all of the target mailboxes are in the same domain as the source mailbox. In case there are such mailboxes certain validation rules are applied that verify the target mailbox existence and that the target mailbox is different than the source.
It is important to note that none of the targets will be created if the validation fails for any of the mailboxes in the list.
That is: a single non-existent local target mailbox in the list will prevent all of the targets from being added regardless of the invalid target position in the list.

Failure when creating forwarding to the same mailbox (avoids forwarding loops)

Request

POST accounts/source_account/email/test.com/usernames/test/forwards

{
    "targets": [
        {"target": "test@test.com"}
    ]
}
 

Response

400 Bad Request

{"test@test.com": "Is the same as current mailbox"}

Failure when creating forwarding to same mailbox on a domain alias

Request

POST accounts/source_account/email/test.com/usernames/test/forwards

{
  "targets": [
    {"target": "test@test-com-alias.com"}
  ]
}
 

Response

409 Conflict

{
    "conflict" : {
	"message" : "Circular target test@test-com-alias.com",
	"code" : 409,
	"details" : ""
    }
}

Failure when creating local forwarding to non-existing mailbox

Request

POST accounts/{account}/email/test.com/usernames/test/forwards

{
    "targets": [
        {"target": "not-existing-mailbox@test.com"}
    ]
}
 

Response

400 Bad Request

{"not-existing-mailbox@test.com": "Target not found"}

Failure when creating a distribution list with a missing local target mailbox

POST accounts/{account}/email/test.com/usernames/test/forwards

{
    "targets": [
        {"target": "existing-mailbox@test.com"},
        {"target": "not-existing-mailbox@test.com"}
    ]
}
 

Response

400 Bad Request

{"not-existing-mailbox@test.com": "Target not found"}

Success creating forwarding to an external mailbox

Notice the different_domain.com in the request is external (different than test.com).
Request

POST accounts/{account}/email/test.com/usernames/test/forwards

{
    "targets": [
        {"target": "test-fwd@different-domain.com"}
    ]
}
 

Response

204 No Content

Success creating forwarding to multiple external mailboxes (distribution list)

Request
Notice that different_domain_1.com and different_domain_2.com are both different than test.com.

POST accounts/{account}/email/test.com/usernames/test/forwards

{
    "targets": [
        {"target": "test-fwd@different-domain_1.com"},
        {"target": "test-fwd1@different-domain_2.com"}
    ]
}
 

Response

204 No Content

See also

• Email API