/folders

GET

List all available mail folders in the QMail system.

GET /api/mail/folders

Description

This endpoint retrieves a list of all available folders in the QMail system. Each folder has an internal name (used in API calls) and a display name (shown to users). Common folders include Inbox, Sent, Drafts, and Trash.

Folder Structure

The QMail system organizes messages into folders similar to traditional email clients. This endpoint helps you discover the available folders and their properties.

Interactive API Tester

Try it out

http://localhost:8080/api/mail/folders

Request

This endpoint does not require any parameters.

Response

Upon success, the endpoint returns a 200 OK response with an array of folder objects.

Response Properties

folders array of objects
An array containing all available folders.

Folder Object Properties

name string
The internal name of the folder (e.g., "inbox", "sent", "drafts", "trash").
display_name string
The user-friendly display name of the folder (e.g., "Inbox", "Sent", "Drafts", "Trash").

Example Response

{
  "folders": [
    {
      "name": "inbox",
      "display_name": "Inbox"
    },
    {
      "name": "sent",
      "display_name": "Sent"
    },
    {
      "name": "drafts",
      "display_name": "Drafts"
    },
    {
      "name": "trash",
      "display_name": "Trash"
    }
  ]
}

Examples

JavaScript Example

const apiHost = 'http://localhost:8080';

async function getFolders() {
    try {
        const response = await fetch(`${apiHost}/api/mail/folders`);
        const data = await response.json();

        console.log('Available folders:');
        data.folders.forEach(folder => {
            console.log(`  ${folder.display_name} (${folder.name})`);
        });
    } catch (error) {
        console.error('Error fetching folders:', error);
    }
}

getFolders();

cURL Example

curl -X GET "http://localhost:8080/api/mail/folders"

Go Example

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

const apiHost = "http://localhost:8080"

type Folder struct {
    Name        string `json:"name"`
    DisplayName string `json:"display_name"`
}

type FoldersResponse struct {
    Folders []Folder `json:"folders"`
}

func main() {
    // Make GET request
    resp, err := http.Get(fmt.Sprintf("%s/api/mail/folders", apiHost))
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    // Read response
    body, _ := ioutil.ReadAll(resp.Body)

    var result FoldersResponse
    json.Unmarshal(body, &result)

    fmt.Println("Available folders:")
    for _, folder := range result.Folders {
        fmt.Printf("  %s (%s)\n", folder.DisplayName, folder.Name)
    }
}