org-mac-link replaces org-mac-link-grabber
[worg.git] / org-contrib / org-mac-message.org
1 #+TITLE:     org-mac-message.el -- linking to messages in OS X Mail.app
2 #+OPTIONS:   ^:{} author:nil
3 #+STARTUP: odd
4
5 [[file:index.org][{Back to Worg's contibutions index}]]
6
7 The org-mac-message.el library provides various methods for linking
8 to OS X Mail.app messages from within org-mode.
9
10 * Installation
11   - To load org-mac-message.el by default:
12
13     : (add-to-list 'org-modules 'org-mac-message)
14
15     Note that =org-modules= must be set before org-mode is loaded.
16
17   - Configure the default Mail.app account you would like to use:
18
19     : (setq org-mac-mail-account "account")
20
21 * Usage
22   org-mac-message.el will create links with the format:
23
24   : [[message://message-ID][Subject]]
25
26   When followed, these links will open the relevant message in
27   Mail.app.
28
29 ** New functions
30
31    - =(org-mac-message-insert-selected)= :: 
32
33         Inserts formatted list of links at point to selected messages
34         in Mail.app.
35
36         To ensure backwards compatability,
37         =(org-mac-message-insert-link)= is aliased to this function.
38
39    - =(org-mac-message-insert-flagged (org-buffer org-heading))= :: 
40
41         Asks for an org buffer and heading within it.  If the heading
42         does not exist, create it at `point-max'.
43      
44         *Warning: the next step is destructive* 
45         
46         Search for flagged mail in Mail.app and insert a formatted list.
47         Delete all =message://= links within the heading's first level.
48         of links under the specified heading.
49
50         If you have [[http://growl.info][Growl]] installed, notifications will inform you of
51         the progress of the AppleScript search.
52
53    - =(org-mac-message-get-links (select-or-flag)= :: 
54
55         Searches for selected messages or flagged messages in the
56         Mail.app account specified by =org-mac-mail-account=.  Creates
57         a formatted list of these links and copies them to the
58         kill-ring.
59
60 ** Examples of usage
61    The following function will search the account =Gmail= for flagged
62    messages and insert them in the org-mode buffer =taskpool.org= under
63    the heading =Flagged mail=.
64   
65 #+BEGIN_SRC emacs-lisp
66 (defun my-mail-import ()
67   (let ((org-mac-mail-account "Gmail"))
68     (org-mac-message-insert-flagged "taskpool.org" "Flagged mail")))
69 #+END_SRC
70
71     This function could then be linked to from an org-mode buffer:
72     
73     : [[elisp:(my-mail-import)][Flagged%20Gmail]]
74
75     or set as a command in the agenda dispatcher:
76
77 #+BEGIN_SRC emacs-lisp
78 (setq org-agenda custom-commands
79       '(("F" "Import links to flagged mail" agenda ""
80          ((org-agenda-mode-hook
81            (my-mail-import))))))
82 #+END_SRC
83
84    
85
86
87    
88            
89