diff --git a/.gitignore b/.gitignore
index 2b1c1bbe..050fed56 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,4 @@ config/development.*
 certs/test-*
 zmta-milter
 zmta-milter.toml
+api-tests-overview.md
diff --git a/test/api/mailboxes-test.js b/test/api/mailboxes-test.js
new file mode 100644
index 00000000..08cdf642
--- /dev/null
+++ b/test/api/mailboxes-test.js
@@ -0,0 +1,457 @@
+/*eslint no-unused-expressions: 0, prefer-arrow-callback: 0, no-console:0 */
+
+/* globals before: false, after: false */
+
+'use strict';
+
+const supertest = require('supertest');
+const chai = require('chai');
+
+const expect = chai.expect;
+chai.config.includeStack = true;
+const config = require('wild-config');
+
+const server = supertest.agent(`http://127.0.0.1:${config.api.port}`);
+
+describe('Mailboxes tests', function () {
+    this.timeout(10000); // eslint-disable-line no-invalid-this
+
+    let user;
+
+    before(async () => {
+        // ensure that we have an existing user account
+        const response = await server
+            .post('/users')
+            .send({
+                username: 'mailboxesuser',
+                password: 'secretvalue',
+                address: 'mailboxesuser.addrtest@example.com',
+                name: 'mailboxes user'
+            })
+            .expect(200);
+        expect(response.body.success).to.be.true;
+        expect(response.body.id).to.exist;
+
+        user = response.body.id;
+    });
+
+    after(async () => {
+        if (!user) {
+            return;
+        }
+
+        const response = await server.delete(`/users/${user}`).expect(200);
+        expect(response.body.success).to.be.true;
+
+        user = false;
+    });
+
+    it('should POST /users/{user}/mailboxes expect success / all data', async () => {
+        const response = await server.post(`/users/${user}/mailboxes`).send({ path: '/coolpath/abcda', hidden: false, retention: 0 }).expect(200);
+
+        expect(response.body.success).to.be.true;
+        expect(response.body.id).to.not.be.empty;
+    });
+
+    it('should POST /users/{user}/mailboxes expect success / hidden and retention fields missing', async () => {
+        const response = await server.post(`/users/${user}/mailboxes`).send({ path: '/coolpath/abcdad' }).expect(200);
+
+        expect(response.body.success).to.be.true;
+        expect(response.body.id).to.not.be.empty;
+    });
+
+    it('should POST /users/{user}/mailboxes expect success / longer path with number', async () => {
+        const response = await server
+            .post(`/users/${user}/mailboxes`)
+            .send({ path: '/cool2/path2/whatisthis346/cool-drink', hidden: false, retention: 0 })
+            .expect(200);
+
+        expect(response.body.success).to.be.true;
+        expect(response.body.id).to.not.be.empty;
+    });
+
+    it('should POST /users/{user}/mailboxes expect failure / retention negative', async () => {
+        const response = await server
+            .post(`/users/${user}/mailboxes`)
+            .send({ path: '/cool2/path2/whatisthis346/cool-drink', hidden: false, retention: -1 })
+            .expect(400);
+
+        expect(response.body.code).to.be.equal('InputValidationError');
+        expect(response.body.error).to.not.be.empty;
+    });
+
+    it('should POST /users/{user}/mailboxes expect failure / retention is string', async () => {
+        const response = await server
+            .post(`/users/${user}/mailboxes`)
+            .send({ path: '/cool2/path2/whatisthis346/cool-drink', hidden: false, retention: 'aaa' })
+            .expect(400);
+
+        expect(response.body.code).to.be.equal('InputValidationError');
+        expect(response.body.error).to.not.be.empty;
+    });
+
+    it('should POST /users/{user}/mailboxes expect failure / path contains double slash', async () => {
+        const response = await server
+            .post(`/users/${user}/mailboxes`)
+            .send({ path: '/cool2//path2/whatisthis346///cool-drink', hidden: false, retention: 0 })
+            .expect(400);
+
+        expect(response.body.code).to.be.equal('InputValidationError');
+        expect(response.body.error).to.not.be.empty;
+    });
+
+    it('should POST /users/{user}/mailboxes expect failure / user format incorrect', async () => {
+        const response = await server
+            .post(`/users/${123}/mailboxes`)
+            .send({ path: '/cool2/path2/whatisthis346/cool-drink', hidden: false, retention: 0 })
+            .expect(400);
+
+        expect(response.body.code).to.be.equal('InputValidationError');
+        expect(response.body.error).to.not.be.empty;
+    });
+
+    it('should POST /users/{user}/mailboxes expect failure / user format not hex', async () => {
+        const response = await server
+            .post(`/users/${'-'.repeat(24)}/mailboxes`)
+            .send({ path: '/cool2/path2/whatisthis346/cool-drink', hidden: false, retention: 0 })
+            .expect(400);
+
+        expect(response.body.code).to.be.equal('InputValidationError');
+        expect(response.body.error).to.not.be.empty;
+    });
+
+    // TODO: rewrite when mailboxes.js gets updated status codes
+    it('should POST /users/{user}/mailboxes expect failure / user not found', async () => {
+        const response = await server
+            .post(`/users/${'0'.repeat(24)}/mailboxes`)
+            .send({ path: '/cool2/path2/whatisthis346/cool-drink', hidden: false, retention: 0 })
+            .expect(500);
+
+        expect(response.body.error).to.be.equal('User not found');
+    });
+
+    it('should POST /users/{user}/mailboxes expect failure / path is missing', async () => {
+        const response = await server.post(`/users/${user}/mailboxes`).send({ path: undefined, hidden: false, retention: 'aaa' }).expect(400);
+
+        expect(response.body.code).to.be.equal('InputValidationError');
+        expect(response.body.error).to.not.be.empty;
+    });
+
+    it('should GET /users/{user}/mailboxes expect success', async () => {
+        const response = await server.get(`/users/${user}/mailboxes`).expect(200);
+
+        expect(response.body.success).to.be.true;
+        expect(response.body.results).to.not.be.empty;
+        expect(response.body.results.length).to.be.equal(8);
+    });
+
+    it('should GET /users/{user}/mailboxes expect success / all params', async () => {
+        const response = await server.get(`/users/${user}/mailboxes?specialUse=true&showHidden=true&counters=true&sizes=true`).expect(200);
+
+        expect(response.body.success).to.be.true;
+        expect(response.body.results).to.not.be.empty;
+        expect(response.body.results.length).to.be.equal(5);
+    });
+
+    it('should GET /users/{user}/mailboxes expect success / some params', async () => {
+        const response = await server.get(`/users/${user}/mailboxes?specialUse=false&counters=true&sizes=true`).expect(200);
+
+        expect(response.body.success).to.be.true;
+        expect(response.body.results).to.not.be.empty;
+        expect(response.body.results.length).to.be.equal(8);
+    });
+
+    it('should GET /users/{user}/mailboxes expect failure / params incorrect type', async () => {
+        const response = await server.get(`/users/${user}/mailboxes?specialUse=what&showHidden=111&counters=-2&sizes=sizes`).expect(400);
+
+        expect(response.body.code).to.be.equal('InputValidationError');
+        expect(response.body.error).to.not.be.empty;
+    });
+
+    it('should GET /users/{user}/mailboxes expect failure / user wrong format', async () => {
+        const response = await server.get(`/users/${123}/mailboxes?specialUse=true&showHidden=true&counters=true&sizes=true`).expect(400);
+
+        expect(response.body.code).to.be.equal('InputValidationError');
+        expect(response.body.error).to.not.be.empty;
+    });
+
+    it('should GET /users/{user}/mailboxes expect failure / user not found', async () => {
+        const response = await server.get(`/users/${'0'.repeat(24)}/mailboxes?specialUse=false&counters=true&sizes=true`).expect(404);
+
+        expect(response.body.error).to.be.equal('This user does not exist');
+        expect(response.body.code).to.be.equal('UserNotFound');
+    });
+
+    it('should GET /users/{user}/mailboxes/{mailbox} expect success', async () => {
+        const mailboxes = await server.get(`/users/${user}/mailboxes`).expect(200);
+
+        const response = await server.get(`/users/${user}/mailboxes/${mailboxes.body.results[0].id}`).expect(200);
+
+        expect(response.body.success).to.be.true;
+        expect(response.body.id).to.not.be.empty;
+        expect(response.body.name).to.be.equal('INBOX');
+    });
+
+    it('should GET /users/{user}/mailboxes/{mailbox} expect success / path specified', async () => {
+        // const mailboxes = await server.get(`/users/${user}/mailboxes`).expect(200);
+
+        const response = await server.get(`/users/${user}/mailboxes/${'resolve'}?path=coolpath/abcda`).expect(200);
+
+        expect(response.body.success).to.be.true;
+        expect(response.body.id).to.not.be.empty;
+        expect(response.body.name).to.be.equal('abcda');
+        expect(response.body.path).to.be.equal('coolpath/abcda');
+    });
+
+    it('should GET /users/{user}/mailboxes/{mailbox} expect success / path inbox specified', async () => {
+        const response = await server.get(`/users/${user}/mailboxes/resolve?path=INBOX`).expect(200);
+
+        expect(response.body.success).to.be.true;
+        expect(response.body.id).to.not.be.empty;
+        expect(response.body.name).to.be.equal('INBOX');
+        expect(response.body.path).to.be.equal('INBOX');
+    });
+
+    it('should GET /users/{user}/mailboxes/{mailbox} expect failure / incorrect params', async () => {
+        const response = await server.get(`/users/${user}/mailboxes/resolve?path=//INBOX`).expect(400);
+
+        expect(response.body.code).to.be.equal('InputValidationError');
+        expect(response.body.error).to.be.not.empty;
+
+        const response2 = await server.get(`/users/${user}/mailboxes/resolve?path=`).expect(400);
+
+        expect(response2.body.code).to.be.equal('InputValidationError');
+        expect(response2.body.error).to.be.not.empty;
+
+        const response3 = await server.get(`/users/${user}/mailboxes/${123}`).expect(400);
+
+        expect(response3.body.code).to.be.equal('InputValidationError');
+        expect(response3.body.error).to.be.not.empty;
+
+        const response4 = await server
+            .get(`/users/${user}/mailboxes/${'-'.repeat(24)}`)
+
+            .expect(400);
+
+        expect(response4.body.code).to.be.equal('InputValidationError');
+        expect(response4.body.error).to.be.not.empty;
+    });
+
+    it('should GET /users/{user}/mailboxes/{mailbox} expect failure / mailbox not found', async () => {
+        const response = await server
+            .get(`/users/${user}/mailboxes/${'0'.repeat(24)}`)
+
+            .expect(404);
+
+        expect(response.body.code).to.be.equal('NoSuchMailbox');
+        expect(response.body.error).to.be.equal('This mailbox does not exist');
+    });
+
+    it('should GET /users/{user}/mailboxes/{mailbox} expect failure / user not found', async () => {
+        const response = await server
+            .get(`/users/${'0'.repeat(24)}/mailboxes`)
+
+            .expect(404);
+
+        expect(response.body.error).to.be.equal('This user does not exist');
+        expect(response.body.code).to.be.equal('UserNotFound');
+    });
+
+    it('should PUT /users/{user}/mailboxes/{mailbox} expect success', async () => {
+        const mailboxes = await server.get(`/users/${user}/mailboxes`).expect(200);
+
+        const response = await server.put(`/users/${user}/mailboxes/${mailboxes.body.results[0].id}`).send({ retention: 10 }).expect(200);
+
+        expect(response.body.success).to.be.true;
+    });
+
+    it('should PUT /users/{user}/mailboxes/{mailbox} expect success / path specified', async () => {
+        const mailboxes = await server.get(`/users/${user}/mailboxes`).expect(200);
+
+        const response = await server.put(`/users/${user}/mailboxes/${mailboxes.body.results[1].id}`).send({ path: 'newPath/folder1' });
+
+        expect(response.body.success).to.be.true;
+    });
+
+    it('should PUT /users/{user}/mailboxes/{mailbox} expect success / all params specified', async () => {
+        const mailboxes = await server.get(`/users/${user}/mailboxes`).expect(200);
+
+        const response = await server
+            .put(`/users/${user}/mailboxes/${mailboxes.body.results.at(-1).id}`)
+            .send({ path: 'newPath/folder2', retention: 100, subscribed: true, hidden: true })
+            .expect(200);
+
+        expect(response.body.success).to.be.true;
+    });
+
+    it('should PUT /users/{user}/mailboxes/{mailbox} expect failure / incorrect params', async () => {
+        const mailboxes = await server.get(`/users/${user}/mailboxes`).expect(200);
+
+        const response = await server.put(`/users/${user}/mailboxes/${mailboxes.body.results[0].id}`).send({ path: '//newpath/path2' }).expect(400);
+
+        expect(response.body.code).to.be.equal('InputValidationError');
+        expect(response.body.error).to.be.not.empty;
+
+        const response2 = await server.put(`/users/${user}/mailboxes/${mailboxes.body.results[0].id}`).send({ path: 123123 }).expect(400);
+
+        expect(response2.body.code).to.be.equal('InputValidationError');
+        expect(response2.body.error).to.be.not.empty;
+
+        const response3 = await server.put(`/users/${user}/mailboxes/${123}`).expect(400);
+
+        expect(response3.body.code).to.be.equal('InputValidationError');
+        expect(response3.body.error).to.be.not.empty;
+
+        const response4 = await server
+            .put(`/users/${user}/mailboxes/${'-'.repeat(24)}`)
+
+            .expect(400);
+
+        expect(response4.body.code).to.be.equal('InputValidationError');
+        expect(response4.body.error).to.be.not.empty;
+
+        const response5 = await server.put(`/users/${user}/mailboxes/${mailboxes.body.results[0].id}`).send({ retention: 'notanumber' }).expect(400);
+
+        expect(response5.body.code).to.be.equal('InputValidationError');
+        expect(response5.body.error).to.be.not.empty;
+
+        const response6 = await server.put(`/users/${user}/mailboxes/${mailboxes.body.results[0].id}`).send({ hidden: 'notabool' }).expect(400);
+
+        expect(response6.body.code).to.be.equal('InputValidationError');
+        expect(response6.body.error).to.be.not.empty;
+
+        const response7 = await server.put(`/users/${user}/mailboxes/${mailboxes.body.results[0].id}`).send({ subscribed: 12345 }).expect(400);
+
+        expect(response7.body.code).to.be.equal('InputValidationError');
+        expect(response7.body.error).to.be.not.empty;
+
+        const response8 = await server.put(`/users/${123}/mailboxes/${mailboxes.body.results[0].id}`).expect(400);
+
+        expect(response8.body.code).to.be.equal('InputValidationError');
+        expect(response8.body.error).to.be.not.empty;
+    });
+
+    it('should PUT /users/{user}/mailboxes/{mailbox} expect failure / mailbox not found', async () => {
+        const response = await server
+            .put(`/users/${user}/mailboxes/${'0'.repeat(24)}`)
+            .send({ path: 'newPath' })
+            .expect(500);
+
+        expect(response.body.error).to.be.equal('Mailbox update failed with code NONEXISTENT');
+    });
+
+    it('should PUT /users/{user}/mailboxes/{mailbox} expect failure / user not found', async () => {
+        const mailboxes = await server.get(`/users/${user}/mailboxes`).expect(200);
+
+        const response = await server
+            .put(`/users/${'0'.repeat(24)}/mailboxes/${mailboxes.body.results.at(-1).id}`)
+            .send({ path: 'newPath' })
+            .expect(500);
+
+        expect(response.body.error).to.be.equal('Mailbox update failed with code NONEXISTENT');
+    });
+
+    it('should PUT /users/{user}/mailboxes/{mailbox} expect failure / nothing was changed', async () => {
+        const mailboxes = await server.get(`/users/${user}/mailboxes`).expect(200);
+
+        const response = await server
+            .put(`/users/${user}/mailboxes/${mailboxes.body.results.at(-1).id}`)
+
+            .expect(400);
+
+        expect(response.body.error).to.be.equal('Nothing was changed');
+    });
+
+    it('should PUT /users/{user}/mailboxes/{mailbox} expect failure / cannot update protected path', async () => {
+        const mailboxes = await server.get(`/users/${user}/mailboxes`).expect(200);
+
+        const inboxMailbox = mailboxes.body.results.find(el => el.path === 'INBOX');
+
+        const response = await server.put(`/users/${user}/mailboxes/${inboxMailbox.id}`).send({ path: 'newPath/folder123' }).expect(500);
+
+        expect(response.body.error).to.be.equal('Mailbox update failed with code CANNOT');
+    });
+
+    it('should DELETE /users/{user}/mailboxes/{mailbox} expect success', async () => {
+        const mailboxes = await server.get(`/users/${user}/mailboxes`).expect(200);
+
+        const validMailbox = mailboxes.body.results.find(el => !el.specialUse && el.path !== 'INBOX');
+
+        const response = await server.del(`/users/${user}/mailboxes/${validMailbox.id}`).expect(200);
+
+        expect(response.body.success).to.be.true;
+    });
+
+    it('should DELETE /users/{user}/mailboxes/{mailbox} expect failure / protected path', async () => {
+        const mailboxes = await server.get(`/users/${user}/mailboxes`).expect(200);
+
+        const response = await server.del(`/users/${user}/mailboxes/${mailboxes.body.results[0].id}`).expect(500);
+
+        expect(response.body.error).to.be.equal('Mailbox deletion failed with code CANNOT');
+        expect(response.body.code).to.be.equal('CANNOT');
+    });
+
+    it('should DELETE /users/{user}/mailboxes/{mailbox} expect failure / incorrect params', async () => {
+        const mailboxes = await server.get(`/users/${user}/mailboxes`).expect(200);
+
+        const response1 = await server.del(`/users/${user}/mailboxes/${123}`).expect(400);
+
+        expect(response1.body.code).to.be.equal('InputValidationError');
+        expect(response1.body.error).to.be.not.empty;
+
+        const response2 = await server
+            .del(`/users/${user}/mailboxes/${'-'.repeat(24)}`)
+
+            .expect(400);
+
+        expect(response2.body.code).to.be.equal('InputValidationError');
+        expect(response2.body.error).to.be.not.empty;
+
+        const response3 = await server.del(`/users/${123}/mailboxes/${mailboxes.body.results[0].id}`).expect(400);
+
+        expect(response3.body.code).to.be.equal('InputValidationError');
+        expect(response3.body.error).to.be.not.empty;
+
+        const response4 = await server
+            .del(`/users/${'-'.repeat(24)}/mailboxes/${mailboxes.body.results[0].id}`)
+
+            .expect(400);
+
+        expect(response4.body.code).to.be.equal('InputValidationError');
+        expect(response4.body.error).to.be.not.empty;
+    });
+
+    it('should DELETE /users/{user}/mailboxes/{mailbox} expect failure / mailbox not found', async () => {
+        const response = await server
+            .del(`/users/${user}/mailboxes/${'0'.repeat(24)}`)
+
+            .expect(500);
+
+        console.log(response.body);
+
+        expect(response.body.error).to.be.equal('Mailbox deletion failed with code NONEXISTENT');
+        expect(response.body.code).to.be.equal('NONEXISTENT');
+    });
+
+    it('should DELETE /users/{user}/mailboxes/{mailbox} expect failure / user not found', async () => {
+        const mailboxes = await server.get(`/users/${user}/mailboxes`).expect(200);
+
+        const response = await server
+            .del(`/users/${'0'.repeat(24)}/mailboxes/${mailboxes.body.results[0].id}`)
+
+            .expect(500);
+
+        expect(response.body.error).to.be.equal('Mailbox deletion failed with code NONEXISTENT');
+    });
+
+    it('should DELETE /users/{user}/mailboxes/{mailbox} expect failure / cannot delete inbox', async () => {
+        const mailboxes = await server.get(`/users/${user}/mailboxes`).expect(200);
+
+        const inboxMailbox = mailboxes.body.results.find(el => el.path === 'INBOX');
+
+        const response = await server.del(`/users/${user}/mailboxes/${inboxMailbox.id}`).expect(500);
+
+        expect(response.body.error).to.be.equal('Mailbox deletion failed with code CANNOT');
+        expect(response.body.code).to.be.equal('CANNOT');
+    });
+});