📄️ Overview
Principals are the entities that represent individuals, groups, resources, or other organizational elements within Stalwart Mail Server. They play a key role in managing access, permissions, and interactions with the mail system. Principals in Stalwart Mail Server follow the JMAP Sharing specification (as outlined in the RFC), which provides a standardized way to define and share resources among users. Each principal type represents a different category of entity and serves a distinct function within the system.
📄️ Individual
The Individual principal type in Stalwart Mail Server represents a single person or user account. It is the fundamental unit for user management, as each email user within the system is stored as an individual principal. Individual principals contain all the information necessary to manage and authenticate a user's account, such as login credentials, email addresses, group memberships, and permissions.
📄️ Group
The Group principal type in Stalwart Mail Server represents a collection of individual users and potentially other groups. Groups function similarly to regular accounts in that they can receive emails, but they differ in a few important ways: group accounts cannot log in to the mail server using IMAP, POP3, or JMAP. Instead, groups are designed to organize users and share resources. When an individual is added as a member of a group, they gain access to the group’s inbox, which appears as a shared folder in their email client when using IMAP or JMAP.
📄️ Mailing List
A Mailing List principal in Stalwart Mail Server represents a group of recipients—both individuals and groups—who are subscribed to receive emails sent to a common email address. Mailing lists are commonly used for distributing messages to multiple users at once, simplifying communication with a large group of people. While similar to groups, mailing lists are designed primarily for one-way communication, where messages are sent to all members of the list, rather than shared access to an inbox like group principals.
📄️ Domain
The Domain principal type in Stalwart Mail Server represents a local domain managed by the mail server. Domain principals are crucial for defining the domains that the mail server recognizes as part of its local configuration. If a domain principal is not created for a specific domain, Stalwart will treat that domain as external and will not accept email delivery for it. This makes domain principals essential for proper routing and handling of emails within the server.
📄️ API Key
The API Key principal type is used to grant external applications access to the management REST API or to register OAuth clients using the OAuth Dynamic Client Registration protocol. API keys allow secure, programmatic interaction with the management interface of the mail server, enabling external tools and applications to automate administrative tasks or integrate with the system's management features. However, it’s important to note that API keys cannot be used with JMAP, IMAP, POP3, or other mail server services for authentication or accessing user mailboxes.
📄️ OAuth Client
The OAuth Client principal represents the OAuth clients that are authorized to request access tokens on behalf of users using the OAuth 2.0 protocol. These clients can be used by external applications to gain secure, delegated access to resources by obtaining an OAuth token from the mail server. OAuth clients can either be manually added by an administrator or dynamically registered using the OAuth Dynamic Client Registration protocol.