All Projects → ikvk → Imap_tools

ikvk / Imap_tools

Licence: apache-2.0
Work with email and mailbox by IMAP

Programming Languages

python
139335 projects - #7 most used programming language
python3
1442 projects

Labels

Projects that are alternatives of or similar to Imap tools

Imap
Object-oriented, fully tested PHP IMAP library
Stars: ✭ 678 (+305.99%)
Mutual labels:  email, imap
Mnm
The legitimate email replacement — n-identity, decentralized, store-and-forward, open protocol, open source. (Server)
Stars: ✭ 162 (-2.99%)
Mutual labels:  email, imap
Kanmail
📥 An email client that functions like a kanban board.
Stars: ✭ 833 (+398.8%)
Mutual labels:  email, imap
Mailkit
A cross-platform .NET library for IMAP, POP3, and SMTP.
Stars: ✭ 4,477 (+2580.84%)
Mutual labels:  email, imap
Mailspring
💌 A beautiful, fast and fully open source mail client for Mac, Windows and Linux.
Stars: ✭ 11,953 (+7057.49%)
Mutual labels:  email, imap
Sieve
Sieve Script Editor
Stars: ✭ 452 (+170.66%)
Mutual labels:  email, imap
How to get emails imap tutorial
How to get emails including there attachments and how to extract various attributes from those emails. See https://youtu.be/zFEEGkvo6O8 for a more detailed information.
Stars: ✭ 30 (-82.04%)
Mutual labels:  email, imap
ESP-Mail-Client
⚡️Arduino Mail Client Library to send, read and get incoming mail notification for ESP32, ESP8266 and SAMD21 devices. The library also supported other Arduino devices using Clients interfaces e.g. WiFiClient, EthernetClient, and GSMClient.
Stars: ✭ 78 (-53.29%)
Mutual labels:  email, imap
Opaquemail
.NET email library and proxy supporting IMAP, POP3, and SMTP with S/MIME and PGP.
Stars: ✭ 91 (-45.51%)
Mutual labels:  email, imap
Inbrief
InBrief is a personal briefing app and dashboard powered by Electron and React
Stars: ✭ 90 (-46.11%)
Mutual labels:  email, imap
Deltachat Core Rust
Delta Chat Rust Core library, used by Android/iOS/desktop apps and bindings
Stars: ✭ 300 (+79.64%)
Mutual labels:  email, imap
Magma
The magma server daemon, is an encrypted email system with support for SMTP, POP, IMAP, HTTP and MOLTEN,. Additional support for DMTP and DMAP is currently in active development.
Stars: ✭ 1,740 (+941.92%)
Mutual labels:  email, imap
Php Imap Client
a easy solution for simple IMAP email access in php
Stars: ✭ 254 (+52.1%)
Mutual labels:  email, imap
Deltachat Desktop
Email-based instant messaging for Desktop.
Stars: ✭ 526 (+214.97%)
Mutual labels:  email, imap
imapx
A cross-platform IMAP library for .NET, supporting .Net 2.0 - 4.5, Mono and Windows Phone
Stars: ✭ 28 (-83.23%)
Mutual labels:  email, imap
Nioimapclient
High performance, async IMAP client implementation
Stars: ✭ 28 (-83.23%)
Mutual labels:  email, imap
yggmail
End-to-end encrypted email for the mesh networking age
Stars: ✭ 72 (-56.89%)
Mutual labels:  email, imap
himalaya
Command-line interface for email management
Stars: ✭ 1,715 (+926.95%)
Mutual labels:  email, imap
Imapcopy
Recursively copy all e-mail messages and folders from one IMAP account to another.
Stars: ✭ 52 (-68.86%)
Mutual labels:  email, imap
Mail
Mail app designed for elementary OS
Stars: ✭ 130 (-22.16%)
Mutual labels:  email, imap

.. http://docutils.sourceforge.net/docs/user/rst/quickref.html

imap_tools

Work with email and mailbox by IMAP:

  • Parsed email message attributes
  • Query builder for searching emails
  • Actions with emails: copy, delete, flag, move, seen, append
  • Actions with folders: list, set, get, create, exists, rename, delete, status
  • No dependencies

.. image:: https://img.shields.io/pypi/dm/imap_tools.svg?style=social

=============== =============================================================== Python version 3.3+ License Apache-2.0 PyPI https://pypi.python.org/pypi/imap_tools/ IMAP RFC VERSION 4rev1 - https://tools.ietf.org/html/rfc3501 EMAIL RFC Internet Message Format - https://tools.ietf.org/html/rfc2822 =============== ===============================================================

.. contents::

Installation

::

$ pip install imap-tools

Guide

Basic ^^^^^ .. code-block:: python

from imap_tools import MailBox, AND

# get list of email subjects from INBOX folder
with MailBox('imap.mail.com').login('[email protected]', 'pwd') as mailbox:
    subjects = [msg.subject for msg in mailbox.fetch()]

# get list of email subjects from INBOX folder - equivalent verbose version
mailbox = MailBox('imap.mail.com')
mailbox.login('[email protected]', 'pwd', initial_folder='INBOX')  # or mailbox.folder.set instead 3d arg
subjects = [msg.subject for msg in mailbox.fetch(AND(all=True))]
mailbox.logout()

MailBox(BaseMailBox), MailBoxUnencrypted(BaseMailBox) - for create mailbox instance.

BaseMailBox.login, MailBox.xoauth2 - authentication functions

BaseMailBox.fetch - email message generator, first searches email nums by criteria, then fetch and yields MailMessage <#email-attributes>_:

  • criteria = 'ALL', message search criteria, query builder <#search-criteria>_
  • charset = 'US-ASCII', indicates charset of the strings that appear in the search criteria. See rfc2978
  • limit = None, limit on the number of read emails, useful for actions with a large number of messages, like "move"
  • miss_defect = True, miss emails with defects
  • miss_no_uid = True, miss emails without uid
  • mark_seen = True, mark emails as seen on fetch
  • reverse = False, in order from the larger date to the smaller
  • headers_only = False, get only email headers (without text, html, attachments)
  • bulk = False, False - fetch each message separately per N commands - low memory consumption, slow; True - fetch all messages per 1 command - high memory consumption, fast

BaseMailBox. - copy, move, delete, flag, seen, append <#actions-with-emails>_

BaseMailBox.folder - folder manager <#actions-with-folders>_

BaseMailBox.search - search mailbox for matching message numbers (this is not uids)

BaseMailBox.box - imaplib.IMAP4/IMAP4_SSL client instance.

Email attributes ^^^^^^^^^^^^^^^^

MailMessage and MailAttachment public attributes are cached by functools.lru_cache

.. code-block:: python

for msg in mailbox.fetch():  # iter: imap_tools.MailMessage
    msg.uid          # str or None: '123'
    msg.subject      # str: 'some subject 你 привет'
    msg.from_        # str: 'Sender.Bartö[email protected]'
    msg.to           # tuple: ('[email protected]', '[email protected]', )
    msg.cc           # tuple: ('[email protected]', )
    msg.bcc          # tuple: ('[email protected]', )
    msg.reply_to     # tuple: ('[email protected]', )
    msg.date         # datetime.datetime: 1900-1-1 for unparsed, may be naive or with tzinfo
    msg.date_str     # str: original date - 'Tue, 03 Jan 2017 22:26:59 +0500'
    msg.text         # str: 'Hello 你 Привет'
    msg.html         # str: '<b>Hello 你 Привет</b>'
    msg.flags        # tuple: ('SEEN', 'FLAGGED', 'ENCRYPTED')
    msg.headers      # dict: {'received': ('from 1.m.ru', 'from 2.m.ru'), 'anti-virus': ('Clean',)}
    msg.size_rfc822  # int: 20664 bytes - size info from server (*useful with headers_only arg)
    msg.size         # int: 20377 bytes

    for att in msg.attachments:  # list: imap_tools.MailAttachment
        att.filename             # str: 'cat.jpg'
        att.payload              # bytes: b'\xff\xd8\xff\xe0\'
        att.content_id           # str: '[email protected]'
        att.content_type         # str: 'image/jpeg'
        att.content_disposition  # str: 'inline'
        att.part                 # email.message.Message: original object
        att.size                 # int: 17361 bytes

    msg.obj              # email.message.Message: original object
    msg.from_values      # dict or None: {'email': '[email protected]', 'name': 'Ya 你', 'full': 'Ya 你 <[email protected]>'}
    msg.to_values        # tuple: ({'email': '', 'name': '', 'full': ''},)
    msg.cc_values        # tuple: ({'email': '', 'name': '', 'full': ''},)
    msg.bcc_values       # tuple: ({'email': '', 'name': '', 'full': ''},)
    msg.reply_to_values  # tuple: ({'email': '', 'name': '', 'full': ''},)

Search criteria ^^^^^^^^^^^^^^^

This chapter about "criteria" and "charset" arguments of MailBox.fetch.

You can use 3 approaches to build search criteria:

.. code-block:: python

from imap_tools import AND, OR, NOT

mailbox.fetch(AND(subject='weather'))  # query, the str-like object
mailbox.fetch('TEXT "hello"')          # str
mailbox.fetch(b'TEXT "\xd1\x8f"')      # bytes, *charset arg is ignored

The "charset" is argument used for encode criteria to this encoding. You can pass criteria as bytes in desired encoding - charset will be ignored.

Query builder implements all search logic described in rfc3501 <https://tools.ietf.org/html/rfc3501#section-6.4.4>_.

======== ===== ========================================== ============================================================ Class Alias Usage Arguments ======== ===== ========================================== ============================================================ AND A combines keys by logical "AND" condition Search keys (see below) | str OR O combines keys by logical "OR" condition Search keys (see below) | str NOT N invert the result of a logical expression AND/OR instances | str Header H for search by headers name: str, value: str UidRange U for search by UID range start: str, end: str ======== ===== ========================================== ============================================================

.. code-block:: python

from imap_tools import A, AND, OR, NOT
# AND
A(text='hello', new=True)  # '(TEXT "hello" NEW)'
# OR
OR(text='hello', date=datetime.date(2000, 3, 15))  # '(OR TEXT "hello" ON 15-Mar-2000)'
# NOT
NOT(text='hello', new=True)  # 'NOT (TEXT "hello" NEW)'
# complex
A(OR(from_='[email protected]', text='"the text"'), NOT(OR(A(answered=False), A(new=True))), to='[email protected]')
# encoding
mailbox.fetch(A(subject='привет'), charset='utf8')
# python note: you can't do: A(text='two', NOT(subject='one'))
A(NOT(subject='one'), text='two')  # use kwargs after logic classes (args)

See more query examples <https://github.com/ikvk/imap_tools/blob/master/examples/search.py>_.

Search key table. Key types marked with * can accepts a sequence of values like list, tuple, set or generator.

============= =============== ====================== ================================================================= Key Types Results Description ============= =============== ====================== ================================================================= answered bool ANSWERED/UNANSWERED with/without the Answered flag seen bool SEEN/UNSEEN with/without the Seen flag flagged bool FLAGGED/UNFLAGGED with/without the Flagged flag draft bool DRAFT/UNDRAFT with/without the Draft flag deleted bool DELETED/UNDELETED with/without the Deleted flag keyword str* KEYWORD KEY with the specified keyword flag no_keyword str* UNKEYWORD KEY without the specified keyword flag from_ str* FROM "[email protected]" contain specified str in envelope struct's FROM field to str* TO "[email protected]" contain specified str in envelope struct's TO field subject str* SUBJECT "hello" contain specified str in envelope struct's SUBJECT field body str* BODY "some_key" contain specified str in body of the message text str* TEXT "some_key" contain specified str in header or body of the message bcc str* BCC "[email protected]" contain specified str in envelope struct's BCC field cc str* CC "[email protected]" contain specified str in envelope struct's CC field date datetime.date* ON 15-Mar-2000 internal date is within specified date date_gte datetime.date* SINCE 15-Mar-2000 internal date is within or later than the specified date date_lt datetime.date* BEFORE 15-Mar-2000 internal date is earlier than the specified date sent_date datetime.date* SENTON 15-Mar-2000 rfc2822 Date: header is within the specified date sent_date_gte datetime.date* SENTSINCE 15-Mar-2000 rfc2822 Date: header is within or later than the specified date sent_date_lt datetime.date* SENTBEFORE 1-Mar-2000 rfc2822 Date: header is earlier than the specified date size_gt int >= 0 LARGER 1024 rfc2822 size larger than specified number of octets size_lt int >= 0 SMALLER 512 rfc2822 size smaller than specified number of octets new True NEW have the Recent flag set but not the Seen flag old True OLD do not have the Recent flag set recent True RECENT have the Recent flag set all True ALL all, criteria by default uid iter(str)/str/U UID 1,2,17 corresponding to the specified unique identifier set header H(str, str)* HEADER "A-Spam" "5.8" have a header that contains the specified str in the text gmail_label str* X-GM-LABELS "label1" have this gmail label. ============= =============== ====================== =================================================================

Server side search notes:

  • For string search keys a message matches if the string is a substring of the field. The matching is case-insensitive.
  • When searching by dates - email's time and timezone are disregarding.

Actions with emails ^^^^^^^^^^^^^^^^^^^

First of all read about uid at rfc3501 <https://tools.ietf.org/html/rfc3501#section-2.3.1.1>_.

You can use 2 approaches to perform these operations:

  • "in bulk" - Perform IMAP operation for message set per 1 command
  • "by one" - Perform IMAP operation for each message separately per N commands

MailBox.fetch generator instance passed as the first argument to any action will be implicitly converted to uid list.

For actions with a large number of messages imap command may be too large and will cause exception at server side, use 'limit' argument for fetch in this case.

.. code-block:: python

with MailBox('imap.mail.com').login('[email protected]', 'pwd', initial_folder='INBOX') as mailbox:

    # COPY all messages from current folder to folder1, *by one
    for msg in mailbox.fetch():
        res = mailbox.copy(msg.uid, 'INBOX/folder1')

    # MOVE all messages from current folder to folder2, *in bulk (implicit creation of uid list)
    mailbox.move(mailbox.fetch(), 'INBOX/folder2')

    # DELETE all messages from current folder, *in bulk (explicit creation of uid list)
    mailbox.delete([msg.uid for msg in mailbox.fetch()])

    # FLAG unseen messages in current folder as Answered and Flagged, *in bulk.
    flags = (imap_tools.MailMessageFlags.ANSWERED, imap_tools.MailMessageFlags.FLAGGED)
    mailbox.flag(mailbox.fetch(AND(seen=False)), flags, True)

    # SEEN: flag as unseen all messages sent at 05.03.2007 in current folder, *in bulk
    mailbox.seen(mailbox.fetch("SENTON 05-Mar-2007"), False)

    # APPEND: add message to mailbox directly, to INBOX folder with SEEN flag and now date
    with open('/tmp/message.eml', 'rb') as f:
        msg = imap_tools.MailMessage.from_bytes(f.read())  # *or use bytes instead MailMessage
    mailbox.append(msg, 'INBOX', dt=None, flag_set=[imap_tools.MailMessageFlags.SEEN])

Actions with folders ^^^^^^^^^^^^^^^^^^^^ .. code-block:: python

with MailBox('imap.mail.com').login('[email protected]', 'pwd') as mailbox:
    # LIST
    for f in mailbox.folder.list('INBOX'):
        print(f)  # {'name': 'INBOX|cats', 'delim': '|', 'flags': ('\\Unmarked', '\\HasChildren')}
    # SET
    mailbox.folder.set('INBOX')
    # GET
    current_folder = mailbox.folder.get()
    # CREATE
    mailbox.folder.create('folder1')
    # EXISTS
    is_exists = mailbox.folder.exists('folder1')
    # RENAME
    mailbox.folder.rename('folder1', 'folder2')
    # DELETE
    mailbox.folder.delete('folder2')
    # STATUS
    stat = mailbox.folder.status('some_folder')
    print(stat)  # {'MESSAGES': 41, 'RECENT': 0, 'UIDNEXT': 11996, 'UIDVALIDITY': 1, 'UNSEEN': 5}

Exceptions ^^^^^^^^^^

Custom lib exceptions here: errors.py <https://github.com/ikvk/imap_tools/blob/master/imap_tools/errors.py>_.

Release notes

History of important changes: release_notes.rst <https://github.com/ikvk/imap_tools/blob/master/docs/release_notes.rst>_

Contribute

If you found a bug or have a question, please let me know - create merge request or issue.

Reasons

  • Excessive low level of imaplib library.
  • Other libraries contain various shortcomings or not convenient.
  • Open source projects make world better.

Thanks

Big thanks to people who helped develop this library:

shilkazx <https://github.com/shilkazx>, somepad <https://github.com/somepad>, 0xThiebaut <https://github.com/0xThiebaut>, TpyoKnig <https://github.com/TpyoKnig>, parchd-1 <https://github.com/parchd-1>, dojasoncom <https://github.com/dojasoncom>, RandomStrangerOnTheInternet <https://github.com/RandomStrangerOnTheInternet>, jonnyarnold <https://github.com/jonnyarnold>, Mitrich3000 <https://github.com/Mitrich3000>, audemed44 <https://github.com/audemed44>, mkalioby <https://github.com/mkalioby>, atlas0fd00m <https://github.com/atlas0fd00m>, unqx <https://github.com/unqx>, daitangio <https://github.com/daitangio>, upils <https://github.com/upils>, Foosec <https://github.com/Foosec>, frispete <https://github.com/frispete>, PH89 <https://github.com/PH89>, amarkham09 <https://github.com/amarkham09>, nixCodeX <https://github.com/nixCodeX>, backelj <https://github.com/backelj>, ohayak <https://github.com/ohayak>, mwherman95926 <https://github.com/mwherman95926>, andyfensham <https://github.com/andyfensham>, mike-code <https://github.com/mike-code>, aknrdureegaesr <https://github.com/aknrdureegaesr>, ktulinger <https://github.com/ktulinger>, SamGenTLEManKaka <https://github.com/SamGenTLEManKaka>, devkral <https://github.com/devkral>, tnusraddinov <https://github.com/tnusraddinov>, thepeshka <https://github.com/thepeshka>, shofstet <https://github.com/shofstet>, the7erm <https://github.com/the7erm>, c0da <https://github.com/c0da>, dev4max <https://github.com/dev4max>, ascheucher <https://github.com/ascheucher>, Borutia <https://github.com/Borutia>, nathan30 <https://github.com/nathan30>, daniel55411 <https://github.com/daniel55411>, rcarmo <https://github.com/rcarmo>, bhernacki <https://github.com/bhernacki>, ilep <https://github.com/ilep>

💰 You may donate <https://github.com/ikvk/imap_tools/blob/master/docs/donate.rst>_, if this library helped you.

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].