Developer Friendly

Management API

Manage domains, email accounts, aliases, forwarders, and DNS via a clean REST API. Full programmatic control over your UGMail email infrastructure.

✨ Fully white-labeled — resellers can offer these APIs under their own brand.

Get Started Visit Guides

Base URL

https://mail.ugmail.co/api

All API endpoints are accessible through this base URL. Authentication is required for most endpoints.

Authentication

Two-step OAuth 2.0 authorization code flow. Tokens are valid for 1 hour.

Flow

POST credentials to /api/oauth and receive an authorization code
Exchange the code at /auth/token for an access_token
Use Authorization: Bearer <access_token> on all subsequent calls

POST/api/oauthObtain a bearer access token (OAuth 2.0)

# Step 1: Request an authorization code with HTTP Basic auth
curl -X POST "https://mail.ugmail.co/api/oauth" \
  -u "your-tenant-admin-username:your-password" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "code",
    "client_id": "ugmail-admin",
    "redirect_uri": "https://mail.ugmail.co/api/oauth/callback"
  }'

# Step 2: Exchange the code for an access token
curl -X POST "https://mail.ugmail.co/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=<auth_code>" \
  --data-urlencode "client_id=ugmail-admin" \
  --data-urlencode "redirect_uri=https://mail.ugmail.co/api/oauth/callback"

# Step 3: Use the bearer token in all subsequent API calls
curl "https://mail.ugmail.co/api/principal?types=domain" \
  -H "Authorization: Bearer <access_token>"

Recommended workflow

Add Domain — create a domain principal first
Create Email Account — create an individual principal on that domain
Add Aliases — optionally add additional addresses
Setup Forwarders — optionally create email forwarding rules

All entities (domains, accounts, groups) are called "principals" with different type values.

1. Domains

Domains must be created before email accounts can use them.

GET/api/principal?types=domainList all domains in your tenant

curl "https://mail.ugmail.co/api/principal?types=domain&limit=100" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST/api/principalCreate a new domain

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

DELETE/api/principal/{domain}Delete a domain (fails if accounts still exist)

2. Email Accounts

Email accounts are principals with type "individual".

GET/api/principal?types=individualList all email accounts (page, limit, types, tenant)

POST/api/principalCreate a new email account

curl -X POST "https://mail.ugmail.co/api/principal" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "tenant": "your_tenant_name",
    "name": "john@example.com",
    "description": "John Doe",
    "secrets": ["SecurePassword123!"],
    "emails": ["john@example.com"],
    "quota": 1073741824,
    "roles": ["user"]
  }'

# Note: quota is in bytes (1073741824 = 1GB)

GET/api/principal/{email}Get details of a specific email account

PATCH/api/principal/{email}Update account (password, quota, suspend, etc.)

# Suspend account (disable login)
curl -X PATCH "https://mail.ugmail.co/api/principal/john@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"action": "set", "field": "disabledPermissions", "value": ["authenticate"]}]'

# Unsuspend account
curl -X PATCH "https://mail.ugmail.co/api/principal/john@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"action": "set", "field": "disabledPermissions", "value": []}]'

DELETE/api/principal/{email}Delete an email account and all its data

3. Aliases

Aliases are additional email addresses that deliver to an existing account.

PATCH/api/principal/{email}Add or remove an alias on an existing account

# Add alias sales@example.com to john@example.com
curl -X PATCH "https://mail.ugmail.co/api/principal/john@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"action":"addItem","field":"emails","value":"sales@example.com"}]'

# Remove alias
curl -X PATCH "https://mail.ugmail.co/api/principal/john@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"action":"removeItem","field":"emails","value":"sales@example.com"}]'

# Catch-all for entire domain
curl -X PATCH "https://mail.ugmail.co/api/principal/john@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"action":"addItem","field":"emails","value":"@example.com"}]'

4. Forwarders

Forward incoming emails to external addresses. Stored as server-level Sieve scripts.

GET/api/forwarders?domain={domain}List all forwarders for a domain

POST/api/forwardersCreate a new email forwarder

curl -X POST "https://mail.ugmail.co/api/forwarders" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fromEmail": "info@example.com",
    "to": "external@gmail.com, backup@yahoo.com",
    "description": "Forward to personal email",
    "keepLocal": true
  }'

DELETE/api/forwarders/{id}Delete a forwarder

5. Security

Two-Factor Authentication (TOTP) and App Passwords for email accounts.

GET/api/principal/{email}Inspect the secrets array for 2FA and app passwords

PATCH/api/principal/{email}Enable TOTP two-factor authentication

# Add a TOTP secret to the account's secrets array
curl -X PATCH "https://mail.ugmail.co/api/principal/john@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"action":"addItem","field":"secrets","value":"otpauth://totp/UGMail:john@example.com?secret=BASE32SECRET&issuer=UGMail"}]'

PATCH/api/principal/{email}Create an app-specific password (IMAP/SMTP clients)

# App passwords are stored as: $app${base64-name}{bcrypt-hash}
curl -X PATCH "https://mail.ugmail.co/api/principal/john@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"action":"addItem","field":"secrets","value":"$app$TXkgaVBob25l$2y$10$hashedpasswordhere"}]'

DKIM & DNS

POST/userapi/dkimCreate a DKIM signature for a domain

curl -X POST "https://mail.ugmail.co/userapi/dkim" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","algorithm":"Ed25519"}'

GET/api/dns/records/{domain}Get required DNS records for a domain

Quick Reference

Resource	Endpoint	Methods
Domains	/api/principal?types=domain	GET, POST, DELETE
Accounts	/api/principal?types=individual	GET, POST, PATCH, DELETE
Aliases	/api/principal/{email}	PATCH (emails array)
Forwarders	/api/forwarders	GET, POST, DELETE
2FA (TOTP)	/api/principal/{email}	PATCH (secrets array)
App Passwords	/api/principal/{email}	PATCH (secrets array)
DKIM	/userapi/dkim	POST
DNS Records	/api/dns/records/{domain}	GET

Automate your email infrastructure

Build tools, dashboards, and integrations on top of UGMail with a clean, well-documented REST API.

Get Started Read the guides