Preferences

Base Path: /actor/current/webmail/DIRECT/mailboxes/{mailboxAddress}/preferences

Version: 3.5.0

Preferences make it easy for your subscribers to manage their email by providing them with a centralized place to control how they send and receive messages. You can configure the following settings in your preferences:

  • Auto-forward: Any message you receive can be automatically forwarded to a group of contacts.

  • Auto-reply: Automatically respond to your emails when you are away from the office.

  • Mailbox sharing: Authorize other users to manage your incoming and outgoing mail.

  • Message rules: Use rules to decide what happens to emails when they arrive. If more than one rule applies to a message, the first rule in the list is used.

  • Signature: Create a signature that can be automatically appended to the messages you send.

Authorization: OAuth 2.0 Bearer token is required to access the resources of this API. Once signed up, credentials and URL to access the OAuth API can be found on My Apps Page.

Methods

Retrieve mail preferences

GET /actor/current/webmail/DIRECT/mailboxes/{mailboxAddress}/preferences/

Retrieves the mail settings for a user's personal mailbox.

Parameters

Name

Type

Data Type

Description

Name:

mailboxAddress

required

Type:

path

Data Type:

string

Description:

URL-encoded address of the mailbox.


Sample Value: developer.portal@example.com

Responses

application/json+fhir

200

Successfully retrieved the user's mail preferences.

application/json+fhir

401

Your API key or access token has expired or is invalid.

Sample Request

curl -X GET "https://api.orionhealth.io/actor/current/webmail/DIRECT/mailboxes/developer.portal@example.com/preferences/" \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Access Token>'

Update mail preferences

PUT /actor/current/webmail/DIRECT/mailboxes/{mailboxAddress}/preferences/

Updates the mail settings for a user's personal mailbox.

Parameters

Name

Type

Data Type

Description

Name:

body

required

Type:

body

Data Type:

Description:

Body of the request.

Sample Payload: 

{
  "mailboxAddress": "developer.portal@example.com",
  "sharedMailboxes": [],
  "autoReplyMessage": "Test auto-reply",
  "messageSignature": "
signature
",
  "filters": [
    {
      "conditions": [
        {
          "type": "senderMatches",
          "address": "junior@ma.direct.test"
        }
      ],
      "actions": [
        {
          "type": "fileIntoFolder",
          "path": "INBOX.AA"
        }
      ]
    },
    {
      "conditions": [
        {
          "type": "subjectContains",
          "searchString": "junior"
        }
      ],
      "actions": [
        {
          "type": "fileIntoFolder",
          "path": "Trash"
        }
      ]
    }
  ],
  "autoForwardGroup": "24",
  "sharedUsers": [
    "shared@example.com"
  ],
  "sharingType": "DELEGATED",
  "sharedMailboxOn": true,
  "autoReplyOn": true,
  "messageSignatureOn": true,
  "autoForwardOn": true
}


Name:

mailboxAddress

required

Type:

path

Data Type:

string

Description:

URL-encoded address of the mailbox.


Sample Value: developer.portal@example.com

Responses

application/json+fhir

200

Successfully updated the user's mail preferences.

application/json+fhir

400

Encountered an error while updating the user's mail preferences, because one or more of the following occurred:

  • We received an unexpected value for autoReplyOn, autoForwardOn, messageSignatureOn or sharedMailboxOn.

  • The contactGroupId is invalid.

  • The folder name or path is invalid.

  • One or more Direct email addresses are invalid.

application/json+fhir

401

Your API key or access token has expired or is invalid.

Sample Request

curl -X PUT "https://api.orionhealth.io/actor/current/webmail/DIRECT/mailboxes/developer.portal@example.com/preferences/" \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Access Token>' \
-H 'Content-Type: application/json' \
-d '{"mailboxAddress":"developer.portal@example.com","sharedMailboxes":[],"autoReplyMessage":"Test auto-reply","messageSignature":"<p>signature</p>","filters":[{"conditions":[{"type":"senderMatches","address":"junior@ma.direct.test"}],"actions":[{"type":"fileIntoFolder","path":"INBOX.AA"}]},{"conditions":[{"type":"subjectContains","searchString":"junior"}],"actions":[{"type":"fileIntoFolder","path":"Trash"}]}],"autoForwardGroup":"24","sharedUsers":["shared@example.com"],"sharingType":"DELEGATED","sharedMailboxOn":true,"autoReplyOn":true,"messageSignatureOn":true,"autoForwardOn":true}'

Find provider (mailbox sharing)

POST /actor/current/webmail/DIRECT/mailboxes/{mailboxAddress}/preferences/search

Finds users you can share your mailbox with.

Parameters

Name

Type

Data Type

Description

Name:

body

required

Type:

body

Data Type:

Description:

Body of the request.

Sample Payload: 

{
  "searchString": "search",
  "maxResult": 15
}


Name:

mailboxAddress

required

Type:

path

Data Type:

string

Description:

URL-encoded address of the mailbox.


Sample Value: developer.portal@example.com

Responses

application/json+fhir

200

We found a list of providers that match your search criteria.

application/json+fhir

400

Your request was invalid. A parameter, or the data in a parameter, may be incorrect.

application/json+fhir

401

Your API key or access token has expired or is invalid.

Sample Request

curl -X POST "https://api.orionhealth.io/actor/current/webmail/DIRECT/mailboxes/developer.portal@example.com/preferences/search" \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Access Token>' \
-H 'Content-Type: application/json' \
-d '{"searchString":"search","maxResult":15}'

Retrieve auto-reply

GET /actor/current/webmail/DIRECT/mailboxes/{mailboxAddress}/preferences/autoReply

Retrieves the user's automatic reply setting.

Parameters

Name

Type

Data Type

Description

Name:

mailboxAddress

required

Type:

path

Data Type:

string

Description:

URL-encoded address of the mailbox.


Sample Value: developer.portal@example.com

Responses

application/json+fhir

200

Successfully retrieved the user's automatic reply setting.

application/json+fhir

401

Your API key or access token has expired or is invalid.

Sample Request

curl -X GET "https://api.orionhealth.io/actor/current/webmail/DIRECT/mailboxes/developer.portal@example.com/preferences/autoReply" \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Access Token>'

Update auto-reply

POST /actor/current/webmail/DIRECT/mailboxes/{mailboxAddress}/preferences/autoReply

Updates the user's automatic reply setting.

Parameters

Name

Type

Data Type

Description

Name:

body

required

Type:

body

Data Type:

Description:

Body of the request.

Sample Payload: 

{
  "autoReplyOn": true,
  "autoReplyMessage": "I am not in office"
}


Name:

mailboxAddress

required

Type:

path

Data Type:

string

Description:

URL-encoded address of the mailbox.


Sample Value: developer.portal@example.com

Responses

application/json+fhir

200

Successfully updated the user's automatic reply setting.

application/json+fhir

400

Encountered an error while updating the user's automatic reply setting, because we received an unexpected value for autoReplyOn.

application/json+fhir

401

Your API key or access token has expired or is invalid.

Sample Request

curl -X POST "https://api.orionhealth.io/actor/current/webmail/DIRECT/mailboxes/developer.portal@example.com/preferences/autoReply" \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Access Token>' \
-H 'Content-Type: application/json' \
-d '{"autoReplyOn":true,"autoReplyMessage":"I am not in office"}'

Retrieve auto-forward

GET /actor/current/webmail/DIRECT/mailboxes/{mailboxAddress}/preferences/autoForward

Retrieves the user's automatic forward setting.

Parameters

Name

Type

Data Type

Description

Name:

mailboxAddress

required

Type:

path

Data Type:

string

Description:

URL-encoded address of the mailbox.


Sample Value: developer.portal@example.com

Responses

application/json+fhir

200

Successfully retrieved the user's automatic forward setting.

application/json+fhir

401

Your API key or access token has expired or is invalid.

Sample Request

curl -X GET "https://api.orionhealth.io/actor/current/webmail/DIRECT/mailboxes/developer.portal@example.com/preferences/autoForward" \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Access Token>'

Update auto-forward

POST /actor/current/webmail/DIRECT/mailboxes/{mailboxAddress}/preferences/autoForward

Updates the user's automatic forward setting.

Parameters

Name

Type

Data Type

Description

Name:

body

required

Type:

body

Data Type:

Description:

Body of the request.

Sample Payload: 

{
  "autoForwardOn": true,
  "autoForwardGroup": 7
}


Name:

mailboxAddress

required

Type:

path

Data Type:

string

Description:

URL-encoded address of the mailbox.


Sample Value: developer.portal@example.com

Responses

application/json+fhir

200

Successfully updated the user's automatic forward setting.

application/json+fhir

400

Encountered an error while updating the user's automatic forward setting, either because we received an unexpected value for autoForwardOn, or the contactGroupId is invalid.

application/json+fhir

401

Your API key or access token has expired or is invalid.

Sample Request

curl -X POST "https://api.orionhealth.io/actor/current/webmail/DIRECT/mailboxes/developer.portal@example.com/preferences/autoForward" \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Access Token>' \
-H 'Content-Type: application/json' \
-d '{"autoForwardOn":true,"autoForwardGroup":7}'

Retrieve signature

GET /actor/current/webmail/DIRECT/mailboxes/{mailboxAddress}/preferences/messageSignature

Retrieves the user's personalized signature.

Parameters

Name

Type

Data Type

Description

Name:

mailboxAddress

required

Type:

path

Data Type:

string

Description:

URL-encoded address of the mailbox.


Sample Value: developer.portal@example.com

Responses

application/json+fhir

200

Successfully retrieved the user's signature.

application/json+fhir

401

Your API key or access token has expired or is invalid.

Sample Request

curl -X GET "https://api.orionhealth.io/actor/current/webmail/DIRECT/mailboxes/developer.portal@example.com/preferences/messageSignature" \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Access Token>'

Update signature

POST /actor/current/webmail/DIRECT/mailboxes/{mailboxAddress}/preferences/messageSignature

Updates the user's personalized signature.

Parameters

Name

Type

Data Type

Description

Name:

body

required

Type:

body

Data Type:

Description:

Body of the request.

Sample Payload: 

{
  "messageSignatureOn": true,
  "messageSignature": "Example Signature"
}


Name:

mailboxAddress

required

Type:

path

Data Type:

string

Description:

URL-encoded address of the mailbox.


Sample Value: developer.portal@example.com

Responses

application/json+fhir

200

Successfully updated the user's signature.

application/json+fhir

400

Encountered an error while updating the user's signature, because we received an unexpected value for messageSignatureOn.

application/json+fhir

401

Your API key or access token has expired or is invalid.

Sample Request

curl -X POST "https://api.orionhealth.io/actor/current/webmail/DIRECT/mailboxes/developer.portal@example.com/preferences/messageSignature" \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Access Token>' \
-H 'Content-Type: application/json' \
-d '{"messageSignatureOn":true,"messageSignature":"Example Signature"}'

Retrieve message rules

GET /actor/current/webmail/DIRECT/mailboxes/{mailboxAddress}/preferences/messageRules

Retrieves the rules for the user's personal mailbox. Rules are used to take actions such as moving a message to a specified folder, or deleting a message.

Parameters

Name

Type

Data Type

Description

Name:

mailboxAddress

required

Type:

path

Data Type:

string

Description:

URL-encoded address of the mailbox.


Sample Value: developer.portal@example.com

Responses

application/json+fhir

200

Successfully retrieved the rules for the specified mailbox.

application/json+fhir

401

Your API key or access token has expired or is invalid.

Sample Request

curl -X GET "https://api.orionhealth.io/actor/current/webmail/DIRECT/mailboxes/developer.portal@example.com/preferences/messageRules" \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Access Token>'

Update message rules

POST /actor/current/webmail/DIRECT/mailboxes/{mailboxAddress}/preferences/messageRules

Updates the rules for the user's personal mailbox.

Parameters

Name

Type

Data Type

Description

Name:

body

optional

Type:

body

Data Type:

Description:

Body of the request.

Sample Payload: 

{
  "filters": [
    {
      "conditions": [
        {
          "type": "senderMatches",
          "address": "dsa@dsa"
        }
      ],
      "actions": [
        {
          "type": "fileIntoFolder",
          "path": "INBOX.sender"
        }
      ]
    },
    {
      "conditions": [
        {
          "type": "subjectContains",
          "searchString": "sa"
        }
      ],
      "actions": [
        {
          "type": "fileIntoFolder",
          "path": "INBOX.subject"
        }
      ]
    }
  ]
}


Name:

mailboxAddress

required

Type:

path

Data Type:

string

Description:

URL-encoded address of the mailbox.


Sample Value: developer.portal@example.com

Responses

application/json+fhir

200

Successfully updated the rules for the specified mailbox.

application/json+fhir

400

Encountered an error while updating the rules for the specified mailbox, because the folder name or path is invalid.

application/json+fhir

401

Your API key or access token has expired or is invalid.

Sample Request

curl -X POST "https://api.orionhealth.io/actor/current/webmail/DIRECT/mailboxes/developer.portal@example.com/preferences/messageRules" \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Access Token>' \
-H 'Content-Type: application/json' \
-d '{"filters":[{"conditions":[{"type":"senderMatches","address":"dsa@dsa"}],"actions":[{"type":"fileIntoFolder","path":"INBOX.sender"}]},{"conditions":[{"type":"subjectContains","searchString":"sa"}],"actions":[{"type":"fileIntoFolder","path":"INBOX.subject"}]}]}'

Retrieve mailbox sharing

GET /actor/current/webmail/DIRECT/mailboxes/{mailboxAddress}/preferences/mailboxSharing

Retrieves the mailbox sharing preferences of the user.

Parameters

Name

Type

Data Type

Description

Name:

mailboxAddress

required

Type:

path

Data Type:

string

Description:

URL-encoded address of the mailbox.


Sample Value: developer.portal@example.com

Responses

application/json+fhir

200

Successfully retrieved the mailbox sharing setting for the specified account.

application/json+fhir

401

Your API key or access token has expired or is invalid.

Sample Request

curl -X GET "https://api.orionhealth.io/actor/current/webmail/DIRECT/mailboxes/developer.portal@example.com/preferences/mailboxSharing" \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Access Token>'

Update mailbox sharing

POST /actor/current/webmail/DIRECT/mailboxes/{mailboxAddress}/preferences/mailboxSharing

Updates the mailbox sharing preferences of the user.

Parameters

Name

Type

Data Type

Description

Name:

body

required

Type:

body

Data Type:

Description:

Body of the request.

Sample Payload: 

{
  "sharedMailboxOn": true,
  "sharedUsers": [
    "Shared User "
  ]
}


Name:

mailboxAddress

required

Type:

path

Data Type:

string

Description:

URL-encoded address of the mailbox.


Sample Value: developer.portal@example.com

Responses

application/json+fhir

200

Successfully updated the mailbox sharing setting for the specified account.

application/json+fhir

400

Encountered an error while updating the user's mailbox sharing preference, either because we received an unexpected value for sharedMailboxOn, or one of the Direct email addresses is invalid.

application/json+fhir

401

Your API key or access token has expired or is invalid.

Sample Request

curl -X POST "https://api.orionhealth.io/actor/current/webmail/DIRECT/mailboxes/developer.portal@example.com/preferences/mailboxSharing" \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Access Token>' \
-H 'Content-Type: application/json' \
-d '{"sharedMailboxOn":true,"sharedUsers":["Shared User <shared.user@example.com>"]}'