# FineMail SDKs 0.2.0

FineMail provides dependency-free TypeScript/JavaScript and Python clients for AI agents and server-side automations. Version 0.2.0 covers all 38 owner-scoped tools published by the FineMail MCP and authenticated REST tool bridge.

## Authentication

Create a scoped API key in the FineMail console or connect through the hosted OAuth 2.1 PKCE flow. Keep the resulting `fse2_mcp_` bearer token in a secret manager or environment variable.

```text
Authorization: Bearer fse2_mcp_<token>
```

Never place the token in source code, browser bundles, logs, prompts, or version control.

## TypeScript / JavaScript

Node.js 18 or newer:

```bash
npm install https://finemail.app/sdk/finestructure-finemail-sdk-0.2.0.tgz
```

```js
import { FineMailClient } from '@finestructure/finemail-sdk'

const client = new FineMailClient({ token: process.env.FINEMAIL_MCP_TOKEN })
const inboxes = await client.listInboxes()
const threads = await client.listThreads({ folder: 'unread', limit: 20 })
console.log({ inboxes, threads })
```

The package also installs the `finemail` CLI. Run `finemail --help` after setting `FINEMAIL_MCP_TOKEN`.

Runnable example: <https://finemail.app/sdk/typescript-example.mjs>

## Python

Python 3.9 or newer:

```bash
pip install https://finemail.app/sdk/finemail_sdk-0.2.0-py3-none-any.whl
```

```python
import os
from finemail_sdk import FineMailClient

client = FineMailClient(os.environ["FINEMAIL_MCP_TOKEN"])
inboxes = client.list_inboxes()
threads = client.list_threads(folder="unread", limit=20)
print({"inboxes": inboxes, "threads": threads})
```

Runnable example: <https://finemail.app/sdk/python-example.py>

## Complete 38-tool method map

| REST/MCP tool | TypeScript / JavaScript | Python |
| --- | --- | --- |
| `finemail_list_inboxes` | `listInboxes()` | `list_inboxes()` |
| `finemail_get_inbox` | `getInbox()` | `get_inbox()` |
| `finemail_create_inbox` | `createInbox()` | `create_inbox()` |
| `finemail_update_inbox` | `updateInbox()` | `update_inbox()` |
| `finemail_delete_inbox` | `deleteInbox()` | `delete_inbox()` |
| `finemail_list_messages` | `listMessages()` | `list_messages()` |
| `finemail_get_message` | `getMessage()` | `get_message()` |
| `finemail_send_message` | `sendMessage()` | `send_message()` |
| `finemail_reply_message` | `replyMessage()` | `reply_message()` |
| `finemail_forward_message` | `forwardMessage()` | `forward_message()` |
| `finemail_update_message` | `updateMessage()` | `update_message()` |
| `finemail_mark_read` | `markRead()` | `mark_read()` |
| `finemail_archive_message` | `archiveMessage()` | `archive_message()` |
| `finemail_delete_message` | `deleteMessage()` | `delete_message()` |
| `finemail_list_threads` | `listThreads()` | `list_threads()` |
| `finemail_get_thread` | `getThread()` | `get_thread()` |
| `finemail_update_thread` | `updateThread()` | `update_thread()` |
| `finemail_delete_thread` | `deleteThread()` | `delete_thread()` |
| `finemail_list_drafts` | `listDrafts()` | `list_drafts()` |
| `finemail_get_draft` | `getDraft()` | `get_draft()` |
| `finemail_create_draft` | `createDraft()` | `create_draft()` |
| `finemail_update_draft` | `updateDraft()` | `update_draft()` |
| `finemail_send_draft` | `sendDraft()` | `send_draft()` |
| `finemail_delete_draft` | `deleteDraft()` | `delete_draft()` |
| `finemail_wait_for_email` | `waitForEmail()` | `wait_for_email()` |
| `finemail_get_attachment` | `getAttachment()` | `get_attachment()` |
| `finemail_list_webhooks` | `listWebhooks()` | `list_webhooks()` |
| `finemail_create_webhook` | `createWebhook()` | `create_webhook()` |
| `finemail_delete_webhook` | `deleteWebhook()` | `delete_webhook()` |
| `finemail_list_domains` | `listDomains()` | `list_domains()` |
| `finemail_create_domain` | `createDomain()` | `create_domain()` |
| `finemail_verify_domain` | `verifyDomain()` | `verify_domain()` |
| `finemail_list_security_rules` | `listSecurityRules()` | `list_security_rules()` |
| `finemail_create_security_rule` | `createSecurityRule()` | `create_security_rule()` |
| `finemail_delete_security_rule` | `deleteSecurityRule()` | `delete_security_rule()` |
| `finemail_get_usage` | `getUsage()` | `get_usage()` |
| `finemail_check_address_availability` | `checkAddressAvailability()` | `check_address_availability()` |
| `finemail_get_configuration` | `getConfiguration()` | `get_configuration()` |

Rich sends support text and HTML bodies, CC/BCC, embedded base64 attachments, idempotency, and controlled RFC headers. The convenience `replyTo`, `inReplyTo`, and `references` arguments are emitted through the tool's supported `headers` object. Replies and forwards preserve FineMail thread state and can reuse existing attachments by ID.

Each method sends a JSON object to:

```text
POST https://finemail.app/api/mcp/tools/{tool}
```

The clients unwrap a successful REST envelope and return its `result`. API failures raise `FineMailError` with safe `status`, `code`, and `details` fields. The default timeout is 30 seconds and can be overridden per client or call.

Machine-readable package metadata and SHA-256 checksums: <https://finemail.app/sdk/index.json>

- OpenAPI: <https://finemail.app/openapi.json>
- MCP: <https://finemail.app/api/mcp>
- A2A Agent Card: <https://finemail.app/.well-known/agent-card.json>