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

# Provision a Mailbox Programmatically via UGMail API

> Create a new email account on any of your domains using the UGMail Management API. Provision one mailbox or thousands in a single script.

UGMail lets you create fully functional email accounts with a single API call. There are no per-user fees and no hard limits on the number of mailboxes you can create, so whether you're provisioning one account for a new hire or thousands of accounts during a bulk onboarding, the process is identical. This guide walks you through creating a mailbox, verifying it exists, and testing that it accepts connections over SMTP and IMAP.

## Prerequisites

* Your domain is already [set up and DNS-verified](/guides/setup-domain) in UGMail
* A valid Bearer token from **Settings → API Connection** at [my.ugmail.co](https://my.ugmail.co)

<Steps>
  <Step title="Ensure your domain is set up">
    The mailbox address you create must belong to a domain that is already registered in your UGMail account and has its DNS records configured. If you haven't done that yet, follow the [Set Up Your First Domain](/guides/setup-domain) guide before continuing.
  </Step>

  <Step title="Create the mailbox">
    Send a `POST` request to `/api/principal` with the `individual` type, a name matching the full email address, the initial password in the `secrets` array, and the email address in the `emails` array.

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

    A `201 Created` response confirms the mailbox is live and ready to use immediately.
  </Step>

  <Step title="Verify the mailbox was created">
    You can confirm the mailbox exists by fetching the principal record you just created. If the request returns the account details without error, the mailbox is active.

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

  <Step title="Test login via SMTP or IMAP">
    Use the credentials you set during creation to verify the mailbox accepts authenticated connections. The connection details are the same for every mailbox on your account:

    | Protocol         | Host             | Port  | Security |
    | ---------------- | ---------------- | ----- | -------- |
    | SMTP (sending)   | `mail.ugmail.co` | `587` | STARTTLS |
    | IMAP (receiving) | `mail.ugmail.co` | `993` | SSL/TLS  |

    You can test SMTP login quickly with `curl`:

    ```bash theme={null}
    curl -v --url "smtp://mail.ugmail.co:587" \
      --ssl-reqd \
      --mail-from "alice@example.com" \
      --mail-rcpt "test@example.com" \
      --user "alice@example.com:SecurePassword123!"
    ```

    A successful SMTP `AUTH` exchange confirms the mailbox is working end-to-end.
  </Step>
</Steps>

<Tip>
  Never hardcode passwords in your provisioning scripts. Instead, generate cryptographically secure random passwords at runtime — for example, using Python's `secrets.token_urlsafe(16)` or Node's `crypto.randomBytes(16).toString('hex')` — and store them in your secrets manager before passing them to the API.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Manage Aliases" icon="at" href="/guides/manage-aliases">
    Add additional addresses like support@ or billing@ to this mailbox.
  </Card>

  <Card title="Connect an AI Agent" icon="robot" href="/guides/ai-agent-smtp">
    Give an AI agent its own dedicated mailbox and hook it up over SMTP.
  </Card>
</CardGroup>