Cloudron 9.0.9: API request Mailboxes enablePop3 field

[jkammerer]

Since the update to Cloudron 9.0.9, our previously working API requests for creating a mailbox no longer function.

Our script used to run without any issues, but now the endpoint /api/v1/mail/boxes returns the following error:

400 - {
  "status": "Bad Request",
  "message": "enablePop3 must be a boolean"
}

In the API documentation
(https://docs.cloudron.io/api.html#tag/Mail/operation/addMailbox)
the field enablePop3 is not listed.
As a result, older requests never included this field and are now invalid.

From our perspective, it would make sense for this field to be optional and—if omitted—automatically interpreted as false. This would maintain backward compatibility for existing integrations.

Additionally, is there a changelog available for recent API changes?

[james]

Hello @jkammerer
The API Doc is currently still outdated for Cloudron 9.
Here is the CURL for creating, getting and deleting a mailbox - the following can be copy-pasted for testing until the cloudron demo server resets:

FQDN="my.demo.cloudron.io"
DOMAIN="demo.cloudron.io"
APITOKEN="3f7c34657239b5d0e4156e341cc66550038665231a45e167c7777d7753703a9b"
MAILBOXOWNER="uid-05a84d23-6eb0-4905-b90d-b912056534b0"
MAILBOXNAME="topic-14553"

# Create the mailbox
curl "https://$FQDN/api/v1/mail/$DOMAIN/mailboxes" \
  -H "Authorization: Bearer $APITOKEN" \
  -H 'content-type: application/json' \
  --data-raw "{\"name\":\"$MAILBOXNAME\",\"ownerId\":\"$MAILBOXOWNER\",\"ownerType\":\"user\",\"active\":true,\"enablePop3\":false,\"storageQuota\":0,\"messagesQuota\":0}"

# Get the mailboxes
curl "https://$FQDN/api/v1/mail/demo.cloudron.io/mailboxes?page=1&per_page=1000" \
  -H "Authorization: Bearer $APITOKEN"

# Delete the created mailbox
curl "https://$FQDN/api/v1/mail/$DOMAIN/mailboxes/$MAILBOXNAME" \
  -X 'DELETE' \
  -H "Authorization: Bearer $APITOKEN" \
  -H 'content-type: application/json' \
  --data-raw '{"deleteMails":true}'

If you need to find API Routes and the API Doc is outdated, you can open the browser network inspector and while using the Cloudron Dashboard you can log API calls.
Example from creating a mailbox:

1. adding a mailbox name
2. selecting a user
3. saving
4. call will be logged

You can then also right-click the item and Copy as cURL (BASH) to get a fully working CURL example with your currently used user and token:

1. find your desired request and right-click
2. click Copy
3. click Copy as cURL (bash)

From the Copy as cURL (bash):

curl 'https://my.demo.cloudron.io/api/v1/mail/demo.cloudron.io/mailboxes?access_token=RgT61xyzteMTi9sDp2ZranmfLr5leZWG9gZyOJ2mn4o' \
  -H 'accept: */*' \
  -H 'accept-language: en-GB,en;q=0.6' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -b '_session=uLw3XpxYvr0UVzqrPSTx9RHisSrWSxW8q4ihlfAv6YP; _session.sig=z1zdrpsUwqytrumzlgkewdIfddY' \
  -H 'origin: https://my.demo.cloudron.io' \
  -H 'pragma: no-cache' \
  -H 'priority: u=1, i' \
  -H 'referer: https://my.demo.cloudron.io/' \
  -H 'sec-ch-ua: "Chromium";v="142", "Brave";v="142", "Not_A Brand";v="99"' \
  -H 'sec-ch-ua-mobile: ?0' \
  -H 'sec-ch-ua-platform: "Windows"' \
  -H 'sec-fetch-dest: empty' \
  -H 'sec-fetch-mode: cors' \
  -H 'sec-fetch-site: same-origin' \
  -H 'sec-gpc: 1' \
  -H 'user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36' \
  --data-raw '{"name":"topic-14553","ownerId":"uid-05a84d23-6eb0-4905-b90d-b912056534b0","ownerType":"user","active":true,"enablePop3":false,"storageQuota":0,"messagesQuota":0}'

[jkammerer]

Thanks, @james We have already updated our API call. Our point was more that changes like this — especially breaking changes — should ideally be documented. We weren’t able to find any documentation mentioning this change.

Additionally, in this specific case, it’s not clear to us why the field suddenly needs to be mandatory. From our perspective, it seems rather obsolete.

[james]

Hello @jkammerer
I understand that backward compatibility is desired.
In this specific case it was actually a bug in the previous version that the field could have been left empty in the API call and it worked.
People still use pop3 and we have to accommodate for this.