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

# Mailboxes API — Provision and Manage Email Accounts

> Provision email accounts with POST /api/principal. Update passwords or aliases with PATCH. Remove accounts with DELETE. No per-user fees.

Mailboxes are email accounts that can send and receive messages. In UGMail, a mailbox is an `individual` principal identified by its full email address. You can provision as many mailboxes as you need — there are no per-user fees. Each mailbox can have a password for IMAP/SMTP access and one or more email addresses (aliases) that deliver into the same inbox.

***

## Create a Mailbox

<br />

`POST /api/principal`

Create a new mailbox for a user on any domain in your account. The domain must already be registered before you can provision mailboxes under it.

### Request Parameters

<ParamField body="name" type="string" required>
  The full email address for the mailbox (e.g., `alice@example.com`). This is the unique identifier for the principal and cannot be changed after creation.
</ParamField>

<ParamField body="type" type="string" required>
  Must be `"individual"` to create a mailbox.
</ParamField>

<ParamField body="secrets" type="array of strings" required>
  One or more passwords for IMAP/SMTP authentication. Pass the password as a string inside an array (e.g., `["SecurePassword123!"]`).
</ParamField>

<ParamField body="emails" type="array of strings" required>
  The list of email addresses that deliver to this mailbox. Always include the primary address (`name`) in this array. Additional entries become aliases.
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL 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"]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://mail.ugmail.co/api/principal",
      headers={
          "Authorization": "Bearer YOUR_TOKEN",
          "Content-Type": "application/json",
      },
      json={
          "name": "alice@example.com",
          "type": "individual",
          "secrets": ["SecurePassword123!"],
          "emails": ["alice@example.com"],
      },
  )

  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://mail.ugmail.co/api/principal", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "alice@example.com",
      type: "individual",
      secrets: ["SecurePassword123!"],
      emails: ["alice@example.com"],
    }),
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "id": "alice@example.com",
  "name": "alice@example.com",
  "type": "individual",
  "emails": ["alice@example.com"]
}
```

### Response Fields

<ResponseField name="id" type="string">
  The unique identifier for the mailbox principal. Identical to `name`.
</ResponseField>

<ResponseField name="name" type="string">
  The primary email address of the mailbox.
</ResponseField>

<ResponseField name="type" type="string">
  Always `"individual"` for mailbox principals.
</ResponseField>

<ResponseField name="emails" type="array of strings">
  All email addresses that deliver to this mailbox, including the primary address and any aliases.
</ResponseField>

***

## List All Mailboxes

<br />

`GET /api/principal`

Retrieve a list of all mailbox principals in your account. Use the `type=individual` query parameter to return only mailboxes and exclude domains and groups.

### Query Parameters

<ParamField query="type" type="string">
  Filter results by principal type. Pass `type=individual` to return only mailbox principals.
</ParamField>

### Example Request

```bash theme={null}
curl "https://mail.ugmail.co/api/principal?type=individual" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Example Response

```json theme={null}
[
  {
    "id": "alice@example.com",
    "name": "alice@example.com",
    "type": "individual",
    "emails": ["alice@example.com"]
  },
  {
    "id": "bob@example.com",
    "name": "bob@example.com",
    "type": "individual",
    "emails": ["bob@example.com", "robert@example.com"]
  }
]
```

***

## Get a Mailbox

<br />

`GET /api/principal/{name}`

Retrieve the details of a specific mailbox by its primary email address.

### Path Parameters

<ParamField path="name" type="string" required>
  The primary email address of the mailbox to retrieve (e.g., `alice@example.com`).
</ParamField>

### Example Request

```bash theme={null}
curl "https://mail.ugmail.co/api/principal/alice@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Example Response

```json theme={null}
{
  "id": "alice@example.com",
  "name": "alice@example.com",
  "type": "individual",
  "emails": ["alice@example.com"]
}
```

***

## Update a Mailbox

<br />

`PATCH /api/principal/{name}`

Update an existing mailbox. Use this endpoint to change the password, add or remove aliases, or update other mailbox properties.

### Path Parameters

<ParamField path="name" type="string" required>
  The primary email address of the mailbox to update (e.g., `alice@example.com`).
</ParamField>

### Request Parameters

<ParamField body="secrets" type="array of strings">
  Replace the mailbox password(s). Provide the new password(s) as an array of strings.
</ParamField>

<ParamField body="emails" type="array of strings">
  Replace the full list of email addresses for this mailbox. To add an alias, include the current addresses plus the new one. To remove an alias, omit it from the array. Always include the primary address.
</ParamField>

### Example — Change Password

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

### Example — Add an Alias

```bash theme={null}
curl -X PATCH "https://mail.ugmail.co/api/principal/alice@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "alice@example.com",
      "a.smith@example.com"
    ]
  }'
```

***

## Delete a Mailbox

<br />

`DELETE /api/principal/{name}`

Permanently remove a mailbox from your account. All email stored in the mailbox is deleted.

### Path Parameters

<ParamField path="name" type="string" required>
  The primary email address of the mailbox to delete (e.g., `alice@example.com`).
</ParamField>

### Example Request

```bash theme={null}
curl -X DELETE "https://mail.ugmail.co/api/principal/alice@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Example Response

```json theme={null}
{
  "success": true
}
```

***

## Connecting to a Mailbox

Once you provision a mailbox, your users can connect to it using any standard IMAP/SMTP email client. Use the following settings:

| Setting       | Value                                                      |
| ------------- | ---------------------------------------------------------- |
| **IMAP Host** | `mail.ugmail.co`                                           |
| **IMAP Port** | `993` (SSL/TLS)                                            |
| **SMTP Host** | `mail.ugmail.co`                                           |
| **SMTP Port** | `587` (STARTTLS)                                           |
| **Username**  | Full email address (e.g., `alice@example.com`)             |
| **Password**  | The value passed in `secrets` when the mailbox was created |

<Note>
  Your domain's DNS records must be fully propagated before SMTP delivery will work. Retrieve the required records from [GET /api/dns/{domain}](/api-reference/dns) and add them at your registrar.
</Note>