Fast Batched Email API Access via JMAP on UGMail (Port 443)

JMAP (JSON Meta Application Protocol) is a modern, open-standard protocol for email access defined in RFC 8620 (core) and RFC 8621 (email). Where IMAP was designed in the 1980s for line-by-line text exchange, JMAP uses JSON over HTTPS and allows you to batch multiple operations into a single request — fetching a list of mailboxes, reading message headers, and marking messages as read all in one round trip. UGMail exposes a full JMAP endpoint so you can build fast, efficient email integrations without wrestling with legacy IMAP commands.

Why use JMAP over IMAP?

Feature	IMAP	JMAP
Transport	Custom TCP protocol	HTTPS (port 443)
Data format	Line-based text commands	JSON
Batched operations	No — one command at a time	Yes — multiple operations per request
Push notifications	Polling or IDLE command	Native push via EventSource
Firewall-friendly	Requires port 993 open	Runs on standard HTTPS (443)
Client library ecosystem	Mature but complex	Growing, simpler to implement

JMAP is the right choice when you’re building a new integration from scratch, need low-latency access, or are operating in environments where non-HTTPS ports are restricted.

Connection details

Setting	Value
Endpoint	`https://mail.ugmail.co`
Port	`443`
Protocol	HTTPS
Authentication	HTTP Basic (`email:password`)

Use your mailbox’s full email address as the username and the password you set via the secrets field in the Management API as the password. All JMAP requests are standard HTTPS — no special TCP connections or TLS configuration beyond what any HTTPS client handles automatically.

Session discovery

Every JMAP client starts by fetching the session object, which describes the capabilities of the server and the URLs for API calls, uploads, downloads, and event streams. Discover the session by sending a GET request to the well-known JMAP endpoint.

Session discovery

curl -u 'alice@example.com:SecurePassword123!' \
  'https://mail.ugmail.co/.well-known/jmap'

The server returns a JSON object describing its capabilities, account IDs, and endpoint URLs. Your client should cache this response and use the apiUrl field for all subsequent method calls.

Making JMAP API calls

JMAP API calls are POST requests to the apiUrl returned by session discovery. Each request body is a JSON object with a using array (declaring which capabilities you need) and a methodCalls array (the operations to perform).

curl -u 'alice@example.com:SecurePassword123!' \
  -H 'Content-Type: application/json' \
  -X POST 'https://mail.ugmail.co/jmap' \
  -d '{
    "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],
    "methodCalls": [
      ["Mailbox/get", { "accountId": "YOUR_ACCOUNT_ID", "ids": null }, "0"]
    ]
  }'

curl -u 'alice@example.com:SecurePassword123!' \
  -H 'Content-Type: application/json' \
  -X POST 'https://mail.ugmail.co/jmap' \
  -d '{
    "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],
    "methodCalls": [
      ["Email/query", {
        "accountId": "YOUR_ACCOUNT_ID",
        "filter": { "inMailbox": "INBOX_ID" },
        "sort": [{ "property": "receivedAt", "isAscending": false }],
        "limit": 10
      }, "0"],
      ["Email/get", {
        "accountId": "YOUR_ACCOUNT_ID",
        "#ids": { "resultOf": "0", "name": "Email/query", "path": "/ids" },
        "properties": ["subject", "from", "receivedAt", "preview"]
      }, "1"]
    ]
  }'

import requests
import json

credentials = ('alice@example.com', 'SecurePassword123!')
base_url = 'https://mail.ugmail.co'

# Step 1: Discover session
session = requests.get(f'{base_url}/.well-known/jmap', auth=credentials).json()
api_url = session['apiUrl']
account_id = list(session['accounts'].keys())[0]

# Step 2: List mailboxes
payload = {
    "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],
    "methodCalls": [
        ["Mailbox/get", {"accountId": account_id, "ids": None}, "0"]
    ]
}
response = requests.post(api_url, auth=credentials, json=payload)
print(json.dumps(response.json(), indent=2))

JMAP client libraries are available for most languages and handle session discovery, batching, and push notifications automatically. Check jmap.io/software for a list of open-source clients and libraries before building a raw HTTP integration from scratch.

Troubleshooting

Replace YOUR_ACCOUNT_ID and INBOX_ID in the example requests with the actual values returned by session discovery. The account ID is unique per mailbox and cannot be guessed from the email address alone.

Symptom	Likely cause	Fix
`401 Unauthorized`	Wrong credentials	Confirm username is the full email address and password matches `secrets`
`404 Not Found` on `/.well-known/jmap`	Wrong base URL	Use `https://mail.ugmail.co` exactly, with no trailing slash
Empty `methodCalls` response	Missing `using` capability	Include all required capability URNs in the `using` array
`accountNotFound` error	Wrong account ID	Re-fetch the session object and use the account ID from `session.accounts`

Get Started

Core Concepts

Protocols

Guides

Security

Fast Batched Email API Access via JMAP on UGMail (Port 443)

Why use JMAP over IMAP?

Connection details

Session discovery

Making JMAP API calls

Further reading

Troubleshooting

​Why use JMAP over IMAP?

​Connection details

​Session discovery

​Making JMAP API calls

​Further reading

​Troubleshooting

Why use JMAP over IMAP?

Connection details

Session discovery

Making JMAP API calls

Further reading

Troubleshooting