{"id":19428676,"url":"https://github.com/linux-profile/email-profile","last_synced_at":"2026-04-17T01:05:51.925Z","repository":{"id":227746438,"uuid":"625602632","full_name":"linux-profile/email-profile","owner":"linux-profile","description":"📩 Email Profile","archived":false,"fork":false,"pushed_at":"2025-09-14T02:10:02.000Z","size":405,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-04T01:35:21.010Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://linux-profile.github.io/email-profile/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linux-profile.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-09T16:11:08.000Z","updated_at":"2024-05-19T20:17:48.000Z","dependencies_parsed_at":"2024-05-07T04:32:56.674Z","dependency_job_id":"c38c5e15-4f7c-4af3-9689-1ada46f8da8f","html_url":"https://github.com/linux-profile/email-profile","commit_stats":null,"previous_names":["linux-profile/email-lib","linux-profile/email-profile"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/linux-profile/email-profile","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-profile%2Femail-profile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-profile%2Femail-profile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-profile%2Femail-profile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-profile%2Femail-profile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linux-profile","download_url":"https://codeload.github.com/linux-profile/email-profile/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-profile%2Femail-profile/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278811847,"owners_count":26050181,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T14:16:10.184Z","updated_at":"2026-04-17T01:05:51.915Z","avatar_url":"https://github.com/linux-profile.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# email-profile\n\n[![PyPI](https://img.shields.io/pypi/v/email-profile)](https://pypi.org/project/email-profile/)\n[![Python](https://img.shields.io/pypi/pyversions/email-profile)](https://pypi.org/project/email-profile/)\n[![Tests](https://img.shields.io/github/actions/workflow/status/linux-profile/email-profile/test.yml?branch=develop\u0026label=tests)](https://github.com/linux-profile/email-profile/actions)\n[![License](https://img.shields.io/github/license/linux-profile/email-profile)](LICENSE)\n[![Downloads](https://img.shields.io/pypi/dm/email-profile)](https://pypi.org/project/email-profile/)\n\nThe simplest way to work with email in Python. No boilerplate, no low-level IMAP commands, no headaches.\n\nJust connect, read, search, send, backup, and restore — with one class.\n\n```python\nfrom email_profile import Email\n\nwith Email(\"user@gmail.com\", \"app_password\") as app:\n    for msg in app.inbox.where().messages():\n        print(f\"{msg.date} | {msg.from_} | {msg.subject}\")\n```\n\nThat's it. No server configuration needed — email-profile auto-discovers your IMAP server from your email address.\n\n---\n\n- **Documentation**: [linux-profile.github.io/email-profile](https://linux-profile.github.io/email-profile/)\n- **Source Code**: [github.com/linux-profile/email-profile](https://github.com/linux-profile/email-profile)\n- **PyPI**: [pypi.org/project/email-profile](https://pypi.org/project/email-profile/)\n\n---\n\n## Install\n\n```bash\npip install email-profile\n```\n\n## Why email-profile?\n\nMost Python email libraries make you deal with `imaplib` directly, parse raw bytes, manage connections manually, and write dozens of lines just to read your inbox.\n\n**email-profile gives you a clean, human API:**\n\n- Write `Email(\"user@gmail.com\", \"pw\")` instead of configuring IMAP servers manually\n- Write `app.inbox.where(Q.unseen()).first()` instead of raw IMAP search commands\n- Write `app.sync()` instead of building your own backup system\n- Write `app.send(to=\"...\", subject=\"...\", body=\"...\")` instead of constructing MIME messages\n\nIt combines IMAP + SMTP + storage + sync in a single library. No other Python package does this.\n\n## Quick Start\n\n### Connect\n\nThree ways to connect — pick the one that fits:\n\n```python\nfrom email_profile import Email\n\n# Just email + password (auto-discovers the server)\nwith Email(\"user@gmail.com\", \"app_password\") as app:\n    print(app.mailboxes())\n\n# From .env file (great for production)\nwith Email.from_env() as app:\n    print(app.mailboxes())\n\n# Explicit server (when you need full control)\nwith Email(\"imap.gmail.com\", \"user@gmail.com\", \"app_password\") as app:\n    print(app.mailboxes())\n```\n\n### Read Emails\n\n```python\nwith Email.from_env() as app:\n    # How many emails?\n    print(app.inbox.where().count())\n\n    # Read them\n    for msg in app.inbox.where().messages():\n        print(f\"{msg.date} | {msg.from_} | {msg.subject}\")\n\n    # Just the first one\n    msg = app.inbox.where().first()\n\n    # Only headers (much faster for large mailboxes)\n    for msg in app.inbox.where().messages(mode=\"headers\"):\n        print(msg.subject)\n```\n\n### Search\n\nFind exactly what you need with composable queries:\n\n```python\nfrom email_profile import Email, Q\nfrom datetime import date\n\nwith Email.from_env() as app:\n    # Combine conditions with \u0026 (AND), | (OR), ~ (NOT)\n    q = Q.subject(\"meeting\") \u0026 Q.unseen()\n    print(app.inbox.where(q).count())\n\n    # From Alice or Bob\n    q = Q.from_(\"alice@x.com\") | Q.from_(\"bob@x.com\")\n\n    # Everything except seen emails\n    q = ~Q.seen()\n\n    # Emails from 2025, larger than 1MB\n    q = Q.since(date(2025, 1, 1)) \u0026 Q.before(date(2025, 12, 31)) \u0026 Q.larger(1_000_000)\n```\n\nOr use validated kwargs if you prefer:\n\n```python\nfrom email_profile import Query\n\nquery = Query(subject=\"report\", unseen=True, since=date(2025, 1, 1))\nquery = Query(subject=\"report\").exclude(subject=\"spam\").or_(subject=\"urgent\")\n```\n\nBuilt-in shortcuts for common searches:\n\n```python\napp.unread().count()\napp.recent(days=7).count()\napp.search(\"invoice\").count()\n```\n\n### Send Emails\n\nSend, reply, and forward — with automatic SMTP discovery:\n\n```python\nwith Email.from_env() as app:\n    # Simple\n    app.send(to=\"recipient@x.com\", subject=\"Hello\", body=\"Hi there!\")\n\n    # HTML + attachments + CC\n    app.send(\n        to=[\"alice@x.com\", \"bob@x.com\"],\n        subject=\"Report\",\n        body=\"See attached.\",\n        html=\"\u003ch1\u003eReport\u003c/h1\u003e\",\n        attachments=[\"report.pdf\"],\n        cc=\"manager@x.com\",\n    )\n\n    # Reply to an email (preserves threading)\n    msg = app.inbox.where().first()\n    app.reply(msg, body=\"Thanks!\")\n\n    # Forward\n    app.forward(msg, to=\"colleague@x.com\", body=\"FYI\")\n```\n\n### Backup \u0026 Restore\n\nSync your entire mailbox to a local SQLite database. Incremental — only downloads new emails. Parallel — multiple mailboxes at once. With progress bars.\n\n```python\nwith Email.from_env() as app:\n    # Backup everything (compares by Message-ID, skips duplicates)\n    result = app.sync()\n    print(f\"{result.inserted} new, {result.skipped} skipped\")\n\n    # Backup one mailbox\n    result = app.sync(mailbox=\"INBOX\")\n\n    # Force re-download (skip duplicate check)\n    result = app.sync(skip_duplicates=False)\n\n    # Restore to server (e.g. after migrating)\n    count = app.restore()\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/sync-demo.svg\" alt=\"Sync demo\"\u003e\n\n### Mailbox Operations\n\n```python\nwith Email.from_env() as app:\n    # Built-in folder shortcuts (auto-detected across languages)\n    app.inbox      # INBOX\n    app.sent       # Sent / Enviados / Enviadas\n    app.trash      # Trash / Lixeira / Papelera\n    app.drafts     # Drafts / Rascunhos\n    app.spam       # Spam / Junk / Lixo Eletrônico\n\n    # Any folder by name\n    work = app.mailbox(\"INBOX.Work\")\n\n    # Message operations\n    work.mark_seen(uid)\n    work.move(uid, \"INBOX.Archive\")\n    work.delete(uid)\n```\n\n### Custom Storage\n\nStorage is lazily initialized — `email.db` is only created when `sync()` or `restore()` is first called.\n\n```python\nfrom email_profile import Email, StorageSQLite\n\n# Default: saves to ./email.db on first sync\nwith Email.from_env() as app:\n    app.sync()\n\n# Custom path\nwith Email.from_env() as app:\n    app.storage = StorageSQLite(\"./backup.db\")\n    app.sync()\n```\n\n## Features\n\n| Feature | Description |\n|---|---|\n| **Auto-discovery** | Detects IMAP/SMTP servers from email domain (50+ providers) |\n| **Unified API** | IMAP + SMTP in a single `Email` class |\n| **Query Builder** | Composable search with `Q` (AND, OR, NOT) and validated `Query` kwargs |\n| **Sync \u0026 Restore** | Incremental backup to SQLite, restore to any server |\n| **Parallel** | Multi-threaded sync and restore with configurable workers |\n| **Progress** | Rich progress bars with per-mailbox status |\n| **Retry** | Exponential backoff on transient failures |\n| **Send** | Send, reply, forward with HTML, attachments, CC/BCC |\n| **Storage** | Pluggable storage backend (SQLite default) |\n| **Flags** | Read/unread, flag, delete, move, copy operations |\n| **Context Manager** | `with Email(...) as app:` for automatic cleanup |\n\n## Supported Providers\n\nAuto-discovery works out of the box. Just use your email and password — no server configuration needed.\n\n| | Provider | IMAP Server |\n|---|---|---|\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/gmail.svg\" width=\"16\"\u003e | Gmail | imap.gmail.com |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/outlook.svg\" width=\"16\"\u003e | Outlook / Hotmail / Live | outlook.office365.com |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/yahoo.svg\" width=\"16\"\u003e | Yahoo | imap.mail.yahoo.com |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/icloud.svg\" width=\"16\"\u003e | iCloud | imap.mail.me.com |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/zoho.svg\" width=\"16\"\u003e | Zoho | imap.zoho.com |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/protonmail.svg\" width=\"16\"\u003e | ProtonMail (Bridge) | 127.0.0.1:1143 |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/aol.svg\" width=\"16\"\u003e | AOL | imap.aol.com |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/yandex.svg\" width=\"16\"\u003e | Yandex | imap.yandex.com |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/mailru.svg\" width=\"16\"\u003e | Mail.ru | imap.mail.ru |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/gmx.svg\" width=\"16\"\u003e | GMX | imap.gmx.com |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/hostinger.svg\" width=\"16\"\u003e | Hostinger | imap.hostinger.com |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/godaddy.svg\" width=\"16\"\u003e | GoDaddy | imap.secureserver.net |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/namecheap.svg\" width=\"16\"\u003e | Namecheap | mail.privateemail.com |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/gandi.svg\" width=\"16\"\u003e | Gandi | mail.gandi.net |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/ovh.svg\" width=\"16\"\u003e | OVH | ssl0.ovh.net |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/ionos.svg\" width=\"16\"\u003e | Ionos (1\u00261) | imap.ionos.com |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/email.svg\" width=\"16\"\u003e | Fastmail | imap.fastmail.com |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/email.svg\" width=\"16\"\u003e | Rackspace | secure.emailsrvr.com |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/email.svg\" width=\"16\"\u003e | Titan | imap.titan.email |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/email.svg\" width=\"16\"\u003e | Locaweb | imap.locaweb.com.br |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/email.svg\" width=\"16\"\u003e | KingHost | imap.kinghost.net |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/email.svg\" width=\"16\"\u003e | UOL | imap.uol.com.br |\n| \u003cimg src=\"https://raw.githubusercontent.com/linux-profile/email-profile/develop/docs/assets/icons/email.svg\" width=\"16\"\u003e | Terra | imap.terra.com.br |\n\nAny server with DNS SRV or MX records is also detected automatically.\n\n## Environment Variables\n\n```env\nEMAIL_USERNAME=user@example.com\nEMAIL_PASSWORD=app_password\nEMAIL_SERVER=imap.example.com  # optional, auto-discovered\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinux-profile%2Femail-profile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinux-profile%2Femail-profile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinux-profile%2Femail-profile/lists"}