Skip to main content
A mailbox in UGMail is a fully functional email account tied to a domain you manage. Once provisioned, a mailbox can send and receive messages over standard protocols — SMTP, IMAP, POP3, and JMAP — and can be accessed by a person, an automated agent, or any application that speaks those protocols. Because UGMail charges no per-mailbox fees, you can create as many accounts as your product requires without worrying about per-seat costs.

​
What is a Mailbox?

Each mailbox is an individual principal in the UGMail data model. It has:
  • A unique email address (for example, alice@example.com)
  • A password stored in the secrets array, used for SMTP/IMAP/POP3/JMAP authentication
  • An emails array listing all addresses that deliver to this mailbox (the primary address plus any aliases)
  • Full association with the domain it belongs to
Mailboxes are isolated within your tenant — credentials from one tenant cannot access mailboxes in another.

​
Creating a Mailbox

Create a mailbox by sending a POST request to /api/principal with type set to "individual". You must supply the following fields:
A successful response returns the principal object for the new mailbox, including its system-assigned ID.
The domain referenced in the email address (example.com in this case) must already exist as a domain principal in your tenant before you can create mailboxes under it. See Understanding Domains to create one first.

​
Accessing a Mailbox

Once a mailbox is created, any email client or application can connect to it using standard protocols. Use the credentials you supplied in secrets alongside the email address as the username.

​
Connection Settings

​
JMAP

JMAP is a modern, HTTP-based alternative to IMAP that is well suited for building custom email clients or server-side integrations. Connect to https://mail.ugmail.co on port 443 using standard HTTP Basic or Bearer authentication with your mailbox credentials.

​
Unlimited Mailboxes, No Per-User Fees

UGMail does not impose per-mailbox pricing. Whether you need ten mailboxes or ten thousand, the cost model stays flat. This makes UGMail especially well suited for:

SaaS products

Provision a dedicated mailbox for every user of your application without worrying about growing per-seat costs.

AI agents

Give each agent its own inbox so it can send and receive email as part of automated workflows.

Transactional addresses

Create addresses like noreply@, invoices@, or alerts@ for specific notification types.

Team inboxes

Stand up shared role addresses (support@, sales@) that multiple team members can access.

​
Updating and Deleting Mailboxes

  • Update a mailbox (for example, to rotate its password or add an alias address) by sending a PATCH request to /api/principal/{name} with the fields you want to change.
  • Delete a mailbox by sending a DELETE request to /api/principal/{name}. Deleted mailboxes are permanently removed and their email history is not retained.
Deleting a mailbox is irreversible. Any email stored in that mailbox will be permanently lost. Export or archive messages before deleting if retention is required.

​
Next Steps

Aliases & Forwarders

Route multiple addresses to one mailbox, or redirect mail to an external destination.

DKIM Signing

Authenticate your outbound mail to improve deliverability.
Last modified on July 17, 2026