
Clarifications of nsimap API

command               comment
ns_imap check #s      Requires a mailbox to be selected first.
ns_imap list #s ref pattern ?substr?     (ditto)


Complete list of nsimap API:

# ns_imap status #s 
# ns_imap error #s  ???
# ns_imap expunge #s   Deletes email in trash folder
# ns_imap ping #s
# ns_imap check #s

# ns_imap n_msgs #s  Returns total count of messages in mailbox
# ns_imap n_recent #s Returns count of messages since last ping???
# For the task of incoming, get value of "Unseen" from ns_imap status
# 

# ns_imap list #s  list of mailbox using reference and pattern.
#                    glob with * for all mailboxes or % for * w/o ones in tree
# ns_imap lsub #s is ns_imap list for only subscribed mailboxes


# Options with #session and mailbox or other params
# ns_imap append #s mailbox text
# ns_imap copy #s sequence mailbox
# ns_imap move #s sequence mailbox
# ns_imap m_create #s mailbox
# ns_imap m_delete #s mailbox
# ns_imap m_rename #s mailbox newname
# ns_imap search # searchCriteria (IMap2 criteria only)
# ns_imap subscribe #s mailbox
# ns_imap unsubscribe #s mailbox
# ns_imap sort #s criteria reverse -flags

#other 
# ns_imap parsedate datestring
# ns_imap getquote #s root
# ns_imap setquota #s root size
# ns_imap setacl #s mailbox user value

#email specific
# ns_imap uid #s msgno   (gets UID of msgno)
# ns_imap struct #s msgno  Returns UID of msgno, internal time info etc. For example:
'uid 4 flags {} size 1634 internaldate.day 16 internaldate.month 8 internaldate.year 2017 internaldate.hours 21 internaldate.minutes 3 internaldate.seconds 45 internaldate.zoccident 0 internaldate.zhours 0 internaldate.zminutes 0 type text encoding 7bit subtype PLAIN lines 10 bytes 169 \
body.charset utf-8 \
body.format flowed \
msgno 3'

another example:

 'uid 6 flags {} size 3226 internaldate.day 17 internaldate.month 8 internaldate.year 2017 internaldate.hours 9 internaldate.minutes 25 internaldate.seconds 9 internaldate.zoccident 0 internaldate.zhours 0 internaldate.zminutes 0 type multipart encoding 7bit subtype REPORT \
body.report-type delivery-status \
body.boundary 1F5D214C96DE.1502961909/or97.net \
part.1 {type text encoding 7bit subtype PLAIN description Notification lines 15 bytes 589 body.charset us-ascii} \
part.2 {type message encoding 7bit subtype DELIVERY-STATUS description {Delivery report} bytes 449} \
part.3 {type message encoding 7bit subtype RFC822 description {Undelivered Message} lines 28 bytes 1134 message {type text encoding 7bit subtype PLAIN lines 3 bytes 10 body.charset utf-8 body.format flowed}} \
part.count 3 msgno 5'

some more examples with varying attachments and content. uid 12 has nested example.

'uid 2 flags {} size 2929 internaldate.day 2 internaldate.month 8 internaldate.year 2017 internaldate.hours 8 internaldate.minutes 17 internaldate.seconds 49 internaldate.zoccident 0 internaldate.zhours 0 internaldate.zminutes 0 type text encoding 7bit subtype PLAIN lines 1 bytes 6 body.charset utf-8 body.format flowed msgno 1'

'uid 3 flags {} size 1268 internaldate.day 16 internaldate.month 8 internaldate.year 2017 internaldate.hours 20 internaldate.minutes 49 internaldate.seconds 8 internaldate.zoccident 0 internaldate.zhours 0 internaldate.zminutes 0 type text encoding 7bit subtype PLAIN lines 1 bytes 6 body.charset utf-8 body.format flowed msgno 2'

'uid 4 flags {} size 1634 internaldate.day 16 internaldate.month 8 internaldate.year 2017 internaldate.hours 21 internaldate.minutes 3 internaldate.seconds 45 internaldate.zoccident 0 internaldate.zhours 0 internaldate.zminutes 0 type text encoding 7bit subtype PLAIN lines 10 bytes 169 body.charset utf-8 body.format flowed msgno 3'

'uid 5 flags {} size 3295 internaldate.day 17 internaldate.month 8 internaldate.year 2017 internaldate.hours 9 internaldate.minutes 24 internaldate.seconds 53 internaldate.zoccident 0 internaldate.zhours 0 internaldate.zminutes 0 type multipart encoding 7bit subtype REPORT body.report-type delivery-status body.boundary 064B414C913C.1502961893/or97.net \
part.1 {type text encoding 7bit subtype PLAIN description Notification lines 16 bytes 629 body.charset us-ascii} \
part.2 {type message encoding 7bit subtype DELIVERY-STATUS description {Delivery report} bytes 480} \
part.3 {type message encoding 7bit subtype RFC822 description 'uid 4 flags {} size 1634 internaldate.day 16 internaldate.month 8 internaldate.year 2017 internaldate.hours 21 internaldate.minutes 3 internaldate.seconds 45 internaldate.zoccident 0 internaldate.zhours 0 internaldate.zminutes 0 type text encoding 7bit subtype PLAIN lines 10 bytes 169 body.charset utf-8 body.format flowed msgno 3'

'uid 6 flags {} size 3226 internaldate.day 17 internaldate.month 8 internaldate.year 2017 internaldate.hours 9 internaldate.minutes 25 internaldate.seconds 9 internaldate.zoccident 0 internaldate.zhours 0 internaldate.zminutes 0 type multipart encoding 7bit subtype REPORT body.report-type delivery-status body.boundary 1F5D214C96DE.1502961909/or97.net \
part.1 {type text encoding 7bit subtype PLAIN description Notification lines 15 bytes 589 body.charset us-ascii} \
part.2 {type message encoding 7bit subtype DELIVERY-STATUS description {Delivery report} bytes 449} \
part.3 {type message encoding 7bit subtype RFC822 description {Undelivered Message} lines 28 bytes 1134 message {type text encoding 7bit subtype PLAIN lines 3 bytes 10 body.charset utf-8 body.format flowed}} \
part.count 3 msgno 5'

'uid 7 flags A size 4452633 internaldate.day 13 internaldate.month 8 internaldate.year 2017 internaldate.hours 18 internaldate.minutes 7 internaldate.seconds 46 internaldate.zoccident 0 internaldate.zhours 0 internaldate.zminutes 0 type multipart encoding 7bit subtype MIXED body.boundary ------------EA9B7FF02CD92F6E7BE79B91 \
part.1 {type text encoding 7bit subtype PLAIN lines 7 bytes 238 body.charset windows-1252 body.format flowed} \
part.2 {type image encoding base64 subtype JPEG bytes 4447046 disposition ATTACHMENT disposition.filename IMG_5951.JPG body.name IMG_5951.JPG} \
part.3 {type text encoding 7bit subtype PLAIN lines 4 bytes 27 disposition ATTACHMENT disposition.filename {Attached Message Part} body.charset UTF-8 body.name {Attached Message Part}} \
part.count 3 msgno 6'

'uid 8 flags {} size 2317061 internaldate.day 10 internaldate.month 8 internaldate.year 2017 internaldate.hours 6 internaldate.minutes 12 internaldate.seconds 14 internaldate.zoccident 0 internaldate.zhours 0 internaldate.zminutes 0 type multipart encoding 7bit subtype MIXED body.boundary Apple-Mail-83B5FB6A-752A-457E-B193-3A9DFD99C5FB \
part.1 {type text encoding 7bit subtype PLAIN lines 2 bytes 4 body.charset us-ascii} \
part.2 {type image encoding base64 subtype JPEG bytes 2312000 disposition INLINE disposition.filename IMG_0725.JPG body.name IMG_0725.JPG body.x-apple-part-url 060021DF-68C0-4C1F-BDC8-FDEE8363B2DF} \
part.3 {type text encoding 7bit subtype PLAIN lines 3 bytes 25 body.charset us-ascii} \
part.count 3 msgno 7'

'uid 9 flags {} size 91768 internaldate.day 2 internaldate.month 8 internaldate.year 2017 internaldate.hours 10 internaldate.minutes 33 internaldate.seconds 48 internaldate.zoccident 0 internaldate.zhours 0 internaldate.zminutes 0 type multipart encoding 7bit subtype MIXED body.boundary 94eb2c11522ea41fb70555c2cc9f \
part.1 {type multipart encoding 7bit subtype ALTERNATIVE body.boundary 94eb2c11522ea41fb20555c2cc9d \
part.1 {type text encoding 7bit subtype PLAIN lines 35 bytes 821 body.charset UTF-8 body.format flowed body.delsp yes} \
part.2 {type text encoding qprint subtype HTML lines 138 bytes 4294 body.charset UTF-8} \
part.count 2} \
part.2 {type application encoding base64 subtype PDF bytes 80754 disposition ATTACHMENT disposition.filename 5070312172586741-12.pdf body.name 5070312172586741-12.pdf} \
part.count 2 msgno 8'

 'uid 10 flags {} size 11267 internaldate.day 27 internaldate.month 3 internaldate.year 2015 internaldate.hours 11 internaldate.minutes 0 internaldate.seconds 21 internaldate.zoccident 0 internaldate.zhours 0 internaldate.zminutes 0 type multipart encoding 7bit subtype MIXED body.boundary 001a11c1f5eeecc5f4051243090a \
part.1 {type text encoding 7bit subtype PLAIN lines 4 bytes 272 body.charset UTF-8} \
part.2 {type application encoding base64 subtype X-DIA-DIAGRAM bytes 2696 disposition ATTACHMENT disposition.filename xdcpm-openacs-core-github-3.dia body.name xdcpm-openacs-core-github-3.dia} \
part.3 {type application encoding base64 subtype X-DIA-DIAGRAM bytes 3074 disposition ATTACHMENT disposition.filename xdcpm-openacs-core-github-4.dia body.name xdcpm-openacs-core-github-4.dia} \
part.count 3 msgno 9'

'uid 11 flags A size 15479 internaldate.day 3 internaldate.month 4 internaldate.year 2015 internaldate.hours 9 internaldate.minutes 59 internaldate.seconds 8 internaldate.zoccident 0 internaldate.zhours 0 internaldate.zminutes 0 type multipart encoding 7bit subtype MIXED body.boundary ------------080507060504090603040608 \
part.1 {type text encoding 7bit subtype PLAIN lines 150 bytes 5716 body.charset utf-8 body.format flowed} \
part.2 {type text encoding base64 subtype PLAIN lines 61 bytes 4542 disposition ATTACHMENT disposition.filename xdcpm-parallel-dev-process1.txt body.charset UTF-8 body.name xdcpm-parallel-dev-process1.txt} \
part.3 {type application encoding base64 subtype OCTET-STREAM bytes 3000 disposition ATTACHMENT disposition.filename xdcpm-parallel-dev-process1.dia body.x-mac-type 0 body.x-mac-creator 0 body.name xdcpm-parallel-dev-process1.dia} \
part.count 3 msgno 10'

 'uid 12 flags {} size 33487 internaldate.day 28 internaldate.month 1 internaldate.year 2017 internaldate.hours 4 internaldate.minutes 15 internaldate.seconds 7 internaldate.zoccident 0 internaldate.zhours 0 internaldate.zminutes 0 type multipart encoding 7bit subtype MIXED body.boundary ----=_Part_22057419_699298704.1485580507727 \
part.1 {type multipart encoding 7bit subtype ALTERNATIVE body.boundary ----=_Part_22057420_472295197.1485580507727 \
part.1 {type text encoding qprint subtype PLAIN lines 87 bytes 2182 disposition INLINE body.charset UTF-8} \
part.2 {type text encoding qprint subtype X-WATCH-HTML lines 11 bytes 286 disposition INLINE body.charset UTF-8} \
part.3 {type text encoding qprint subtype HTML lines 703 bytes 26358 disposition INLINE body.charset UTF-8} \
part.count 3} \
part.2 {type text encoding base64 subtype CALENDAR lines 13 bytes 1046 disposition ATTACHMENT disposition.filename Apple_Support_Appt.ics} \
part.count 2 msgno 11'




# ns_imap headers #s msgno ?-array arr_name
# ns_imap header #s msgno hdrname
# ns_imap text #s msgno -flags UID/PEEK/INTERNAL (peek doesn't set \Seen flag)
# ns_imap body #s msgno part -flags UID/PEEK/INTERNAL
# ns_imap bodystruct #s msgno part -flags 
# ns_imap delete #s sequence -flags
# ns_imap undelete #s sequence flags


Other useful lib procs provided by ns_map:

  ns_imap parsedate datestring
        parses date/time string and returns seconds since epoch if date is
        correct or empty string if not

  ns_imap uid #s msgno
        returns UID for specified message number

  ns_imap striphtml text ?tags?
        strips dangerous HTML tags from the given HTML text, 
        by default it removes body/title/div/object/frame tags.
        If tags are specified it will use them instead of internal list.

  ns_imap encode type data
  ns_imap decode type data
        performs encodeing/decoding given text according given format.
        type may be one of the following: base64 qprint
