Using the REST API#
This documentation applies to Piler enterprise edition 1.7.2
Revision #1
Publication date: Apr 20, 2023
Introduction#
The REST API allows you to automate the most frequent operations for piler enterprise.
You need to set the authentication header, in this tutorial we’ll use the default admin account. The hostname will be archive.aaa.fu. Note that customer admins may also use the REST API to affect their organization.
$ user='admin@local:pilerrocks'
Domains#
Get the domain list#
curl -u "$user" archive.aaa.fu/api/v1/get_domains
[{"domain":"aaa.fu","mapped":"aaa.fu","ldap":"company A"}, {"domain":"acts.hu","mapped":"fictive.com","ldap":"company F"}, {"domain":"bbb.fu","mapped":"bbb.fu","ldap":""}, {"domain":"fictive.com","mapped":"fictive.com","ldap":"company F"}, {"domain":"fictive.net","mapped":"fictive.com","ldap":"company F"}, {"domain":"fictive.org","mapped":"fictive.com","ldap":"company F"}, {"domain":"local","mapped":"local","ldap":""},{"domain":"no.domain","mapped":"bbb.fu","ldap":""}]
Add a domain#
curl -u "$user" -d @data.json archive.aaa.fu/api/v1/add_domain
data.json:
[
{"domain":"qqq.fu","mapped":"qqq.fu","ldap_id":"0"},
{"domain":"qqq.com","mapped":"qqq.fu","ldap_id":"0"}
]
Delete a domain#
curl -u "$user" -d @data.json archive.aaa.fu/api/v1/delete_domain
data.json:
[
{"domain":"qqq.fu"},
{"domain":"qqq.com"}
]
Customers#
Get the customer id list#
curl -u "$user" archive.aaa.fu/api/v1/get_customers
["bbb","fictive","aaa"]
Get the customer settings#
curl -u "$user" archive.aaa.fu/api/v1/get_customer_list
[{"id":"2","customer_id":"aaa","customer_address":"aaa@aaa.fu","gui_url":"aaa1.acts.hu","domain":"aaa.fu","worker":"cust1.acts.hu","quota":"100","used":"0","retention_days":"2557","branding_url":null,"branding_logo":null,"support_link":null,"background_colour":null,"text_colour":null,"enable_purge":"0","enabled":"1","created":"1496555400","status":"OK"},{"id":"3","customer_id":"bbb","customer_address":"bbb@aaa.fu","gui_url":"bbb1.acts.hu","domain":"bbb.fu","worker":"cust1.acts.hu","quota":"1","used":"0","retention_days":"730","branding_url":null,"branding_logo":null,"support_link":null,"background_colour":null,"text_colour":null,"enable_purge":"1","enabled":"1","created":"1495555400","status":"OK"},{"id":"1","customer_id":"fictive","customer_address":"fictive@aaa.fu","gui_url":"cust1.acts.hu","domain":"fictive.com","worker":"cust1.acts.hu","quota":"0","used":"0","retention_days":"30","branding_url":null,"branding_logo":null,"support_link":null,"background_colour":null,"text_colour":null,"enable_purge":"1","enabled":"1","created":"1497291760","status":"OK"}]
Get the customer settings for customer id=1#
curl -u "$user" archive.aaa.fu/api/v1/get_customer_list/id/1
{"id":"1","customer_id":"fictive","customer_address":"fictive@aaa.fu","gui_url":"cust1.acts.hu","domain":"fictive.com","worker":"cust1.acts.hu","quota":"0","used":"0","retention_days":"30","branding_url":null,"branding_logo":null,"support_link":null,"background_colour":null,"text_colour":null,"enable_purge":"1","enabled":"1","created":"1497291760"}
Add a customer#
curl -u "$user" -d @data.json archive.aaa.fu/api/v1/add_customer
data.json:
[{
"customer_id": "qqq",
"customer_address": "qqq@aaa.fu",
"worker": "cust1.aaa.fu",
"quota": 20,
"retention_days": 45,
"gui_url": "qqq.aaa.fu",
"domain": "qqq.fu",
"admin_password": "$6$rounds=5000$7Sm7typK$UEjSSkYPNsPpv81Tv71NGAWCaSFprJz4b5YGFmRO640r9S8HohZlgYmjj5Qb7J08PQ4BzNFjKBqtLPv96Oxz90",
"branding_url": "",
"support_link": "",
"enable_purge": 1
}]
Update customer settings#
curl -u "$user" -d @data.json archive.aaa.fu/api/v1/update_customer
[{
"customer_id": "qqq",
"customer_address": "qqq525@aaa.fu",
"worker": "cust1.aaa.fu",
"quota": 20,
"retention_days": 45,
"gui_url": "qqq.aaa.hu",
"domain": "qqq.fu",
"branding_url": "",
"support_link": "",
"text_colour": "",
"background_colour": "",
"branding_logo": "",
"enable_purge": 1
}]
Delete customer settings from the database#
curl -u "$user" -d ‘[{"customer_id": "bbb"}]’ archive.aaa.fu/api/v1/delete_customer
Note that this removes only the customer reference from the customer_settings table. The customer’s data (mysql, manticore/sphinx, and emails) are not affected. These must be deleted manually.
Users#
Add a user#
curl -u "$user" -d @data.json archive.aaa.fu/api/v1/add_user
data.json:
[{
"username": "bela",
"realname": "bela baba",
"email": "bela@local",
"domain": "local",
"password": "$6$rounds=5000$7Sm7typK$UEjSSkYPNsPpv81Tv71NGAWCaSFprJz4b5YGFmRO640r9S8HohZlgYmjj5Qb7J08PQ4BzNFjKBqtLPv96Oxz90",
"isadmin": "0",
"dn": "",
"samaccountname": ""
}]
Update a user#
curl -u "$user" -d @data.json archive.aaa.fu/api/v1/update_user
data.json:
[{
"uid": "2",
"username": "bela",
"realname": "bela babaaaaa",
"password": "",
"email": "bela@local",
"domain": "local",
"isadmin": "0",
"group": "aaaa4",
"dn": "",
"samaccountname": ""
}]
Delete a user#
curl -u "$user" -d @data.json archive.aaa.fu/api/v1/delete_user
data.json:
[{
"uid": "2",
"username": "bela"
}]
Groups#
Get groups#
curl -u "$user" cust1.aaa.fu/api/v1/get_groups
[{"id":"1","groupname":"group1"}]
curl -u "$user" -d '[{"id":1}]' cust1.aaa.fu/api/v1/get_group
Add group#
curl -u "$user" -d @data.json cust1.aaa.fu/api/v1/add_group
data.json:
[{
"groupname":"aaaa",
"email":"bela@aaa.fu\nsanyi@aaa.fu",
"assigned_email":"jerry@aaa.fu\naaaa@aaa.fu"
}]
Update group#
curl -u "$user" -d @data.json cust1.aaa.fu/api/v1/update_group
data.json:
[{
"id": 2,
"groupname":"aaaa4",
"email":"belaja@aaa.fu\nsanyi@aaa.fu",
"assigned_email":"jerry@aaa.fu\naaaa@aaa.fu"
}]
Delete group#
curl -u "$user" -d '[{"id": 1}]' archive.aaa.fu/api/v1/delete_group
Header checks#
Note that you need to reload the piler daemons to re-read the header checks.
Get header checks#
curl -u "$user" cust1.aaa.fu/api/v1/get_header_checks
[{"id":"1","pattern":"subject:.*utf-8\\?Q\\?=E4=B[A-Z0-9]=[[:xdigit:]]{2}=E5","tag":"TAG1"}, {"id":"2","pattern":"(To:.*@aaa.fu|From: Alice)","tag":"ALICE"}, {"id":"3","pattern":"From:.*@yahoo.com","tag":"YAHOO"},
{"id":"4","pattern":"Authenticated sender: bob","tag":"BOB"},
{"id":"5","pattern":"Subject: \\[SPAM\\]","tag":"SPAM"}]
Delete header check rule#
curl -u "$user" -d '[{"id":1}]' cust1.aaa.fu/api/v1/delete_header_check
Add a header check rule#
curl -u "$user" -d @data.json cust1.aaa.fu/api/v1/add_header_check
[{
"pattern":"From:.*@yoyo.com",
"tag":"KKKKKK"
}]