Accounts-account-email-domain-usernames-mailboxName-forwards:POST

(Difference between revisions)
Jump to: navigation, search
m (1 revision: Release 96)
(→Failure when creating forwarding to the same mailbox (avoids forwarding loops))
Line 54: Line 54:
 
; 404 Not Found
 
; 404 Not Found
 
: The domain name does not exist.
 
: The domain name does not exist.
 +
 +
; 409 Conflict
 +
: Create of the forwarder would produce an impossible to delivery loops namely:
 +
:# the usernames on the forward source and target are the same, '''and''': 
 +
:## the domains on the source is an alias of the target's domain name, '''or'''
 +
:## the domains on the target is an alias of the source's domain name
  
 
== Examples ==
 
== Examples ==
  
−
=== Failure setting forwarding with missing required parameter ===
+
=== Failure when creating a forwarding with missing required parameter ===
 
'''Request'''
 
'''Request'''
 
  <nowiki>
 
  <nowiki>
Line 72: Line 78:
 
  </nowiki>
 
  </nowiki>
  
−
 
+
=== Failure when creating a forwarding with an empty list of targets ===
−
=== Failure setting forwarding by not providing target ===
+
 
'''Request'''
 
'''Request'''
 
  <nowiki>
 
  <nowiki>
Line 88: Line 93:
 
  </nowiki>
 
  </nowiki>
  
−
=== Success setting forwarding ===
+
=== Success when creating a forwarding ===
 
'''Request'''
 
'''Request'''
 
  <nowiki>
 
  <nowiki>
Line 95: Line 100:
 
{
 
{
 
     "targets": [
 
     "targets": [
−
         {"target": "test-fwd@test.com"}
+
         {"target": "test-fwd@example.com"}
 
     ]
 
     ]
 
}
 
}
Line 105: Line 110:
 
</nowiki>
 
</nowiki>
  
−
 
+
=== Success setting multiple forwarding targets (distribution list) ===
−
=== Success setting forwards ===
+
 
'''Request'''
 
'''Request'''
 
  <nowiki>
 
  <nowiki>
Line 114: Line 118:
 
     "targets": [
 
     "targets": [
 
         {"target": "test-fwd@test.com"},
 
         {"target": "test-fwd@test.com"},
−
         {"target": "test-fwd1@test.com"}
+
         {"target": "test-fwd1@example.com"}
 
     ]
 
     ]
 
}
 
}
Line 124: Line 128:
 
</nowiki>
 
</nowiki>
  
−
=== Setting forwarding with local storage ===
+
=== Creating local forwarding or distribution list that contains mailboxes in the source domain ===
−
In order to have local storage for forwarding, target mailboxes have to be in the same local domain as the source mailbox.<br>
+
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.<br/>
−
So the previous two examples of successful setup of forwarding are showing how to setup forwarding with local storage for respectively one and multiple target mailboxes.
+
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.<br/>
−
=== Failure setting forwarding to a single mailbox with local storage by setting the source address as the target address ===
+
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'''
 
'''Request'''
 
  <nowiki>
 
  <nowiki>
Line 134: Line 140:
 
{
 
{
 
     "targets": [
 
     "targets": [
−
         {"target": "source-account@test.com"}
+
         {"target": "test@test.com"}
 
     ]
 
     ]
 
}
 
}
Line 143: Line 149:
 
400 Bad Request
 
400 Bad Request
  
−
{"source-account@test.com": "Is the same as current mailbox"}
+
{"test@test.com": "Is the same as current mailbox"}
 +
</nowiki>
 +
 
 +
=== Failure when creating forwarding to same mailbox on a domain alias ===
 +
'''Request'''
 +
<nowiki>
 +
POST accounts/source_account/email/test.com/usernames/test/forwards
 +
 
 +
{
 +
  "targets": [
 +
    {"target": "test@test-com-alias.com"}
 +
  ]
 +
}
 +
</nowiki>
 +
 
 +
'''Response'''
 +
<nowiki>
 +
409 Conflict
 +
 
 +
{
 +
    "conflict" : {
 +
"message" : "Circular target test@test-com-alias.com",
 +
"code" : 409,
 +
"details" : ""
 +
    }
 +
}
 
</nowiki>
 
</nowiki>
  
−
=== Failure setting forwarding to a single mailbox with local storage by providing a non-existing target ===
+
=== Failure when creating local forwarding to non-existing mailbox ===
 
'''Request'''
 
'''Request'''
 
  <nowiki>
 
  <nowiki>
Line 165: Line 196:
 
</nowiki>
 
</nowiki>
  
−
=== Failure setting forwarding to multiple mailboxes with local storage by providing a non-existing target ===
+
=== Failure when creating a distribution list with a missing local target mailbox ===
−
It is important to know that either '''all or none''' of the targets will be set-up for forwarding.<br>
+
−
That is: a single non-existant mailbox in the targets list will prevent all of the targets from being added irrespective of it's position in the targets list.
+
 
  <nowiki>
 
  <nowiki>
 
POST accounts/{account}/email/test.com/usernames/test/forwards
 
POST accounts/{account}/email/test.com/usernames/test/forwards
Line 186: Line 215:
 
</nowiki>
 
</nowiki>
  
−
=== Success setting forwarding to a single mailbox without local storage ===
+
=== Success creating forwarding to an external mailbox ===
−
Notice the '''different_domain''' in the request.<br>
+
Notice the '''different_domain.com''' in the request is external (different than '''test.com''').<br>
 
'''Request'''
 
'''Request'''
 
  <nowiki>
 
  <nowiki>
Line 194: Line 223:
 
{
 
{
 
     "targets": [
 
     "targets": [
−
         {"target": "test-fwd@different_domain.com"}
+
         {"target": "test-fwd@different-domain.com"}
 
     ]
 
     ]
 
}
 
}
Line 204: Line 233:
 
</nowiki>
 
</nowiki>
  
−
=== Success setting forwarding to multiple mailboxes without local storage ===
+
=== Success creating forwarding to multiple external mailboxes (distribution list) ===
 
'''Request'''<br>
 
'''Request'''<br>
−
Notice that '''different_domain_1.com''' and '''different_domain_2.com''' are both not test.com.
+
Notice that '''different_domain_1.com''' and '''different_domain_2.com''' are both different than '''test.com'''.
 
  <nowiki>
 
  <nowiki>
 
POST accounts/{account}/email/test.com/usernames/test/forwards
 
POST accounts/{account}/email/test.com/usernames/test/forwards
Line 212: Line 241:
 
{
 
{
 
     "targets": [
 
     "targets": [
−
         {"target": "test-fwd@different_domain_1.com"},
+
         {"target": "test-fwd@different-domain_1.com"},
−
         {"target": "test-fwd1@different_domain_2.com"}
+
         {"target": "test-fwd1@different-domain_2.com"}
 
     ]
 
     ]
 
}
 
}

Revision as of 10:20, 14 August 2014

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

Sets forwarding for specified mailbox,domain and account.

Contents


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
Create of the forwarder would produce an impossible to delivery loops namely:
  1. the usernames on the forward source and target are the same, and:
    1. the domains on the source is an alias of the target's domain name, or
    2. the domains on the target is an alias of the source's domain name

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


blog comments powered by Disqus

Retrieved from "http://docs.hostway.com/index.php?title=Accounts-account-email-domain-usernames-mailboxName-forwards:POST&oldid=1603"
Personal tools
Namespaces
Variants
Actions
APIs
Navigation
Toolbox