FortiMail™REST API Reference

Version 5.3

1
FORTINET DOCUMENT LIBRARY
http://docs.fortinet.com

FORTINET VIDEO GUIDE

http://video.fortinet.com

FORTINET BLOG
https://blog.fortinet.com

CUSTOMER SERVICE & SUPPORT

https://support.fortinet.com

FORTINET COOKBOOK
http://cookbook.fortinet.com

FORTINET TRAINING SERVICES

http://www.fortinet.com/training

FORTIGUARD CENTER
http://www.fortiguard.com

END USER LICENSE AGREEMENT

http://www.fortinet.com/doc/legal/EULA.pdf

FEEDBACK
Email: techdocs@fortinet.com

February 28, 2017

TABLE OF CONTENTS

Introduction ........................................................................................................................................................................ 4
Enabling REST API support ............................................................................................................................................ 4
Authentication .................................................................................................................................................................... 4
Setting up an authenticated session .............................................................................................................................. 4
FortiMail REST API HTTP response codes .................................................................................................................. 5
REST API for system level resources ............................................................................................................................ 5
REST API for domain level resources ........................................................................................................................... 6
REST API for administrative actions .............................................................................................................................. 7
System resource list and URLs....................................................................................................................................... 7
Example commands ....................................................................................................................................................... 15
Admin login .................................................................................................................................................................. 15
Get domain information .............................................................................................................................................. 15
Access control rule management ............................................................................................................................. 15
List Access Control Rules ...................................................................................................................................... 16
Create a new Access Control Rule ...................................................................................................................... 16
Modify an existing Access Control Rule .............................................................................................................. 16
Delete an existing Access Control Rule .............................................................................................................. 17
Move existing Access Control Rules .................................................................................................................... 17

3
Introduction

This document provides the REST API information supported in FortiMail version 5.3.4 release. This document
covers the FortiMail GUI supported REST API reference only. These APIs can be used to retrieve, create,
update and delete configuration settings, to retrieve dynamic system statistics, and to perform basic
administrative actions such as reboot and shut down.

When using the APIs, the following conventions are followed:

Http GET --- To retrieve all resources or particular resource

Http POST --- To create a new resource or perform certain administrative actions

Http PUT --- To update an existing resource

Http Delete --- To delete an existing resource

Enabling REST API support

By default, this feature is disabled on FortiMail. To enable it, use the following CLI command:

config system global

set rest-api enable
end

Authentication
When making requests to FortiMail appliance using the REST API, you will need

1. A valid admin username and password (so that an authenticated session can be established)
2. Appropriate access permissions for the requested resource (controlled by admin profile)

Setting up an authenticated session

To establish a valid authentication session, you must make a POST request to the FortiMail login handler with
your admin username and password. The POST request should contain JSON data with ‘name’ and ‘password’
fields:

URL: http(s)://host_or_ip/api/v1/AdminLogin/

4
 Method: POST

JSON: {“name”: “admin”, “password”: “****”}

If login is successful, the response will contain the authentication token in the APSCOOKIE cookie value. This
cookie value must be included in any further requests.
Note: The permissions for the administrative account you use will affect which objects and operations you'll
have access to, so ensure the user has the permissions required for the actions you wish to perform.

FortiMail REST API HTTP response codes

FortiMail REST APIs use well-defined HTTP status codes to indicate query results to the API. Following are
some of the HTTP status codes used:

HTTP Response Code Description

200-OK API request successful.

400- Bad Request Bad request.

403 - Forbidden Request is missing authentication token or administrator is missing access profile
permissions.

404- Not Found Unable to find the specified resource.

405- Method Not Allowed Specified HTTP method is not allowed for this resource

500 Internal Server Error

REST API for system level resources

FortiMail supports retrieval and modification of system level CMDB configuration settings as well as system
level statistics. The API can be accessed using the following URL:

http(s)://host_ip/api/v1/resource_name/resource_id/sub_resource_name/sub_resource_id/

where:

resource_name --- Specifies the type of resource to query (such as SysInterface), required.

resource_id --- Unique ID of the resource as specified by resource_name (such as port1), optional.
If not present, returns entire list of resources.

sub_resource_name --- Some resources may have sub / child resources, use this to query sub resources,
5
 optional

sub_resource_id --- Unique ID of the sub resource as specified by sub_resource_name, optional. If not
present, returns entire list of sub resources.

Examples:

…/api/v1/SysInterface/ --- returns list of network interfaces

…/api/v1/SysInterface/port1/ --- return details of network interface ‘port1’

…/api/v1/SysGlobal/ --- returns details of global settings (only one instance)

…/api/v1/ProfSession/inbound/ ProfSessionSenderWhitelist/

--- returns sender whitelist/saftlist of session profile ‘inbound’

For a full list of system level resources, refer to the Supported Resources List.

REST API for domain level resources

FortiMail also supports retrieval and modification of domain level CMDB configuration settings. The API can be
accessed using the following URL:

http(s)://host_ip/api/v1/domain/domain_name/resource_name/resource_id/sub_r
esource_name/sub_resource_id/

It is very similar to the URL for system level resources, only two new tokens are added:

domain --- Required keyword, use to perform domain level queries

domain_name --- FQDN name of the domain to query (such as fortinet.com)

Examples:

…/api/v1/domain/abc.com/ProfAntispam/

--- returns list of antispam profiles for domain ‘abc.com’

…/api/v1/domain/abc.com/PolicyRecipient/

--- returns list of recipient based policies for domain ‘abc.com’

…/api/v1/domain/abc.com/PolicyRecipient/1/

--- returns details of recipient based policy ‘1’ for domain ‘abc.com’

For a full list of domain level resources, refer to the Supported Resources List.

6
REST API for administrative actions
Apart from resources, FortiMail REST API supports basic administrative actions such as restarting / shutting
down a device. Use the following URL to send action request:

URL: http(s)://host_ip/api/v1/SysStatusCommand/

Method: POST

JSON: {“action”: action_value}

Where action_value is one of the following integers:

1 --- Restart

2 --- Shut down

3 --- Reload

System resource list and URLs

Note: Resources marked with * also apply to domain level REST APIs.

URL HTTP Method Summary

/Addressbook/ GET, POST, PUT, Contacts

* DELETE

/AddressbookGroup/ GET, POST, PUT, Contact groups

* DELETE

/ArchAccount/ GET, POST, PUT, Archive accounts

DELETE

/ArchExempt/ GET, POST, PUT, Archive exempt policy

DELETE

/ArchJournalSource/ GET, POST, PUT, Archive journaling source

DELETE

/ArchPolicy/ GET, POST, PUT, Archive policy

DELETE

/AsBounceverifyKey/ GET, POST, PUT, Bounce verification keys

DELETE

7
/AsDeepheader/ GET, PUT Deep header analysis
settings

/AsGreylist/ GET Greylist

/AsGreylisyAutoexempt/ GET Auto exempt greylist

/AsMsisdnReputationAuto_blacklist/ GET Endpoint reputation auto

blocklist

/AsMsisdnReputationBlacklist/ GET, DELETE Endpoint reputation

blocklist

/AsMsisdnReputationExempt/ GET, DELETE Endoint reputation exempt

list

/AsSenderReputation/ GET Sender reputation list

/AsSpamreport/ GET, PUT Quarantine / spam report

settings

/AsUrl_fgas_exempt_list/ GET, POST, PUT, URL exempt list

DELETE

/CalResource/ GET, POST, PUT,

* DELETE

/CalendarServer/ GET, PUT Calendar server settings

/CentralBackupConfig/ GET, PUT Central backup

configuration

/CentralConfigList/ GET, DELETE Central backup list

/ContentScanRules/ GET, POST, PUT, DLP content scan rules

DELETE

/ContentScanRulesConditions/ GET, POST, PUT, DLP content scan rule

DELETE conditions

/ContentScanRulesExceptions/ GET, POST, PUT, DLP content scan rule

DELETE exceptions

/domain/ GET, POST, PUT, Protected domain settings

DELETE

/DomainSettingSenderAddrRateCtrlExempt/ GET, POST, PUT, Sender rate control exempt

list for specified domain
8
 DELETE settings

/DomainSpamReportRcpt/ GET, PUT Domain level quarantine /

spam report settings

/FilePattern/ GET, POST, PUT, File patterns / filters

* DELETE

/FileSignature/ GET, POST, PUT, File signatures for AV scan

DELETE

/Fingerprint_doc/ GET, DELETE Fingerprint document list

/LogAltMMailto/ GET, POST, DELETE Alert email accounts

/LogAltMSetting/ GET, PUT Alert email settings

/LogReport_config/ GET, POST, PUT, Log report configurations

DELETE

/LogReportFile/ GET, DELETE Log report files

/LogSetLocal/ GET, PUT Local log settings

/MailSetStrgNfs/ GET, PUT Mail storage settings

/MailSetStrgRemote_storage_ibe/ GET, PUT Centralized IBE storage

settings

/MailSetStrgServer/ GET, PUT Centralized quarantine

storage settings

/MailSetSystemquarantine/ GET, PUT System quarantine settings

/MailSetSystemquarantineFolder/ GET, POST, PUT, System quarantine folders

DELETE

/PolicyIp/ GET, POST, PUT, IP policies

DELETE

/PolicyRecipient/ GET, POST, PUT, Recipient policies

* DELETE

/ProfAntispam/ GET, POST, PUT, AntiSpam profiles

* DELETE

/ProfAntispam_action/ GET, POST, PUT, AntiSpam action profiles

9
* DELETE

/ProfAntispamBannedwords/ GET, POST, PUT, AntiSpam profile banned

* DELETE words

/ProfAntispamDnsblServer/ GET, POST, PUT, AntiSpam profile DNSBL

* DELETE servers

/ProfAntispamSurblServer/ GET, POST, PUT, AntiSpam profile SURBL

* DELETE servers

/ProfAntispamWhitelistwords/ GET, POST, PUT, AntiSpam profile safelist

* DELETE words

/ProfAntivirus/ GET, POST, PUT, AntiVirus profiles

* DELETE

/ProfAntivirus_action/ GET, POST, PUT, AntiVirus action profiles

* DELETE

/ProfAuthImap/ GET, POST, PUT, IMAP authentication profiles

* DELETE

/ProfAuthPop3/ GET, POST, PUT, POP3 authentication profiles

* DELETE

/ProfAuthRadius/ GET, POST, PUT, Radius authentication

* DELETE profiles

/ProfAuthSmtp/ GET, POST, PUT, Smtp authentication profiles

* DELETE

/ProfCertificate_binding/ GET, POST, PUT, Certificate binding profiles

DELETE

/ProfContent/ GET, POST, PUT, Content profiles

* DELETE

/ProfContent_action/ GET, POST, PUT, Content action profiles

* DELETE

/ProfContentAttachment/ GET, POST, PUT, Content profile attachment

* DELETE scan rules

/ProfContentMonitor/ GET, POST, PUT, Content monitor profile

* DELETE

10
/ProfDictionary/ GET, POST, PUT, Dictionary profiles
DELETE

/ProfDictionary_group/ GET, POST, PUT, Dictionary group

DELETE

/ProfDictionaryDictionaryItem/ GET, POST, PUT, Dictionary profile dictionary

DELETE entries

/ProfDlp/ GET, POST, PUT, DLP profiles

DELETE

/ProfDlpContentScan/ GET, POST, PUT, DLP profile content scan

DELETE settings

/ProfEmail_address_group/ GET, POST, PUT, Email address groups

DELETE

/ProfEncryption/ GET, POST, PUT, Encryption profiles

DELETE

/ProfIp_address_group/ GET, POST, PUT, IP address groups

DELETE

/ProfIp_pool/ GET, POST, PUT, IP pools

DELETE

/ProfLdap/ GET, POST, PUT, LDAP profiles

DELETE

/ProfMisc/ * GET, POST, PUT, Resource profiles

DELETE

/ProfNotification/ GET, POST, PUT, Notification profiles

DELETE

/ProfSessionRecipientWhitelist/ GET, POST, PUT, Session profile recipient

DELETE safelist

/ProfSessionRemovedHeader/ GET, POST, PUT, Session profile removed

DELETE headers

/ProfSessionSenderBlacklist/ GET, POST, PUT, Session profile sender

DELETE blocklist

/ProfSessionSenderWhitelist/ GET, POST, PUT, Session profile sender

11
 DELETE safelist

/ProfTls/ GET, POST, PUT, TLS profiles

DELETE

/ProfUri_filter/ GET, POST, PUT, URI filter profiles

DELETE

/RaidSystem/ GET Raid system status

/RaidSystemArray/ GET Raid array information

/RaidSystemDisk/ GET Raid disk information

/SemailDbDomain/ GET, DELETE IBE domains

/SemailDbUser/ GET, DELETE IBE users

/Sensitive_dataCompliance/ GET DLP standard compliance

data

/Sensitive_dataFingerprint/ GET, POST, PUT, DLP fingerprint data

DELETE

/Sensitive_dataFingerprint_source/ GET, POST, PUT, DLP fingerprint source

DELETE

/Sensitive_dataFingerprintDocument/ GET, DELETE DLP fingerprint documents

/SysAccprofile/ GET, POST, PUT, Admin access profiles

DELETE

/SysAdmin/ GET, POST, PUT, System administrators

DELETE

/SysAntispam/ GET, PUT System AntiSpam settings

/SysAppearance/ GET, PUT System appearance settings

/SysAutoupdate/ GET, PUT FortiGuard AntiVirus auto

update settings

/SysBackup_restore/ GET, PUT Mail data auto backup

settings

/SysBurstRestore/ PUT Restore mail data from

backup

12
/SysDateSetting/ GET, PUT System date

/SysDdns/ GET, POST, PUT, DDNS servers

DELETE

/SysDisclaimer/ GET, PUT System disclaimer settings

/SysDisclaimer_exclude/ GET, POST, PUT, Disclaimer exclusion list

DELETE

/SysDns/ GET, PUT System DNS server settings

/SysEncryptionIbe/ GET, PUT IBE encryption settings

/SysEncryptionIbe_auth/ GET, POST, PUT, IBE user authentication list

DELETE

/SysFortiguard/ GET, PUT FortiGuard AntiSpam

settings

/SysFortisandbox/ GET, PUT FortiSandbox settings

/SysGlobal/ GET, PUT System global settings

/SysHa/ GET, PUT HA settings

/SysHaInterface/ GET, PUT HA interface settings

/SysHaService/ GET, PUT HA service monitor settings

/SysHaStatus/ GET HA status

/SysInterface/ GET, POST, PUT, Network interface list

DELETE

/SysLink_monitor/ GET, PUT Link monitor settings

/SysLink_monitorInterface/ GET, PUT Link monitor interface

settings

/SysMailserver/ GET, PUT Mail server settings

/SysRemote_mail_server/ GET, POST, PUT, Remote email servers

DELETE

/SysRoute/ GET, POST, PUT, Network routing list

DELETE

13
/SysSched_backup/ GET, PUT System configuration
scheduled backup settings

/SysScheduledLocalBackup/ GET, PUT Scheduled local backup list

/SysSnmpCommunity/ GET, POST, PUT, SNMP communities

DELETE

/SysSnmpCommunityHost/ GET, POST, PUT, Hosts for a SNMP

DELETE community

/SysSnmpSnmpv3_user/ GET, POST, PUT, SNMP users

DELETE

/SysSnmpSnmpv3_userHost/ GET, POST, PUT, Notification hosts for a

DELETE SNMP user

/SysSnmpSysinfo/ GET, PUT SNMP system information

settngs

/SysSnmpThreshold/ GET, PUT SNMP threshold settings

/SysStatisticSummary/ GET Mail statistics summary

/SysStatusCommand/ POST Restart / Shut donw /

Reload system command

/SysStatusLicinfo/ GET System AS / AV license

status

/SysStatusLicinfoLicenses/ GET Feature license list

/SysStatusSysinfo/ GET System status information

/SysStatusUsage/ GET System resource usage

/SysTimeManual/ GET, PUT System time & zone settings

/SysTimeNtp/ GET, PUT System NTP server settings

/SysWccpSettings/ GET, PUT FortiGate WCCP settings

/UserAlias/ GET, POST, PUT, User aliases

* DELETE

/UserMail/ GET, POST, PUT, Mail users

* DELETE

14
 /UserMap/ GET, POST, PUT, Address maps
* DELETE

/UserPki/ GET, POST, PUT, PKI Users

DELETE

/UserUser_group/ GET, POST, PUT, User groups

* DELETE

Example commands
Admin login

curl -v -H "Content-Type: application/json" -X POST -d

'{"name":"admin","password":"*****"}' https://ip_or_host/api/v1/AdminLogin
-c cookie.txt

If login is successful, the cookies will be save to cookie.txt, which will be used in the below commands.

Get domain information

curl -k -v --cookie cookie.txt https://ip_or_host/api/v1/Domain

Access control rule management

Supported values for 'action' attribute of ACL. If not set, the default action is reject.

1 --- safe-relay
2 --- relay
3 --- reject
4 --- discard
5 --- safe

Supported values for 'recipient-pattern-type' and 'sender-pattern-type' attributes of ACL:

0 --- default / wild-card

1 --- regular expression
2 --- email group
3 --- ldap group

Supported values for 'authenticated' attribute of ACL:

0 --- any
1 --- authenticated
2 --- not-authenticated
15
Supported values for 'sender-ip-type' attribute of ACL:

0 --- ip mask
1 --- ip group

Supported values for 'sortingDirection' attribute of applicable JSON requests (i.e. ACL rule):

1 --- enabled/sorting
2 --- disabled/no sorting

Supported values for 'reqAction' attribute of all JSON requests:

1 --- GET
2 --- CREATE
3 --- DELETE
5 --- UPDATET
14 --- MOVE

Note: If reqAction is present in JSON, it takes precedence over HTTP method header (i.e. HTTP
GET/POST/PUT/DELETE).

List Access Control Rules

To list ACL rules in original order:

curl -v -b cookie.txt -v -H "Content-Type: application/json" -X PUT -d
'{"reqAction":1,"sortingDirection":2}'
http://ip_or_host/api/v1/MailSetAccessRule

To list ACL rules in descending order:

curl -v -b cookie.txt -v -H "Content-Type: application/json" -X PUT -d
'{"reqAction":1,"sortingDirection":1}'
http://ip_or_host/api/v1/MailSetAccessRule

Create a new Access Control Rule

curl -v -H "Content-Type: application/json" -X POST -d

'{"status":true,"sender_pattern":"*@example.com","sender_ip_mask":"192.168.
1.1/32", "action":2}' -b cookie.txt
http://ip_or_host/api/v1/MailSetAccessRule/0
--No mkey is required

Modify an existing Access Control Rule

curl -v -H "Content-Type: application/json" -X PUT -d '{"action":3}' -b
cookie.txt http://ip_or_host/api/v1/MailSetAccessRule/1
--"1" is the mkey

16
--Set access rule "1" action to “Reject”

Delete an existing Access Control Rule

curl -v -H "Content-Type: application/json" -X DELETE -b cookie.txt
http://ip_or_host/api/v1/MailSetAccessRule/3
--Delete Access Control Rule "3"

Move existing Access Control Rules

You can move a rule up one place, down one place, before another rule, or after another rule. To move a rule
to the top or bottom, you can find the first. or last rule ID (mkey) and move the rule before the first rule or
after the last rule.

reqAction: 14 -- required, only one value: 14 means to move

moveAction : up -- required, 4 values: up/down/before/after

mmkey: 3 – required, ID of the ACL rule to be moved

refMkey: 2 – required, reference ID of the ACL rule when moving before/after this ID

To move rule"3" up one place:

curl -v -H "Content-Type: application/json" -X PUT -d

'{"reqAction":"14","mmkey":3,"moveAction":"up"}' -b cookie.txt
http://ip_or_host/api/v1/MailSetAccessRule

To move rule "3" after rule "2":

curl -v -H "Content-Type: application/json" -X PUT -d

'{"reqAction":"14","mmkey":3,"moveAction":"after",”refMkey”:2}' -b
cookie.txt http://ip_or_host/api/v1/MailSetAccessRule

17
Copyright© 2016 Fortinet, Inc. All rights reserved. Fortinet®, FortiGate®, FortiCare® and FortiGuard®, and certain other marks are registered trademarks of Fortinet, Inc., in the
U.S. and other jurisdictions, and other Fortinet names herein may also be registered and/or common law trademarks of Fortinet. All other product or company names may be
trademarks of their respective owners. Performance and other metrics contained herein were attained in internal lab tests under ideal conditions, and actual performance and
other results may vary. Network variables, different network environments and other conditions may affect performance results. Nothing herein represents any binding
commitment by Fortinet, and Fortinet disclaims all warranties, whether express or implied, except to the extent Fortinet enters a binding written contract, signed by Fortinet’s
General Counsel, with a purchaser that expressly warrants that the identified product will perform according to certain expressly-identified performance metrics and, in such
event, only the specific performance metrics expressly identified in such binding written contract shall be binding on Fortinet. For absolute clarity, any such warranty will be
limited to performance in the same ideal conditions as in Fortinet’s internal lab tests. In no event does Fortinet make any commitment related to future deliverables, features, or
development, and circumstances may change such that any forward-looking statements herein are not accurate. Fortinet disclaims in full any covenants, representations, and
guarantees pursuant hereto, whether express or implied. Fortinet reserves the right to change, modify, transfer, or otherwise revise this publication without notice, and the most
current version of the publication shall be applicable.