README.md in chronicle-email-0.2.1 vs README.md in chronicle-email-0.2.2

@@ -7,20 +7,59 @@
 
 ```sh
 # Install chronicle-etl and this plugin
 $ gem install chronicle-etl
 $ chronicle-etl plugins:install email
+```
 
-# Process emails from an mbox file
-$ chronicle-etl --extractor email:mbox -i test.mbox  --transformer email --fields subject
+### Extracting email from IMAP
+
+For Gmail accounts, you can create an [app password](https://myaccount.google.com/apppasswords); your email address is your username.
+
+```sh
+# Save username and password
+$ chronicle-etl secrets:set imap username [e-mail]
+$ chronicle-etl secrets:set imap password APPPASSWORD
+
+# Then, retrieve your email from the last five days
+$ chronicle-etl --extractor email:imap --transformer email --since 5d --loader json
+
+# If you don't want to save your credentials as a secret, you can just pass
+# them to the extractor directly
+$ chronicle-etl --extractor email:imap --transformer email --since 5d --loader json \
+    --extractor-opts username:[e-mail] --password:APPPASSWORD
 ```
 
+### Processing email from an .mbox file
+The MBOX format is used to archive an email mailbox. [Google Takeout](https://takeout.google.com/settings/takeout) exports emails from gmail in this format.
+
+```sh
+# Retrieve the subject lines of all emails in test.mbox
+$ chronicle-etl --extractor email:mbox --input inbox.mbox --transformer email --fields subject
+```
+
 ## Available Connectors
 ### Extractors
 
+#### `imap`
+Extractor for importing recent emails from an IMAP server.
+
+##### Settings
+
+- `since`: Retrieve emails since this date
+- `until`: Retrieve emails until this date
+- `username`
+- `password`
+- `host`: (default: imap.gmail.com)
+- `port`: (default: 993) Use 143 for unencrypted connections
+- `mailbox`: (default: "[Gmail]/All Mail")
+- `search_query`: When using Gmail, you can pass in a search query (`from:foo has:attachment`) to filter messages by
+
+For accessing Gmail, you can create a one-time [app password](https://myaccount.google.com/apppasswords). Your email address is your username.
+
 #### `mbox`
-Extractor for importing emails from an mbox file
+Extractor for importing emails from an MBOX file
 
 ##### Settings
 - `input`: A path to an .mbox file
 
 ### Transformers
@@ -29,8 +68,5 @@
 Transform an email (in the form of a string) into Chronicle Schema
 
 ##### Settings
 - `body_as_markdown`: (default: false) Whether to convert the email body into markdown
 - `remove_signature`: (default: true) Whether to attempt to strip out the email signature (using the [`email_reply_parser`](https://github.com/github/email_reply_parser) gem)
-
-## Roadmap
-- Add an IMAP (and gmail) extractor #1
\ No newline at end of file