Skip to main content

Hotmail CLI

A small read-only CLI for Hotmail and Outlook.com mailboxes. It uses Microsoft Graph to search messages and download file attachments from your mailbox.

中文文档: README.zh-CN.md

Why Use This

  • Works with personal Microsoft accounts such as Hotmail and Outlook.com.
  • Uses Microsoft device code login, so the CLI never sees your password.
  • Requests only Mail.Read.
  • Downloads attachments from matching messages.
  • Stores the OAuth token locally with 0600 file permissions.

This tool is intentionally narrow. It does not send email, delete messages, mark messages, or manage calendars.

Installation

uvx hotmail-cli --help

Or install it into an environment:

uv tool install hotmail-cli
hotmail --help

Microsoft App Setup

You need your own Microsoft Entra app registration. This is free and lets Microsoft show you exactly what the CLI is allowed to access.

  1. Open the Microsoft Entra admin center.
  2. Go to App registrations -> New registration.
  3. Name it hotmail-cli or any name you prefer.
  4. For Supported account types, choose Personal Microsoft accounts only for Hotmail/Outlook.com.
  5. Leave Redirect URI empty.
  6. Create the app.
  7. Open Authentication -> Settings.
  8. Enable Allow public client flows and save.
  9. Copy the Application (client) ID.

Sign In

export HOTMAIL_CLIENT_ID="your Microsoft app client id"
hotmail auth

The command prints a URL and code. Open the URL in your browser, enter the code, sign in to Microsoft, and approve the requested Mail.Read access.

The token cache is saved to:

~/.hotmail-cli/token.json

You can also pass the client id directly:

hotmail --client-id "your Microsoft app client id" auth

Search Messages

Search by subject:

hotmail search --subject "statement" --top 10

Search by subject, sender, and date range:

hotmail search \
  --subject "invoice" \
  --sender "billing@example.com" \
  --since 2026-06-01 \
  --until 2026-06-27 \
  --top 10

The output is Microsoft Graph message JSON. Each message includes an id that can be used with fetch and attachments.

Microsoft Graph message $search cannot be reliably combined with $filter or $orderby, so Hotmail CLI searches by subject server-side first, then applies sender and date filters locally.

Fetch One Message

hotmail fetch MESSAGE_ID

Download Attachments

hotmail attachments MESSAGE_ID --output-dir downloads

Only Microsoft Graph fileAttachment items are saved. Inline items and reference attachments are ignored.

Local Development

uv sync
uv run pytest
uv run hotmail --help

Build the package:

uv build

Security Notes

  • Do not commit ~/.hotmail-cli/token.json.
  • Do not share message IDs or downloaded attachments publicly.
  • Revoke access anytime from your Microsoft account security page or from the app registration.

License

MIT

Metadata

Release files for hotmail-cli 0.1.1

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

Source distribution (sdist)

Source distribution for hotmail-cli 0.1.1
File Size Uploaded Provenance Actions
hotmail_cli-0.1.1.tar.gz 11.3 kB Without provenance Details for hotmail_cli-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hotmail-cli 0.1.1
File Interpreter ABI Platform Actions
hotmail_cli-0.1.1-py3-none-any.whl Python 3 none any Details for hotmail_cli-0.1.1-py3-none-any.whl

Total release size: 19.5 kB

Release files / hotmail_cli-0.1.1.tar.gz

Download URL hotmail_cli-0.1.1.tar.gz
Size 11.3 kB
Tags Source
SHA-256 checksum
How to use checksums
1dfefde76a50ef5f0296199d229561062fe262a529137c8b24600b4aa3f2b462
BLAKE2b-256 checksum
How to use checksums
305848f151ab8f5a82eb334c88a4aaff1ea3581134a74e113685cb44cc4cc393
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / hotmail_cli-0.1.1-py3-none-any.whl

Download URL hotmail_cli-0.1.1-py3-none-any.whl
Size 8.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e7b9caab5be9e0e2995d17262f55145eaa1981964f0b18c8c7e169bf265ca514
BLAKE2b-256 checksum
How to use checksums
d2169a98cb36f498aa7423bb6b52debe3da44a4350bb5b7eeef0fbb60bce211a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for hotmail-cli 0.1.1

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.1 This release

2 release files No 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