UGMail Management API Authentication with Bearer Tokens

Every request to the UGMail Management API must be authenticated with a tenant-scoped Bearer token. This token identifies your account, enforces access control, and ensures that operations you perform are isolated to your tenant. There are no API keys, OAuth flows, or rotating secrets to manage — one token covers all Management API endpoints.

Get your Bearer token

Sign in to your UGMail account at my.ugmail.co, then navigate to Settings → API Connection. Your Bearer token is displayed on that page. Click the copy button to grab it.

Your Bearer token grants full management access to your UGMail tenant — including the ability to delete domains and mailboxes. Never commit it to version control, hardcode it in client-side code, or share it in public forums. Store it in an environment variable or a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or your CI/CD platform’s secret store.

Use the token in requests

Include the token in the Authorization header of every Management API request using the Bearer scheme:

Authorization: Bearer YOUR_TOKEN

The examples below show how to do this in curl, Python, and Node.js.

curl -X GET "https://mail.ugmail.co/api/principal" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

import requests

TOKEN = "YOUR_TOKEN"  # load from environment in production

response = requests.get(
    "https://mail.ugmail.co/api/principal",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
)

response.raise_for_status()
print(response.json())

const TOKEN = process.env.UGMAIL_TOKEN; // always load from env

const response = await fetch("https://mail.ugmail.co/api/principal", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
});

if (!response.ok) {
  throw new Error(`UGMail API error: ${response.status} ${response.statusText}`);
}

const data = await response.json();
console.log(data);

Error responses

If your token is missing, malformed, or invalid, the API returns one of the following error responses.

Status code	Meaning
`401 Unauthorized`	The `Authorization` header is missing, the token is malformed, or the token is not recognised. Check that you copied the full token and that the header is formatted correctly.
`403 Forbidden`	The token is valid but does not have permission to perform the requested operation. This can occur if your account plan does not include a particular feature or if you are attempting to access another tenant’s resources.

A 401 response body looks like this:

{
  "error": "Unauthorized",
  "message": "Missing or invalid Bearer token."
}

The Management API does not use session cookies or HTTP Basic auth. If you have previously used another email API that relies on username/password authentication, note that UGMail’s Management API exclusively uses Bearer tokens. SMTP, IMAP, and other protocol connections do use per-mailbox username/password credentials — see the Protocols Overview for details.

Rotate your token

If you believe your token has been compromised or you want to rotate it as part of a routine security practice, return to Settings → API Connection in my.ugmail.co and generate a new token. Your previous token is invalidated immediately upon rotation.

Update every environment — local development, staging, and production — in quick succession after rotating. Because the old token is invalidated immediately, any service still using it will begin returning 401 Unauthorized errors until you deploy the new token.

Get Started

Core Concepts

Protocols

Guides

Security

UGMail Management API Authentication with Bearer Tokens

Get your Bearer token

Use the token in requests

Error responses

Rotate your token

Next steps

Quickstart

API Reference

​Get your Bearer token

​Use the token in requests

​Error responses

​Rotate your token

​Next steps

Quickstart

API Reference

Get your Bearer token

Use the token in requests

Error responses

Rotate your token

Next steps