> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mail.ugmail.co/llms.txt
> Use this file to discover all available pages before exploring further.

# UGMail Mailboxes: Provision Unlimited Email Accounts

> Mailboxes in UGMail are individual email accounts you provision via the API. Create unlimited mailboxes for users, agents, or automated workflows.

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:

| Field     | Type   | Description                                              |
| --------- | ------ | -------------------------------------------------------- |
| `name`    | string | The primary email address for this mailbox               |
| `type`    | string | Must be `"individual"`                                   |
| `secrets` | array  | One or more passwords for authenticating to this mailbox |
| `emails`  | array  | Email addresses that deliver to this mailbox             |

```bash theme={null}
curl -X POST "https://mail.ugmail.co/api/principal" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "alice@example.com",
    "type": "individual",
    "secrets": ["SecurePassword123!"],
    "emails": ["alice@example.com"]
  }'
```

A successful response returns the principal object for the new mailbox, including its system-assigned ID.

<Note>
  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](/concepts/domains) to create one first.
</Note>

## 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

| Protocol | Server           | Port | Security |
| -------- | ---------------- | ---- | -------- |
| SMTP     | `mail.ugmail.co` | 587  | STARTTLS |
| IMAP     | `mail.ugmail.co` | 993  | SSL/TLS  |
| POP3     | `mail.ugmail.co` | 995  | SSL/TLS  |
| JMAP     | `mail.ugmail.co` | 443  | HTTPS    |

<CodeGroup>
  ```text IMAP (e.g., Thunderbird / Apple Mail) theme={null}
  Incoming server:  mail.ugmail.co
  Port:             993
  Security:         SSL/TLS
  Username:         alice@example.com
  Password:         <value from secrets array>
  ```

  ```text SMTP (outbound sending) theme={null}
  Outgoing server:  mail.ugmail.co
  Port:             587
  Security:         STARTTLS
  Username:         alice@example.com
  Password:         <value from secrets array>
  ```

  ```text POP3 (download-and-delete) theme={null}
  Incoming server:  mail.ugmail.co
  Port:             995
  Security:         SSL/TLS
  Username:         alice@example.com
  Password:         <value from secrets array>
  ```
</CodeGroup>

### 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:

<CardGroup cols={2}>
  <Card title="SaaS products" icon="rocket">
    Provision a dedicated mailbox for every user of your application without worrying about growing per-seat costs.
  </Card>

  <Card title="AI agents" icon="robot">
    Give each agent its own inbox so it can send and receive email as part of automated workflows.
  </Card>

  <Card title="Transactional addresses" icon="envelope">
    Create addresses like `noreply@`, `invoices@`, or `alerts@` for specific notification types.
  </Card>

  <Card title="Team inboxes" icon="users">
    Stand up shared role addresses (`support@`, `sales@`) that multiple team members can access.
  </Card>
</CardGroup>

## 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.

<Warning>
  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.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Aliases & Forwarders" icon="shuffle" href="/concepts/aliases-forwarders">
    Route multiple addresses to one mailbox, or redirect mail to an external destination.
  </Card>

  <Card title="DKIM Signing" icon="shield-check" href="/concepts/dkim-signing">
    Authenticate your outbound mail to improve deliverability.
  </Card>
</CardGroup>