TypeScript SDK

A fully-typed client for Node.js and the browser.

Install

$npm install @usgm/sdk

Requires Node.js 18+.

Initialize

1import { UsgmClient } from "@usgm/sdk";
2
3const usgm = new UsgmClient({
4 apiKey: process.env.USGM_API_KEY, // never hard-code the key
5});

Usage

1// List mail (auto-paginates)
2for await (const mail of usgm.mails.list({ isRead: false })) {
3 console.log(mail.id, mail.sender);
4}
5
6// Fetch one item
7const mail = await usgm.mails.get("80421");
8
9// Mark it read
10await usgm.mails.update("80421", { isRead: true });
11
12// Create a folder and file the mail into it
13const folder = await usgm.folders.create({ name: "Taxes", color: "blue" });
14await usgm.mails.update("80421", { folderId: folder.id });

Error handling

1import { UsgmError } from "@usgm/sdk";
2
3try {
4 await usgm.mails.get("does-not-exist");
5} catch (err) {
6 if (err instanceof UsgmError) {
7 console.error(err.code, err.statusCode, err.requestId);
8 }
9 throw err;
10}

Transient 429 and 5xx responses are retried automatically with exponential backoff. See Errors for the full problem+json contract.