Client Mailbox Access via API

Customizations
1

Hi,

I am doing some testing around client mailboxes, I have managed to:

https://developer.bigfix.com/rest-api/api/mailbox.html

  1. List client mailbox - confirms mailbox is empty
curl -k -u ${USER}:${PASS} "https://${SERVER}:52311/api/mailbox/549222702"
  1. Add file to client mailbox - xml returns success
curl --data @data.txt -k -u ${USER}:${PASS} "https://${SERVER}:52311/api/mailbox/549222702" -H "Content-Disposition: attachment; filename=data.txt"  -H "Content-Type: application/octet-stream"
  1. List client mailbox - confirms new file in the mailbox

Output:

<?xml version="1.0" encoding="UTF-8"?>
<BESAPI xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="BESAPI.xsd">
        <ComputerMailboxFile Resource="https://1.1.1.1:52311/api/mailbox/549222702/969716">
                <Name>data</Name>
                <ID>969716</ID>
                <SHA1>d7735aa1b7845f89fc8f1540f4d9b066f8b61eca</SHA1>
                <Size>23</Size>
                <Timestamp>Mon, 10 Nov 2025 13:48:41 +0000</Timestamp>
        </ComputerMailboxFile>
</BESAPI>
  1. Attempt to read the content of the file but it doesnt return
curl -k -u ${USER}:${PASS} "https://${SERVER}:52311/api/mailbox/549222702/969716"

Output:

<?xml version="1.0" encoding="UTF-8"?>
<BESAPI xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="BESAPI.xsd">
        <ComputerMailboxFile Resource="https://1.1.1.1:52311/api/mailbox/549222702/969716">
                <Name>data</Name>
                <ID>969716</ID>
                <SHA1>d7735aa1b7845f89fc8f1540f4d9b066f8b61eca</SHA1>
                <Size>23</Size>
                <Timestamp>Mon, 10 Nov 2025 13:48:41 +0000</Timestamp>
        </ComputerMailboxFile>
</BESAPI>

I was expecting #4 to return the contents of the file, the documentation says:

“Fetches the details of the specified file in the specified computer's mailbox.” and "Response: List of files in the mailbox.”.

Is there another way to view the contents of the file or am I only able to query the contents of the file via Analysis?

Thanks,

2

I don’t believe you’d be able to read/view the contents of the mailbox file via the REST API, no (they are encrypted).

Out of curiosity, what is the use case? What are you trying to achieve?

3

Thanks for the reply, I’m just investigating how it works in order to see what I can possibly use it for. I do not currently have a solid use case for it yet.

It looks like the files are not encrypted, atleast the local files are not. They do seem to strip CR/LF but I need to test further to confirm that I’m not posting with incorrect arguments.

Local QNA (Linux)

[root@x007 tmp]# /opt/BESClient/bin/qna
Default masthead location, using /etc/opt/BESClient/actionsite.afxm
Q: files of folder "mailboxsite" of data folder of client
A: /opt/BESClient/__BESData/mailboxsite/data
A: /opt/BESClient/__BESData/mailboxsite/data2
T: 3750

Q: lines of file "data" of folder "mailboxsite" of data folder of client
A: hello this is some data
T: 1062

On the filesystem:

[root@x007 ~]# sha1sum /opt/BESClient/__BESData/mailboxsite/data
d7735aa1b7845f89fc8f1540f4d9b066f8b61eca  /opt/BESClient/__BESData/mailboxsite/data

[root@x007 tmp]# file /opt/BESClient/__BESData/mailboxsite/data
/opt/BESClient/__BESData/mailboxsite/data: ASCII text, with no line terminators


[root@x007 tmp]# cat /opt/BESClient/__BESData/mailboxsite/data
hello this is some data
1 Like
4

The files sent are not encrypted on the destination, no, but they may be in traffic. The idea is that it allows you to distribute unique files to endpoints and using properties then make the data available in BigFix. The best possible use-case would be bringing 3rd party data into BigFIx - you get data from a 3rd party source, you parse it and break it up to unique file for each device and then each file you post it to the client - then next day you redo the entire thing and compare the hashes of the files (in fact, this is the exact design of the ServiceNow Data Flows engine - it sends individual CMDB files in comma-separated format to each endpoint and a ServiceNow analysis reach each value as a separate property).

One other example I’ve personally used for is distribution of manifest files for dynamic downloads.

1 Like
5

Mailbox files (and actions) are encrypted uniquely for each Client, so, they are secure at rest on the Root Server, and Relays, as well as secure in transit. It is only on the Client that mailbox files/actions can be decrypted.

Reference: Mailboxing

6

Just one word of caution of a design bit that surprised me - if you post a file to mailbox, and in fact the same to site, with the same name as a file that already exists it does not override the file! It keeps both instead. So as you are building up your use case keep that in mind and make plans to put some kind of clean-up process too. We had an issue where we have been posting files, thinking they were overwriting the previous file and then tried to change the TLS settings on the root server which recreates the certs & reencrypts all files… Well, we found out the hard way! The process was running and took a week to complete during which time environment was unavailable and we couldn’t even stop the process!

7

Thanks, this is good to know. We are currently testing dataflow which is what made me curious about this in the first place :slight_smile: