|
Activate API
The API feature is disabled by default in FortiMail. To enable it, execute the following command in the Command Line Interface (CLI):
config system web-service
set rest-api-status enable
end
Login to FortiMail through the API
To establish a connection with a FortiMail server in server mode using the API, initiate a POST request to the URL https://<IP>/api/v1/AdminLogin with the provided payload:
{
"name": "username",
"password": "password"
}
Upon receiving a response with a status code 200, the login process is successful and a session is established.
Create a contact list (AddressbookGroup)
To generate a new Contact List (AddressbookGroup), perform a POST request to https://<IP>/api/v1/domain/<domain_name>/AddressbookGroup/0 (mind the '0') with the following payload:
{
"group_name": "test_g3"
}
To retrieve a list of all created Contact Lists, a simple GET request is sufficient: https://<IP>/api/v1/domain/<domain_name>/AddressbookGroup/
The response will have the following format:
{
"objectID": "AddressbookGroupCollection:{D:dom.com}",
...
"collection": [
{
"mdomain": "dom.com",
"mkey": 1,
"group_name": "test_g1",
"owner_id": 2,
"type": 2
},
{
"mdomain": "dom.com",
"mkey": 2,
"group_name": "test_g2",
"owner_id": 2,
"type": 2
},
{
"mdomain": "dom.com",
"mkey": 3,
"group_name": "test_g3",
"owner_id": 2,
"type": 2
}
]
}
It is important to note that each AddressbookGroup has a unique mkey value. The mkey value holds significance for various other requests detailed in subsequent sections.
If information about a specific AddressbookGroup is required, a GET request to https://<IP>/api/v1/domain/<domain_name>/AddressbookGroup/<mkey> can be used.
Manage contacts
Creating a generic contact is straightforward. Send a POST request to https://<IP>/api/v1/domain/<domain_name>/AddressBook/0 (mind the '0') using a payload like the following one:
{
"first_name": "simple",
"last_name": "user"
}
The system will respond with information about the created contact, including an mkey value. This value can be used to retrieve information about the contact itself via a GET request to https://<IP>/api/v1/domain/<doamin_name>/AddressBook/<mkey>.
A DELETE request at the same address will remove the contact from the FortiMail database.
Associate contacts with contact lists
To associate a contact with a contact list, perform a POST request to https://<IP>/api/v1/domain/<domain_name>/AddressBook/. The payload should include the following:
{
"reqAction": 8,
"extraParam": "1,2,3",
"mmkey": "39,40"
}
Here, extraParam represents the list of contact list mkey values, and mmkey (mind the double 'm') represents the contacts to associate with. Upon success, the system will confirm the action.
To verify associations, send a GET request to https://<IP>/api/v1/domain/<domain_name>/AddressBook/?extraparam=<mkey>. This will provide the desired contact list contents.
To remove a contact from a contact list, send a DELETE request to https://<IP>/api/v1/domain/<domain_name>/AddressBook/?mmkey=<contact_mkey>&extraParam=<contact_list_mkey>.
These commands can be used to streamline the processes of enabling the API, establishing connections, and managing connections; facilitating simple automation of FortiMail administration.
|
