> ## 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 Management API — Complete Reference Overview

> The UGMail Management API is a REST API for creating domains, provisioning mailboxes, managing aliases and forwarders, and configuring DKIM.

The UGMail Management API gives you programmatic control over every aspect of your email infrastructure. Use it to create and configure custom domains, provision unlimited mailboxes, manage aliases and forwarders, and retrieve the DNS records you need to go live — all through a single, consistent REST interface.

## Base URL

All API requests are made to the following base URL:

```
https://mail.ugmail.co/api/
```

Every request must be made over HTTPS. Plain HTTP is not supported.

## Authentication

All endpoints require a Bearer token passed in the `Authorization` header. Retrieve your token from [my.ugmail.co](https://my.ugmail.co) → **Settings** → **API Connection**.

```bash theme={null}
Authorization: Bearer YOUR_TOKEN
```

See the [Authentication](/api-reference/authentication) page for full details on obtaining and rotating tokens.

## Request & Response Format

The API accepts and returns JSON for all endpoints. Set the `Content-Type: application/json` header on any request that includes a body.

## Principal Types

Most API operations revolve around **principals** — the core resource type in UGMail. A principal can represent a domain, an individual mailbox, or a group address.

| Type         | Description                     | Example name        |
| ------------ | ------------------------------- | ------------------- |
| `domain`     | A custom email domain you own   | `example.com`       |
| `individual` | A mailbox or email account      | `alice@example.com` |
| `group`      | A mailing list or group address | `team@example.com`  |

## Explore the API

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn how to obtain and use Bearer tokens to authenticate every request.
  </Card>

  <Card title="Domains" icon="globe" href="/api-reference/domains">
    Create, list, retrieve, and delete custom email domains.
  </Card>

  <Card title="Mailboxes" icon="envelope" href="/api-reference/mailboxes">
    Provision email accounts, set passwords, and manage account details.
  </Card>

  <Card title="Aliases" icon="at" href="/api-reference/aliases">
    Add multiple email addresses to a single mailbox inbox.
  </Card>

  <Card title="Forwarders" icon="forward" href="/api-reference/forwarders">
    Redirect incoming mail from one address to another automatically.
  </Card>

  <Card title="DNS Records" icon="server" href="/api-reference/dns">
    Fetch the MX, SPF, and DKIM records required to activate your domain.
  </Card>

  <Card title="DKIM" icon="shield-check" href="/api-reference/dkim">
    Enable cryptographic email signing to improve deliverability and trust.
  </Card>
</CardGroup>

## HTTP Status Codes

The API uses standard HTTP status codes to indicate the result of every request.

| Code  | Meaning                                                                    |
| ----- | -------------------------------------------------------------------------- |
| `200` | **Success** — the request completed successfully                           |
| `201` | **Created** — a new resource was successfully created                      |
| `400` | **Bad Request** — check your JSON syntax or required fields                |
| `401` | **Unauthorized** — your token is missing or malformed                      |
| `403` | **Forbidden** — your token is valid but lacks permission for this resource |
| `404` | **Not Found** — the requested resource does not exist                      |
| `409` | **Conflict** — a resource with that name already exists                    |
| `500` | **Server Error** — something went wrong on our end; try again later        |