Provision a Mailbox Programmatically via UGMail API

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 in UGMail
A valid Bearer token from Settings → API Connection at my.ugmail.co

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 guide before continuing.

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.

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

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

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

A 201 Created response confirms the mailbox is live and ready to use immediately.

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.

curl "https://mail.ugmail.co/api/principal/alice@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"

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:

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.

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.

Get Started

Core Concepts

Protocols

Guides

Security

Provision a Mailbox Programmatically via UGMail API

Prerequisites

Next steps

Manage Aliases

Connect an AI Agent

​Prerequisites

​Next steps

Manage Aliases

Connect an AI Agent

Prerequisites

Next steps