1. Authentication

All API requests require an authentication.
If authentication is invalid or omitted, then an error message will be returned with 401 status code.

Bearer authentication requires the generation of a token that you can create in "Access tokens" section of Cleanmail account.
Token will inherit of roles of the linked account.

curl -H "Authorization: Bearer xxxx" [url]
# replace xxxx by the token generated in your administration interface

The bearer authentication has no link with the account password.
You can update your password without consequence on your tokens.
You can create one token for each application with or without expiration dates.
If the account attached to the token is disabled or deleted, the requests will be rejected.

2. Authorizations

Each request is subject to specific rights.
Calling an API authenticated with an account which do not have required permissions will return a 403 error.
List of enabled permissions are contained in roles entities.
If new roles can be created on a specific domains for customization issues, some of them are predefined on the platform and reachable for all domains.

3. Filtering and sorting

Some of GET requests allow you to filter and sort the query result.

3.1. Filtering

Add a parameter to your query to filter the result of your request. Only one filter is allowed.

Example:

  • GET /domains?name=mydomain.net - Retrieve a domain whose name is exactly "mydomain.net"

  • GET /domains?name=mydomain* - Retrieve a list of domains whose name starts with "mydomain"

  • GET /domains?name=*mydomain - Retrieve a list of domains whose name ends with "mydomain"

  • GET /domains?name=*mydomain* - Retrieve a list of domains whose name contains "mydomain"

3.2. Sorting

A generic parameter sort can be used to describe sorting rules. Specify the field name that you want to use for sorting the result and prefix it by negative sign to reverse order.

Example:

  • GET /domains?sort=-name - Retrieves a list of domains in descending order of name

  • GET /domains?sort=id - Retrieves a list of domains in ascending order of id

4. Pagination

You can paginate your GET requests by passing additional offset and pageSize parameters in your query.
The count of the total number of available results is send in a x-total-count header of the response.

Example:

  • GET domains?offset=0&pageSize=10 - Retrieve the list of the 10 firsts domains

5. Endpoints

5.1. AccessControls

5.1.1. Delete admin account

DELETE /security/admins/{adminId}

Description

Delete administrator account and all its accesses.

Parameters
Path Parameters
Name Description Required Default Pattern

adminId

X

null
Return Type

[String]

Content Type

  • /

Responses
Table 1. HTTP Response Codes
Code Message Datatype

200

OK

[String]
Example HTTP request
Example Curl request
Example HTTP response

5.1.2. List admins

GET /security/admins

Description

Get list of administrators of domains, customers or brokers on which the logged-in user has the GRANT permission.

Parameters
Query Parameters
Name Description Required Default Pattern

offset

-

0

pageSize

-

40

sort

Define the sort applied on response. Prefix the field login by '-' to reverse the sort.

-

null

search

Filter by login, email, displayName

-

null
Return Type

array[Admin]

Content Type

  • /

Responses
Table 2. HTTP Response Codes
Code Message Datatype

200

OK

List[Admin]
Example HTTP request
Example Curl request
Example HTTP response

5.1.3. Get admin

GET /security/admins/{adminId}

Description

Get administrator account and all the associated permissions.

Parameters
Path Parameters
Name Description Required Default Pattern

adminId

X

null
Return Type

Admin

Content Type

  • /

Responses
Table 3. HTTP Response Codes
Code Message Datatype

200

OK

Admin
Example HTTP request
Example Curl request
Example HTTP response

5.1.4. List permissions

GET /security/permissions

Description

List all permissions which can be assigned to an administrator for a given scope. The returned permissions are limited to the current user’s permissions on the given object.

Parameters
Query Parameters
Name Description Required Default Pattern

scope

Restrict the list of permissions by scope.

X

null

id

X

null
Return Type

array[PermissionDTO]

Content Type

  • application/json

Responses
Table 4. HTTP Response Codes
Code Message Datatype

200

OK

List[PermissionDTO]
Example HTTP request
Example Curl request
Example HTTP response

5.1.5. Update admin

PATCH /security/admins/{adminId}

Description

Update an existing administrator account.

Parameters
Path Parameters
Name Description Required Default Pattern

adminId

X

null
Body Parameter
Name Description Required Default Pattern

AdminUpdate

AdminUpdate

X
Return Type

Admin

Content Type

  • /

Responses
Table 5. HTTP Response Codes
Code Message Datatype

200

OK

Admin
Example HTTP request
Example Curl request
Example HTTP response

5.2. AuthenticationTokens

5.2.1. Create token

POST /admins/{adminId}/tokens

Description

Create an authentication token for a give user.

Parameters
Path Parameters
Name Description Required Default Pattern

adminId

X

null
Body Parameter
Name Description Required Default Pattern

PersonalTokenAdd

PersonalTokenAdd

X
Return Type

-

Content Type

  • application/json

Responses
Table 6. HTTP Response Codes
Code Message Datatype

403

Only sysadmin or target user can call this endpoint.

PersonalToken

404

Resource does not exist.

PersonalToken
Example HTTP request
POST /admins/ByE3n/tokens HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY3MCwiZXhwIjoxNzgxNzgxMjcwfQ.pVMYXjzDG35JxK3LcSUQtx0n1BSIZTJallVgHwtHwCa64EDtDPP6h_3IlFbnGoKHAd08c4cNIVFytdKRAVq0ig
Content-Length: 45
Host: localhost:8080

{"name":"mytoken","expiration":1813313670967}
Example Curl request
$ curl 'http://localhost:8080/admins/ByE3n/tokens' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY3MCwiZXhwIjoxNzgxNzgxMjcwfQ.pVMYXjzDG35JxK3LcSUQtx0n1BSIZTJallVgHwtHwCa64EDtDPP6h_3IlFbnGoKHAd08c4cNIVFytdKRAVq0ig' \
    -d '{"name":"mytoken","expiration":1813313670967}'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 153

{
  "id" : "ByE3n",
  "name" : "mytoken",
  "value" : "7d69d40ed1a02af826c7cfeff7c71333",
  "expiration" : 1813313670967,
  "createdAt" : 1781777670988
}

5.2.2. List of user’s tokens

GET /admins/{adminId}/tokens

Description

Returns the list of administrator’s tokens. Tokens' values are not reachable after creation.

Parameters
Path Parameters
Name Description Required Default Pattern

adminId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 7. HTTP Response Codes
Code Message Datatype

403

Only sysadmin or target user can call this endpoint.

List[PersonalToken]

404

Resource does not exist.

List[PersonalToken]
Example HTTP request
GET /admins/ByE3n/tokens HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY2OSwiZXhwIjoxNzgxNzgxMjY5fQ.cAal2VxT9Lb8rObLwsFPM5ZCepWBcXs0sJCZlSr0zXmFseBQQ9S1BYwcNqaMY0rdhsDh5cAwkBI6GlG72_u22g
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/admins/ByE3n/tokens' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY2OSwiZXhwIjoxNzgxNzgxMjY5fQ.cAal2VxT9Lb8rObLwsFPM5ZCepWBcXs0sJCZlSr0zXmFseBQQ9S1BYwcNqaMY0rdhsDh5cAwkBI6GlG72_u22g'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 185

[ {
  "id" : "ByE3n",
  "name" : "mytoken",
  "expiration" : 1813313669000,
  "createdAt" : 1781777669000
}, {
  "id" : "By46n",
  "name" : "mytoken2",
  "createdAt" : 1781777669000
} ]

5.2.3. Delete a token

DELETE /admins/{adminId}/tokens/{id}

Description

Revoke a token of a given admin.

Parameters
Path Parameters
Name Description Required Default Pattern

adminId

X

null

id

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 8. HTTP Response Codes
Code Message Datatype

403

Only sysadmin or target user can call this endpoint.

[String]

404

Resource does not exist.

[String]
Example HTTP request
DELETE /admins/ByE3n/tokens/ByE3n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY2OCwiZXhwIjoxNzgxNzgxMjY4fQ.o_EtpARJvX1pKGFD9msJEYyvXbBZ-SJUGDmtZ41f8pNb0BGCAItGbcGrv4yaVREX3pdUq5vVaUvuca_1TkaIAw
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/admins/ByE3n/tokens/ByE3n' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY2OCwiZXhwIjoxNzgxNzgxMjY4fQ.o_EtpARJvX1pKGFD9msJEYyvXbBZ-SJUGDmtZ41f8pNb0BGCAItGbcGrv4yaVREX3pdUq5vVaUvuca_1TkaIAw'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.3. DomainAliases

5.3.1. Add domain alias

POST /domains/{domainId}/aliases

Description

Add new names to the existing aliases list. Returns the list of added elements

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Body Parameter
Name Description Required Default Pattern

string

[string]

X
Return Type

-

Content Type

  • application/json

Responses
Table 9. HTTP Response Codes
Code Message Datatype

404

A problem occured. The domain may not exist

List[Alias]

403

You do not have permission to execute this request.

List[Alias]

409

An alias or a domain may already exists with the given name

List[Alias]
Example HTTP request
POST /domains/Eygdk/aliases HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU1OCwiZXhwIjoxNzgxNzgxMTU4fQ.e_LKyOcsMnaVKXwZtQ09o7HX4_QmOjtaa4kFqqdOYTxrR2R_w9-iiWE4qFR53eWPyCuvUz5-yO4eUgKJURQaRQ
Content-Length: 27
Host: localhost:8080

["starks.net","wolves.net"]
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/aliases' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU1OCwiZXhwIjoxNzgxNzgxMTU4fQ.e_LKyOcsMnaVKXwZtQ09o7HX4_QmOjtaa4kFqqdOYTxrR2R_w9-iiWE4qFR53eWPyCuvUz5-yO4eUgKJURQaRQ' \
    -d '["starks.net","wolves.net"]'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: Content-Location
Location: http://localhost:8080/domains/Eygdk/aliases
Content-Type: application/json
Content-Length: 96

[ {
  "id" : "ByE3n",
  "name" : "starks.net"
}, {
  "id" : "By46n",
  "name" : "wolves.net"
} ]

5.3.2. Delete a domain alias

DELETE /domains/{domainId}/aliases/{aliasId}

Description

Delete an alias using its ID.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null

aliasId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 10. HTTP Response Codes
Code Message Datatype

400

A problem occured. Possible cause: at least one parameter might not match required format

AdressAlias

403

You do not have permission to execute this request.

AdressAlias

404

A problem occured. The domain and/or the alias may not exist

AdressAlias
Example HTTP request
DELETE /domains/Eygdk/aliases/ByE3n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU1NiwiZXhwIjoxNzgxNzgxMTU2fQ.mhTAELKO_xArU0sdur1gpxuwS27v6MhSwXEkJGNZ_pDbtOm1cV8xrezUb0dvK3AG23vWzREYCSWgS08dzSlltQ
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/aliases/ByE3n' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU1NiwiZXhwIjoxNzgxNzgxMTU2fQ.mhTAELKO_xArU0sdur1gpxuwS27v6MhSwXEkJGNZ_pDbtOm1cV8xrezUb0dvK3AG23vWzREYCSWgS08dzSlltQ'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.3.3. List domain aliases

GET /domains/{domainId}/aliases

Description

Returns the aliases lists of the domain

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Query Parameters
Name Description Required Default Pattern

sort

Define the sort applied on response. Prefix the field name by '-' to reverse the sort.

-

null

offset

Index of the first alias to return, defaults to 0

-

null

pageSize

Maximum number of aliases returned, defaults to 40

-

null
Return Type

-

Content Type

  • application/json

Responses
Table 11. HTTP Response Codes
Code Message Datatype

404

A problem occured. The domain may not exist

List[Alias]

403

You do not have permission to execute this request.

List[Alias]
Example HTTP request
GET /domains/Eygdk/aliases HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU2MSwiZXhwIjoxNzgxNzgxMTYxfQ.x7zh0kg0UdZntrRvdvHQMeE4q6apCqsO0KzkkgVMFk5RPdIOBwDGml4rstwQrwFH_uE_9GpqYrWjdX74AQ72DQ
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/aliases' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU2MSwiZXhwIjoxNzgxNzgxMTYxfQ.x7zh0kg0UdZntrRvdvHQMeE4q6apCqsO0KzkkgVMFk5RPdIOBwDGml4rstwQrwFH_uE_9GpqYrWjdX74AQ72DQ'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: X-Total-Count
X-Total-Count: 2
Content-Type: application/json
Content-Length: 98

[ {
  "id" : "ByE3n",
  "name" : "lanisters.net"
}, {
  "id" : "By46n",
  "name" : "lions.net"
} ]

5.3.4. Edit domain aliases

PUT /domains/{domainId}/aliases

Description

Replace the aliases of the domain by the given list of aliases. Returns the list of aliases

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Body Parameter
Name Description Required Default Pattern

string

[string]

X
Return Type

-

Content Type

  • application/json

Responses
Table 12. HTTP Response Codes
Code Message Datatype

404

A problem occured. The domain may not exist

List[Alias]

403

You do not have permission to execute this request.

List[Alias]

409

An alias may already exists with the given name

List[Alias]
Example HTTP request
PUT /domains/Eygdk/aliases HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU1NywiZXhwIjoxNzgxNzgxMTU3fQ.L3Wvg9e65RbNFEShY6O_UkB71f1TPtFszQXNVsmmcx2KR6RUoSXIEaRImaaVIgbl2AEEsh39cs2OE9UD31PBEQ
Content-Length: 29
Host: localhost:8080

["lanisters.net","lions.net"]
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/aliases' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU1NywiZXhwIjoxNzgxNzgxMTU3fQ.L3Wvg9e65RbNFEShY6O_UkB71f1TPtFszQXNVsmmcx2KR6RUoSXIEaRImaaVIgbl2AEEsh39cs2OE9UD31PBEQ' \
    -d '["lanisters.net","lions.net"]'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 98

[ {
  "id" : "ByE3n",
  "name" : "lions.net"
}, {
  "id" : "By46n",
  "name" : "lanisters.net"
} ]

5.4. DomainPolicies

5.4.1. New policy

POST /domains/{domainId}/policies

Description

Create a new policy in a given domain. Only sysadmin can create a new policy.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Body Parameter
Name Description Required Default Pattern

Policy

Policy

X
Return Type

Policy

Content Type

  • application/json

Responses
Table 13. HTTP Response Codes
Code Message Datatype

403

Only users with sysadmin role can execute this request.

Policy

409

A policy may already exists with the given name

Policy

422

Operation cannot be done because of not met conditions.

Policy

201

Created

Policy
Example HTTP request
POST /domains/ByE3n/policies HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY3NywiZXhwIjoxNzgxNzgxMjc3fQ.9mTO0P5i1zsr5jItJoR-0EaL0xEh2GrBLoQzj-XOsBvX9GLXCbgJGgLw7Q0RUmvjYI2Z--DUiTX_Hh1un7Ensw
Content-Length: 516
Host: localhost:8080

{"name":"policyA","domainId":"ByE3n","quarantine":true,"retention":false,"archive":false,"mailSizeLimit":8,"spamScore":7.2,"incoming":true,"relayProps":{"relaySpam":true,"advertPrefix":"[PUB]","prefixSpam":"[SPAM]","relayBadHeaders":true,"relayBadAttachments":true,"spamScoreLimit":20.0},"quarantineProps":{"duration":31,"storeSpam":true,"storeVirus":true,"storeAdvert":true,"storeBlacklisted":true,"storeSenderVerify":true,"storeBadHeaders":true,"storeBadEncoding":true,"storeBadAttachments":true},"outgoing":false}
Example Curl request
$ curl 'http://localhost:8080/domains/ByE3n/policies' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY3NywiZXhwIjoxNzgxNzgxMjc3fQ.9mTO0P5i1zsr5jItJoR-0EaL0xEh2GrBLoQzj-XOsBvX9GLXCbgJGgLw7Q0RUmvjYI2Z--DUiTX_Hh1un7Ensw' \
    -d '{"name":"policyA","domainId":"ByE3n","quarantine":true,"retention":false,"archive":false,"mailSizeLimit":8,"spamScore":7.2,"incoming":true,"relayProps":{"relaySpam":true,"advertPrefix":"[PUB]","prefixSpam":"[SPAM]","relayBadHeaders":true,"relayBadAttachments":true,"spamScoreLimit":20.0},"quarantineProps":{"duration":31,"storeSpam":true,"storeVirus":true,"storeAdvert":true,"storeBlacklisted":true,"storeSenderVerify":true,"storeBadHeaders":true,"storeBadEncoding":true,"storeBadAttachments":true},"outgoing":false}'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: Content-Location
Location: http://localhost:8080/policies/Eygdk
Content-Type: application/json
Content-Length: 779

{
  "id" : "Eygdk",
  "name" : "policyA",
  "domainId" : "ByE3n",
  "quarantine" : true,
  "retention" : false,
  "archive" : false,
  "mailSizeLimit" : 8,
  "spamScore" : 7.2,
  "incoming" : true,
  "relayProps" : {
    "relaySpam" : true,
    "relayAdvert" : true,
    "advertPrefix" : "[PUB]",
    "prefixSpam" : "[SPAM]",
    "relayBadHeaders" : true,
    "relayBadAttachments" : true,
    "spamScoreLimit" : 20.0
  },
  "quarantineProps" : {
    "duration" : 31,
    "storeSpam" : true,
    "storeVirus" : true,
    "storeAdvert" : true,
    "storeBlacklisted" : true,
    "storeSenderVerify" : true,
    "storeBadHeaders" : true,
    "storeBadEncoding" : true,
    "storeBadAttachments" : true
  },
  "retentionProps" : null,
  "archiveProps" : null,
  "outgoing" : false
}

5.4.2. Delete a policy

DELETE /policies/{policyId}

Description

Delete an existing policy. Only sysadmin can delete a policy.

Parameters
Path Parameters
Name Description Required Default Pattern

policyId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 14. HTTP Response Codes
Code Message Datatype

404

Policy not found with given id.

[String]

400

A problem occured. Possible cause: the policy is affected to a domain or a user.

[String]

403

Only users with sysadmin role can execute this request.

[String]
Example HTTP request
DELETE /policies/Eygdk HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY4NiwiZXhwIjoxNzgxNzgxMjg2fQ.ROkCRvlT_R5zJRKFh3fY60BdKVxTlbtd-PMu-nGRQzgluxb5aCov_1rAQNg_Dn1hemrMXLBqb8FeV-8qxS3XjA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/policies/Eygdk' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY4NiwiZXhwIjoxNzgxNzgxMjg2fQ.ROkCRvlT_R5zJRKFh3fY60BdKVxTlbtd-PMu-nGRQzgluxb5aCov_1rAQNg_Dn1hemrMXLBqb8FeV-8qxS3XjA'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.4.3. Single domain policy

GET /policies/{policyId}

Description

Get all parameters of an existing policy

Parameters
Path Parameters
Name Description Required Default Pattern

policyId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 15. HTTP Response Codes
Code Message Datatype

404

Policy not found with given id

Policy
Example HTTP request
GET /policies/YyjPn HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY3OSwiZXhwIjoxNzgxNzgxMjc5fQ.omuJOZfNw77ILBqMjfwCMOi3HqT3LJEDhLu7XX5pZ9FCWAv43I95SFvGDB2SXzwx3r8Fg36u07QBDxbdPudgZg
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/policies/YyjPn' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY3OSwiZXhwIjoxNzgxNzgxMjc5fQ.omuJOZfNw77ILBqMjfwCMOi3HqT3LJEDhLu7XX5pZ9FCWAv43I95SFvGDB2SXzwx3r8Fg36u07QBDxbdPudgZg'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 1111

{
  "id" : "YyjPn",
  "name" : "DefaultTestPolicy",
  "domainId" : "Eygdk",
  "quarantine" : true,
  "retention" : false,
  "archive" : true,
  "mailSizeLimit" : 6,
  "spamScore" : 7.6,
  "incoming" : true,
  "relayProps" : {
    "relaySpam" : false,
    "relayAdvert" : true,
    "advertPrefix" : "[ADVERT]",
    "prefixSpam" : null,
    "relayBadHeaders" : false,
    "relayBadAttachments" : false,
    "spamScoreLimit" : 7.6
  },
  "quarantineProps" : {
    "duration" : 3,
    "storeSpam" : true,
    "storeVirus" : false,
    "storeAdvert" : false,
    "storeBlacklisted" : false,
    "storeSenderVerify" : false,
    "storeBadHeaders" : true,
    "storeBadEncoding" : true,
    "storeBadAttachments" : true
  },
  "retentionProps" : null,
  "archiveProps" : {
    "duration" : 12,
    "archiveByCopy" : false,
    "storeMailOut" : true,
    "storeCleanMailIn" : true,
    "storeSpam" : true,
    "storeBadHeaders" : true,
    "storeBadEncoding" : true,
    "storeBadAttachments" : true,
    "storeAdvert" : false,
    "storeBlacklisted" : false,
    "storeSenderVerify" : false
  },
  "outgoing" : false
}

5.4.4. List domain policies

GET /domains/{domainId}/policies

Description

Returns a list of policies of a given domain.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Query Parameters
Name Description Required Default Pattern

sort

Define the sort applied on response. Prefix the field name by '-' to reverse the sort.

-

null

offset

Index of the first domain to return, defaults to 0

-

null

pageSize

Maximum number of domains returned, defaults to 40

-

null
Return Type

array[Policy]

Content Type

  • application/json

Responses
Table 16. HTTP Response Codes
Code Message Datatype

200

OK

List[Policy]
Example HTTP request
GET /domains/ByE3n/policies HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY4MywiZXhwIjoxNzgxNzgxMjgzfQ.DQwFY1VGnBESoyeOmHvfDrFZQskejmAlZsvAQYIkQGKg0BCPJn6fHAj1r1I1-u2hZ7tfe9EbBLECdvoCk2NQAA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/ByE3n/policies' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY4MywiZXhwIjoxNzgxNzgxMjgzfQ.DQwFY1VGnBESoyeOmHvfDrFZQskejmAlZsvAQYIkQGKg0BCPJn6fHAj1r1I1-u2hZ7tfe9EbBLECdvoCk2NQAA'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: X-Total-Count
X-Total-Count: 2
Content-Type: application/json
Content-Length: 1984

[ {
  "id" : "Eygdk",
  "name" : "policyB",
  "domainId" : "ByE3n",
  "quarantine" : true,
  "retention" : false,
  "archive" : false,
  "mailSizeLimit" : 14,
  "spamScore" : 5.0,
  "incoming" : true,
  "relayProps" : {
    "relaySpam" : false,
    "relayAdvert" : true,
    "advertPrefix" : "",
    "prefixSpam" : null,
    "relayBadHeaders" : false,
    "relayBadAttachments" : false,
    "spamScoreLimit" : 5.0
  },
  "quarantineProps" : {
    "duration" : 30,
    "storeSpam" : true,
    "storeVirus" : false,
    "storeAdvert" : false,
    "storeBlacklisted" : false,
    "storeSenderVerify" : false,
    "storeBadHeaders" : true,
    "storeBadEncoding" : true,
    "storeBadAttachments" : true
  },
  "retentionProps" : null,
  "archiveProps" : null,
  "outgoing" : false
}, {
  "id" : "ByE3n",
  "name" : "Politique-lannister.net",
  "domainId" : "ByE3n",
  "quarantine" : true,
  "retention" : true,
  "archive" : true,
  "mailSizeLimit" : 5,
  "spamScore" : 6.8,
  "incoming" : true,
  "relayProps" : {
    "relaySpam" : true,
    "relayAdvert" : true,
    "advertPrefix" : "[AD]",
    "prefixSpam" : null,
    "relayBadHeaders" : true,
    "relayBadAttachments" : true,
    "spamScoreLimit" : 10.0
  },
  "quarantineProps" : {
    "duration" : 31,
    "storeSpam" : false,
    "storeVirus" : false,
    "storeAdvert" : false,
    "storeBlacklisted" : false,
    "storeSenderVerify" : false,
    "storeBadHeaders" : false,
    "storeBadEncoding" : false,
    "storeBadAttachments" : false
  },
  "retentionProps" : {
    "duration" : 5,
    "storeMailOut" : false,
    "storeCleanMailIn" : false
  },
  "archiveProps" : {
    "duration" : 48,
    "archiveByCopy" : false,
    "storeMailOut" : false,
    "storeCleanMailIn" : false,
    "storeSpam" : false,
    "storeBadHeaders" : false,
    "storeBadEncoding" : false,
    "storeBadAttachments" : false,
    "storeAdvert" : false,
    "storeBlacklisted" : false,
    "storeSenderVerify" : false
  },
  "outgoing" : false
} ]

5.4.5. Edit a policy

PATCH /policies/{policyId}

Description

Edit properties of an existing policy. Apply changes only on specified fields in request. Attributes which are not provided will not be updated. Only sysadmin can update a policy.

Parameters
Path Parameters
Name Description Required Default Pattern

policyId

X

null
Body Parameter
Name Description Required Default Pattern

Policy

Policy

X
Return Type

-

Content Type

  • application/json

Responses
Table 17. HTTP Response Codes
Code Message Datatype

400

A problem occured. Possible cause: the policy name does not match required format

Policy

403

Only users with sysadmin role can execute this request.

Policy

422

Operation cannot be done because of not met conditions.

Policy

404

Policy not found with given id

Policy
Example HTTP request
PATCH /policies/ByE3n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY5NSwiZXhwIjoxNzgxNzgxMjk1fQ.0ljLKDYkwpEfdLTystknqLm95MiPQ7BYW75pGMDO2EhiXU7onuiWN6HOC18DF23KzVSWVbWxPNYftl0DFdJLOA
Content-Length: 18
Host: localhost:8080

{"name":"policyC"}
Example Curl request
$ curl 'http://localhost:8080/policies/ByE3n' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY5NSwiZXhwIjoxNzgxNzgxMjk1fQ.0ljLKDYkwpEfdLTystknqLm95MiPQ7BYW75pGMDO2EhiXU7onuiWN6HOC18DF23KzVSWVbWxPNYftl0DFdJLOA' \
    -d '{"name":"policyC"}'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.5. Domains

5.5.1. Create domain

POST /domains

Description

Create a new domain. System will create a default policy with the given data (quarantine, archive, retention). Next, use policies API to set default values of different services.

Parameters
Body Parameter
Name Description Required Default Pattern

DomainAdd

DomainAdd

X
Return Type

Domain

Content Type

  • application/json

Responses
Table 18. HTTP Response Codes
Code Message Datatype

400

A problem occurred. Possible cause: the domain name does not match required format

Domain

403

Authorisation failure. You may have reached the limitation of domain creation or you do not have the sysadmin role.

Domain

409

A domain may already exists with the given name

Domain

422

Operation cannot be done because of not met conditions.

Domain

201

Created

Domain
Example HTTP request
POST /domains HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU5OSwiZXhwIjoxNzgxNzgxMTk5fQ.DDx16-CZRrXgvGwy2xJxtbvgHX1_p2BvuowTRal-bpZNRAZ67QC-a0QOifkt9XNs0p9gRLL6FnrBkjcpUQEuqw
Content-Length: 464
Host: localhost:8080

{"name":"got.com","status":"ENABLED","incoming":true,"outgoing":false,"quarantine":true,"retention":true,"archive":true,"defaultLanguage":"DE","autoProvisioningOn":true,"greylistingOn":true,"senderVerifyOn":true,"customerId":"ByE3n","externalId":"HBO-2019","outgoingSubnets":["92.123.51.204/31","92.23.81.244/31"],"platforms":[{"name":"platform","transportDest":"1.2.3.4","transportType":"SMTP","transportPort":25,"authType":"local","authData":"","default":true}]}
Example Curl request
$ curl 'http://localhost:8080/domains' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU5OSwiZXhwIjoxNzgxNzgxMTk5fQ.DDx16-CZRrXgvGwy2xJxtbvgHX1_p2BvuowTRal-bpZNRAZ67QC-a0QOifkt9XNs0p9gRLL6FnrBkjcpUQEuqw' \
    -d '{"name":"got.com","status":"ENABLED","incoming":true,"outgoing":false,"quarantine":true,"retention":true,"archive":true,"defaultLanguage":"DE","autoProvisioningOn":true,"greylistingOn":true,"senderVerifyOn":true,"customerId":"ByE3n","externalId":"HBO-2019","outgoingSubnets":["92.123.51.204/31","92.23.81.244/31"],"platforms":[{"name":"platform","transportDest":"1.2.3.4","transportType":"SMTP","transportPort":25,"authType":"local","authData":"","default":true}]}'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: Content-Location
Location: http://localhost:8080/domains/Eygdk
Content-Type: application/json
Content-Length: 2441

{
  "id" : "Eygdk",
  "name" : "got.com",
  "description" : null,
  "status" : "ENABLED",
  "wblistPriority" : "USER",
  "defaultLanguage" : "DE",
  "autoProvisioningOn" : true,
  "senderVerifyOn" : true,
  "greylistingOn" : true,
  "externalId" : null,
  "policy" : {
    "id" : "Eygdk",
    "name" : "Politique-got.com",
    "domainId" : "Eygdk",
    "quarantine" : true,
    "retention" : true,
    "archive" : true,
    "mailSizeLimit" : 21,
    "spamScore" : 5.0,
    "incoming" : true,
    "relayProps" : {
      "relaySpam" : false,
      "relayAdvert" : true,
      "advertPrefix" : "",
      "prefixSpam" : null,
      "relayBadHeaders" : false,
      "relayBadAttachments" : false,
      "spamScoreLimit" : 5.0
    },
    "quarantineProps" : {
      "duration" : 31,
      "storeSpam" : true,
      "storeVirus" : false,
      "storeAdvert" : false,
      "storeBlacklisted" : false,
      "storeSenderVerify" : false,
      "storeBadHeaders" : true,
      "storeBadEncoding" : true,
      "storeBadAttachments" : true
    },
    "retentionProps" : {
      "duration" : 5,
      "storeMailOut" : true,
      "storeCleanMailIn" : true
    },
    "archiveProps" : {
      "duration" : 48,
      "archiveByCopy" : false,
      "storeMailOut" : true,
      "storeCleanMailIn" : true,
      "storeSpam" : true,
      "storeBadHeaders" : true,
      "storeBadEncoding" : true,
      "storeBadAttachments" : true,
      "storeAdvert" : false,
      "storeBlacklisted" : false,
      "storeSenderVerify" : false
    },
    "outgoing" : false
  },
  "domainAliases" : [ ],
  "activeUsersCount" : 0,
  "policiesCount" : 1,
  "quarantine" : true,
  "retention" : true,
  "archive" : true,
  "incoming" : true,
  "outgoingSubnets" : [ "92.123.51.204/31", "92.23.81.244/31" ],
  "creationDate" : 1781777599234,
  "deletionDate" : null,
  "purgeDate" : null,
  "outgoingProviders" : [ ],
  "customer" : {
    "id" : "ByE3n",
    "brokerId" : "ByE3n",
    "name" : "Alinto",
    "description" : null,
    "externalId" : null,
    "createdAt" : 1781777598000
  },
  "platforms" : [ {
    "id" : "Eygdk",
    "name" : "platform",
    "transportDest" : "1.2.3.4",
    "transportType" : "SMTP",
    "transportPort" : 25,
    "fallbackTransportDest" : null,
    "fallbackTransportType" : null,
    "fallbackTransportPort" : null,
    "apiType" : null,
    "apiData" : null,
    "authType" : "local",
    "authData" : null,
    "default" : true
  } ]
}

5.5.2. Affect users access

PUT /domains/{domainId}/access

Description

Define list of permissions assigned to end users of a domain.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Body Parameter
Name Description Required Default Pattern

string

[string]

X
Return Type

AclDTO

Content Type

  • /

Responses
Table 19. HTTP Response Codes
Code Message Datatype

200

OK

AclDTO
Example HTTP request
Example Curl request
Example HTTP response

5.5.3. Create admin access

POST /domains/{domainId}/admins

Description

Create a new administrator access on current domain.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Body Parameter
Name Description Required Default Pattern

AdminAdd

AdminAdd

X
Return Type

Admin

Content Type

  • /

Responses
Table 20. HTTP Response Codes
Code Message Datatype

200

OK

Admin
Example HTTP request
Example Curl request
Example HTTP response

5.5.4. Delete domain option

DELETE /domains/{domainId}/options/{optionName}

Description

Delete option value for domain scope. The value of the parent scope will be used

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null

optionName

X

null
Return Type

Option

Content Type

  • application/json

Responses
Table 21. HTTP Response Codes
Code Message Datatype

200

OK

Option
Example HTTP request
DELETE /domains/Eygdk/options/DOMAIN_ADMIN HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU5MywiZXhwIjoxNzgxNzgxMTkzfQ.noOAd74F3O54d-5qnXV5RsyfkiMnOXUVYNnwTlpHeXfeeDgh0jm-jH-JlWRrQpF_d14igLZML3YbJD0FEuolpQ
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/options/DOMAIN_ADMIN' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU5MywiZXhwIjoxNzgxNzgxMTkzfQ.noOAd74F3O54d-5qnXV5RsyfkiMnOXUVYNnwTlpHeXfeeDgh0jm-jH-JlWRrQpF_d14igLZML3YbJD0FEuolpQ'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.5.5. Revoke admin access

DELETE /domains/{domainId}/admins/{adminId}

Description

Delete administrator access on current domain. If this admin has no other access, the account will be deleted.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null

adminId

X

null
Return Type

[String]

Content Type

  • /

Responses
Table 22. HTTP Response Codes
Code Message Datatype

200

OK

[String]
Example HTTP request
Example Curl request
Example HTTP response

5.5.6. Delete a domain

DELETE /domains/{domainId}

Description

Delete an existing domain and its users. Domain is just tagged as deleted. All services are suspended. Domain will be really deleted after a quarantine delay. You can revert the deletion during this quarantine. Only sysadmin can delete a domain.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Header Parameters
Name Description Required Default Pattern

X-Ignore-MX

-

null
Return Type

-

Content Type

  • application/json

Responses
Table 23. HTTP Response Codes
Code Message Datatype

403

Only users with sysadmin role can execute this request.

Domain

404

Domain not found with given id

Domain

422

Operation cannot be done because of not met conditions.

Domain
Example HTTP request
DELETE /domains/Eygdk HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU5NywiZXhwIjoxNzgxNzgxMTk3fQ.eb9gzn5O9EWVdIJGnPURdGnOsUlrGGPPar3f0nBABfZu2FMWNq2lvKjwlq9FjXI9rvL3ygoO1Rus6SyzQ168sA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU5NywiZXhwIjoxNzgxNzgxMTk3fQ.eb9gzn5O9EWVdIJGnPURdGnOsUlrGGPPar3f0nBABfZu2FMWNq2lvKjwlq9FjXI9rvL3ygoO1Rus6SyzQ168sA'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.5.7. Get admin

GET /domains/{domainId}/admins/{adminId}

Description

Get administrator account and all the associated permissions.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null

adminId

X

null
Return Type

Admin

Content Type

  • /

Responses
Table 24. HTTP Response Codes
Code Message Datatype

200

OK

Admin
Example HTTP request
Example Curl request
Example HTTP response

5.5.8. Single domain

GET /domains/{domainId}

Description

Get an existing domain

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 25. HTTP Response Codes
Code Message Datatype

404

Domain not found with given id

Domain
Example HTTP request
GET /domains/Eygdk HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzYwMiwiZXhwIjoxNzgxNzgxMjAyfQ.Gzhn8gp2s75Nz_qkKdHExAgx9-myvwLnIeAe-0q_frDyg7TuT9GWH_KcVkXLQV8UFq7SJXs5k-rDCIBwk0bWUA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzYwMiwiZXhwIjoxNzgxNzgxMjAyfQ.Gzhn8gp2s75Nz_qkKdHExAgx9-myvwLnIeAe-0q_frDyg7TuT9GWH_KcVkXLQV8UFq7SJXs5k-rDCIBwk0bWUA'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 1823

{
  "id" : "Eygdk",
  "name" : "got.com",
  "description" : null,
  "status" : "ENABLED",
  "wblistPriority" : "USER",
  "defaultLanguage" : "EN",
  "autoProvisioningOn" : false,
  "senderVerifyOn" : true,
  "greylistingOn" : true,
  "externalId" : null,
  "policy" : {
    "id" : "Eygdk",
    "name" : "Politique-got.com",
    "domainId" : "Eygdk",
    "quarantine" : false,
    "retention" : false,
    "archive" : false,
    "mailSizeLimit" : 21,
    "spamScore" : 5.0,
    "incoming" : true,
    "relayProps" : {
      "relaySpam" : true,
      "relayAdvert" : true,
      "advertPrefix" : "",
      "prefixSpam" : null,
      "relayBadHeaders" : true,
      "relayBadAttachments" : true,
      "spamScoreLimit" : 10.0
    },
    "quarantineProps" : null,
    "retentionProps" : null,
    "archiveProps" : null,
    "outgoing" : false
  },
  "domainAliases" : [ ],
  "activeUsersCount" : 0,
  "policiesCount" : 1,
  "quarantine" : false,
  "retention" : false,
  "archive" : false,
  "incoming" : true,
  "outgoingSubnets" : [ ],
  "creationDate" : 1781777602000,
  "deletionDate" : null,
  "purgeDate" : null,
  "outgoingProviders" : [ {
    "id" : "ByE3n",
    "name" : "Microsoft",
    "spfProvider" : "spf.protection.outlook.com",
    "active" : true
  } ],
  "customer" : {
    "id" : "ByE3n",
    "brokerId" : "ByE3n",
    "name" : "Alinto",
    "description" : null,
    "externalId" : null,
    "createdAt" : 1781777601000
  },
  "platforms" : [ {
    "id" : "Eygdk",
    "name" : "platform",
    "transportDest" : "1.2.3.4",
    "transportType" : "SMTP",
    "transportPort" : 25,
    "fallbackTransportDest" : null,
    "fallbackTransportType" : null,
    "fallbackTransportPort" : null,
    "apiType" : null,
    "apiData" : null,
    "authType" : "local",
    "authData" : null,
    "default" : true
  } ]
}

5.5.9. List admins

GET /domains/{domainId}/admins

Description

List all administrators accounts defined on domain.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Query Parameters
Name Description Required Default Pattern

offset

-

0

pageSize

-

40

sort

Define the sort applied on response. Prefix the field login by '-' to reverse the sort.

-

null

search

Filter by login, email, displayName

-

null
Return Type

array[Admin]

Content Type

  • /

Responses
Table 26. HTTP Response Codes
Code Message Datatype

200

OK

List[Admin]
Example HTTP request
Example Curl request
Example HTTP response

5.5.10. List domain options

GET /domains/{domainId}/options

Description

Returns a list of options defined for given domain

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Return Type

array[Option]

Content Type

  • application/json

Responses
Table 27. HTTP Response Codes
Code Message Datatype

200

OK

List[Option]
Example HTTP request
GET /domains/Eygdk/options HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU5OCwiZXhwIjoxNzgxNzgxMTk4fQ.g0PQl4dyTJT_Jr7AAyh1cs7CaV8-MuHR6TgzD5v76WjaRJcAzyos3p5bAS_3v3L_s3KVlNV5qINIyTMqH4MttA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/options' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU5OCwiZXhwIjoxNzgxNzgxMTk4fQ.g0PQl4dyTJT_Jr7AAyh1cs7CaV8-MuHR6TgzD5v76WjaRJcAzyos3p5bAS_3v3L_s3KVlNV5qINIyTMqH4MttA'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: X-Total-Count
X-Total-Count: 3
Content-Type: application/json
Content-Length: 1094

[ {
  "value" : null,
  "parentValue" : "protect.winterfell.net",
  "option" : {
    "ptfScope" : true,
    "urlScope" : false,
    "customerScope" : true,
    "domainScope" : true,
    "userScope" : false,
    "restricted" : true,
    "group" : null,
    "name" : "APP_URL",
    "type" : "HOST",
    "values" : null,
    "description" : null
  }
}, {
  "value" : "domain_value",
  "parentValue" : "value_by_default",
  "option" : {
    "ptfScope" : true,
    "urlScope" : false,
    "customerScope" : false,
    "domainScope" : true,
    "userScope" : false,
    "restricted" : false,
    "group" : null,
    "name" : "DOMAIN_OPTION_EXAMPLE",
    "type" : "STRING",
    "values" : null,
    "description" : null
  }
}, {
  "value" : "reporter@targaryen.net",
  "parentValue" : "noreply@cleanmail.eu",
  "option" : {
    "ptfScope" : true,
    "urlScope" : false,
    "customerScope" : false,
    "domainScope" : true,
    "userScope" : false,
    "restricted" : false,
    "group" : null,
    "name" : "DOMAIN_ADMIN",
    "type" : "EMAIL",
    "values" : null,
    "description" : null
  }
} ]

5.5.11. List domains

GET /domains

Description

Returns a list of domains. If the response does not contain a domain which does exist, the problem might caused by a missing security role on the searched domain.

Parameters
Query Parameters
Name Description Required Default Pattern

offset

Index of the first domain to return, defaults to 0

-

null

pageSize

Maximum number of domains returned, defaults to 40

-

null

sort

Define the sort applied on response. Prefix the field name by '-' to reverse the sort.

-

null

name

Filter domains by name

-

null

status

Filter domains by status

-

null

customerId

Filter domains by customer Id

-

null

externalId

Filter domains by external Id

-

null

platformId

Filter domains by platform id

-

null

platformName

Filter domains by platform name

-

null
Return Type

array[Domain]

Content Type

  • application/json

Responses
Table 28. HTTP Response Codes
Code Message Datatype

200

OK

List[Domain]
Example HTTP request
GET /domains?name=stark.net HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzYwMywiZXhwIjoxNzgxNzgxMjAzfQ.QzSxoIYoy4RDWn7-82LTBsdmN-GBR_WcvJWjN8wdTXZE5MzaDaqsdok0WmBDPnAXvDz0rQirpjamdGSDlxnkTw
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains?name=stark.net' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzYwMywiZXhwIjoxNzgxNzgxMjAzfQ.QzSxoIYoy4RDWn7-82LTBsdmN-GBR_WcvJWjN8wdTXZE5MzaDaqsdok0WmBDPnAXvDz0rQirpjamdGSDlxnkTw'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: X-Total-Count
X-Total-Count: 1
Content-Type: application/json
Content-Length: 1831

[ {
  "id" : "Eygdk",
  "name" : "stark.net",
  "description" : null,
  "status" : "ENABLED",
  "wblistPriority" : "USER",
  "defaultLanguage" : "FR",
  "autoProvisioningOn" : false,
  "senderVerifyOn" : true,
  "greylistingOn" : true,
  "externalId" : null,
  "policy" : {
    "id" : "Eygdk",
    "name" : "Politique-stark.net",
    "domainId" : "Eygdk",
    "quarantine" : false,
    "retention" : false,
    "archive" : false,
    "mailSizeLimit" : 21,
    "spamScore" : 5.0,
    "incoming" : true,
    "relayProps" : {
      "relaySpam" : true,
      "relayAdvert" : true,
      "advertPrefix" : "",
      "prefixSpam" : null,
      "relayBadHeaders" : true,
      "relayBadAttachments" : true,
      "spamScoreLimit" : 10.0
    },
    "quarantineProps" : null,
    "retentionProps" : null,
    "archiveProps" : null,
    "outgoing" : false
  },
  "domainAliases" : [ ],
  "activeUsersCount" : 0,
  "policiesCount" : 1,
  "quarantine" : false,
  "retention" : false,
  "archive" : false,
  "incoming" : true,
  "outgoingSubnets" : [ ],
  "creationDate" : 1781777603000,
  "deletionDate" : null,
  "purgeDate" : null,
  "outgoingProviders" : [ {
    "id" : "ByE3n",
    "name" : "Microsoft",
    "spfProvider" : "spf.protection.outlook.com",
    "active" : true
  } ],
  "customer" : {
    "id" : "ByE3n",
    "brokerId" : "ByE3n",
    "name" : "Alinto",
    "description" : null,
    "externalId" : null,
    "createdAt" : 1781777602000
  },
  "platforms" : [ {
    "id" : "Eygdk",
    "name" : "platform",
    "transportDest" : "1.2.3.4",
    "transportType" : "SMTP",
    "transportPort" : 25,
    "fallbackTransportDest" : null,
    "fallbackTransportType" : null,
    "fallbackTransportPort" : null,
    "apiType" : null,
    "apiData" : null,
    "authType" : "local",
    "authData" : null,
    "default" : true
  } ]
} ]

5.5.12. List users access

GET /domains/{domainId}/access

Description

List all permissions assigned to end users of a domain.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Return Type

array[AclPermissionStatus]

Content Type

  • /

Responses
Table 29. HTTP Response Codes
Code Message Datatype

200

OK

List[AclPermissionStatus]
Example HTTP request
Example Curl request
Example HTTP response

5.5.13. Define admin access

PUT /domains/{domainId}/admins/{adminId}/authorities

Description

Set administrator accesses on current domain.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null

adminId

X

null
Body Parameter
Name Description Required Default Pattern

string

[string]

X
Return Type

[String]

Content Type

  • /

Responses
Table 30. HTTP Response Codes
Code Message Datatype

200

OK

[String]
Example HTTP request
Example Curl request
Example HTTP response

5.5.14. Set domain option

POST /domains/{domainId}/options

Description

Set option value to a domain. The list of available options can be consulted in api GET /options

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Body Parameter
Name Description Required Default Pattern

OptionAdd

OptionAdd

X
Return Type

Option

Content Type

  • application/json

Responses
Table 31. HTTP Response Codes
Code Message Datatype

200

OK

Option
Example HTTP request
POST /domains/Eygdk/options HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzYwMCwiZXhwIjoxNzgxNzgxMjAwfQ.TFKgxc8mtZq8ETbidRQOPNynIhuYmXdBqPLl5-HKuCBoFzAcb2Mn6w0VMVFyO2nYdX5tW70XJsrXBdoEA4DmAA
Content-Length: 53
Host: localhost:8080

{"name":"DOMAIN_ADMIN","value":"admin@targaryen.net"}
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/options' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzYwMCwiZXhwIjoxNzgxNzgxMjAwfQ.TFKgxc8mtZq8ETbidRQOPNynIhuYmXdBqPLl5-HKuCBoFzAcb2Mn6w0VMVFyO2nYdX5tW70XJsrXBdoEA4DmAA' \
    -d '{"name":"DOMAIN_ADMIN","value":"admin@targaryen.net"}'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 370

{
  "value" : "admin@targaryen.net",
  "parentValue" : "support@cleanmail.tld",
  "option" : {
    "ptfScope" : true,
    "urlScope" : false,
    "customerScope" : false,
    "domainScope" : true,
    "userScope" : false,
    "restricted" : false,
    "group" : null,
    "name" : "DOMAIN_ADMIN",
    "type" : "EMAIL",
    "values" : null,
    "description" : null
  }
}

5.5.15. Edit a domain

PATCH /domains/{domainId}

Description

Edit properties of an existing domain. Apply changes only on specified fields in request. Attributes which are not provided will not be updated.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Body Parameter
Name Description Required Default Pattern

DomainUpdate

DomainUpdate

X
Header Parameters
Name Description Required Default Pattern

X-Ignore-MX

-

null
Return Type

-

Content Type

  • application/json

Responses
Table 32. HTTP Response Codes
Code Message Datatype

400

A problem occured. Possible cause: the domain name does not match required format

Domain

422

Operation cannot be done because of not met conditions.

Domain

404

Domain not found with given id

Domain
Example HTTP request
PATCH /domains/Eygdk HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU5NCwiZXhwIjoxNzgxNzgxMTk0fQ.mcyj7MtYnECIr8--KOzZCqwHgWKSN6AmXuduxgdTAeRnSKcJr4u4kfUK7U6C8H2xyu4AywCKK2HOVau8EHYWcw
Content-Length: 24
Host: localhost:8080

{"defaultLanguage":"ES"}
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU5NCwiZXhwIjoxNzgxNzgxMTk0fQ.mcyj7MtYnECIr8--KOzZCqwHgWKSN6AmXuduxgdTAeRnSKcJr4u4kfUK7U6C8H2xyu4AywCKK2HOVau8EHYWcw' \
    -d '{"defaultLanguage":"ES"}'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.6. DomainsDKIM

5.6.1. Add DKIM

POST /domains/{domainId}/dkim

Description

Create DKIM entry and return public key.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Body Parameter
Name Description Required Default Pattern

DkimDTO

DkimDTO

-
Return Type

-

Content Type

  • application/json

Responses
Table 33. HTTP Response Codes
Code Message Datatype

404

A problem occured. The domain may not exist.

List[[string]]

403

You do not have permission to execute this request. (sysadmin required)

List[[string]]
Example HTTP request
POST /domains/Eygdk/dkim HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU4NSwiZXhwIjoxNzgxNzgxMTg1fQ.YaONi2mKs4GK14l3bstrSSe83i-keJbx-OKnROCEOsEn-heQuGVZ5SnJxY-aslhg2LEO74FUWalC5dzEVKygvA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/dkim' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU4NSwiZXhwIjoxNzgxNzgxMTg1fQ.YaONi2mKs4GK14l3bstrSSe83i-keJbx-OKnROCEOsEn-heQuGVZ5SnJxY-aslhg2LEO74FUWalC5dzEVKygvA'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 442

[ "protect._domainkey.stark.com TXT v=DKIM1; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy5OLoJFpGKJTeFfcw+ITI2d8s7kAGMZZSg3qHEdKCNZPHWKPwDFk0Eo6WLsEsKJFzauXGMiy0YoazOaL/80mC2uQ4DMBBwQyrCBqhoRma7FhbAHBZ0zfdxqZnKrbNe6Mh3wvpERHAYvxnluT7ZJQlnT2aIb5hxyNXe4gzZYq4l9RZ7Qr+jyO4Hwe2GsAFc7QldPwaafi4hk5m/AF38mmSD2xHnGnTP6SCecGJ/O8BhxcZ1fhXLzYpBqoySrFmOhWsgx0jDadAJK+xP+3JmNa8UUIF6Eaai17Tf4QzEAz9Jatm8UkccEsLUstkXXN14cj3By/zsGhyJLsVtmrxfLfhQIDAQAB" ]

5.6.2. Delete domain DKIM

DELETE /domains/{domainId}/dkim

Description

Delete dkim informations of an existing domain.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 34. HTTP Response Codes
Code Message Datatype

403

You do not have permission to execute this request. (sysadmin required)

[String]

404

A problem occured. The domain may not exist

[String]
Example HTTP request
DELETE /domains/Eygdk/dkim HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU4MSwiZXhwIjoxNzgxNzgxMTgxfQ.iz3AQB3ryB93ROl-QwqTADzEA4EO2oSr55ygrfJKMFwXyC19ogKihzO8NpXcFGg8QkIhruQVxPwm3dIP8zF7oA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/dkim' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU4MSwiZXhwIjoxNzgxNzgxMTgxfQ.iz3AQB3ryB93ROl-QwqTADzEA4EO2oSr55ygrfJKMFwXyC19ogKihzO8NpXcFGg8QkIhruQVxPwm3dIP8zF7oA'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.6.3. Get DKIM

GET /domains/{domainId}/dkim

Description

Get the DKIM values of a domain

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 35. HTTP Response Codes
Code Message Datatype

403

You do not have permission to execute this request.

List[[string]]

404

No DKIM values found. Or the domain may not exist

List[[string]]
Example HTTP request
GET /domains/Eygdk/dkim HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU4NCwiZXhwIjoxNzgxNzgxMTg0fQ.19s5dWl_I6sWQBO2jX5XKPONTQF4aM2QiGkYdu6V9epqCXcW_O7MGIVY13-b15m-EKhIePVTl6Bikgq9Vq2M8Q
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/dkim' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU4NCwiZXhwIjoxNzgxNzgxMTg0fQ.19s5dWl_I6sWQBO2jX5XKPONTQF4aM2QiGkYdu6V9epqCXcW_O7MGIVY13-b15m-EKhIePVTl6Bikgq9Vq2M8Q'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 535

[ "protect._domainkey.stark.com TXT v=DKIM1; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC4AOcbCtlVjd6U5RoRwtVqwHmnXAGHYHgpbJZMC8Sj7u3EZ1ByNlLVmHAYKa4SW4jfG4+tf93S8HTOEWXYA037YnxiNVsNYCEMnVwlAYJplv5wunXDd7MDFxtrjdJmJcZ5HjlBcckD6OpKw+QhDRa+i4Pf98RlHDYyx7HGGoFCywIDAQAB", "protect._domainkey.winterfell.net TXT v=DKIM1; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC4AOcbCtlVjd6U5RoRwtVqwHmnXAGHYHgpbJZMC8Sj7u3EZ1ByNlLVmHAYKa4SW4jfG4+tf93S8HTOEWXYA037YnxiNVsNYCEMnVwlAYJplv5wunXDd7MDFxtrjdJmJcZ5HjlBcckD6OpKw+QhDRa+i4Pf98RlHDYyx7HGGoFCywIDAQAB" ]

5.6.4. Update domain DKIM

PUT /domains/{domainId}/dkim

Description

Replace DKIM values for a domain. Returns the dkim values

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Body Parameter
Name Description Required Default Pattern

DkimDTO

DkimDTO

-
Return Type

-

Content Type

  • application/json

Responses
Table 36. HTTP Response Codes
Code Message Datatype

404

A problem occured. The domain may not exist.

List[[string]]

403

You do not have permission to execute this request. (sysadmin required)

List[[string]]
Example HTTP request
PUT /domains/Eygdk/dkim HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU4MiwiZXhwIjoxNzgxNzgxMTgyfQ.ifX-IhOVB0DiVh6g5l2TcXJwmPWJXGugCazrh5TQnctYBIz8OTCuIvHh5vPo0PMXpx8VmZdU75YqsSVHrRoKUw
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/dkim' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU4MiwiZXhwIjoxNzgxNzgxMTgyfQ.ifX-IhOVB0DiVh6g5l2TcXJwmPWJXGugCazrh5TQnctYBIz8OTCuIvHh5vPo0PMXpx8VmZdU75YqsSVHrRoKUw'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 442

[ "protect._domainkey.stark.com TXT v=DKIM1; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuM0cmzjTTuTUKr9vgxjgIcuuR5o+uxriN6QUgQ81+iqf/YyRzEEoBswhywBixC6xMuwTLnAA3wKzlY7PSi5VANRYlAuz1ieI1fg9EjPLoq+34vCM19xJ+RDLLOmK7IaZkDIuyt6fNMXBOtA1an0hITuUqncn7Na0LQRRPHA4ItWavfieqXs//NyvBEYabFnKtaIohK4jTMs9c4JrAi8kSOwB57WhEpNNRqXLmVLJIlNCVEB/T1t/kgDo7kork2cEd+ABa+XK4jPb3GIlmeriphgh6q+G7Bafl6BAxTfIQFv/9jB0vQ0I95ZCj24kZx2JZdHOXhzIt0LZe8tAowlwyQIDAQAB" ]

5.7. Emails

5.7.1. Delete attachment

DELETE /emails/attachments/{uid}/{filename}

Description

Delete uploaded file on server.

Parameters
Path Parameters
Name Description Required Default Pattern

uid

X

null

filename

X

null
Return Type

[File]

Content Type

  • /

Responses
Table 37. HTTP Response Codes
Code Message Datatype

200

OK

[File]
Example HTTP request
Example Curl request
Example HTTP response

5.7.2. Get all email attachments

GET /users/{userId}/emails/{folderPath}/{messageId}/attachments

Description
Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null

folderPath

X

null

messageId

X

null
Query Parameters
Name Description Required Default Pattern

dl

dl

-

null
Return Type

-

Content Type

  • /

Responses
Table 38. HTTP Response Codes
Code Message Datatype

404

File not found.

[Object]
Example HTTP request
Example Curl request
Example HTTP response

5.7.3. Download email attachment part

GET /users/{userId}/emails/{folderPath}/{emailId}/attachments/{partId}

Description
Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null

folderPath

X

null

emailId

X

null

partId

X

null
Query Parameters
Name Description Required Default Pattern

dl

-

null
Return Type

-

Content Type

  • /

Responses
Table 39. HTTP Response Codes
Code Message Datatype

404

File not found.

[File]
Example HTTP request
Example Curl request
Example HTTP response

5.7.4. Download attachment

GET /emails/attachments/{uid}/{filename}

Description
Parameters
Path Parameters
Name Description Required Default Pattern

uid

X

null

filename

X

null
Return Type

-

Content Type

  • /

Responses
Table 40. HTTP Response Codes
Code Message Datatype

404

File not found.

[File]
Example HTTP request
Example Curl request
Example HTTP response

5.7.5. Get email

GET /users/{userIdOrEmail}/emails/{folderPath}/{fugluIdOrMailId}

Description

Get user’s email from a userId or Email and FugluId or mailId

Parameters
Path Parameters
Name Description Required Default Pattern

userIdOrEmail

Id of the user

X

null

folderPath

Id of the folder

X

null

fugluIdOrMailId

Id of the email. Can be the value of header X-Fuglu-Id or Message-ID

X

null
Query Parameters
Name Description Required Default Pattern

fields

List of attended datas

-

null
Return Type

ImapMessageContent

Content Type

  • application/json

Responses
Table 41. HTTP Response Codes
Code Message Datatype

200

Mail returned successfully

ImapMessageContent

403

Authorisation failure.

ImapMessageContent

404

The user or the mail not exist.

ImapMessageContent

500

Something went wrong. Possibly unable to connect to Imap.

ImapMessageContent
Example HTTP request
Example Curl request
Example HTTP response

5.7.6. Get folders

GET /users/{userIdOrEmail}/emails/folders/{path}

Description

Get user’s IMAP folders.

Parameters
Path Parameters
Name Description Required Default Pattern

userIdOrEmail

User id or email

X

null

path

Path of the parent folder. If not specified, the root is used.

X

null
Query Parameters
Name Description Required Default Pattern

fields

Attended fields types. STATS returns messages counts and number of unread elements

-

null
Return Type

array[ImapFolder]

Content Type

  • application/json

Responses
Table 42. HTTP Response Codes
Code Message Datatype

200

Folders returned successfully

List[ImapFolder]

403

Authorisation failure.

List[ImapFolder]

404

The user not exist.

List[ImapFolder]

500

Something went wrong. Possibly unable to connect to Imap.

List[ImapFolder]
Example HTTP request
Example Curl request
Example HTTP response

5.7.7. Get folders

GET /users/{userIdOrEmail}/emails/folders

Description

Get user’s IMAP folders.

Parameters
Path Parameters
Name Description Required Default Pattern

userIdOrEmail

User id or email

X

null
Query Parameters
Name Description Required Default Pattern

fields

Attended fields types. STATS returns messages counts and number of unread elements

-

null
Return Type

array[ImapFolder]

Content Type

  • application/json

Responses
Table 43. HTTP Response Codes
Code Message Datatype

200

Folders returned successfully

List[ImapFolder]

403

Authorisation failure.

List[ImapFolder]

404

The user not exist.

List[ImapFolder]

500

Something went wrong. Possibly unable to connect to Imap.

List[ImapFolder]
Example HTTP request
Example Curl request
Example HTTP response

5.7.8. Get folder content

GET /users/{userIdOrEmail}/emails/{folderPath}

Description

Get all emails contained in a folder.

Parameters
Path Parameters
Name Description Required Default Pattern

userIdOrEmail

User id or email

X

null

folderPath

Folder path

X

null
Query Parameters
Name Description Required Default Pattern

sort

Define the sort applied on response. Prefix the field send_date by '-' to reverse the sort.

-

null

offset

Index of the first mail to return, defaults to 0

-

null

pageSize

Maximum number of mails returned, defaults to 40

-

null

receivedAfter

Determines the date from which the search is launched

-

null

receivedBefore

Determines the date until which the search is launched

-

null

from

Search on the sender

-

null

to

Search on the main recipients

-

null

cc

Search on the secondary recipients

-

null

subject

Search on the subject of the message

-

null

body

Search on the content of the message

-

null

operator

Operator to apply on the search (AND/OR/NOT)

-

AND

id

Search on the id of the message

-

null
Return Type

array[ImapMessage]

Content Type

  • application/json

Responses
Table 44. HTTP Response Codes
Code Message Datatype

200

Mails returned successfully

List[ImapMessage]

403

Authorisation failure.

List[ImapMessage]

404

The user or the folder not exist.

List[ImapMessage]

500

Something went wrong. Possibly unable to connect to Imap.

List[ImapMessage]
Example HTTP request
Example Curl request
Example HTTP response

5.7.9. Release an email

POST /users/{userIdOrEmail}/emails/{folderPath}/{fugluId}/release

Description

Release an email via its folder (e.g. \"INBOX\") and its id. Id can be the value of the messageId or X-Fuglu-Id headers. The email will be sent to the final mailbox. If the message was store in the quarantine, the spam tag would be removed and send to its recipient. Note that releasing an email which contain virus is not allowed by default. To by-pass this control, add a X-Virus-Lover header to your request. Action is asynchrone.

Parameters
Path Parameters
Name Description Required Default Pattern

userIdOrEmail

X

null

folderPath

X

null

fugluId

X

null
Header Parameters
Name Description Required Default Pattern

X-Virus-Lover

-

null
Return Type

[Object]

Content Type

  • application/json

Responses
Table 45. HTTP Response Codes
Code Message Datatype

202

Release request accepted and will be processed as soon as possible.

[Object]

404

The user or the couple folder/fugluId may not exist

[Object]

412

Release not allowed. The email you attempt to release is infected and no header X-Virus-Lover found in the request OR the header X-Virus-Lover is present in the request while the email is not infected

[Object]

403

Authorisation failure. You are not allowed to release this email.

[Object]

204

No Content

[Object]
Example HTTP request
Example Curl request
Example HTTP response

5.7.10. Send email

POST /users/{userIdOrEmail}/emails/send

Description

Send an email with current logged in user as sender.

Parameters
Path Parameters
Name Description Required Default Pattern

userIdOrEmail

User id or email

X

null
Body Parameter
Name Description Required Default Pattern

SmtpMessage

SmtpMessage

X
Return Type

[String]

Content Type

  • application/json

Responses
Table 46. HTTP Response Codes
Code Message Datatype

400

Error in given parameters.

[String]

200

OK

[String]
Example HTTP request
Example Curl request
Example HTTP response

5.7.11. Upload attachment

POST /emails/attachments

Description

Upload a file on server in order to attach it in an e-mail. The response of the upload give datas which will be used in the API for sending message. Files are automaticaly deleted on server when they are included in an e-mail during its sending.

Parameters
Body Parameter
Name Description Required Default Pattern

UploadFileRequest

UploadFileRequest

-
Return Type

AttachmentFile

Content Type

  • /

Responses
Table 47. HTTP Response Codes
Code Message Datatype

200

OK

AttachmentFile
Example HTTP request
Example Curl request
Example HTTP response

5.8. FilteringRulesOnAttachments

5.8.1. Add attachment filter to domain

POST /domains/{domainId}/filters/attachments

Description

Add attachment filter rule to the domain. Returns the added element.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 48. HTTP Response Codes
Code Message Datatype

404

Domain may not exist

FilterAttachment

403

You do not have permission to execute this request.

FilterAttachment

409

This item may already exists with same rules

FilterAttachment
Example HTTP request
POST /domains/Eygdk/filters/attachments HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 105
Host: localhost:8080

{ "action": "ALLOW", "checkType": "CONTENTTYPE", "filter":  ".xlsx" , "description":  "Allow xslx files"}
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/filters/attachments' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{ "action": "ALLOW", "checkType": "CONTENTTYPE", "filter":  ".xlsx" , "description":  "Allow xslx files"}'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: Content-Location
Location: http://localhost:8080/domains/Eygdk/filters/attachments
Content-Type: application/json
Content-Length: 209

{
  "id" : "ByE3n",
  "action" : "ALLOW",
  "checkType" : "CONTENTTYPE",
  "filter" : ".xlsx",
  "scope" : "stark.net",
  "priority" : 1,
  "description" : "Allow xslx files",
  "createdDate" : 1781777611556
}

5.8.2. Delete an attachment filter.

DELETE /filters/attachments/{attachmentId}

Description

Delete an existing attachment filter.

Parameters
Path Parameters
Name Description Required Default Pattern

attachmentId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 49. HTTP Response Codes
Code Message Datatype

400

A problem occured

[String]

403

You do not have permission to execute this request.

[String]

404

No attachment filter found with given id

[String]
Example HTTP request
DELETE /filters/attachments/ByE3n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzYxMiwiZXhwIjoxNzgxNzgxMjEyfQ.xw5DmHqUQVDk6rybtRPHCCaJDz9BT0Gkwel2_2ArbU816UG81Oi8VWuhmypitqIkv5r4paE635Wm41Kbohy1zQ
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/filters/attachments/ByE3n' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzYxMiwiZXhwIjoxNzgxNzgxMjEyfQ.xw5DmHqUQVDk6rybtRPHCCaJDz9BT0Gkwel2_2ArbU816UG81Oi8VWuhmypitqIkv5r4paE635Wm41Kbohy1zQ'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.8.3. Get domain’s attachement filters

GET /domains/{domainId}/filters/attachments

Description

Returns attachments filter rules of the domain.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Query Parameters
Name Description Required Default Pattern

offset

Index of the first filter rule to return, defaults to 0

-

null

pageSize

Maximum number of groups returned, defaults to 40

-

null

sort

Define the sort applied on response. Prefix the field name by '-' to reverse the sort.

-

null

action

Filter the list by action

-

null
Return Type

-

Content Type

  • application/json

  • application/vnd.ms-excel

Responses
Table 50. HTTP Response Codes
Code Message Datatype

404

Domain may not exist

List[FilterAttachment]

403

You do not have permission to execute this request.

List[FilterAttachment]
Example HTTP request
Example Curl request
Example HTTP response

5.8.4. Edit an attachment filter.

PATCH /filters/attachments/{attachmentId}

Description

Edit properties of an existing attachment filter. Apply changes only on specified fields in request. Attributes which are not provided will not be updated.

Parameters
Path Parameters
Name Description Required Default Pattern

attachmentId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 51. HTTP Response Codes
Code Message Datatype

400

A problem occured

FilterAttachment

403

You do not have permission to execute this request.

FilterAttachment

404

No attachment filter found with given id

FilterAttachment
Example HTTP request
PATCH /filters/attachments/ByE3n HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 73
Host: localhost:8080

{ "action": "DENY", "filter":  ".xls" , "description":  "Deny xls files"}
Example Curl request
$ curl 'http://localhost:8080/filters/attachments/ByE3n' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{ "action": "DENY", "filter":  ".xls" , "description":  "Deny xls files"}'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.9. FilteringRulesOnSenders

5.9.1. Add entries

POST /wblist

Description

Add a list of rules. Returns the list of added elements.

Parameters
Body Parameter
Name Description Required Default Pattern

FilterSenderItem

FilterSenderItem

X
Return Type

-

Content Type

  • application/json

Responses
Table 52. HTTP Response Codes
Code Message Datatype

403

You do not have permission to execute this request.

List[FilterSender]

409

An identical rule may already exists

List[FilterSender]

422

Operation cannot be done because of not met conditions.

List[FilterSender]
Example HTTP request
POST /wblist HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2MiwiZXhwIjoxNzgxNzgxMzYyfQ.Cy72WCXrvcH3UzwHEEwlgIrHEJLmWQphaifpod6_bCkd-2eM8DxMAD-tqPwPw7QCh_dMWDV5rK36QPpR8c_lqg
Content-Length: 229
Host: localhost:8080

[{"value":"daenerys@goodguys.fr","owner":"iswittercoming.net","type":"ALLOW","spfOn":true},{"value":"baelish@badguys.fr","owner":"notyet@iswittercoming.net","type":"BLOCK","expireAt":1787048162542,"description":"he's a traitor"}]
Example Curl request
$ curl 'http://localhost:8080/wblist' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2MiwiZXhwIjoxNzgxNzgxMzYyfQ.Cy72WCXrvcH3UzwHEEwlgIrHEJLmWQphaifpod6_bCkd-2eM8DxMAD-tqPwPw7QCh_dMWDV5rK36QPpR8c_lqg' \
    -d '[{"value":"daenerys@goodguys.fr","owner":"iswittercoming.net","type":"ALLOW","spfOn":true},{"value":"baelish@badguys.fr","owner":"notyet@iswittercoming.net","type":"BLOCK","expireAt":1787048162542,"description":"he's a traitor"}]'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 444

[ {
  "id" : "ByE3n",
  "value" : "daenerys@goodguys.fr",
  "owner" : "iswittercoming.net",
  "type" : "ALLOW",
  "createdDate" : 1781777762571,
  "expireAt" : null,
  "description" : null,
  "spfOn" : true
}, {
  "id" : "By46n",
  "value" : "baelish@badguys.fr",
  "owner" : "notyet@iswittercoming.net",
  "type" : "BLOCK",
  "createdDate" : 1781777762602,
  "expireAt" : 1787048162542,
  "description" : "he's a traitor",
  "spfOn" : null
} ]

5.9.2. Add domain rule

POST /domains/{domainId}/wblist

Description

Add elements in domain filtering rules. Returns the list of added elements.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Body Parameter
Name Description Required Default Pattern

FilterSenderAdd

FilterSenderAdd

X
Return Type

-

Content Type

  • application/json

Responses
Table 53. HTTP Response Codes
Code Message Datatype

404

Domain may not exist

List[FilterSender]

403

You do not have permission to execute this request.

List[FilterSender]

409

An identical rule may already exist

List[FilterSender]

422

Operation cannot be done because of not met conditions.

List[FilterSender]
Example HTTP request
POST /domains/Eygdk/wblist HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2MCwiZXhwIjoxNzgxNzgxMzYwfQ.Zt1KvDh9PV6jWeMjZ2K_tuQBih5ZvSaNACMMbbKPxZdaB0cjuzTSb2sPb5rS1kxBVwXJPr4_LArZYI46TLYV1w
Content-Length: 164
Host: localhost:8080

[{"value":"daenerys@goodguys.fr","type":"ALLOW","spfOn":true},{"value":"baelish@badguys.fr","type":"BLOCK","expireAt":1787048160706,"description":"he's a traitor"}]
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/wblist' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2MCwiZXhwIjoxNzgxNzgxMzYwfQ.Zt1KvDh9PV6jWeMjZ2K_tuQBih5ZvSaNACMMbbKPxZdaB0cjuzTSb2sPb5rS1kxBVwXJPr4_LArZYI46TLYV1w' \
    -d '[{"value":"daenerys@goodguys.fr","type":"ALLOW","spfOn":true},{"value":"baelish@badguys.fr","type":"BLOCK","expireAt":1787048160706,"description":"he's a traitor"}]'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: Content-Location
Location: http://localhost:8080/domains/Eygdk/wblist
Content-Type: application/json
Content-Length: 419

[ {
  "id" : "ByE3n",
  "value" : "daenerys@goodguys.fr",
  "owner" : "alive.net",
  "type" : "ALLOW",
  "createdDate" : 1781777760728,
  "expireAt" : null,
  "description" : null,
  "spfOn" : true
}, {
  "id" : "By46n",
  "value" : "baelish@badguys.fr",
  "owner" : "alive.net",
  "type" : "BLOCK",
  "createdDate" : 1781777760744,
  "expireAt" : 1787048160706,
  "description" : "he's a traitor",
  "spfOn" : null
} ]

5.9.3. Add mailbox rule

POST /users/{userId}/wblist

Description

Add elements in mailbox filtering rules. Returns the list of added elements.

Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null
Body Parameter
Name Description Required Default Pattern

FilterSenderAdd

FilterSenderAdd

X
Return Type

-

Content Type

  • application/json

Responses
Table 54. HTTP Response Codes
Code Message Datatype

404

User may not exist

List[FilterSender]

403

You do not have permission to execute this request.

List[FilterSender]

409

An identical rule may already exist

List[FilterSender]

422

Operation cannot be done because of not met conditions.

List[FilterSender]
Example HTTP request
POST /users/By46n/wblist HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc0NSwiZXhwIjoxNzgxNzgxMzQ1fQ.w0qEkS-lqvnfW9vWTfaun1zD7DdBhPLcDOaF7wIHCa9yyfGWb7ExVf8PkloWz1BNccRCb1jV9C_6W5osRtoHTA
Content-Length: 164
Host: localhost:8080

[{"value":"daenerys@goodguys.fr","type":"ALLOW","spfOn":true},{"value":"baelish@badguys.fr","type":"BLOCK","expireAt":1787048145391,"description":"he's a traitor"}]
Example Curl request
$ curl 'http://localhost:8080/users/By46n/wblist' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc0NSwiZXhwIjoxNzgxNzgxMzQ1fQ.w0qEkS-lqvnfW9vWTfaun1zD7DdBhPLcDOaF7wIHCa9yyfGWb7ExVf8PkloWz1BNccRCb1jV9C_6W5osRtoHTA' \
    -d '[{"value":"daenerys@goodguys.fr","type":"ALLOW","spfOn":true},{"value":"baelish@badguys.fr","type":"BLOCK","expireAt":1787048145391,"description":"he's a traitor"}]'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: Content-Location
Location: http://localhost:8080/users/By46n/wblist
Content-Type: application/json
Content-Length: 451

[ {
  "id" : "ByE3n",
  "value" : "daenerys@goodguys.fr",
  "owner" : "notyet@iswittercoming.net",
  "type" : "ALLOW",
  "createdDate" : 1781777745449,
  "expireAt" : null,
  "description" : null,
  "spfOn" : true
}, {
  "id" : "By46n",
  "value" : "baelish@badguys.fr",
  "owner" : "notyet@iswittercoming.net",
  "type" : "BLOCK",
  "createdDate" : 1781777745592,
  "expireAt" : 1787048145391,
  "description" : "he's a traitor",
  "spfOn" : null
} ]

5.9.4. Delete domain rule

DELETE /domains/{domainId}/wblist/{wbItemId}

Description

Delete a domain’s rule.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null

wbItemId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 55. HTTP Response Codes
Code Message Datatype

404

A problem occured. The domain may not exist

FilterSender

403

You do not have permission to execute this request.

FilterSender
Example HTTP request
DELETE /domains/Eygdk/wblist/ByE3n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc1MywiZXhwIjoxNzgxNzgxMzUzfQ.ACVaZR7tdAWzRDwaW3_3IysF4Xh3a-vbtlEkbIux0JOMl1cxmXGow8HV1pf448NYW1HNx0WfOeAtA-Vi98jWDA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/wblist/ByE3n' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc1MywiZXhwIjoxNzgxNzgxMzUzfQ.ACVaZR7tdAWzRDwaW3_3IysF4Xh3a-vbtlEkbIux0JOMl1cxmXGow8HV1pf448NYW1HNx0WfOeAtA-Vi98jWDA'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.9.5. Delete mailbox rule

DELETE /users/{userId}/wblist/{wbItemId}

Description

Delete a mailbox rule.

Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null

wbItemId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 56. HTTP Response Codes
Code Message Datatype

404

A problem occured. The user may not exist

FilterSender

403

You do not have permission to execute this request.

FilterSender
Example HTTP request
DELETE /users/By46n/wblist/ByE3n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2NywiZXhwIjoxNzgxNzgxMzY3fQ.awIaocaenFZXVFj3b9n3-WHJMzCb5-sQNBECV3A8OVhdPjU1dbpggowxIyR4NOTk1l-4FRGIs_AesFfqCBLwIw
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/users/By46n/wblist/ByE3n' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2NywiZXhwIjoxNzgxNzgxMzY3fQ.awIaocaenFZXVFj3b9n3-WHJMzCb5-sQNBECV3A8OVhdPjU1dbpggowxIyR4NOTk1l-4FRGIs_AesFfqCBLwIw'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.9.6. Get domain’s filter rules

GET /domains/{domainId}/wblist

Description

Returns senders which are defined in the allowlist and blocklist of the domain.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Query Parameters
Name Description Required Default Pattern

offset

Index of the first rule to return, defaults to 0

-

null

pageSize

Maximum number of entities returned, defaults to 40

-

null

sort

Define the sort applied on response. Prefix the field name by '-' to reverse the sort.

-

null

type

Filter the list by type, 'ALLOW' for allowlist and 'BLOCK' for blocklist

-

null

value

Filter the list by the sender value

-

null
Return Type

-

Content Type

  • application/json

  • application/vnd.ms-excel

Responses
Table 57. HTTP Response Codes
Code Message Datatype

404

Domain may not exist

List[FilterSender]

403

You do not have permission to execute this request.

List[FilterSender]
Example HTTP request
GET /domains/Eygdk/wblist HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc1OSwiZXhwIjoxNzgxNzgxMzU5fQ.Wznv6K2Q7ktfCmp7nBYSNFUrNCAckt658lXIOOQKTcku8hicRtnAb7YdPger5ama9fk-ZJf-GgYlJteHt3X5HA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/wblist' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc1OSwiZXhwIjoxNzgxNzgxMzU5fQ.Wznv6K2Q7ktfCmp7nBYSNFUrNCAckt658lXIOOQKTcku8hicRtnAb7YdPger5ama9fk-ZJf-GgYlJteHt3X5HA'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: X-Total-Count
X-Total-Count: 5
Content-Type: application/json
Content-Length: 1001

[ {
  "id" : "ByE3n",
  "value" : "daenerys@goodguys.fr",
  "owner" : "alive.net",
  "type" : "ALLOW",
  "createdDate" : 1781777759000,
  "expireAt" : null,
  "description" : null,
  "spfOn" : true
}, {
  "id" : "By46n",
  "value" : "baelish@badguys.fr",
  "owner" : "alive.net",
  "type" : "BLOCK",
  "createdDate" : 1781777759000,
  "expireAt" : null,
  "description" : "he's a traitor",
  "spfOn" : null
}, {
  "id" : "Eygdk",
  "value" : "arya@goodguys.fr",
  "owner" : "alive.net",
  "type" : "ALLOW",
  "createdDate" : 1781777759000,
  "expireAt" : null,
  "description" : null,
  "spfOn" : true
}, {
  "id" : "YyjPn",
  "value" : "deadguys.fr",
  "owner" : "alive.net",
  "type" : "BLOCK",
  "createdDate" : 1781777759000,
  "expireAt" : 1787048159000,
  "description" : null,
  "spfOn" : null
}, {
  "id" : "Vnoey",
  "value" : "joffrey@badguys.fr",
  "owner" : "alive.net",
  "type" : "BLOCK",
  "createdDate" : 1781777759000,
  "expireAt" : null,
  "description" : null,
  "spfOn" : null
} ]

5.9.7. Get user’s filter rules

GET /users/{userId}/wblist

Description

Returns senders which are defined in the allowlist and blocklist of the user.

Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null
Query Parameters
Name Description Required Default Pattern

offset

Index of the first rule to return, defaults to 0

-

null

pageSize

Maximum number of entities returned, defaults to 40

-

null

sort

Define the sort applied on response. Prefix the field name by '-' to reverse the sort.

-

null

type

Filter the list by type, 'ALLOW' for allowlist and 'BLOCK' for blocklist

-

null

value

Filter the list by the sender value

-

null
Return Type

-

Content Type

  • application/json

  • application/vnd.ms-excel

Responses
Table 58. HTTP Response Codes
Code Message Datatype

404

User may not exist

List[FilterSender]

403

You do not have permission to execute this request.

List[FilterSender]
Example HTTP request
GET /users/By46n/wblist HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2NiwiZXhwIjoxNzgxNzgxMzY2fQ.TT-_VSmsd_CkI2STkvyaQNqHLqRMJ71tGadkirj6MLyVCXk_34WG_rSWDAu3dT3e9bO63LmENRdvG0GV8ZYV5g
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/users/By46n/wblist' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2NiwiZXhwIjoxNzgxNzgxMzY2fQ.TT-_VSmsd_CkI2STkvyaQNqHLqRMJ71tGadkirj6MLyVCXk_34WG_rSWDAu3dT3e9bO63LmENRdvG0GV8ZYV5g'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: X-Total-Count
X-Total-Count: 5
Content-Type: application/json
Content-Length: 1072

[ {
  "id" : "ByE3n",
  "value" : "daenerys@goodguys.fr",
  "owner" : "notyet@iswittercoming.net",
  "type" : "ALLOW",
  "createdDate" : 1781777766000,
  "expireAt" : null,
  "description" : null,
  "spfOn" : false
}, {
  "id" : "By46n",
  "value" : "baelish@badguys.fr",
  "owner" : "notyet@iswittercoming.net",
  "type" : "ALLOW",
  "createdDate" : 1781777766000,
  "expireAt" : 1787048166000,
  "description" : null,
  "spfOn" : false
}, {
  "id" : "Eygdk",
  "value" : "arya@goodguys.fr",
  "owner" : "notyet@iswittercoming.net",
  "type" : "ALLOW",
  "createdDate" : 1781777766000,
  "expireAt" : null,
  "description" : null,
  "spfOn" : false
}, {
  "id" : "YyjPn",
  "value" : "deadguys.fr",
  "owner" : "notyet@iswittercoming.net",
  "type" : "BLOCK",
  "createdDate" : 1781777766000,
  "expireAt" : null,
  "description" : null,
  "spfOn" : null
}, {
  "id" : "Vnoey",
  "value" : "joffrey@badguys.fr",
  "owner" : "notyet@iswittercoming.net",
  "type" : "BLOCK",
  "createdDate" : 1781777766000,
  "expireAt" : null,
  "description" : null,
  "spfOn" : null
} ]

5.9.8. Update domain rule

PUT /domains/{domainId}/wblist/{wbItemId}

Description

Replace a rule by another one.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null

wbItemId

X

null
Body Parameter
Name Description Required Default Pattern

FilterSenderAdd

FilterSenderAdd

X
Return Type

-

Content Type

  • application/json

Responses
Table 59. HTTP Response Codes
Code Message Datatype

404

Domain may not exist

FilterSender

403

You do not have permission to execute this request.

FilterSender

409

An identical rule may already exists

FilterSender

422

Operation cannot be done because of not met conditions.

FilterSender
Example HTTP request
PUT /domains/Eygdk/wblist/ByE3n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2NSwiZXhwIjoxNzgxNzgxMzY1fQ.nkZUwU6WdDSUmwYHJgYZPz02P-Ju9Pk0pjg5ldJe5L-HC2rsv8aapTcqrrOyI8W3RTzFhDar2sbiIloOOCf1IA
Content-Length: 43
Host: localhost:8080

{"value":"rickon@stark.net","type":"BLOCK"}
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/wblist/ByE3n' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2NSwiZXhwIjoxNzgxNzgxMzY1fQ.nkZUwU6WdDSUmwYHJgYZPz02P-Ju9Pk0pjg5ldJe5L-HC2rsv8aapTcqrrOyI8W3RTzFhDar2sbiIloOOCf1IA' \
    -d '{"value":"rickon@stark.net","type":"BLOCK"}'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 193

{
  "id" : "ByE3n",
  "value" : "rickon@stark.net",
  "owner" : "alive.net",
  "type" : "BLOCK",
  "createdDate" : 1781777765000,
  "expireAt" : null,
  "description" : null,
  "spfOn" : null
}

5.9.9. Update mailbox rule

PUT /users/{userId}/wblist/{wbItemId}

Description

Replace a rule by another one.

Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null

wbItemId

X

null
Body Parameter
Name Description Required Default Pattern

FilterSenderAdd

FilterSenderAdd

X
Return Type

-

Content Type

  • application/json

Responses
Table 60. HTTP Response Codes
Code Message Datatype

404

User may not exist

FilterSender

403

You do not have permission to execute this request.

FilterSender

409

An identical rule may already exists

FilterSender

422

Operation cannot be done because of not met conditions.

FilterSender
Example HTTP request
PUT /users/By46n/wblist/ByE3n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2MywiZXhwIjoxNzgxNzgxMzYzfQ.ll8iHa4XfGGygN1sfMVpJVrS_p8bY9nTM3fXW6k4bH8XDrLVwpAiBoHvLaPaCgGbYKxloglita2zg2IJ_uprgg
Content-Length: 41
Host: localhost:8080

{"value":"done@stark.net","type":"BLOCK"}
Example Curl request
$ curl 'http://localhost:8080/users/By46n/wblist/ByE3n' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2MywiZXhwIjoxNzgxNzgxMzYzfQ.ll8iHa4XfGGygN1sfMVpJVrS_p8bY9nTM3fXW6k4bH8XDrLVwpAiBoHvLaPaCgGbYKxloglita2zg2IJ_uprgg' \
    -d '{"value":"done@stark.net","type":"BLOCK"}'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 207

{
  "id" : "ByE3n",
  "value" : "done@stark.net",
  "owner" : "notyet@iswittercoming.net",
  "type" : "BLOCK",
  "createdDate" : 1781777763000,
  "expireAt" : null,
  "description" : null,
  "spfOn" : null
}

5.9.10. Set domain rules

PUT /domains/{domainId}/wblist

Description

Replace the whole list of domain’s filtering rules by another list. Returns the list of added elements.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Body Parameter
Name Description Required Default Pattern

FilterSenderAdd

FilterSenderAdd

X
Return Type

-

Content Type

  • application/json

Responses
Table 61. HTTP Response Codes
Code Message Datatype

404

Domain may not exist

List[FilterSender]

403

You do not have permission to execute this request.

List[FilterSender]

409

An identical rule may already exists

List[FilterSender]

422

Operation cannot be done because of not met conditions.

List[FilterSender]
Example HTTP request
PUT /domains/Eygdk/wblist HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2MSwiZXhwIjoxNzgxNzgxMzYxfQ.jtWhh7hyb0MkjNu2v7300cyLyKHdEBFSoDcYItvAc51FaIKBanH85tlImkCWydkBYBMqByZT4MFcb6swIFstxQ
Content-Length: 120
Host: localhost:8080

[{"value":"rickon@stark.net","type":"ALLOW","spfOn":true},{"value":"tywin.net","type":"BLOCK","expireAt":1787048161674}]
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/wblist' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2MSwiZXhwIjoxNzgxNzgxMzYxfQ.jtWhh7hyb0MkjNu2v7300cyLyKHdEBFSoDcYItvAc51FaIKBanH85tlImkCWydkBYBMqByZT4MFcb6swIFstxQ' \
    -d '[{"value":"rickon@stark.net","type":"ALLOW","spfOn":true},{"value":"tywin.net","type":"BLOCK","expireAt":1787048161674}]'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 394

[ {
  "id" : "ByE3n",
  "value" : "rickon@stark.net",
  "owner" : "alive.net",
  "type" : "ALLOW",
  "createdDate" : 1781777761700,
  "expireAt" : null,
  "description" : null,
  "spfOn" : true
}, {
  "id" : "By46n",
  "value" : "tywin.net",
  "owner" : "alive.net",
  "type" : "BLOCK",
  "createdDate" : 1781777761725,
  "expireAt" : 1787048161674,
  "description" : null,
  "spfOn" : null
} ]

5.9.11. Set mailbox rules

PUT /users/{userId}/wblist

Description

Replace the whole list of user’s filtering rules by another list. Returns the list of added elements.

Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null
Body Parameter
Name Description Required Default Pattern

FilterSenderAdd

FilterSenderAdd

X
Return Type

-

Content Type

  • application/json

Responses
Table 62. HTTP Response Codes
Code Message Datatype

404

User may not exist

List[FilterSender]

403

You do not have permission to execute this request.

List[FilterSender]

409

An identical rule may already exists

List[FilterSender]

422

Operation cannot be done because of not met conditions.

List[FilterSender]
Example HTTP request
PUT /users/By46n/wblist HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2NCwiZXhwIjoxNzgxNzgxMzY0fQ.s_4qZk_b3DnyzdtY4dwFpqwggfFsZJVLYgdi5-pLxbEjcA33z3uFSyPYwW1WtqmZEjFEV2Wme2YxX-DkX4377A
Content-Length: 82
Host: localhost:8080

[{"value":"rickon@stark.net","type":"BLOCK"},{"value":"tywin.net","type":"BLOCK"}]
Example Curl request
$ curl 'http://localhost:8080/users/By46n/wblist' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3Nzc2NCwiZXhwIjoxNzgxNzgxMzY0fQ.s_4qZk_b3DnyzdtY4dwFpqwggfFsZJVLYgdi5-pLxbEjcA33z3uFSyPYwW1WtqmZEjFEV2Wme2YxX-DkX4377A' \
    -d '[{"value":"rickon@stark.net","type":"BLOCK"},{"value":"tywin.net","type":"BLOCK"}]'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 417

[ {
  "id" : "ByE3n",
  "value" : "rickon@stark.net",
  "owner" : "notyet@iswittercoming.net",
  "type" : "BLOCK",
  "createdDate" : 1781777764372,
  "expireAt" : null,
  "description" : null,
  "spfOn" : null
}, {
  "id" : "By46n",
  "value" : "tywin.net",
  "owner" : "notyet@iswittercoming.net",
  "type" : "BLOCK",
  "createdDate" : 1781777764388,
  "expireAt" : null,
  "description" : null,
  "spfOn" : null
} ]

5.10. FilteringRulesOnURI

5.10.1. Add URI-BL filter to domain

POST /domains/{domainId}/filters/uris

Description

Add URI-BL filter rule to the domain. Returns the added element.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Body Parameter
Name Description Required Default Pattern

FilterUriBlAdd

FilterUriBlAdd

X
Return Type

-

Content Type

  • application/json

Responses
Table 63. HTTP Response Codes
Code Message Datatype

404

Domain may not exist

FilterUriBl

403

You do not have permission to execute this request.

FilterUriBl

409

This item may already exists with same rules

FilterUriBl
Example HTTP request
POST /domains/Eygdk/filters/uris HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 96
Host: localhost:8080

{ "action": "URIDNSBL_SKIP_DOMAIN", "filter":  "bulist.com" , "description":  "Rule bulist.com"}
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/filters/uris' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{ "action": "URIDNSBL_SKIP_DOMAIN", "filter":  "bulist.com" , "description":  "Rule bulist.com"}'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: Content-Location
Location: http://localhost:8080/domains/Eygdk/filters/uris
Content-Type: application/json
Content-Length: 197

{
  "id" : "ByE3n",
  "scope" : "stark.net",
  "action" : "URIDNSBL_SKIP_DOMAIN",
  "filter" : "bulist.com",
  "priority" : 1,
  "description" : "Rule bulist.com",
  "createdDate" : 1781777621674
}

5.10.2. Delete an uriBl filter.

DELETE /filters/uris/{uriId}

Description

Delete an existing uriBl filter.

Parameters
Path Parameters
Name Description Required Default Pattern

uriId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 64. HTTP Response Codes
Code Message Datatype

400

A problem occured

[String]

403

You do not have permission to execute this request.

[String]

404

No uriBl filter found with given id

[String]
Example HTTP request
DELETE /filters/uris/ByE3n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzYzNSwiZXhwIjoxNzgxNzgxMjM1fQ.U4DS-iLxriWS4NcA6s6xfVUXk9lICvb2s9lApsU46BS0tNH9Rq_gRpYgBxaWfAGVbDCKiY68-OnBNUOAhThquA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/filters/uris/ByE3n' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzYzNSwiZXhwIjoxNzgxNzgxMjM1fQ.U4DS-iLxriWS4NcA6s6xfVUXk9lICvb2s9lApsU46BS0tNH9Rq_gRpYgBxaWfAGVbDCKiY68-OnBNUOAhThquA'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.10.3. Get domain’s URI-BL filters

GET /domains/{domainId}/filters/uris

Description

Returns URI-BL elements of the domain.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Query Parameters
Name Description Required Default Pattern

offset

Index of the first filter rule to return, defaults to 0

-

null

pageSize

Maximum number of groups returned, defaults to 40

-

null

sort

Define the sort applied on response. Prefix the field name by '-' to reverse the sort.

-

null

action

Filter the list by action

-

null
Return Type

-

Content Type

  • application/json

  • application/vnd.ms-excel

Responses
Table 65. HTTP Response Codes
Code Message Datatype

404

Domain may not exist

List[FilterUriBl]

403

You do not have permission to execute this request.

List[FilterUriBl]
Example HTTP request
Example Curl request
Example HTTP response

5.10.4. Edit an uriBl filter.

PATCH /filters/uris/{uriId}

Description

Edit properties of an existing uriBl filter. Apply changes only on specified fields in request. Attributes which are not provided will not be updated.

Parameters
Path Parameters
Name Description Required Default Pattern

uriId

X

null
Body Parameter
Name Description Required Default Pattern

FilterUriBlAdd

FilterUriBlAdd

X
Return Type

-

Content Type

  • application/json

Responses
Table 66. HTTP Response Codes
Code Message Datatype

400

A problem occured

FilterUriBl

403

You do not have permission to execute this request.

FilterUriBl

404

No uriBl filter found with given id

FilterUriBl
Example HTTP request
PATCH /filters/uris/ByE3n HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 68
Host: localhost:8080

{ "action": "WHITELIST_URI_HOST", "description":  "Rule bulist.com"}
Example Curl request
$ curl 'http://localhost:8080/filters/uris/ByE3n' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{ "action": "WHITELIST_URI_HOST", "description":  "Rule bulist.com"}'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.11. Health

5.11.1. Run domain diagnostic

POST /domains/{domainId}/health

Description

Run integrity tests on the domain

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 67. HTTP Response Codes
Code Message Datatype

404

Domain does not exist.

EntityHealth

403

You do not have permission to execute this request.

EntityHealth
Example HTTP request
POST /domains/Eygdk/health HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU5MiwiZXhwIjoxNzgxNzgxMTkyfQ.3AL1D3uN9netpRzvnVfN4b5eopziLEwyUeNGMk0tqUowF5p2m9LKlDjpA14EYSEXYa6cU3IWJXjQ5bWtzUZvjA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/health' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU5MiwiZXhwIjoxNzgxNzgxMTkyfQ.3AL1D3uN9netpRzvnVfN4b5eopziLEwyUeNGMk0tqUowF5p2m9LKlDjpA14EYSEXYa6cU3IWJXjQ5bWtzUZvjA'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 496

{
  "performedAt" : 1781784792,
  "report" : {
    "status" : false,
    "entries" : [ {
      "type" : "MX",
      "result" : "ERROR_MX_MISSING_ENTRY",
      "output" : [ "Lookup for MX entry in DNS for targaryen.net", "Fail: No MX entry found" ]
    }, {
      "type" : "DKIM",
      "result" : "ERROR_DKIM_MISSING_ENTRY",
      "output" : [ "Lookup for dkim entry in DNS for targaryen.net", "Fail: DKIM DNS entry not found for domain \"targaryen.net\" and selector \"protect\"" ]
    } ]
  }
}

5.11.2. Run diagnostic on existing relay

POST /platforms/{platformId}/health

Description

Will check SMTP connectivity of the platform.

Parameters
Path Parameters
Name Description Required Default Pattern

platformId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 68. HTTP Response Codes
Code Message Datatype

404

Platform does not exist.

EntityHealth

403

You do not have permission to execute this request.

EntityHealth
Example HTTP request
Example Curl request
Example HTTP response

5.11.3. Get domain health

GET /domains/{domainId}/health

Description

Get result of the last tests on the domain

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 69. HTTP Response Codes
Code Message Datatype

404

Domain does not exist.

EntityHealth

403

You do not have permission to execute this request.

EntityHealth
Example HTTP request
GET /domains/Eygdk/health HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU5MSwiZXhwIjoxNzgxNzgxMTkxfQ.B8_X4JdbO7gb_d2s6rutpKUq5_Koxj5o168by_ZYRHlZCXnH1TU9w8DrWmlNzlU65_LPa8Zfljm5U_OU0Uq6cQ
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/health' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU5MSwiZXhwIjoxNzgxNzgxMTkxfQ.B8_X4JdbO7gb_d2s6rutpKUq5_Koxj5o168by_ZYRHlZCXnH1TU9w8DrWmlNzlU65_LPa8Zfljm5U_OU0Uq6cQ'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 410

{
  "performedAt" : 1781784791,
  "report" : {
    "status" : true,
    "entries" : [ {
      "type" : "MX",
      "result" : "OK",
      "output" : [ "Passed" ]
    }, {
      "type" : "DKIM",
      "result" : "ERROR_DKIM_MISSING_ENTRY",
      "output" : [ "Lookup for dkim entry in DNS for targaryen.net", "Fail: DKIM DNS entry not found for domain \"targaryen.net\" and selector \"protect\"" ]
    } ]
  }
}

5.11.4. Get health errors

GET /health

Description

Get all failures found on your environment.

Parameters
Return Type

-

Content Type

  • /

Responses
Table 70. HTTP Response Codes
Code Message Datatype

403

You do not have permission to execute this request.

List[DiagnosticEntryDTO]
Example HTTP request
GET /health HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY0NiwiZXhwIjoxNzgxNzgxMjQ2fQ.P0twKwg_QIxKEsCOECQUyEmT7XhsPUNCwDgTGRWrveIDYGIIy4mCZl0ghFnJ20PS5J4dJTtVqA9YbFf65yj3iw
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/health' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzY0NiwiZXhwIjoxNzgxNzgxMjQ2fQ.P0twKwg_QIxKEsCOECQUyEmT7XhsPUNCwDgTGRWrveIDYGIIy4mCZl0ghFnJ20PS5J4dJTtVqA9YbFf65yj3iw'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 1200

[ {
  "id" : "YyjPn",
  "name" : "stark.net",
  "type" : "DOMAIN",
  "health" : {
    "performedAt" : 1781784846,
    "report" : {
      "status" : false,
      "entries" : [ {
        "type" : "MX",
        "result" : "ERROR_MX_INVALID_ENTRY",
        "output" : [ "Lookup for MX entry in DNS for stark.net", "Required: 83.145.xxx.xxx", "Fail" ]
      }, {
        "type" : "DKIM",
        "result" : "ERROR_DKIM_INVALID_COUPLE",
        "output" : [ "Lookup for dkim entry in DNS for stark.net", "Fail: DKIM key defined in DNS does not match with private part" ]
      } ]
    }
  }
}, {
  "id" : "Eygdk",
  "name" : "targaryen.net",
  "type" : "DOMAIN",
  "health" : {
    "performedAt" : 1781784846,
    "report" : {
      "status" : false,
      "entries" : [ {
        "type" : "MX",
        "result" : "ERROR_MX_MISSING_ENTRY",
        "output" : [ "Lookup for MX entry in DNS for targaryen.net", "Fail: No MX entry found" ]
      }, {
        "type" : "DKIM",
        "result" : "ERROR_DKIM_MISSING_ENTRY",
        "output" : [ "Lookup for dkim entry in DNS for targaryen.net", "Fail: DKIM DNS entry not found for domain \"targaryen.net\" and selector \"cleanmail\"" ]
      } ]
    }
  }
} ]

5.11.5. Get diagnostic of existing relay

GET /platforms/{platformId}/health

Description

Get results of the last tests.

Parameters
Path Parameters
Name Description Required Default Pattern

platformId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 71. HTTP Response Codes
Code Message Datatype

404

Platform does not exist.

EntityHealth

403

You do not have permission to execute this request.

EntityHealth
Example HTTP request
Example Curl request
Example HTTP response

5.11.6. Try relay configuration

POST /health/try-relay

Description

Will check SMTP connectivity of the platform.

Parameters
Body Parameter
Name Description Required Default Pattern

RelayCheckHealthDTO

RelayCheckHealthDTO

X
Return Type

-

Content Type

  • application/json

Responses
Table 72. HTTP Response Codes
Code Message Datatype

403

You do not have permission to execute this request.

HealthRecord
Example HTTP request
Example Curl request
Example HTTP response

5.12. Tasks

5.12.1. Execute task

POST /tasks

Description

Launch a new task. Each type of task has its own access restrictions. - send_welcome_mail: Send an e-mail to the user containing a description of the service and a link to a password setup page. - send_token_mail: Send an e-mail to a the user containing a link with a token to log in to the application. - send_password_reset_mail: Send an e-mail to a the user containing a link to reset his/her password.

Parameters
Body Parameter
Name Description Required Default Pattern

Task

Task

X
Return Type

[String]

Content Type

  • application/json

Responses
Table 73. HTTP Response Codes
Code Message Datatype

202

Command is valid and will be executed.

[String]

400

Invalid parameters

[String]

403

Authorisation failure.

[String]

422

Operation cannot be done because of not met conditions.

[String]

401

Authentication failure.

[String]
Example HTTP request
POST /tasks HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU3NCwiZXhwIjoxNzgxNzgxMTc0fQ.cjTSKFQ1VfL_A1Fvy_6Bl-C6-jRAp8fEm65xI57TFJ3zCLxABuw3pupk9AbgVIrsR6JwEtBfgbW5jWucI7Xp8A
Content-Length: 77
Host: localhost:8080

{"command":"send_welcome_mail","params":{"recipient":"cersei@lannister.net"}}
Example Curl request
$ curl 'http://localhost:8080/tasks' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU3NCwiZXhwIjoxNzgxNzgxMTc0fQ.cjTSKFQ1VfL_A1Fvy_6Bl-C6-jRAp8fEm65xI57TFJ3zCLxABuw3pupk9AbgVIrsR6JwEtBfgbW5jWucI7Xp8A' \
    -d '{"command":"send_welcome_mail","params":{"recipient":"cersei@lannister.net"}}'
Example HTTP response
HTTP/1.1 202 Accepted
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.13. TemporaryAuthTokens

5.13.1. Temporary auth tokens

GET /token

Description

Generate a token for a user which allow the authententication. Action available only for the owner itself or and administrator with impersonnate permission.

Parameters
Query Parameters
Name Description Required Default Pattern

username

Email address of the required user

X

null

validity

Number of hours the token will be active

-

null
Return Type

AuthToken

Content Type

  • application/json

Responses
Table 74. HTTP Response Codes
Code Message Datatype

202

Asynchrone request has been taken into account : token is going to be sent soon

AuthToken

400

A problem occured. Possible causes: the account does not have quarantine or retention or archive service.

AuthToken

404

Unknown username

AuthToken
Example HTTP request
Example Curl request
Example HTTP response

5.14. Users

5.14.1. New user

POST /users

Description

Create a new user’s account in the domain specified in user’s email address.

Parameters
Body Parameter
Name Description Required Default Pattern

NewUser

NewUser

X
Return Type

User

Content Type

  • application/json

Responses
Table 75. HTTP Response Codes
Code Message Datatype

400

A problem occured. Possible causes: the account email does not match email format or domain not found

User

409

A user may already exists with the given name

User

422

Operation cannot be done because of not met conditions.

User

201

Created

User
Example HTTP request
POST /users HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcxOCwiZXhwIjoxNzgxNzgxMzE4fQ.-J8sVK_2dZjSGQ6kK9atim98299XpdP-EqSC-MxNLrkJl9zsLbSygGEgxHk_sYww21R23JkpE5ff3VK3iEseXw
Content-Length: 252
Host: localhost:8080

{"email":"tywin@lannister.net","firstname":"Tywin","lastname":"Lannister","status":"ENABLED","language":"EN","password":"HearMeRoar!","domainId":"ByE3n","platformId":"ByE3n","senderVerifyOn":"ENABLED","sendNotification":false,"senderVerifyActive":true}
Example Curl request
$ curl 'http://localhost:8080/users' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcxOCwiZXhwIjoxNzgxNzgxMzE4fQ.-J8sVK_2dZjSGQ6kK9atim98299XpdP-EqSC-MxNLrkJl9zsLbSygGEgxHk_sYww21R23JkpE5ff3VK3iEseXw' \
    -d '{"email":"tywin@lannister.net","firstname":"Tywin","lastname":"Lannister","status":"ENABLED","language":"EN","password":"HearMeRoar!","domainId":"ByE3n","platformId":"ByE3n","senderVerifyOn":"ENABLED","sendNotification":false,"senderVerifyActive":true}'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: Content-Location
Location: http://localhost:8080/users/By46n
Content-Type: application/json
Content-Length: 2109

{
  "id" : "By46n",
  "email" : "tywin@lannister.net",
  "firstname" : "Tywin",
  "lastname" : "Lannister",
  "status" : "ENABLED",
  "language" : "EN",
  "creationDate" : 1781777718148,
  "domainId" : "ByE3n",
  "policy" : {
    "id" : "ByE3n",
    "name" : "Politique-lannister.net",
    "domainId" : "ByE3n",
    "quarantine" : true,
    "retention" : true,
    "archive" : true,
    "mailSizeLimit" : 5,
    "spamScore" : 6.8,
    "incoming" : true,
    "relayProps" : {
      "relaySpam" : true,
      "relayAdvert" : true,
      "advertPrefix" : "[AD]",
      "prefixSpam" : null,
      "relayBadHeaders" : true,
      "relayBadAttachments" : true,
      "spamScoreLimit" : 10.0
    },
    "quarantineProps" : {
      "duration" : 31,
      "storeSpam" : false,
      "storeVirus" : false,
      "storeAdvert" : false,
      "storeBlacklisted" : false,
      "storeSenderVerify" : false,
      "storeBadHeaders" : false,
      "storeBadEncoding" : false,
      "storeBadAttachments" : false
    },
    "retentionProps" : {
      "duration" : 5,
      "storeMailOut" : false,
      "storeCleanMailIn" : false
    },
    "archiveProps" : {
      "duration" : 48,
      "archiveByCopy" : false,
      "storeMailOut" : false,
      "storeCleanMailIn" : false,
      "storeSpam" : false,
      "storeBadHeaders" : false,
      "storeBadEncoding" : false,
      "storeBadAttachments" : false,
      "storeAdvert" : false,
      "storeBlacklisted" : false,
      "storeSenderVerify" : false
    },
    "outgoing" : false
  },
  "senderVerifyOn" : true,
  "greylistingOn" : null,
  "domainPolicyId" : "ByE3n",
  "domainStatus" : "ENABLED",
  "domainPlatformId" : "ByE3n",
  "platform" : {
    "id" : "ByE3n",
    "name" : "Westeros",
    "transportDest" : "smtp.westeros.com",
    "transportType" : "SMTP",
    "transportPort" : 25,
    "fallbackTransportDest" : null,
    "fallbackTransportType" : null,
    "fallbackTransportPort" : null,
    "apiType" : null,
    "apiData" : null,
    "authType" : "local",
    "authData" : null,
    "default" : true
  },
  "mfaType" : null,
  "lastConnectionDate" : null
}

5.14.2. Delete user option

DELETE /users/{userId}/options/{optionName}

Description

Delete option value for user scope. The value of the parent scope will be used

Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null

optionName

X

null
Return Type

Option

Content Type

  • application/json

Responses
Table 76. HTTP Response Codes
Code Message Datatype

200

OK

Option
Example HTTP request
DELETE /users/By46n/options/USER_OPTION_EXAMPLE HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcyMSwiZXhwIjoxNzgxNzgxMzIxfQ.41awwlbn_3xaYPH_vC_6WSu_GR1mXz5ULto1uELjfXGdDv1hJTar0ylOGNBtZsoCVQ9NYIclh7k-wPsTwcx5CA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/users/By46n/options/USER_OPTION_EXAMPLE' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcyMSwiZXhwIjoxNzgxNzgxMzIxfQ.41awwlbn_3xaYPH_vC_6WSu_GR1mXz5ULto1uELjfXGdDv1hJTar0ylOGNBtZsoCVQ9NYIclh7k-wPsTwcx5CA'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.14.3. Delete a user

DELETE /users/{userId}

Description

Delete an existing user

Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 77. HTTP Response Codes
Code Message Datatype

404

User or domain not found with given id

User
Example HTTP request
DELETE /users/By46n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcyNSwiZXhwIjoxNzgxNzgxMzI1fQ.-19iQIAv02gfZOG-ZjVj_6lWhzc-csAQjR45uaqjWuqF4E8I5fw9Cn7FpyAwb_QV87KwafExA_6PlaBIEvFe-Q
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/users/By46n' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcyNSwiZXhwIjoxNzgxNzgxMzI1fQ.-19iQIAv02gfZOG-ZjVj_6lWhzc-csAQjR45uaqjWuqF4E8I5fw9Cn7FpyAwb_QV87KwafExA_6PlaBIEvFe-Q'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.14.4. Single user

GET /users/{userId}

Description

Get an existing user’s account

Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 78. HTTP Response Codes
Code Message Datatype

404

User not found with given id

User
Example HTTP request
GET /users/By46n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcyMiwiZXhwIjoxNzgxNzgxMzIyfQ.8FMsUdLUjenebR5W3MHlT-6-ZIR0qiCPWhP1B5Qsw4mPbR6_1PgH6nmduC6Rh22g6rACFq13E8d0fPaQFENQCQ
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/users/By46n' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcyMiwiZXhwIjoxNzgxNzgxMzIyfQ.8FMsUdLUjenebR5W3MHlT-6-ZIR0qiCPWhP1B5Qsw4mPbR6_1PgH6nmduC6Rh22g6rACFq13E8d0fPaQFENQCQ'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 1368

{
  "id" : "By46n",
  "email" : "sansa@stark.net",
  "firstname" : "Sansa",
  "lastname" : "Stark",
  "status" : "ENABLED",
  "language" : "EN",
  "creationDate" : 1781777722000,
  "domainId" : "Eygdk",
  "policy" : {
    "id" : "Eygdk",
    "name" : "Politique-stark.net",
    "domainId" : "Eygdk",
    "quarantine" : false,
    "retention" : false,
    "archive" : false,
    "mailSizeLimit" : 21,
    "spamScore" : 5.0,
    "incoming" : true,
    "relayProps" : {
      "relaySpam" : true,
      "relayAdvert" : true,
      "advertPrefix" : "",
      "prefixSpam" : null,
      "relayBadHeaders" : true,
      "relayBadAttachments" : true,
      "spamScoreLimit" : 10.0
    },
    "quarantineProps" : null,
    "retentionProps" : null,
    "archiveProps" : null,
    "outgoing" : false
  },
  "senderVerifyOn" : null,
  "greylistingOn" : null,
  "domainPolicyId" : "Eygdk",
  "domainStatus" : "ENABLED",
  "domainPlatformId" : "Eygdk",
  "platform" : {
    "id" : "Eygdk",
    "name" : "platform",
    "transportDest" : "1.2.3.4",
    "transportType" : "SMTP",
    "transportPort" : 25,
    "fallbackTransportDest" : null,
    "fallbackTransportType" : null,
    "fallbackTransportPort" : null,
    "apiType" : null,
    "apiData" : null,
    "authType" : "local",
    "authData" : null,
    "default" : true
  },
  "mfaType" : null,
  "lastConnectionDate" : null
}

5.14.5. List domain users

GET /domains/{domainId}/users

Description

Returns the list of users of a given domain.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Query Parameters
Name Description Required Default Pattern

offset

Index of the first account to return, defaults to 0

-

null

pageSize

Maximum number of users returned, defaults to 40

-

null

sort

Define the sort applied on response. Prefix the field name by '-' to reverse the sort.

-

null

email

Filter by email

-

null

platformName

Filter by platform name

-

null
Return Type

-

Content Type

  • application/json

  • application/vnd.ms-excel

Responses
Table 79. HTTP Response Codes
Code Message Datatype

404

Domain not found with given id

List[User]
Example HTTP request
GET /domains/ByE3n/users?name=*lannister.net HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcyNiwiZXhwIjoxNzgxNzgxMzI2fQ.9bncqycM6__xIcIDI3J7YNHphju4QdYZFPkvP3bljg345HlCzJZmeBbtISdB1WPiGj3b3mtA46APDOjUk2Eutg
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/ByE3n/users?name=*lannister.net' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcyNiwiZXhwIjoxNzgxNzgxMzI2fQ.9bncqycM6__xIcIDI3J7YNHphju4QdYZFPkvP3bljg345HlCzJZmeBbtISdB1WPiGj3b3mtA46APDOjUk2Eutg'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: X-Total-Count
X-Total-Count: 3
Content-Type: application/json
Content-Length: 6192

[ {
  "id" : "ByE3n",
  "email" : "cersei@lannister.net",
  "firstname" : "Cersei",
  "lastname" : "Lannister",
  "status" : "ENABLED",
  "language" : "FR",
  "creationDate" : 1781777726000,
  "domainId" : "ByE3n",
  "policy" : {
    "id" : "ByE3n",
    "name" : "Politique-lannister.net",
    "domainId" : "ByE3n",
    "quarantine" : true,
    "retention" : true,
    "archive" : true,
    "mailSizeLimit" : 5,
    "spamScore" : 6.8,
    "incoming" : true,
    "relayProps" : {
      "relaySpam" : true,
      "relayAdvert" : true,
      "advertPrefix" : "[AD]",
      "prefixSpam" : null,
      "relayBadHeaders" : true,
      "relayBadAttachments" : true,
      "spamScoreLimit" : 10.0
    },
    "quarantineProps" : {
      "duration" : 31,
      "storeSpam" : false,
      "storeVirus" : false,
      "storeAdvert" : false,
      "storeBlacklisted" : false,
      "storeSenderVerify" : false,
      "storeBadHeaders" : false,
      "storeBadEncoding" : false,
      "storeBadAttachments" : false
    },
    "retentionProps" : {
      "duration" : 5,
      "storeMailOut" : false,
      "storeCleanMailIn" : false
    },
    "archiveProps" : {
      "duration" : 48,
      "archiveByCopy" : false,
      "storeMailOut" : false,
      "storeCleanMailIn" : false,
      "storeSpam" : false,
      "storeBadHeaders" : false,
      "storeBadEncoding" : false,
      "storeBadAttachments" : false,
      "storeAdvert" : false,
      "storeBlacklisted" : false,
      "storeSenderVerify" : false
    },
    "outgoing" : false
  },
  "senderVerifyOn" : true,
  "greylistingOn" : null,
  "domainPolicyId" : "ByE3n",
  "domainStatus" : "ENABLED",
  "domainPlatformId" : "ByE3n",
  "platform" : {
    "id" : "ByE3n",
    "name" : "Westeros",
    "transportDest" : "smtp.westeros.com",
    "transportType" : "SMTP",
    "transportPort" : 25,
    "fallbackTransportDest" : null,
    "fallbackTransportType" : null,
    "fallbackTransportPort" : null,
    "apiType" : null,
    "apiData" : null,
    "authType" : "local",
    "authData" : null,
    "default" : true
  }
}, {
  "id" : "By46n",
  "email" : "joffrey@lannister.net",
  "firstname" : "Joffrey",
  "lastname" : "Lannister",
  "status" : "DISABLED",
  "language" : "EN",
  "creationDate" : 1781777726000,
  "domainId" : "ByE3n",
  "policy" : {
    "id" : "ByE3n",
    "name" : "Politique-lannister.net",
    "domainId" : "ByE3n",
    "quarantine" : true,
    "retention" : true,
    "archive" : true,
    "mailSizeLimit" : 5,
    "spamScore" : 6.8,
    "incoming" : true,
    "relayProps" : {
      "relaySpam" : true,
      "relayAdvert" : true,
      "advertPrefix" : "[AD]",
      "prefixSpam" : null,
      "relayBadHeaders" : true,
      "relayBadAttachments" : true,
      "spamScoreLimit" : 10.0
    },
    "quarantineProps" : {
      "duration" : 31,
      "storeSpam" : false,
      "storeVirus" : false,
      "storeAdvert" : false,
      "storeBlacklisted" : false,
      "storeSenderVerify" : false,
      "storeBadHeaders" : false,
      "storeBadEncoding" : false,
      "storeBadAttachments" : false
    },
    "retentionProps" : {
      "duration" : 5,
      "storeMailOut" : false,
      "storeCleanMailIn" : false
    },
    "archiveProps" : {
      "duration" : 48,
      "archiveByCopy" : false,
      "storeMailOut" : false,
      "storeCleanMailIn" : false,
      "storeSpam" : false,
      "storeBadHeaders" : false,
      "storeBadEncoding" : false,
      "storeBadAttachments" : false,
      "storeAdvert" : false,
      "storeBlacklisted" : false,
      "storeSenderVerify" : false
    },
    "outgoing" : false
  },
  "senderVerifyOn" : null,
  "greylistingOn" : null,
  "domainPolicyId" : "ByE3n",
  "domainStatus" : "ENABLED",
  "domainPlatformId" : "ByE3n",
  "platform" : {
    "id" : "ByE3n",
    "name" : "Westeros",
    "transportDest" : "smtp.westeros.com",
    "transportType" : "SMTP",
    "transportPort" : 25,
    "fallbackTransportDest" : null,
    "fallbackTransportType" : null,
    "fallbackTransportPort" : null,
    "apiType" : null,
    "apiData" : null,
    "authType" : "local",
    "authData" : null,
    "default" : true
  }
}, {
  "id" : "Eygdk",
  "email" : "tommen@lannister.net",
  "firstname" : "Tommen",
  "lastname" : "Lannister",
  "status" : "DISABLED",
  "language" : "EN",
  "creationDate" : 1781777726000,
  "domainId" : "ByE3n",
  "policy" : {
    "id" : "ByE3n",
    "name" : "Politique-lannister.net",
    "domainId" : "ByE3n",
    "quarantine" : true,
    "retention" : true,
    "archive" : true,
    "mailSizeLimit" : 5,
    "spamScore" : 6.8,
    "incoming" : true,
    "relayProps" : {
      "relaySpam" : true,
      "relayAdvert" : true,
      "advertPrefix" : "[AD]",
      "prefixSpam" : null,
      "relayBadHeaders" : true,
      "relayBadAttachments" : true,
      "spamScoreLimit" : 10.0
    },
    "quarantineProps" : {
      "duration" : 31,
      "storeSpam" : false,
      "storeVirus" : false,
      "storeAdvert" : false,
      "storeBlacklisted" : false,
      "storeSenderVerify" : false,
      "storeBadHeaders" : false,
      "storeBadEncoding" : false,
      "storeBadAttachments" : false
    },
    "retentionProps" : {
      "duration" : 5,
      "storeMailOut" : false,
      "storeCleanMailIn" : false
    },
    "archiveProps" : {
      "duration" : 48,
      "archiveByCopy" : false,
      "storeMailOut" : false,
      "storeCleanMailIn" : false,
      "storeSpam" : false,
      "storeBadHeaders" : false,
      "storeBadEncoding" : false,
      "storeBadAttachments" : false,
      "storeAdvert" : false,
      "storeBlacklisted" : false,
      "storeSenderVerify" : false
    },
    "outgoing" : false
  },
  "senderVerifyOn" : null,
  "greylistingOn" : null,
  "domainPolicyId" : "ByE3n",
  "domainStatus" : "ENABLED",
  "domainPlatformId" : "ByE3n",
  "platform" : {
    "id" : "ByE3n",
    "name" : "Westeros",
    "transportDest" : "smtp.westeros.com",
    "transportType" : "SMTP",
    "transportPort" : 25,
    "fallbackTransportDest" : null,
    "fallbackTransportType" : null,
    "fallbackTransportPort" : null,
    "apiType" : null,
    "apiData" : null,
    "authType" : "local",
    "authData" : null,
    "default" : true
  }
} ]

5.14.6. List user options

GET /users/{userId}/options

Description

Returns a list of options defined for given user

Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null
Return Type

array[Option]

Content Type

  • application/json

Responses
Table 80. HTTP Response Codes
Code Message Datatype

200

OK

List[Option]
Example HTTP request
GET /users/By46n/options HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcyMywiZXhwIjoxNzgxNzgxMzIzfQ.phNc7jxJF1ZFuUrjQPm4uggmRVIpckDGLZmj4_Yb1co1qjw6fm7ms9P_M8LZHXlpQZuH_N7oP-Ww0zkNjehlvw
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/users/By46n/options' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcyMywiZXhwIjoxNzgxNzgxMzIzfQ.phNc7jxJF1ZFuUrjQPm4uggmRVIpckDGLZmj4_Yb1co1qjw6fm7ms9P_M8LZHXlpQZuH_N7oP-Ww0zkNjehlvw'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: X-Total-Count
X-Total-Count: 1
Content-Type: application/json
Content-Length: 344

[ {
  "value" : "1",
  "parentValue" : "0",
  "option" : {
    "ptfScope" : true,
    "urlScope" : false,
    "customerScope" : false,
    "domainScope" : false,
    "userScope" : true,
    "restricted" : false,
    "group" : null,
    "name" : "USER_OPTION_EXAMPLE",
    "type" : "STRING",
    "values" : null,
    "description" : null
  }
} ]

5.14.7. List users

GET /users

Description

Returns the list of users regardless of the domain. If the response does not contain a user which does exist, the problem might caused by a missing security role on the domain of the searched user.

Parameters
Query Parameters
Name Description Required Default Pattern

offset

Index of the first account to return, defaults to 0

-

null

pageSize

Maximum number of users returned, defaults to 40

-

null

sort

Define the sort applied on response. Prefix the field name by '-' to reverse the sort.

-

null

email

Filter by email

-

null

platformName

Filter by platform name

-

null
Return Type

array[User]

Content Type

  • application/json

Responses
Table 81. HTTP Response Codes
Code Message Datatype

200

OK

List[User]
Example HTTP request
GET /users?name=ByE3n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcxOSwiZXhwIjoxNzgxNzgxMzE5fQ.woIYxyHgFKj4W9UE3DD_BSd94EVbfvle7wpxkOQ8nipzIvK10DF6zugxGq01uRa11dX7jeJJB9_SPdBLajP1ig
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/users?name=ByE3n' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcxOSwiZXhwIjoxNzgxNzgxMzE5fQ.woIYxyHgFKj4W9UE3DD_BSd94EVbfvle7wpxkOQ8nipzIvK10DF6zugxGq01uRa11dX7jeJJB9_SPdBLajP1ig'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: X-Total-Count
X-Total-Count: 3
Content-Type: application/json
Content-Length: 4716

[ {
  "id" : "ByE3n",
  "email" : "cersei@lannister.net",
  "firstname" : "Cersei",
  "lastname" : "Lannister",
  "status" : "ENABLED",
  "language" : "FR",
  "creationDate" : 1781777718000,
  "domainId" : "ByE3n",
  "policy" : {
    "id" : "ByE3n",
    "name" : "Politique-lannister.net",
    "domainId" : "ByE3n",
    "quarantine" : true,
    "retention" : true,
    "archive" : true,
    "mailSizeLimit" : 5,
    "spamScore" : 6.8,
    "incoming" : true,
    "relayProps" : {
      "relaySpam" : true,
      "relayAdvert" : true,
      "advertPrefix" : "[AD]",
      "prefixSpam" : null,
      "relayBadHeaders" : true,
      "relayBadAttachments" : true,
      "spamScoreLimit" : 10.0
    },
    "quarantineProps" : {
      "duration" : 31,
      "storeSpam" : false,
      "storeVirus" : false,
      "storeAdvert" : false,
      "storeBlacklisted" : false,
      "storeSenderVerify" : false,
      "storeBadHeaders" : false,
      "storeBadEncoding" : false,
      "storeBadAttachments" : false
    },
    "retentionProps" : {
      "duration" : 5,
      "storeMailOut" : false,
      "storeCleanMailIn" : false
    },
    "archiveProps" : {
      "duration" : 48,
      "archiveByCopy" : false,
      "storeMailOut" : false,
      "storeCleanMailIn" : false,
      "storeSpam" : false,
      "storeBadHeaders" : false,
      "storeBadEncoding" : false,
      "storeBadAttachments" : false,
      "storeAdvert" : false,
      "storeBlacklisted" : false,
      "storeSenderVerify" : false
    },
    "outgoing" : false
  },
  "senderVerifyOn" : true,
  "greylistingOn" : null,
  "domainPolicyId" : "ByE3n",
  "domainStatus" : "ENABLED",
  "domainPlatformId" : "ByE3n",
  "platform" : {
    "id" : "ByE3n",
    "name" : "Westeros",
    "transportDest" : "smtp.westeros.com",
    "transportType" : "SMTP",
    "transportPort" : 25,
    "fallbackTransportDest" : null,
    "fallbackTransportType" : null,
    "fallbackTransportPort" : null,
    "apiType" : null,
    "apiData" : null,
    "authType" : "local",
    "authData" : null,
    "default" : true
  }
}, {
  "id" : "Eygdk",
  "email" : "elia@martell.net",
  "firstname" : "Elia",
  "lastname" : "Martell",
  "status" : "DISABLED",
  "language" : "EN",
  "creationDate" : 1781777719000,
  "domainId" : "Eygdk",
  "policy" : {
    "id" : "Eygdk",
    "name" : "Politique-martell.net",
    "domainId" : "Eygdk",
    "quarantine" : false,
    "retention" : false,
    "archive" : false,
    "mailSizeLimit" : 21,
    "spamScore" : 5.0,
    "incoming" : true,
    "relayProps" : {
      "relaySpam" : true,
      "relayAdvert" : true,
      "advertPrefix" : "",
      "prefixSpam" : null,
      "relayBadHeaders" : true,
      "relayBadAttachments" : true,
      "spamScoreLimit" : 10.0
    },
    "quarantineProps" : null,
    "retentionProps" : null,
    "archiveProps" : null,
    "outgoing" : false
  },
  "senderVerifyOn" : null,
  "greylistingOn" : null,
  "domainPolicyId" : "Eygdk",
  "domainStatus" : "ENABLED",
  "domainPlatformId" : "Eygdk",
  "platform" : {
    "id" : "Eygdk",
    "name" : "platform",
    "transportDest" : "1.2.3.4",
    "transportType" : "SMTP",
    "transportPort" : 25,
    "fallbackTransportDest" : null,
    "fallbackTransportType" : null,
    "fallbackTransportPort" : null,
    "apiType" : null,
    "apiData" : null,
    "authType" : "local",
    "authData" : null,
    "default" : true
  }
}, {
  "id" : "By46n",
  "email" : "oberyn@martell.net",
  "firstname" : "Oberyn",
  "lastname" : "Martell",
  "status" : "DISABLED",
  "language" : "EN",
  "creationDate" : 1781777719000,
  "domainId" : "Eygdk",
  "policy" : {
    "id" : "Eygdk",
    "name" : "Politique-martell.net",
    "domainId" : "Eygdk",
    "quarantine" : false,
    "retention" : false,
    "archive" : false,
    "mailSizeLimit" : 21,
    "spamScore" : 5.0,
    "incoming" : true,
    "relayProps" : {
      "relaySpam" : true,
      "relayAdvert" : true,
      "advertPrefix" : "",
      "prefixSpam" : null,
      "relayBadHeaders" : true,
      "relayBadAttachments" : true,
      "spamScoreLimit" : 10.0
    },
    "quarantineProps" : null,
    "retentionProps" : null,
    "archiveProps" : null,
    "outgoing" : false
  },
  "senderVerifyOn" : null,
  "greylistingOn" : null,
  "domainPolicyId" : "Eygdk",
  "domainStatus" : "ENABLED",
  "domainPlatformId" : "Eygdk",
  "platform" : {
    "id" : "Eygdk",
    "name" : "platform",
    "transportDest" : "1.2.3.4",
    "transportType" : "SMTP",
    "transportPort" : 25,
    "fallbackTransportDest" : null,
    "fallbackTransportType" : null,
    "fallbackTransportPort" : null,
    "apiType" : null,
    "apiData" : null,
    "authType" : "local",
    "authData" : null,
    "default" : true
  }
} ]

5.14.8. Set user option

POST /users/{userId}/options

Description

Set option value to an user. The list of available options can be consulted in api GET /options

Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null
Body Parameter
Name Description Required Default Pattern

OptionAdd

OptionAdd

X
Return Type

Option

Content Type

  • application/json

Responses
Table 82. HTTP Response Codes
Code Message Datatype

200

OK

Option
Example HTTP request
POST /users/By46n/options HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcyNCwiZXhwIjoxNzgxNzgxMzI0fQ.YGdqFNP3uDkgVVfN4-v-EsPkkg25K5SOP-LrFK6mqclrCFHA0V0dPITtSsi0xvPRi-GZGKNQgCsS7aZe_oa0vg
Content-Length: 42
Host: localhost:8080

{"name":"USER_OPTION_EXAMPLE","value":"1"}
Example Curl request
$ curl 'http://localhost:8080/users/By46n/options' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcyNCwiZXhwIjoxNzgxNzgxMzI0fQ.YGdqFNP3uDkgVVfN4-v-EsPkkg25K5SOP-LrFK6mqclrCFHA0V0dPITtSsi0xvPRi-GZGKNQgCsS7aZe_oa0vg' \
    -d '{"name":"USER_OPTION_EXAMPLE","value":"1"}'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 340

{
  "value" : "1",
  "parentValue" : "0",
  "option" : {
    "ptfScope" : true,
    "urlScope" : false,
    "customerScope" : false,
    "domainScope" : false,
    "userScope" : true,
    "restricted" : false,
    "group" : null,
    "name" : "USER_OPTION_EXAMPLE",
    "type" : "STRING",
    "values" : null,
    "description" : null
  }
}

5.14.9. Edit a user

PATCH /users/{userId}

Description

Edit properties of an existing user. Apply changes only on specified fields in request. Attributes which are not provided will not be updated. Returns the updated user’s account.

Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null
Body Parameter
Name Description Required Default Pattern

UpdateUser

UpdateUser

X
Return Type

-

Content Type

  • application/json

Responses
Table 83. HTTP Response Codes
Code Message Datatype

400

A problem has occured. Possible cause: the account email does not match email format

[String]

404

User not found with given id

[String]
Example HTTP request
PATCH /users/By46n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcxOSwiZXhwIjoxNzgxNzgxMzE5fQ.woIYxyHgFKj4W9UE3DD_BSd94EVbfvle7wpxkOQ8nipzIvK10DF6zugxGq01uRa11dX7jeJJB9_SPdBLajP1ig
Content-Length: 36
Host: localhost:8080

{"lastname":"Stark","language":"DE"}
Example Curl request
$ curl 'http://localhost:8080/users/By46n' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcxOSwiZXhwIjoxNzgxNzgxMzE5fQ.woIYxyHgFKj4W9UE3DD_BSd94EVbfvle7wpxkOQ8nipzIvK10DF6zugxGq01uRa11dX7jeJJB9_SPdBLajP1ig' \
    -d '{"lastname":"Stark","language":"DE"}'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.15. UsersAliases

5.15.1. Add addresses to an email alias

POST /domains/{domainId}/groups/{groupId}/addresses

Description

The email address could be a domain account, another email alias or an external email address.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null

groupId

X

null
Body Parameter
Name Description Required Default Pattern

string

[string]

X
Return Type

-

Content Type

  • application/json

Responses
Table 84. HTTP Response Codes
Code Message Datatype

404

A problem occured. The domain or the user may not exist

AdressAlias

403

You do not have permission to execute this request.

AdressAlias
Example HTTP request
POST /domains/Eygdk/groups/ByE3n/addresses HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU0OCwiZXhwIjoxNzgxNzgxMTQ4fQ.QmP6VUsKR_5BmjxKTbw3QGg6EV5F1dfUCYNllgaAZ_U4mAvMI9XFmAP1whIWJydZDxuW6l4ytSv5CN1RezGA8Q
Content-Length: 36
Host: localhost:8080

["joffrey@got.net","ramsay@got.net"]
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/groups/ByE3n/addresses' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU0OCwiZXhwIjoxNzgxNzgxMTQ4fQ.QmP6VUsKR_5BmjxKTbw3QGg6EV5F1dfUCYNllgaAZ_U4mAvMI9XFmAP1whIWJydZDxuW6l4ytSv5CN1RezGA8Q' \
    -d '["joffrey@got.net","ramsay@got.net"]'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 325

{
  "id" : "ByE3n",
  "email" : "badguys@got.net",
  "recipients" : [ {
    "id" : "ByE3n",
    "email" : "joffrey@got.net",
    "firstname" : null,
    "lastname" : null,
    "type" : "USER"
  }, {
    "id" : "By46n",
    "email" : "ramsay@got.net",
    "firstname" : null,
    "lastname" : null,
    "type" : "USER"
  } ]
}

5.15.2. New email alias

POST /domains/{domainId}/groups

Description

Create a new email alias.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Body Parameter
Name Description Required Default Pattern

NewAddressAlias

NewAddressAlias

X
Return Type

AdressAlias

Content Type

  • application/json

Responses
Table 85. HTTP Response Codes
Code Message Datatype

400

A problem occured. Arguments passed to the request may not match required format or the email's domain may not match the domain

AdressAlias

403

You do not have permission to execute this request.

AdressAlias

404

A problem occured. The domain may not exist

AdressAlias

409

A email alias may already exists with the given name

AdressAlias

422

Operation cannot be done because of not met conditions.

AdressAlias

201

Created

AdressAlias
Example HTTP request
POST /domains/Eygdk/groups HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU0NCwiZXhwIjoxNzgxNzgxMTQ0fQ.jRqmnGv_YPAVniptY6vXCFWfP4ZuVo-SPkgAJQL0tiuZ94OWZ_vled7vczIo6S87_gz4Eelj2pq7-mRTEhaeWA
Content-Length: 30
Host: localhost:8080

{"email":"children@stark.net"}
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/groups' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU0NCwiZXhwIjoxNzgxNzgxMTQ0fQ.jRqmnGv_YPAVniptY6vXCFWfP4ZuVo-SPkgAJQL0tiuZ94OWZ_vled7vczIo6S87_gz4Eelj2pq7-mRTEhaeWA' \
    -d '{"email":"children@stark.net"}'
Example HTTP response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: Content-Location
Location: http://localhost:8080/domains/Eygdk/groups/ByE3n
Content-Type: application/json
Content-Length: 76

{
  "id" : "ByE3n",
  "email" : "children@stark.net",
  "recipients" : [ ]
}

5.15.3. Delete an email alias.

DELETE /groups/{groupId}

Description

Delete an email alais list using its ID.

Parameters
Path Parameters
Name Description Required Default Pattern

groupId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 86. HTTP Response Codes
Code Message Datatype

400

A problem occured. Possible cause: at least one parameter might not match required format or the domain of the alias may not match the domain

AdressAlias

403

You do not have permission to execute this request.

AdressAlias

404

A problem occured. The domain and/or the alias may not exist

AdressAlias
Example HTTP request
DELETE /groups/ByE3n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzUzOSwiZXhwIjoxNzgxNzgxMTM5fQ.H-MapjbZJtk3AmJ2L1hgdzTC8g3sM3qaLyyQqGL41KUHpTaKqmbfvKi9Xz-c_FBZ5kMyBjF6p_HwC12Bt9-2fQ
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/groups/ByE3n' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzUzOSwiZXhwIjoxNzgxNzgxMTM5fQ.H-MapjbZJtk3AmJ2L1hgdzTC8g3sM3qaLyyQqGL41KUHpTaKqmbfvKi9Xz-c_FBZ5kMyBjF6p_HwC12Bt9-2fQ'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.15.4. Delete an email alias recipient.

DELETE /domains/{domainId}/groups/{groupId}/addresses/{addressId}

Description

Delete an email alias recipient using the user ID.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null

groupId

X

null

addressId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 87. HTTP Response Codes
Code Message Datatype

400

A problem occured. Possible cause: at least one parameter might not match required format or the domain of the alias may not match the domain

AdressAlias

403

You do not have permission to execute this request.

AdressAlias

404

A problem occured. The domain and/or the user and/or the alias may not exist ; the domain may not contain the user

AdressAlias
Example HTTP request
DELETE /domains/Eygdk/groups/ByE3n/addresses/ByE3n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU0NywiZXhwIjoxNzgxNzgxMTQ3fQ.VUWd5dO2daPjf5-n9BTjNWY5JfVHO-WMF0D_dbQGfZaEiIOOHziVts0VoEy3FX6VCARLYlfcbyVY5BtQz5fAmA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/groups/ByE3n/addresses/ByE3n' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU0NywiZXhwIjoxNzgxNzgxMTQ3fQ.VUWd5dO2daPjf5-n9BTjNWY5JfVHO-WMF0D_dbQGfZaEiIOOHziVts0VoEy3FX6VCARLYlfcbyVY5BtQz5fAmA'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.15.5. List the targeted addresses of an alias.

GET /domains/{domainId}/groups/{groupId}

Description
Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null

groupId

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 88. HTTP Response Codes
Code Message Datatype

404

A problem occured. The domain or the user may not exist

AdressAlias

403

You do not have permission to execute this request.

AdressAlias
Example HTTP request
GET /domains/Eygdk/groups/ByE3n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU0MSwiZXhwIjoxNzgxNzgxMTQxfQ.WAnela67M7tafzpoyurkyrTmy0e8vkp_GwA8UHDT3xxAMuCdsfTUZ8IvlITm5XNAeiG9oXil4RXMlMDnHhDrEA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/groups/ByE3n' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU0MSwiZXhwIjoxNzgxNzgxMTQxfQ.WAnela67M7tafzpoyurkyrTmy0e8vkp_GwA8UHDT3xxAMuCdsfTUZ8IvlITm5XNAeiG9oXil4RXMlMDnHhDrEA'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 484

{
  "id" : "ByE3n",
  "email" : "badguys@got.net",
  "recipients" : [ {
    "id" : "ByE3n",
    "email" : "joffrey@got.net",
    "firstname" : "Joffrey",
    "lastname" : "Baratheon",
    "type" : "USER"
  }, {
    "id" : "By46n",
    "email" : "ramsay@got.net",
    "firstname" : "Ramsay",
    "lastname" : "Bolton",
    "type" : "USER"
  }, {
    "id" : "Eygdk",
    "email" : "themontain@got.net",
    "firstname" : "Gregor",
    "lastname" : "Clegane",
    "type" : "USER"
  } ]
}

5.15.6. List email aliases of a domain.

GET /domains/{domainId}/groups

Description

Returns the email aliases of the domain. Filtering option on fields: 'email', 'recipient'.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null
Query Parameters
Name Description Required Default Pattern

sort

Define the sort applied on response. Prefix the field name by '-' to reverse the sort.

-

null

offset

Index of the first group to return, defaults to 1

-

null

pageSize

Maximum number of groups returned, defaults to 40

-

null

email

Filter groups by the alias's email

-

null

recipient

Filter groups by recipient's email

-

null
Return Type

-

Content Type

  • application/json

  • application/vnd.ms-excel

Responses
Table 89. HTTP Response Codes
Code Message Datatype

404

A problem occured. The domain may not exist

List[AdressAlias]

403

You do not have permission to execute this request.

List[AdressAlias]
Example HTTP request
GET /domains/Eygdk/groups?address=ramsay@got.net HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU0NSwiZXhwIjoxNzgxNzgxMTQ1fQ.5wuNOh_BkVxwigvFNfdY5ooa4UxBsgJ3FpPX4Al9xwjgvRTJrDbijZaZpk9POACfNKjR57sUWvxVx_Jhm1g0bA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/groups?address=ramsay@got.net' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU0NSwiZXhwIjoxNzgxNzgxMTQ1fQ.5wuNOh_BkVxwigvFNfdY5ooa4UxBsgJ3FpPX4Al9xwjgvRTJrDbijZaZpk9POACfNKjR57sUWvxVx_Jhm1g0bA'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: X-Total-Count
X-Total-Count: 1
Content-Type: application/json
Content-Length: 329

[ {
  "id" : "ByE3n",
  "email" : "badguys@got.net",
  "recipients" : [ {
    "id" : "ByE3n",
    "email" : "joffrey@got.net",
    "firstname" : null,
    "lastname" : null,
    "type" : "USER"
  }, {
    "id" : "By46n",
    "email" : "ramsay@got.net",
    "firstname" : null,
    "lastname" : null,
    "type" : "USER"
  } ]
} ]

5.15.7. Edit an email alias.

PATCH /domains/{domainId}/groups/{groupId}

Description

Edit the address of an existing email alias.

Parameters
Path Parameters
Name Description Required Default Pattern

domainId

X

null

groupId

X

null
Body Parameter
Name Description Required Default Pattern

NewAddressAlias

NewAddressAlias

X
Return Type

-

Content Type

  • application/json

Responses
Table 90. HTTP Response Codes
Code Message Datatype

400

A problem occured. Possible cause: at least one parameter might not match required format or the domain of the alias may not match the domain

AdressAlias

403

You do not have permission to execute this request.

AdressAlias

404

A problem occured. The domain and/or the email alias may not exist

AdressAlias
Example HTTP request
PATCH /domains/Eygdk/groups/ByE3n HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU0MywiZXhwIjoxNzgxNzgxMTQzfQ.U-mMFxxPABXVKqG1laaSdeRMEDX1dA5rn-c2megjSDNQ7moegyKT-ZO8-vEHaFU8YU4bMB-2BkRpEj5FD5_-LA
Content-Length: 78
Host: localhost:8080

{"email":"deadguys@got.net","recipients":["joffrey@got.net","ramsay@got.net"]}
Example Curl request
$ curl 'http://localhost:8080/domains/Eygdk/groups/ByE3n' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzU0MywiZXhwIjoxNzgxNzgxMTQzfQ.U-mMFxxPABXVKqG1laaSdeRMEDX1dA5rn-c2megjSDNQ7moegyKT-ZO8-vEHaFU8YU4bMB-2BkRpEj5FD5_-LA' \
    -d '{"email":"deadguys@got.net","recipients":["joffrey@got.net","ramsay@got.net"]}'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.16. UsersSigns

5.16.1. Delete sign

DELETE /users/{userId}/sign

Description

Delete the HTML sign of the given user.

Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null
Return Type

Sign

Content Type

  • application/json

Responses
Table 91. HTTP Response Codes
Code Message Datatype

400

A problem occured. Possible causes: the account does not have quarantine or retention or archive service.

Sign

404

Unknown user

Sign

204

No Content

Sign
Example HTTP request
DELETE /users/By46n/sign HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcwNCwiZXhwIjoxNzgxNzgxMzA0fQ.gv4zdyjmgG7E6N-AdEuLDxfIMbO_7T9mQdbtcz64cKf9fFypoQPAMCjz-DovbKkweJXdYChDh4hC8sI5jy_EBA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/users/By46n/sign' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcwNCwiZXhwIjoxNzgxNzgxMzA0fQ.gv4zdyjmgG7E6N-AdEuLDxfIMbO_7T9mQdbtcz64cKf9fFypoQPAMCjz-DovbKkweJXdYChDh4hC8sI5jy_EBA'
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

5.16.2. Get sign

GET /users/{userId}/sign

Description

Get HTML sign of given user.

Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null
Return Type

Sign

Content Type

  • application/json

Responses
Table 92. HTTP Response Codes
Code Message Datatype

400

A problem occured. Possible causes: the account does not have quarantine or retention or archive service.

Sign

404

Unknown user

Sign

422

Operation cannot be done because of not met conditions.

Sign

200

OK

Sign
Example HTTP request
GET /users/By46n/sign HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcwMywiZXhwIjoxNzgxNzgxMzAzfQ.nSNHOMgE9JkeCS1b68H-5vMsyvDciAvsg8orlH0ZAKdQnrwdbrig9leJZ_24fM6DwSFeP7SKSG_ON6S4mJT0sA
Host: localhost:8080
Example Curl request
$ curl 'http://localhost:8080/users/By46n/sign' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ2ZXJzaW9uIjozLCJhdXRob3JpdGllcyI6WyJTWVNBRE1JTiJdLCJzdWIiOiJhZG1pbkB0ZXN0Lm5ldCIsImlhdCI6MTc4MTc3NzcwMywiZXhwIjoxNzgxNzgxMzAzfQ.nSNHOMgE9JkeCS1b68H-5vMsyvDciAvsg8orlH0ZAKdQnrwdbrig9leJZ_24fM6DwSFeP7SKSG_ON6S4mJT0sA'
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 65

{
  "sign" : "Um9iZXJ0IFN0YXJrPGJyLz5LaW5nIG9mIHRoZSBub3J0aA=="
}

5.16.3. Set sign

PUT /users/{userId}/sign

Description

Set HTML sign to given user.

Parameters
Path Parameters
Name Description Required Default Pattern

userId

X

null
Body Parameter
Name Description Required Default Pattern

Sign

Sign

X
Return Type

Sign

Content Type

  • application/json

Responses
Table 93. HTTP Response Codes
Code Message Datatype

400

A problem occured. Possible causes: the account does not have quarantine or retention or archive service.

Sign

404

Unknown user

Sign

200

OK

Sign
Example HTTP request
Example Curl request
Example HTTP response

6. Models

6.1. AclDTO

Field Name Required Nullable Type Description Format

id

Integer

Identifier of the entry

int32

username

X

String

Grantee of the permissions

permissions

List of AclPermissionStatus

List of embedded permissions

6.2. AclPermissionStatus

Permission and its activation status

Field Name Required Nullable Type Description Format

name

String

Permission's name

enabled

Boolean

Permission's activation status

6.3. Admin

Field Name Required Nullable Type Description Format

id

Integer

int32

login

X

String

Login used for authentication

displayName

String

Display name of the account

email

String

Email address. Used for password recovery

enabled

Boolean

Whether the account is enabled or not

language

[String]

Language of the account

Enum: fr (French), en (English), de (German), es (Spanish), nb (Norwegian), da (Danish),

totp

[Boolean]

Account's defined multi-factor authentication.

Enum: false, false,

sysAdmin

Boolean

Whether the account is a system administrator or not

authorities

List of Authority

List of authorities granted to the user

authoritiesCount

Integer

Count of authorities granted to the user

int32

lastConnectionDate

Date

Date of last connection to application.

date-time

createdAt

Date

Account creation date

date-time

6.4. AdminAdd

Field Name Required Nullable Type Description Format

id

Integer

Unique identifier of an existing account

int32

login

String

Login used for authentication. Required only in case of new account creation.

displayName

String

Display name of the account. Required only in case of new account creation.

email

String

Email address. Used for password recovery. Required only in case of new account creation.

password

String

Clear password of the account. Required only in case of new account creation.

enabled

Boolean

Whether the account is enabled or not. Required only in case of new account creation.

language

[String]

Language of the account. Required only in case of new account creation.

Enum: fr (French), en (English), de (German), es (Spanish), nb (Norwegian), da (Danish),

permissions

X

List of [string]

List of permissions granted to the user

6.5. AdminUpdate

Field Name Required Nullable Type Description Format

email

String

Email address. Used for password recovery

displayName

String

Display name of the account

password

String

Clear password of the account. Required only in case of new account creation.

enabled

Boolean

Whether the account is enabled or not. Required only in case of new account creation.

totp

Boolean

Activation status of TOTP. Can only disable the feature. Enabling TOTP must be done through a dedicated flow (QRCode).

language

[String]

Language of the account

Enum: fr (French), en (English), de (German), es (Spanish), nb (Norwegian), da (Danish),

6.6. AdressAlias

Field Name Required Nullable Type Description Format

id

Integer

Idenfier of the alias

int32

email

X

String

Address of the alias

recipients

List of EmailAliasRecipient

The email addresses targeted by the alias.

6.7. Alias

Field Name Required Nullable Type Description Format

id

Integer

Idenfier of the alias

int32

name

X

String

Name of the alias

6.8. ArchiveProps

Field Name Required Nullable Type Description Format

duration

Integer

Number of MONTHS the messages are archived

int32

archiveByCopy

Boolean

Determine if system must archive all e-mails, even internal ones, by copying messages from final mailbox.

storeMailOut

Boolean

Determine if system must archive sent emails

storeCleanMailIn

Boolean

Determine if system must archive clean incoming emails

storeSpam

Boolean

Determine if system must archive incoming email detected as spams

storeBadHeaders

Boolean

Determine if system must archive incoming emails with bad headers

storeBadEncoding

Boolean

Determine if system must archive incoming emails with bad encoding

storeBadAttachments

Boolean

Determine if system must archive incoming emails with unauthorized file formats

storeAdvert

Boolean

Determine if system must archive incoming emails which seem to be advertising

storeBlacklisted

Boolean

Determine if system must archive incoming blocked sender

storeSenderVerify

Boolean

Determine if system must archive incoming emails with improper sender verify

6.9. AttachmentFile

Field Name Required Nullable Type Description Format

uid

String

Unique identifier of the file on our server.

name

String

Filename

uri

String

Access URI of the stored file

type

String

Content-type of the file

size

Long

File size in bytes

int64

6.10. AuthToken

Field Name Required Nullable Type Description Format

token

String

Token value

expireAt

Date

Expiration date of the token

date-time

url

String

Authenticated url to the application

6.11. Authority

Field Name Required Nullable Type Description Format

objectType

String

objectId

Integer

int32

objectName

String

permissions

[List] of [string]

Enum:

securedObjectClass

String

securedObjectName

String

6.12. CustomerDTO

Field Name Required Nullable Type Description Format

id

Integer

int32

brokerId

Integer

int32

name

String

description

String

externalId

String

createdAt

Date

date-time

6.13. DiagnosticEntryDTO

Field Name Required Nullable Type Description Format

id

Integer

int32

name

String

type

String

health

X

oas_any_type_not_mapped

6.14. DkimDTO

Field Name Required Nullable Type Description Format

privateKey

String

publicKey

String

selector

String

6.15. Domain

Field Name Required Nullable Type Description Format

id

Integer

Idenfier of the domain

int32

name

X

String

Name of the domain

description

String

Description of the domain

status

X

[String]

Activation status of the domain

Enum: ENABLED, DISABLED, PENDING, DELETED,

wblistPriority

[String]

Defines which filtering rules take priority in the case of conflict between domain's and mailbox's filtering rules.

Enum: DOMAIN, USER,

defaultLanguage

X

[String]

Default Language of the accounts in this domain

Enum: fr (French), en (English), de (German), es (Spanish), nb (Norwegian), da (Danish),

autoProvisioningOn

X

Boolean

Activation status of automatic creation of users' accounts

senderVerifyOn

Boolean

Activate the sender verify for the domain. True by default

greylistingOn

Boolean

Activate the greylisting for the domain. True by default

externalId

String

External reference of your choice (i.e. reference of customer in your billing system)

policy

Policy

The domain's policy

domainAliases

List of Alias

The domain's aliases

activeUsersCount

Long

Number of active users of the domain

int64

policiesCount

Integer

Number of policies declared for this domain

int32

quarantine

Boolean

Presence of at least one policy with quarantine service

retention

Boolean

Presence of at least one policy with retention service

archive

Boolean

Presence of at least one policy with archive service

incoming

Boolean

Presence of at least one policy with incoming service

outgoingSubnets

Set of [string]

List of hosts allowed to send messages (required format: a.b.c.d/y)

creationDate

Date

The domain's creation date.

date-time

deletionDate

Date

The date the domain was marked as deleted.

date-time

purgeDate

Date

The date the domain will actually be deleted.

date-time

outgoingProviders

List of OutgoingProvider

The list of outgoing provider to which the domain belongs

customer

CustomerDTO

Customer to which the domain belongs

platforms

List of PlatformDTO

List of smtp relays

6.16. DomainAdd

domain

Field Name Required Nullable Type Description Format

name

X

String

Name of the domain

description

String

Description of the domain

status

X

[String]

Activation status of the domain

Enum: ENABLED, DISABLED,

wblistPriority

[String]

Defines which filtering rules take priority in the case of conflict between domain's and mailbox's filtering rules. User by default

Enum: DOMAIN, USER,

incoming

Boolean

Activate relay service

outgoing

Boolean

Activate status of outgoing service

quarantine

X

Boolean

Activation status of quarantine service

retention

X

Boolean

Activation status of retention service

archive

X

Boolean

Activation status of archiving service

defaultLanguage

X

[String]

Default Language of the accounts in this domain

Enum: fr (French), en (English), de (German), es (Spanish), nb (Norwegian), da (Danish),

autoProvisioningOn

Boolean

Activation status of automatic creation of users' accounts

senderVerifyOn

Boolean

Activate the sender verify for the domain. True by default

greylistingOn

Boolean

Activate the greylisting for the domain. True by default

customerId

Integer

The identifiers of the customers to which the domain belongs

int32

externalId

String

External reference of your choice (i.e. reference of customer in your billing system)

outgoingSubnets

List of [string]

List of subnets allowed to send messages (format : a.b.c.d/y)

outgoingProvidersIds

List of [integer]

The list of ids of outgoing providers enabled for the domain

int32

platforms

List of PlatformDTO

The list of smtp relays

aliases

List of [string]

List of domain aliases

6.17. DomainUpdate

domain

Field Name Required Nullable Type Description Format

name

String

Name of the domain

description

String

Description of the domain

status

[String]

Activation status of the domain

Enum: ENABLED, DISABLED, PENDING,

wblistPriority

[String]

Defines which filtering rules take priority in the case of conflict between domain's and mailbox's filtering rules.

Enum: DOMAIN, USER,

quarantine

Boolean

Activation status of quarantine service

retention

Boolean

Activation status of retention service

archive

Boolean

Activation status of archiving service

defaultLanguage

[String]

Default Language of the accounts in this domain

Enum: fr (French), en (English), de (German), es (Spanish), nb (Norwegian), da (Danish),

autoProvisioningOn

Boolean

Activation status of automatic creation of users' accounts

senderVerifyOn

Boolean

Activate the sender verify for the domain. True by default

greylistingOn

Boolean

Activate the greylisting for the domain. True by default

customerId

Integer

Id of the customer to which the domain belongs

int32

policyId

Integer

Id of the default policy for current domain

int32

externalId

String

External reference of your choice (i.e. reference of customer in your billing system)

outgoingSubnets

List of [string]

List of subnets allowed to send messages (format : a.b.c.d/y)

outgoingProvidersIds

List of [integer]

The list of ids of outgoing providers enabled for the domain

int32

aliases

List of [string]

List of domain aliases

platforms

List of PlatformDTO

The list of platforms which contain settings for SMTP, authentication, remediation API

6.18. EmailAliasRecipient

Field Name Required Nullable Type Description Format

id

Integer

Idenfier of the alias

int32

email

X

String

Email address of the recipient

firstname

String

Firstname of the user (only set if the address match with an account of the current domain)

type

[String]

Type of email

Enum: USER, ALIAS, EXTERNAL_ADDRESS,

6.19. EntityHealth

Field Name Required Nullable Type Description Format

performedAt

X

Date

Timestamp of the last check

date-time

report

X

HealthRecord

Details of the diagnostic

6.20. FilterAttachment

Field Name Required Nullable Type Description Format

id

Integer

Idenfier

int32

action

X

[String]

Action of the filter

Enum: deny, allow,

checkType

X

[String]

Content concerned by the action

Enum: filename, contenttype, archive-contenttype, archive-filename,

filter

X

String

Requirement to check to execute the action (regex).

description

String

Any comments to explain the reason behind this rule.

createdDate

Date

Creation date

date-time

6.21. FilterSender

Field Name Required Nullable Type Description Format

id

Integer

Idenfier of the rule

int32

value

X

String

The address to block or allow. It can be an email or a domain

owner

X

String

Owner of the rule. Can be an mailbox or a domain

type

X

[String]

Action applied if rule match

Enum: ALLOW, BLOCK, PROTECTED,

createdDate

Date

Creation date

date-time

expireAt

Date

Expiration date for the rule

date-time

description

String

Free description field

spfOn

Boolean

Activates the SPF on senders. Only applied and required for allowlist.

6.22. FilterSenderAdd

The filtering rule to add to the domain. It is possible to add a rule for a specific email address or an entire domain.

Field Name Required Nullable Type Description Format

value

X

String

The address to block or allow. It can be an email or a domain

type

X

[String]

Action applied if rule match

Enum: ALLOW, BLOCK, PROTECTED,

expireAt

Date

Expiration date for the rule

date-time

description

String

Free description field

spfOn

Boolean

Activates the SPF on senders. Only applied and required for allowlist.

6.23. FilterSenderItem

Field Name Required Nullable Type Description Format

value

X

String

The address to block or allow. It can be an email or a domain

owner

X

String

Owner of the rule. Can be an mailbox or a domain

type

X

[String]

Action applied if rule match

Enum: ALLOW, BLOCK, PROTECTED,

expireAt

Date

Expiration date for the rule

date-time

description

String

Free description field

spfOn

Boolean

Activates the SPF on senders. Only applied and required for allowlist.

6.24. FilterUriBl

Field Name Required Nullable Type Description Format

id

Integer

Idenfier

int32

action

X

[String]

Action of the filter. URIDNSBL_SKIP_DOMAIN : Ignores checking for URIs containing the specified domain name. The spam score will therefore not be impacted. WHITELIST_URI_HOST : Messages containing URIs with the specified domain name will be positively influenced. This will have the effect of significantly lowering the spam score. BLACKLIST_URI_HOST : Messages containing URIs with the specified domain name will be negatively influenced. This will result in a significant increase of the spam score.

Enum: uridnsbl_skip_domain, whitelist_uri_host, blacklist_uri_host,

filter

X

String

Content concerned by the action

description

String

Any comments to explain the reason behind this rule.

createdDate

Date

Creation date

date-time

6.25. FilterUriBlAdd

uriBl filter

Field Name Required Nullable Type Description Format

action

X

[String]

Action of the filter. URIDNSBL_SKIP_DOMAIN : Ignores checking for URIs containing the specified domain name. The spam score will therefore not be impacted) WHITELIST_URI_HOST : Messages containing URIs with the specified domain name will be positively influenced. This will have the effect of significantly lowering the spam score. BLACKLIST_URI_HOST : (Messages containing URIs with the specified domain name will be negatively influenced. This will result in a significant increase of the spam score.

Enum: uridnsbl_skip_domain, whitelist_uri_host, blacklist_uri_host,

filter

X

String

Requirement to check to execute the action (regex).

description

String

Any comments to explain the reason behind this rule.

6.26. HealthRecord

Field Name Required Nullable Type Description Format

status

X

Boolean

Global health status of the entity

entries

X

List of HealthResult

List all tests performed on the entity

6.27. HealthResult

Field Name Required Nullable Type Description Format

type

String

ref

Integer

int32

result

[String]

Enum: OK, ERROR, ERROR_DKIM_MISSING_ENTRY, ERROR_DKIM_INVALID_COUPLE, ERROR_MX_MISSING_ENTRY, ERROR_MX_INVALID_ENTRY,

output

List of [string]

6.28. ImapFolder

Field Name Required Nullable Type Description Format

name

String

Folder name

path

String

Folder path

unreadMessageCount

Integer

Number of unread messages contained in the folder

int32

messageCount

Integer

Number of messages contained in the folder

int32

messagesUri

String

Uri which can be used to get the list of messages contained in the folder

childrenUri

String

Uri which can be used to get the subfolders contained in the folder

6.29. ImapMessage

Field Name Required Nullable Type Description Format

List of headers of the message

Map of [AnyType]

List of email attachments

ImapMessageAttachmentList

Unique identifier of the email. Useful in the message content API.

String

Uri which allow to get the details of the message (list of headers, attachment, body)

String

Define if email has been read

Boolean

Define if email has been answered

Boolean

Define if email is new since the last time the folder has been opened

Boolean

Define if email has been mark as deleted

Boolean

Define if email contains attachments

Boolean

Define if email has been marked as important by the sender

Boolean

Date the message was sent

Date

date-time

Subject of the message

String

Sender of the message

String

Main recipients of the message

List of [string]

Copy recipients of the message

List of [string]

Blind copy recipients of the message

List of [string]

Size of the message in bytes

Integer

int32

6.30. ImapMessageAttachment

Field Name Required Nullable Type Description Format

Id of the attachment in the message

String

Filename

String

Content type of the file

String

Size of the file in bytes

Integer

int32

URI used for downloading the file

String

URI used for displaying the file

String

6.31. ImapMessageAttachmentList

Field Name Required Nullable Type Description Format

List of attachments

List of ImapMessageAttachment

URI used to download an archive which contains all the attachments

String

Number of attachments

Integer

int32

6.32. ImapMessageContent

Field Name Required Nullable Type Description Format

List of headers of the message

Map of [AnyType]

List of email attachments

ImapMessageAttachmentList

Unique identifier of the email. Useful in the message content API.

String

Uri which allow to get the details of the message (list of headers, attachment, body)

String

Define if email has been read

Boolean

Define if email has been answered

Boolean

Define if email is new since the last time the folder has been opened

Boolean

Define if email has been mark as deleted

Boolean

Define if email contains attachments

Boolean

Define if email has been marked as important by the sender

Boolean

Date the message was sent

Date

date-time

Subject of the message

String

Sender of the message

String

Main recipients of the message

List of [string]

Copy recipients of the message

List of [string]

Blind copy recipients of the message

List of [string]

Size of the message in bytes

Integer

int32

Content of the message. Only accessible by owner of the message.

String

Content source of the message. Only accessible by owner of the message.

String

6.33. NewAddressAlias

group

Field Name Required Nullable Type Description Format

email

X

String

Address of the alias

recipients

List of [string]

The email addresses targeted by the alias.

6.34. NewUser

user

Field Name Required Nullable Type Description Format

email

X

String

Username of the accoount.

firstname

String

Firstname of the user

lastname

String

Lastname of the user

status

X

[String]

Activation status of the account

Enum: ENABLED, DISABLED,

language

[String]

Language of the account

Enum: fr (French), en (English), de (German), es (Spanish), nb (Norwegian), da (Danish),

password

String

Clear password of the account. This field will be empty in responses of GET requests.

domainId

X

String

Domain's identifier of the account

policyId

String

Policy's identifier of the account.

platformId

String

Platform's identifier of the account. Take the domain's platform if not defined.

authId

String

Authentication provider's identifier of the account. Take the domain's default one if not defined.

senderVerifyOn

[String]

Activation status the sender verify.

Enum: ENABLED, DISABLED, INHERITED,

greylistingOn

[String]

Activation status of greylisting.

Enum: ENABLED, DISABLED, INHERITED,

sendNotification

Boolean

Send email to the user to inform him of the account creation. False by default.

sign

String

Automatic HTML sign used in compose message form when retention service is enabled.

senderVerifyActive

Boolean

greyListingActive

Boolean

6.35. Option

Field Name Required Nullable Type Description Format

value

String

Option value for current scope

parentValue

String

Parent option value used if no scope value is defined. For instance, if a user scope value is not defined, will use the domain scope value.

option

OptionDef

Option datas

6.36. OptionAdd

Field Name Required Nullable Type Description Format

name

X

String

Name of the option

value

X

String

Value of the option

6.37. OptionDef

Field Name Required Nullable Type Description Format

ptfScope

X

Boolean

Is enabled on platform scope

urlScope

X

Boolean

Is enabled on url scope

customerScope

X

Boolean

Is enabled on customer scope

domainScope

X

Boolean

Is enabled on domain scope

userScope

X

Boolean

Is enabled on user scope

restricted

X

Boolean

Define if the option update requires sysadmin role

name

X

String

Option name

type

X

[String]

Datatype for value property

Enum: BOOL, STRING, EMAIL, URL, LIST, COLOR, DOC, TEXT,

values

List of [string]

List of values allowed for the option

description

String

6.38. OutgoingProvider

Field Name Required Nullable Type Description Format

id

Integer

Idenfier of the outgoing provider

int32

name

X

String

Provider name

spfProvider

X

String

SPF provider

active

X

Boolean

active

6.39. PermissionDTO

Field Name Required Nullable Type Description Format

name

String

editable

Boolean

6.40. PersonalToken

Field Name Required Nullable Type Description Format

id

Integer

Idenfier of the token

int32

name

X

String

Name of the token

value

String

Value of the token. Only filled after post requests.

expiration

Date

Expiration date of the token

date-time

createdAt

Date

Creation date of the token

date-time

lastUse

Date

Last use date

date-time

6.41. PersonalTokenAdd

token

Field Name Required Nullable Type Description Format

name

X

String

Name of the token

expiration

Date

Expiration date of the token

date-time

6.42. PlatformDTO

Field Name Required Nullable Type Description Format

name

X

String

Name of the platform.

transportDest

X

String

IP or hostname of the main smtp server.

transportType

X

[String]

Protocol used to deliever message to the main smtp server.

Enum: SMTP, SMTPS_ENCRYPT, SMTPS_MAY,

transportPort

X

Integer

Port of the main smtp server.

int32

fallbackTransportDest

String

IP or hostname of the secondary smtp server.

fallbackTransportType

[String]

Protocol used to deliever message to the secondary smtp server.

Enum: SMTP, SMTPS_ENCRYPT, SMTPS_MAY,

fallbackTransportPort

Integer

Port of the secondary smtp server.

int32

apiType

X

[String]

Type of API for remediation.

Enum: IMAP, EXCHANGE, O365,

apiData

[PlatformDTO_apiData]

authType

[String]

Type of authentication

Enum: local, imap, ldap, oidc, entra,

authData

[PlatformDTO_authData]

default

Boolean

Default platform is used for relay messages when user is not created.

6.43. Policy

policy

Field Name Required Nullable Type Description Format

id

Integer

Idenfier of the policy

int32

name

X

String

Name of the policy.

domainId

Integer

Id of the associated domain.

int32

quarantine

X

Boolean

Activation status of quarantine service

retention

X

Boolean

Activation status of retention service

archive

Boolean

Activation status of archiving service

mailSizeLimit

Integer

Determine mail size limit in MB.

int32

spamScore

Float

Score from which a message is treated as a spam.

float

incoming

X

Boolean

Activation status of incoming service

relayProps

RelayProps

Relay parameters of the policy

quarantineProps

QuarantineProps

Quarantaine parameters of the policy

retentionProps

RetentionProps

Retention parameters of the policy

archiveProps

ArchiveProps

Archive parameters of the policy

outgoing

Boolean

Activation status of outgoing service

6.44. QuarantineProps

Field Name Required Nullable Type Description Format

duration

Integer

Number of days the messages are store in quarantine

int32

storeSpam

Boolean

Determine if system must store spams

storeVirus

Boolean

Determine if system must store incoming emails which seem to contain a virus

storeAdvert

Boolean

Determine if system must store incoming emails which seem to be advertising

storeBlacklisted

Boolean

Determine if system must store incoming blocked sender

storeSenderVerify

Boolean

Determine if system must store incoming emails with improper sender verify

storeBadHeaders

Boolean

Determine if system must store emails with bad headers

storeBadEncoding

Boolean

Determine if system must store emails detected with bad encoding

storeBadAttachments

Boolean

Determine if system must store emails with unauthorized file formats

6.45. RelayCheckHealthDTO

Field Name Required Nullable Type Description Format

id

Integer

Unique identifier of the relay check health configuration. Only if platform already exists.

int32

transportDest

X

String

IP or hostname of the main smtp server.

transportPort

X

Integer

Port of the main smtp server.

int32

fallbackTransportDest

String

IP or hostname of the secondary smtp server.

fallbackTransportPort

Integer

Port of the secondary smtp server.

int32

authType

X

String

Authentication type to use when connecting to the relay.

authData

X

oas_any_type_not_mapped

apiType

X

String

Type of mail server in context of remediation.

apiData

X

oas_any_type_not_mapped

6.46. RelayProps

Field Name Required Nullable Type Description Format

relaySpam

Boolean

Determine if system must deliver incoming emails considered as spam.

relayAdvert

Boolean

Determine if system must deliver incoming emails considered as advertising.

advertPrefix

String

Prefix added to subject of email detected as adverts. Set an empty string to disable prefixing.

prefixSpam

String

Prefix added to subject of email detected as spam. Set an empty string to disable prefixing.

relayBadHeaders

Boolean

Determine if system must deliver incoming emails which contain bad headers.

relayBadAttachments

Boolean

Determine if system must deliver incoming emails which contain attachments with unauthorized file extensions (.exe,.zip,…​)

spamScoreLimit

Float

Score from which a message considered as spam is not delievered.

float

6.47. RetentionProps

Field Name Required Nullable Type Description Format

duration

Integer

Number of days the messages are store in retention

int32

storeMailOut

Boolean

Determine if system must store sent emails

storeCleanMailIn

Boolean

Determine if system must store clean incoming emails

6.48. Sign

Field Name Required Nullable Type Description Format

sign

String

The user signature in the html format and encoded in Base64

6.49. SmtpMessage

datas

Field Name Required Nullable Type Description Format

to

List of [string]

List of main recipients email addresses

cc

List of [string]

List of recipients email addresses who would recieve a copy of the message

bcc

List of [string]

List of recipients email addresses who would recieve a copy of the message but hidden for the other recipients

body

String

HTML content of the message.

subject

String

Subject of the message

attachments

List of SmtpMessageAttachment

List of files which would be attached to the message. Those files must have been sent to the server first with the attachments API.

draftId

String

If the message has been saved in draft, specify the id given by the API to delete it when the message is sent

originId

String

Id of the original message while replying or forwarding an email

ack

Boolean

True if an acknownledgment is required when the message is opened by the recipient

important

Boolean

Mark the message as important

6.50. SmtpMessageAttachment

Field Name Required Nullable Type Description Format

name

X

String

Name of the file as it would appear in the email

uid

X

String

Id of the file returned by the attachment storage api

6.51. Task

Field Name Required Nullable Type Description Format

command

X

[String]

ID of the command

Enum: send_token_mail, send_welcome_mail,

params

X

Map of [AnyType]

List of datas used by the command. - For command 'send_token_mail' : ```{"recipient":"cersei@lannister.net","validity":24}``` - For command 'send_password_reset_mail' : ```{"recipient":"cersei@lannister.net","validity":6}``` - For command 'send_welcome_mail' : ```{"recipient":"cersei@lannister.net"}```

param

X

oas_any_type_not_mapped

6.52. UpdateUser

user

Field Name Required Nullable Type Description Format

email

X

String

Username of the accoount.

firstname

String

Firstname of the user

lastname

String

Lastname of the user

status

X

[String]

Activation status of the account

Enum: ENABLED, DISABLED,

language

[String]

Language of the account

Enum: fr (French), en (English), de (German), es (Spanish), nb (Norwegian), da (Danish),

password

String

Clear password of the account. This field will be empty in responses of GET requests.

domainId

X

String

Domain's identifier of the account

policyId

String

Policy's identifier of the account.

platformId

String

Platform's identifier of the account. Take the domain's platform if not defined.

authId

String

Authentication provider's identifier of the account. Take the domain's default one if not defined.

senderVerifyOn

[String]

Activation status the sender verify.

Enum: ENABLED, DISABLED, INHERITED,

greylistingOn

[String]

Activation status of greylisting.

Enum: ENABLED, DISABLED, INHERITED,

sendNotification

Boolean

Send email to the user to inform him of the account creation. False by default.

sign

String

Automatic HTML sign used in compose message form when retention service is enabled.

mfaType

[String]

Disable account's multi-factor authentication.

Enum: NONE,

senderVerifyActive

Boolean

greyListingActive

Boolean

6.53. UploadFileRequest

Field Name Required Nullable Type Description Format

file

X

File

file

binary

6.54. User

Field Name Required Nullable Type Description Format

id

Integer

Idenfier of the user

int32

email

X

String

Username of the accoount.

firstname

String

Firstname of the user

lastname

String

Lastname of the user

status

X

[String]

Activation status of the account

Enum: ENABLED, DISABLED,

language

X

[String]

Language of the account

Enum: fr (French), en (English), de (German), es (Spanish), nb (Norwegian), da (Danish),

creationDate

Date

The account's creation date

date-time

domainId

X

Integer

Domain's identifier of the account

int32

policy

Policy

The user's policy

senderVerifyOn

Boolean

Activate the sender verify for the user. True by default

greylistingOn

Boolean

Activate the greylisting for the domain. True by default

domainPolicyId

Integer

Default policy id of the domain

int32

domainStatus

[String]

The status of the domain

Enum: ENABLED, DISABLED, DELETED, PENDING,

domainPlatformId

Integer

Default platform id of the domain

int32

platform

PlatformDTO

SMTP relay data

mfaType

[String]

Account's defined multi-factor authentication.

Enum: NONE, TOTP,

lastConnectionDate

Date

Date of last connection to application.

date-time