Skip to main content

pysdk — AIMail Python SDK

AIMail (agent mail) Python runtime SDK: gateway HTTP client, 15 mail / contact / note / board / identity tool functions (7 mail+contact+note incl. search_mail + 6 A2A board + 2 identity: activate_address_code, set_public_whoami), the inbound preprocess chain, an MCP server, and ready-made host adapters (Hermes / DeerFlow). Board resources (skills, role prompts, role souls) ship with the package and are released at install time to the local config directory, where users can personalize them.

This SDK lives in the metercai/aimail monorepo under pysdk/ (CLI in cli/, TypeScript SDK in tssdk/, bridge in bridge/). The pip package aimailsdk (import name aimail) is the published surface of this tree — the wheel mirrors pysdk/ 1:1 for code and maps the repo-root resources/ to aimail/resources/, so repo and installed layouts are identical either way. Asset resources (board prompts/souls, skills) are single-sourced at the repo-root resources/: a repo checkout reads that directory directly (no copy step), and each npm adapter package stages its own resources/ copy in its own prepack (node ../mail-core/scripts/stage-resources.mjs --dest ., git-ignored) because a tarball can only carry files under the package directory.

What File(s)
Core (framework-agnostic, stdlib-only) aimail_base.py (identity/signature/config/register), aimail_tools.py (send_mail + contacts + notes + _GatewayClient), aimail_board.py (A2A board), gateway_api.py (v1 API client), _aimail_bootstrap.py (location-agnostic sys.path boot)
MCP server aimail_mcp_server.py (stdio JSON-RPC, platform-agnostic)
Adapters (host-injected) hermes/ (aimail_hermes + patch/register/toolsets, 6 modules), deer-flow/ (aimail_inbound + aimail_deerflow + manage)
Resources resources/skills/ (SKILL.md + DESCRIPTION.md), resources/board/role_prompt/ (6 board role prompt templates, released as-is)
Glue __init__.py — unified entry: import aimail re-exports the curated API and boots the flat core

Install

pip install aimailsdk      # from PyPI (import name stays `aimail`)
pip install .                 # from the repo root (hatchling, force-include)

No hard third-party dependencies — the core is stdlib-only. Optional extras, all lazy/host-gated:

  • aimail[hermes] — PyYAML for the Hermes adapter's profile-config parsing
  • aimail[deerflow] — fastapi (the DeerFlow inbound router imports it at module level; the DeerFlow host always ships FastAPI)
  • aimail[docs] — markitdown (attachment → markdown conversion)

Platform adapters are host-injected: importing aimail.hermes.* outside a Hermes gateway prints registration-skipped warnings by design.

Usage

import aimail

# unified entry (boots the flat core, re-exports the curated API)
aimail.send_mail(to="x@example.com", subject="hi", body="hello")
client = aimail.GatewayClient(aimail.agent_email(), api_key="...")

# legacy flat imports still work (host adapters use this)
import sys, aimail
sys.path.insert(0, aimail.core_dir())
import aimail_base, aimail_tools

Host adapters never import the package path directly — each entry calls _aimail_bootstrap() (in _aimail_bootstrap.py), which resolves the core directory in all three layouts: pip site-packages, self-contained bundle (provisioner copies), and repo checkout.

Resources & the local config directory

Board resources are seeds, not read-at-runtime-from-the-SDK files. The SDK install entry (python -m aimail.install install --type …, which the CLI's aimail install delegates to) releases them via aimail._resources_release to:

~/.aimail/systems/{system_id}/board/
└── role_prompt/        # 6 role prompt templates — read by the preprocess chain

Both the Python and the TypeScript (tssdk/) runtimes read from this same location, so users can edit a role prompt file to personalize behavior — and the change applies to every platform at once.

Development

# repo layout: core modules import each other by bare name
python3 -c "import sys; sys.path.insert(0, 'pysdk'); import aimail_base"

# build & verify the wheel (three layouts must all import)
python3 -m venv /tmp/v && /tmp/v/bin/pip install .
/tmp/v/bin/python -c "import aimail; print(aimail.core_dir())"
aimail install --payload source           # resolves pip > repo pysdk/
  • metercai/aimail — this monorepo: aimail CLI (cli/), Python SDK (pysdk/, you are here), TypeScript SDK (tssdk/), bridge distributions.
  • metercai/aimail-gateway — the AIMail gateway: SMTP/HTTP mail service, address & activation APIs, and the board endpoints the SDK client talks to.

Metadata

Release files for aimailsdk 0.1.55

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for aimailsdk 0.1.55
File Interpreter ABI Platform Actions
aimailsdk-0.1.55-py3-none-any.whl Python 3 none any Details for aimailsdk-0.1.55-py3-none-any.whl

Release files / aimailsdk-0.1.55-py3-none-any.whl

Download URL aimailsdk-0.1.55-py3-none-any.whl
Size 211.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7fffe21e57f0138444550d002ed0d0c4602b9eebd0d7708fe39ffc201d873234
BLAKE2b-256 checksum
How to use checksums
3d9c23c5898896d613e2a2b049eb5c73008409fedd17705eecb15aaab612e54f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

Security for aimailsdk 0.1.55

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

1 file in this release has been uploaded with provenance metadata.

Attestation for aimailsdk-0.1.55-py3-none-any.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.55 This release

1 release file Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page