> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.usglobalmail.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usglobalmail.com/_mcp/server.

# TypeScript SDK

## Install

**`npm`**

```bash title="npm"
npm install @usgm/sdk
```

**`yarn`**

```bash title="yarn"
yarn add @usgm/sdk
```

**`pnpm`**

```bash title="pnpm"
pnpm add @usgm/sdk
```

Requires Node.js 18+.

## Initialize

```typescript
import { UsgmClient } from "@usgm/sdk";

const usgm = new UsgmClient({
  token: process.env.USGM_API_KEY!, // never hard-code the key
});
```

## Usage

```typescript
// Your account profile
const account = await usgm.account.get();
console.log(account.email, account.status);

// List mail, one page at a time (cursor pagination)
let cursor: string | undefined;
do {
  const page = await usgm.mails.list({ cursor });
  for (const mail of page.data) {
    console.log(mail.id, mail.sender_name);
  }
  cursor = page.next_cursor ?? undefined;
} while (cursor);

// Fetch one item
const mail = await usgm.mails.get({ id: "80421" });

// Create a folder
const folder = await usgm.folders.create({ name: "Taxes" });
```

## Error handling

```typescript
import { UsgmError } from "@usgm/sdk";

try {
  await usgm.mails.get({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof UsgmError) {
    // `body` is the RFC 9457 problem+json payload (code, request_id, detail, …)
    console.error(err.statusCode, err.body);
  }
  throw err;
}
```

> **Note**
>
> Transient `429` and `5xx` responses are retried automatically with exponential backoff. See
> [Errors](/guides/core-concepts/errors) for the full problem+json contract.