This document describes how to automate message management and release on a Cisco SMA via the REST API in order to process large volumes of messages.
Cisco recommends that you have knowledge of these topics:
This document is not restricted to specific software and hardware versions.
The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, ensure that you understand the potential impact of any command.
Automating message release is essential for environments with high email volume. By using the API, administrators can filter specific messages (for example, by sender) and release them programmatically, reducing operational time and the risk of human error compared to manual management in the GUI.
In order to manage the quarantine, start by performing an initial query to verify connectivity and confirm the data structure.
https://dhxyz-sma2.iphmx.com/sma/api/v2.0/quarantine/messages?quarantineType=pvo&quarantines=TEST_QUARANTINE&limit=25&offset=0&orderBy=received&orderDir=desc&startDate=2026-03-15T00:00:00.000Z&endDate=2026-03-16T00:00:00.000Z
When retrieving the information, you can see the same amount of messages in the API call and in the GUI.
postman GET request
TEST_QUARANTINE messages
Generate your Base64 authentication token for the authorization header:
echo -n 'username:password' | base64
Execute the curl request to extract the messages into a local file:
curl -X GET "https://dhxyz-sma2.iphmx.com/sma/api/v2.0/quarantine/messages?quarantineType=pvo&quarantines=TEST_QUARANTINE&limit=25&offset=0&orderBy=received&orderDir=desc&startDate=2026-03-15T00:00:00.000Z&endDate=2026-03-16T00:00:00.000Z" \
-H "Authorization: Basic token-generated-in-base64" \
-H "Accept: application/json" \
-o response.json
Check the total number of messages received:
$ grep "totalCount" response.json | awk '{ print $2, $3}'
{"totalCount": 24},
Use JQ to filter the MIDs of the messages you wish to release (for example, filtering by domain).
$ jq '[.data[] | select(.attributes.sender | endswith("@labcisco.com")) | .mid]' response.json > mids-labcisco-domain.json
$ cat mids-labcisco-domain.json
[
440,
439,
438,
437,
436,
435,
434,
433,
425,
414
]
The number of MIDs, can be match if you make a search into the TEST_QUARANTINE into the SMA GUI.
quarantine search
quarantine results
Filter the MIDs and generate the payload file.
$ jq '{action:"release", quarantineType:"pvo", quarantineName:"TEST_QUARANTINE", mids:[.data[] | select(.attributes.sender | endswith("@labcisco.com")) | .mid]}' response.json > payload.json
$ cat payload.json
{
"action": "release",
"quarantineType": "pvo",
"quarantineName": "TEST_QUARANTINE",
"mids": [
440,
439,
438,
437,
436,
435,
434,
433,
425,
414
]
}
Send the release request to the SMA:
$ curl -X POST "https://dhxyz-sma2.iphmx.com/sma/api/v2.0/quarantine/messages" \
-H "Authorization: Basic token-generated-in-base64" \
-H "Content-Type: application/json" \
-d @payload.json
{"data": {"action": "release", "totalCount": 10}}
When checking mail_logs for released messages, you can filter by grep "release" mail_logs and the same MIDs you filter above, the same be the ones that got released.
Sun Mar 15 11:48:21 2026 Info: MID 436 released from quarantine "TEST_QUARANTINE" (manual) t=1393
Sun Mar 15 11:48:21 2026 Info: MID 425 released from quarantine "TEST_QUARANTINE" (manual) t=1411
Sun Mar 15 11:48:21 2026 Info: MID 414 released from quarantine "TEST_QUARANTINE" (manual) t=2787
Sun Mar 15 11:48:21 2026 Info: MID 433 released from quarantine "TEST_QUARANTINE" (manual) t=1397
Sun Mar 15 11:48:21 2026 Info: MID 440 released from quarantine "TEST_QUARANTINE" (manual) t=1387
Sun Mar 15 11:48:21 2026 Info: MID 439 released from quarantine "TEST_QUARANTINE" (manual) t=1388
Sun Mar 15 11:48:21 2026 Info: MID 434 released from quarantine "TEST_QUARANTINE" (manual) t=1396
Sun Mar 15 11:48:21 2026 Info: MID 437 released from quarantine "TEST_QUARANTINE" (manual) t=1391
Sun Mar 15 11:48:21 2026 Info: MID 435 released from quarantine "TEST_QUARANTINE" (manual) t=1395
Sun Mar 15 11:48:21 2026 Info: MID 438 released from quarantine "TEST_QUARANTINE" (manual) t=1390
If you make the same search for the domain you released the messages, you see that the search has no results, since all the messages were released.
quarantine new results
Re-run the GET command from Retrieve All Messages in order to confirm that the totalCount has decreased or that the specific MIDs are no longer present.
postman GET query
$ curl -X GET "https://dhxyz-sma2.iphmx.com/sma/api/v2.0/quarantine/messages?quarantineType=pvo&quarantines=TEST_QUARANTINE&limit=25&offset=0&orderBy=received&orderDir=desc&startDate=2026-03-12T00:00:00.000Z&endDate=2026-03-14T00:00:00.000Z" \
-H "Authorization: Basic token-generated-in-base64" \
-H "Accept: application/json" \
-o response.json
$ jq '[.data[] | select(.attributes.sender | endswith("@labcisco.com")) | .mid]' response.json > mids-labcisco-domain.json
$ cat mids-labcisco-domain.json
[]
In order to handle bulk operations effectively, you must understand how to manage large datasets using pagination. When you need to process a large number of messages, you must calculate the limit and offset parameters to ensure you retrieve the complete set of data without exceeding API response constraints.
When retrieving a large volume of messages, use this logic to configure your request:
The process used in the previous 10-message example serves as the foundation for all bulk operations. In order to scale your workflow, simply iterate through the queue by systematically incrementing the offset parameter. By 'playing' with these values—adjusting the limit to define your batch size and the offset to navigate through the pages — you can effectively retrieve and process your entire quarantine queue, regardless of the total message count.
| Revision | Publish Date | Comments |
|---|---|---|
1.0 |
07-Apr-2026
|
Initial Release |