> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mail.ugmail.co/llms.txt
> Use this file to discover all available pages before exploring further.

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

> JMAP is a modern, efficient alternative to IMAP. Connect to UGMail's JMAP endpoint at mail.ugmail.co:443 for fast, batched email operations over HTTPS.

JMAP (JSON Meta Application Protocol) is a modern, open-standard protocol for email access defined in [RFC 8620](https://datatracker.ietf.org/doc/html/rfc8620) (core) and [RFC 8621](https://datatracker.ietf.org/doc/html/rfc8621) (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.

```bash Session discovery theme={null}
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).

<CodeGroup>
  ```bash curl — list mailboxes theme={null}
  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"]
      ]
    }'
  ```

  ```bash curl — get emails theme={null}
  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"]
      ]
    }'
  ```

  ```python Python (requests) theme={null}
  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))
  ```
</CodeGroup>

<Note>
  JMAP client libraries are available for most languages and handle session discovery, batching, and push notifications automatically. Check [jmap.io/software](https://jmap.io/software.html) for a list of open-source clients and libraries before building a raw HTTP integration from scratch.
</Note>

## Further reading

* [jmap.io](https://jmap.io) — official JMAP specification site with guides and client library listings
* [RFC 8620](https://datatracker.ietf.org/doc/html/rfc8620) — JMAP core specification
* [RFC 8621](https://datatracker.ietf.org/doc/html/rfc8621) — JMAP for email (Mail, Mailbox, Thread, SearchSnippet)

## Troubleshooting

<Warning>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.</Warning>

| 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` |