> ## 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 Quickstart: Add a Domain and Send Your First Email

> Create your UGMail account, get your API token, add your first domain, and provision a mailbox ready to send and receive email — in under a minute.

This guide walks you through the fastest path to a working UGMail mailbox. By the end you'll have a domain registered, a mailbox provisioned, and the connection details you need to start sending and receiving email.

<Steps>
  <Step title="Create your account">
    Go to [my.ugmail.co](https://my.ugmail.co) and sign up for a UGMail account. The sign-up flow takes under a minute — no credit card required to explore the platform.
  </Step>

  <Step title="Retrieve your Bearer token">
    After signing in, navigate to **Settings → API Connection**. Copy the Bearer token shown there. Every Management API request you make must include this token in the `Authorization` header.

    Keep this token private. Treat it like a password — anyone who holds it can manage your entire tenant.
  </Step>

  <Step title="Add a domain">
    Register the domain you want to use for email. Replace `YOUR_TOKEN` and `example.com` with your own values.

    ```bash theme={null}
    curl -X POST "https://mail.ugmail.co/api/principal" \
      -H "Authorization: Bearer YOUR_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "example.com",
        "type": "domain"
      }'
    ```

    A successful response returns the new domain object including its `id`.
  </Step>

  <Step title="Fetch DNS records and configure your registrar">
    Retrieve the DNS records UGMail needs you to publish. These include MX, SPF, and DKIM records.

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

    The response lists each record with its type, name, and value. Log in to your domain registrar and add every record exactly as shown.

    <Note>
      DNS propagation can take anywhere from a few minutes to 48 hours depending on your registrar and TTL settings. UGMail will begin routing mail for your domain once it detects the records are live. You can re-query the endpoint at any time to check propagation status.
    </Note>
  </Step>

  <Step title="Provision a mailbox">
    Create your first mailbox. Assign it a secure password and one or more email addresses on your domain.

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

    The response returns the mailbox object. The mailbox is active immediately — no additional activation step required.
  </Step>

  <Step title="Connect via SMTP or IMAP">
    Use the credentials you just created to connect any email client or application. The server settings are the same for every mailbox on your tenant.

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

    Use `alice@example.com` as the username and the password you set in `secrets` above.
  </Step>
</Steps>

## What's next

You now have a working mailbox on your own domain. Here are a few natural next steps:

* **Add aliases or forwarders** — route additional addresses to the same mailbox without creating new credentials.
* **Configure DKIM** — verify your DKIM record is live to maximise deliverability.
* **Automate provisioning** — integrate the Management API into your application's onboarding flow.
* **Explore JMAP** — if you're building a custom mail client or AI agent, JMAP gives you a modern, efficient alternative to IMAP.

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Learn more about Bearer token auth and see Python and Node.js examples.
  </Card>

  <Card title="Set Up a Domain" icon="globe" href="/guides/setup-domain">
    A deeper walkthrough of domain registration, DNS, and DKIM verification.
  </Card>

  <Card title="Protocols Overview" icon="network-wired" href="/protocols/overview">
    Full details on all seven supported protocols and their connection settings.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Complete endpoint reference for the UGMail Management API.
  </Card>
</CardGroup>