Developer
UG
UGMail Developer Portal
API docs, quick-starts, examples and support — white-label mail platform for your app or site.
Introduction
UGMail provides business-grade email hosting and developer APIs to provision mailboxes, manage domains, aliases, and receive event webhooks. UGMail is white-label; you manage domains and users while we power the mail backend.
API Base URL
https://api.ugmail.site/v2
Quick Checklist
- Create scoped API key in UGMail Admin
- Implement server-side proxy for username checks
- Set up DKIM/SPF for domains
- Register a webhook endpoint to receive events
Security reminder: do not expose API keys in browser code. Use a server or serverless function to call UGMail API.
Authentication & Security
UGMail uses Bearer tokens for API authentication. Create keys in Admin and scope them by capability (user management, domains, webhooks, read-only).
Header
Authorization: Bearer YOUR_API_KEYBest practices
- Use minimum required scopes per API key.
- IP allowlist production keys.
- Rotate keys quarterly.
- Use TLS for all API & webhook endpoints.
Check Username Availability
Validate that the desired local-part is free on a specific domain before attempting to create the mailbox.
Endpoint
GET /domains/{domain}/users/{username}Example (cURL)
curl -i "https://api.ugmail.site/v2/domains/ugmail.site/users/patrick" -H "Authorization: Bearer YOUR_API_KEY"
Interpretation
- 200 OK — username exists (taken)
- 404 Not Found — username available
Flow: frontend → your backend proxy → UGMail API. Backend returns available: true/false to frontend.
User Management
Provision and manage mailboxes programmatically.
Create mailbox
POST /domains/{domain}/users
{
"username": "jane.doe",
"password": "S3cure!Passw0rd",
"first_name": "Jane",
"last_name": "Doe",
"quota_mb": 51200
}
Responses
{
"user": "jane.doe@ugmail.site",
"status": "created"
}
Transport passwords over TLS and consider using generated app passwords for SMTP access.
Domain Management
Manage domains, verify DNS records, and display domain health in the admin UI.
List domains
GET /domainsDomain DNS check
GET /domains/{domain}/dns
Response:
{
"domain":"yourdomain.com",
"mx": {"status":"ok","expected":["mx1.ugmail.site","mx2.ugmail.site"]},
"spf": {"status":"ok","record":"v=spf1 include:_spf.ugmail.site -all"},
"dkim": {"status":"pending","selector":"ugm1"},
"dmarc": {"status":"ok","record":"v=DMARC1; p=quarantine"}
}
Aliases
Create role-based or forwarding aliases.
Create alias
POST /domains/{domain}/aliases
{
"alias": "sales",
"target": "jane.doe"
}
Delete
DELETE /domains/{domain}/aliases/{alias}SMTP / IMAP / POP3
SMTP (send)
- Host:
smtp.ugmail.site - Ports: 587 (STARTTLS), 465 (SSL/TLS)
- Auth: full email + password or app password
IMAP (receive)
- Host:
imap.ugmail.site - Port: 993 (SSL/TLS)
- Use IMAP for multi-device sync
App Passwords
Generate app passwords for programmatic SMTP usage; avoid storing primary passwords in integrations.
Webhooks
Subscribe to real-time events and verify them via HMAC signatures.
Register webhook
POST /webhooks
{
"url":"https://yourapp.com/webhooks/ugmail",
"events":["message.delivered","message.bounced","user.created"]
}
Verify signature
Header: X-UGMail-Signature: sha256=HEX_SIGNATURE
Compute: HMAC_SHA256(webhook_secret, raw_body) and compare timing-safe.
Code Examples
Server-side examples you can copy into your backend.
Node.js — username-check proxy
/* server.js */
import express from "express";
import fetch from "node-fetch";
import cors from "cors";
const app = express(); app.use(cors()); app.use(express.json());
const API = "https://api.ugmail.site/v2";
const KEY = process.env.UGMAIL_API_KEY;
app.get("/api/check-username", async (req, res) => {
const { domain, username } = req.query;
if (!domain || !username) return res.status(400).json({ error:"missing" });
const r = await fetch(`${API}/domains/${domain}/users/${encodeURIComponent(username)}`, {
headers: { Authorization: `Bearer ${KEY}` }
});
if (r.status === 404) return res.json({ available: true });
if (r.ok) return res.json({ available: false });
return res.status(r.status).json({ error: await r.text() });
});
app.listen(3000);
PHP — simple proxy (validate.php)
$code === 404]);
?>
Python — create user
import os, requests
API="https://api.ugmail.site/v2"
KEY=os.getenv("UGMAIL_API_KEY")
def create_user(domain, username, password, first, last):
r = requests.post(f"{API}/domains/{domain}/users",
headers={"Authorization":f"Bearer {KEY}"},
json={"username":username,"password":password,"first_name":first,"last_name":last}, timeout=15)
r.raise_for_status()
return r.json()
Best Practices
- Always check username availability server-side (avoid exposing API keys).
- Validate username pattern on the client to reduce API calls.
- Use idempotency keys for create endpoints.
- Respect rate limits — implement exponential backoff on 429.
- Monitor webhook retries and implement durable queues.
- Enable SPF/DKIM/DMARC for every sending domain.
- Rotate API keys and use scopes & IP allowlists.
Welcome Email (Post-signup)
Use this template for the welcome message after registration.
Subject
Welcome to UGMail — Your Business Email Account is Ready
Plain / HTML
Subject: Welcome to UGMail — Your Business Email Account is Ready
Hi {{first_name}},
Welcome to UGMail — your new business email solution.
Account: {{user_email}}
Login: https://mail.ugmail.site
Need help? Contact support@ugmail.site
Quick Start:
1. Sign in and change your password.
2. Configure your mobile or desktop client using IMAP/SMTP.
3. Explore the dashboard for aliases, forwarding, and calendar.
Thanks,
The UGMail Team
Support
If you need integration assistance, billing, or technical support:
- Email:
support@ugmail.site - Admin Dashboard: https://my.ugmail.site
- Status: status.ugmail.site
Freshdesk: this portal supports the Freshdesk widget (see bottom-right). Replace the placeholder key in the script section with your Freshdesk widget key to enable chat/ticket creation.
