Mailboxes, also known as Folders or Labels, are used to categorize et organize Emails.

About Gmail labels

Gmail handles email storage differently from traditional IMAP providers. Instead of storing messages in multiple distinct folders, Gmail keeps all emails in a single folder and adds its own label system on top of it.

Because labels are a layer added by Gmail (not part of the original IMAP folder model), they can behave differently — most notably, a single email can have multiple labels. This is not possible in the legacy IMAP folder model, where an email can only exist in one folder at a time unless it is duplicated.

In Unipile, labels from Gmail are exposed as folders for consistency with other providers. As a result, you might encounter specific behaviors, such as the same email appearing in multiple “folders.” We’ll explain these differences in more detail throughout this guide.

Learn more about labels in Gmail Developers Documentation.

About Roles

Many email providers have special-use folders such as Inbox, Archive, Trash, and Sent. These are managed directly by the provider. In Unipile, we refer to these as roles.
The available roles correspond to the Special-Use attributes defined in RFC 6154, though the names may differ slightly (for example, \Trash becomes TRASH).

Gmail, however, does not use traditional folders or the Special-Use attribute. Instead, Unipile marks certain labels with is_system = true and infers a role based on the label’s name so that it aligns with the list of special uses for consistency across providers.

Because Gmail offers more features than most traditional providers, it also has system labels for specific usage scenarios that go beyond the RFC list. In these cases, is_system is still set to true, but no role is assigned if the label does not match any RFC special use.

OAuth permissions scope

To manage labels on Google accounts, you must use the gmail.labels (non-sensitive) or gmail.modify(restrictive) scope.

To manage folders on Microsoft Outlook accounts, you must use the Mail.ReadWrite scope.

For more informations about permissions, read Permissions Required.

Get folders and labels

To get the list of folders or Gmail labels, use List all Folders method.

const { data } = await emailsApi.getFoldersList({
  path: {
    account_id: "acc_123456789",
  },
  query: {
    limit: 20,
  },
});

folders = emails_api.get_folders_list(
    "acc_123456789",
    limit=20,
)

curl --request GET \
     --url https://api.unipile.com/v2/account_id/folders \
     --header 'accept: application/json'

Create a folder or label

To create a new folder or a new Gmail label, use Create a Folder method and provide a name. You can create an Outlook sub-folder by passing the ID of the parent folder.

const { data } = await emailsApi.createFolder({
  path: {
    account_id: "acc_123456789",
  },
  body: {
    name: 'My Folder',
  },
});

folder = emails_api.create_folder(
    "acc_123456789",
    {"name": "My Folder"},
)

curl --request POST \
     --url https://api.unipile.com/v2/account_id/folders \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"name":"My Folder"}'

Edit a folder or label

To edit an existing folder or Gmail label, use Update a Folder method and provide the new name, color, etc...

const { data } = await emailsApi.updateFolder({
  path: {
    account_id: "acc_123456789",
    folder_id: "folder_id",
  },
  body: {
    name: 'New name',
  },
});

folder = emails_api.update_folder(
    "acc_123456789",
    "folder_id",
    {"name": "New name"},
)

curl --request PATCH \
     --url https://api.unipile.com/v2/account_id/folders/folder_id \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"name":"New name"}'

Delete a folder or label

To delete a folder or a Gmail label, use Delete a Folder method.

❗️

Important side effects

• On Gmail, deleting a label will remove that label from all emails it is applied to, but the emails themselves will remain.
• On other providers, deleting a folder will also permanently delete all emails contained in it.

await emailsApi.deleteFolder({
  path: {
    account_id: "acc_123456789",
    folder_id: "folder_id",
  },
});

emails_api.delete_folder("acc_123456789", "folder_id")

curl --request DELETE \
     --url https://api.unipile.com/v2/account_id/folders/folder_id