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

2014-06-24T15:30:53Z

Bozhidar.mihaylov:

= POST accounts/{account}/email/{domain}/usernames/{mailbox}/forwards =
Sets forwarding for specified mailbox,domain and account.

__TOC__

== Request ==
<code>POST accounts/{account}/email/{domain}/usernames/{mailbox}/forwards</code>

=== URI Parameters ===
; account - ''string''
:
; domain - ''string''
:
; mailbox - ''string''
:

=== Request Headers ===
{{Authorization}}

; Content-Type
: Required. Set this header to <code>application/json; charset=UTF-8</code>

=== Request Body ===
<nowiki>
{
"targets": [
{"target": "{target-email}"},
{"target": "{target-email1}"},
]
}
</nowiki>

==== 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.

== Examples ==

=== Failure setting forwarding with missing required parameter ===
'''Request'''
<nowiki>
POST accounts/{account}/email/test.com/usernames/test/forwards

{empty request body}
</nowiki>

'''Response'''
<nowiki>
400 Bad Request

{"targets":"Required"}
</nowiki>

=== Failure setting forwarding by not providing target ===
'''Request'''
<nowiki>
POST accounts/{account}/email/test.com/usernames/test/forwards

{"targets":[]}
</nowiki>

'''Response'''
<nowiki>
400 Bad Request

{"targets": "Shorter than minimum length 1"}
</nowiki>

=== Success setting forwarding ===
'''Request'''
<nowiki>
POST accounts/{account}/email/test.com/usernames/test/forwards

{
"targets": [
{"target": "test-fwd@test.com"}
]
}
</nowiki>

'''Response'''
<nowiki>
204 No Content
</nowiki>

=== Success setting forwards ===
'''Request'''
<nowiki>
POST accounts/{account}/email/test.com/usernames/test/forwards

{
"targets": [
{"target": "test-fwd@test.com"},
{"target": "test-fwd1@test.com"}
]
}
</nowiki>

'''Response'''
<nowiki>
204 No Content
</nowiki>

=== Setting forwarding with local storage ===
In order to have local storage for forwarding, target mailboxes have to be in the same local domain as the source mailbox.<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.
=== Failure setting forwarding to a single mailbox with local storage by setting the source address as the target address ===
'''Request'''
<nowiki>
POST accounts/source_account/email/test.com/usernames/test/forwards

{
"targets": [
{"target": "source-account@test.com"}
]
}
</nowiki>

'''Response'''
<nowiki>
400 Bad Request

{"source-account@test.com": "Is the same as current mailbox"}
</nowiki>

=== Failure setting forwarding to a single mailbox with local storage by providing a non-existing target ===
'''Request'''
<nowiki>
POST accounts/{account}/email/test.com/usernames/test/forwards

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

'''Response'''
<nowiki>
400 Bad Request

{"not-existing-mailbox@test.com": "Target not found"}
</nowiki>

=== Failure setting forwarding to multiple mailboxes with local storage by providing a non-existing target ===
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>
POST accounts/{account}/email/test.com/usernames/test/forwards

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

'''Response'''
<nowiki>
400 Bad Request

{"not-existing-mailbox@test.com": "Target not found"}
</nowiki>

=== Success setting forwarding to a single mailbox without local storage ===
Notice the '''different_domain''' in the request.<br>
'''Request'''
<nowiki>
POST accounts/{account}/email/test.com/usernames/test/forwards

{
"targets": [
{"target": "test-fwd@different_domain.com"}
]
}
</nowiki>

'''Response'''
<nowiki>
204 No Content
</nowiki>

=== Success setting forwarding to multiple mailboxes without local storage ===
'''Request'''<br>
Notice that '''different_domain_1.com''' and '''different_domain_2.com''' are both not test.com.
<nowiki>
POST accounts/{account}/email/test.com/usernames/test/forwards

{
"targets": [
{"target": "test-fwd@different_domain_1.com"},
{"target": "test-fwd1@different_domain_2.com"}
]
}
</nowiki>

'''Response'''
<nowiki>
204 No Content
</nowiki>

== See also ==
* [[Email API|Email API]]

{{disqus}}
[[Category:Hostway API]]
[[Category:Email API]]

Hostway API Documentation - User contributions [en]

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