The user-friendly, lightweight, and fast email client Latest Release: 3.20.0 / 4.2.0 (News), on 20 November 2023

The Python plugin

This plugin offers Python scripting access to Claws Mail.

Python code can be entered interactively into an embedded Python
console, or stored in scripts. 

These scripts are then available via the menu. You can assign
keyboard shortcuts to them just like it is done with other menu items.
You can also put buttons for script invokation into the toolbars
using Claws Mail's builtin toolbar editor.

You can provide scripts working on the main window by placing files
into ~/.claws-mail/python-scripts/main.

You can also provide scripts working on an open compose window
by placing files into ~/.claws-mail/python-scripts/compose.

The folder ~/.claws-mail/python-scripts/auto/ may contain some
scripts that are automatically executed when certain events
occur. Currently, the following files in this directory
are recognised:

  compose_any
  	Gets executed whenever a compose window is opened, no matter
  	if that opening happened as a result of composing a new message,
  	replying or forwarding a message.
  	
  startup
  	Executed at plugin load
  	
  shutdown
  	Executed at plugin unload

The distribution comes with some example scripts.

-------------------------------------------------------------------------------
DOCUMENTATION
(last updated 30-12-2015)

DESCRIPTION
    This module can be used to access some of Claws Mail's data structures
    in order to extend or modify the user interface or automate repetitive tasks.
    
    Whenever possible, the interface works with standard GTK+ widgets
    via the PyGTK bindings, so you can refer to the GTK+ / PyGTK documentation
    to find out about all possible options.
    
    The interface to Claws Mail in this module is extended on a 'as-needed' basis.
    If you're missing something specific, try contacting the author.

CLASSES
    __builtin__.object
        Account
        ComposeWindow
        Folder
        FolderProperties
        Mailbox
        MessageInfo
        Node
    
    class Account(__builtin__.object)
     |  Account objects.
     |  
     |  Do not construct objects of this type yourself.
     |  
     |  Methods defined here:
     |  
     |  __cmp__(...)
     |      x.__cmp__(y) <==> cmp(x,y)
     |  
     |  __init__(...)
     |      x.__init__(...) initializes x; see help(type(x)) for signature
     |  
     |  __str__(...)
     |      x.__str__() <==> str(x)
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  account_name
     |      account_name - name of the account
     |  
     |  address
     |      address - address of the account
     |  
     |  is_default
     |      is_default - whether this account is the default account
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes defined here:
     |  
     |  __new__ = 
     |      T.__new__(S, ...) -> a new object with type S, a subtype of T
    
    class ComposeWindow(__builtin__.object)
     |  ComposeWindow objects. Optional argument to constructor: sender account address.
     |  
     |  Methods defined here:
     |  
     |  __init__(...)
     |      x.__init__(...) initializes x; see help(type(x)) for signature
     |  
     |  add_Bcc(...)
     |      add_Bcc(text) - append another Bcc header with text
     |      
     |      Add another header line with the combo box set to Bcc:, and the
     |      content set to text.
     |  
     |  add_Cc(...)
     |      add_Cc(text) - append another Cc header with text
     |      
     |      Add another header line with the combo box set to Cc:, and the
     |      content set to text.
     |  
     |  add_To(...)
     |      add_To(text) - append another To header with text
     |      
     |      Add another header line with the combo box set to To:, and the
     |      content set to text.
     |  
     |  add_header(...)
     |      add_header(headername, text) - add a custom header
     |      
     |      Adds a custom header with the header set to headername, and the
     |      contents set to text.
     |  
     |  attach(...)
     |      attach(filenames) - attach a list of files
     |      
     |      Attach files to the mail. The filenames argument is a list of
     |      string of the filenames that are being attached.
     |  
     |  get_account_selection(...)
     |      get_account_selection() - get account selection widget
     |      
     |      Returns the account selection combo box as a gtk.ComboBox
     |  
     |  get_from(...)
     |      get_from - get From header entry
     |      
     |      Get a string of the current From header entry.
     |  
     |  get_header_list(...)
     |      get_header_list() - get list of headers
     |      
     |      Gets a list of headers that are currently defined in the compose window.
     |      The return value is a list of tuples, where the first tuple element is
     |      the header name (entry in the combo box) and the second element is the contents.
     |  
     |  get_subject(...)
     |      get_subject() - get subject
     |      
     |      Get a string of the current subject entry.
     |  
     |  save_message_to(...)
     |      save_message_to(folder) - save message to folder id
     |      
     |      Set the folder where the sent message will be saved to. folder may be
     |      a Folder, a string of the folder identifier (e.g. #mh/foo/bar), or
     |      None is which case the message will not be saved at all.
     |  
     |  set_from(...)
     |      set_from(text) - set From header entry to text
     |      
     |      Set the From header entry to text. text must be a string.
     |      Beware: No sanity checking is performed.
     |  
     |  set_modified(...)
     |      set_modified(bool) - set or unset modification marker of compose window
     |      
     |      Set or unset the modification marker of the compose window. This marker determines
     |      for example whether you get a confirmation dialog when closing the compose window
     |      or not.
     |      In the usual case, Claws Mail keeps track of the modification status itself.
     |      However, there are cases when it might be desirable to overwrite the marker,
     |      for example because a compose_any script modifies the body or subject which
     |      can be regarded compose window preprocessing and should not trigger a confirmation
     |      dialog on close like a manual edit.
     |  
     |  set_subject(...)
     |      set_subject(text) - set subject to text
     |      
     |      Set the subject to text. text must be a string.
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  account
     |      account - the account corresponding to this compose window
     |  
     |  forwardinfo
     |      forwardinfo - The MessageInfo object of the message that is being forwarded, or None
     |  
     |  replyinfo
     |      replyinfo - The MessageInfo object of the message that is being replied to, or None
     |  
     |  text
     |      text - the gtk.TextView widget of the message body
     |  
     |  ui_manager
     |      ui_manager - the gtk.UIManager of the compose window
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes defined here:
     |  
     |  __new__ = 
     |      T.__new__(S, ...) -> a new object with type S, a subtype of T
    
    class Folder(__builtin__.object)
     |  Folder objects.
     |  
     |  The __init__ function takes two optional arguments:
     |  folder = Folder(identifier, [create_if_not_existing=False])
     |  The identifier is an id string (e.g. '#mh/Mail/foo/bar'),create_if_not_existing is a boolean expression.
     |  
     |  Methods defined here:
     |  
     |  __init__(...)
     |      x.__init__(...) initializes x; see help(type(x)) for signature
     |  
     |  __str__(...)
     |      x.__str__() <==> str(x)
     |  
     |  get_identifier(...)
     |      get_identifier() - get identifier
     |      
     |      Get identifier for folder as a string (e.g. #mh/foo/bar).
     |      
     |      DEPRECATED: Use identifier property instead.
     |  
     |  get_messages(...)
     |      get_messages() - get a tuple of messages in folder
     |      
     |      Get a tuple of MessageInfos for the folder.
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  identifier
     |      identifier - identifier of folder
     |  
     |  mailbox
     |      mailbox - corresponding mailbox
     |  
     |  mailbox_name
     |      mailbox_name - name of the corresponding mailbox
     |      
     |      DEPRECATED: Use folder.mailbox.name instead
     |  
     |  name
     |      name - name of folder
     |  
     |  num_forwarded_messages
     |      num_forwarded_messages - number of forwarded messages in folder
     |  
     |  num_ignored_messages
     |      num_ignored_messages - number of ignored messages in folder
     |  
     |  num_locked_messages
     |      num_locked_messages - number of locked messages in folder
     |  
     |  num_marked_messages
     |      num_marked_messages - number of marked messages in folder
     |  
     |  num_messages
     |      num_messages - total number of messages in folder
     |  
     |  num_new_messages
     |      num_new_messages - number of new messages in folder
     |  
     |  num_replied_messages
     |      num_replied_messages - number of replied messages in folder
     |  
     |  num_unread_marked_messages
     |      num_unread_marked_messages - number of unread marked messages in folder
     |  
     |  num_unread_messages
     |      num_unread_messages - number of unread messages in folder
     |  
     |  num_watched_messages
     |      num_watched_messages - number of watched messages in folder
     |  
     |  path
     |      path - path of folder
     |  
     |  properties
     |      properties - folder properties object
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes defined here:
     |  
     |  __new__ = 
     |      T.__new__(S, ...) -> a new object with type S, a subtype of T
    
    class FolderProperties(__builtin__.object)
     |  FolderProperties objects.
     |  
     |  Do not construct objects of this type yourself.
     |  
     |  Methods defined here:
     |  
     |  __init__(...)
     |      x.__init__(...) initializes x; see help(type(x)) for signature
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  default_account
     |      default_account - the default account when composing from this folder
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes defined here:
     |  
     |  __new__ = 
     |      T.__new__(S, ...) -> a new object with type S, a subtype of T
    
    class Mailbox(__builtin__.object)
     |  Mailbox objects.
     |  
     |  Do not construct objects of this type yourself.
     |  
     |  Methods defined here:
     |  
     |  __init__(...)
     |      x.__init__(...) initializes x; see help(type(x)) for signature
     |  
     |  __str__(...)
     |      x.__str__() <==> str(x)
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  name
     |      name - name of the mailbox
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes defined here:
     |  
     |  __new__ = 
     |      T.__new__(S, ...) -> a new object with type S, a subtype of T
    
    class MessageInfo(__builtin__.object)
     |  A MessageInfo represents a single message.
     |  
     |  Do not construct objects of this type yourself.
     |  
     |  Methods defined here:
     |  
     |  __init__(...)
     |      x.__init__(...) initializes x; see help(type(x)) for signature
     |  
     |  __str__(...)
     |      x.__str__() <==> str(x)
     |  
     |  add_tag(...)
     |      add_tag(tag) - add a tag to this message
     |      
     |      Add a tag to this message. If the tag is already set, nothing is done.
     |      If the tag does not exist, a ValueError exception is raised.
     |  
     |  get_header(...)
     |      get_header(name) - get a message header with a given name
     |      
     |      Get a message header content with a given name. If the header does not exist,
     |      the value 'None' is returned. If multiple headers with the same name exist,
     |      the first one is returned.
     |  
     |  get_tags(...)
     |      get_tags() - get message tags
     |      
     |      Returns a tuple of tags that apply to this message.
     |  
     |  is_forwarded(...)
     |      is_forwarded() - checks if the message has been forwarded
     |      
     |      Returns True if the forwarded flag of the message is set.
     |      
     |      This function is deprecated in favor of the 'forwarded' attribute.
     |  
     |  is_locked(...)
     |      is_locked() - checks if the message has been locked
     |      
     |      Returns True if the locked flag of the message is set.
     |      
     |      This function is deprecated in favor of the 'locked' attribute.
     |  
     |  is_marked(...)
     |      is_marked() - checks if the message is marked
     |      
     |      Returns True if the marked flag of the message is set.
     |      
     |      This function is deprecated in favor of the 'marked' attribute.
     |  
     |  is_new(...)
     |      is_new() - checks if the message is new
     |      
     |      Returns True if the new flag of the message is set.
     |      
     |      This function is deprecated in favor of the 'new' attribute.
     |  
     |  is_replied(...)
     |      is_replied() - checks if the message has been replied to
     |      
     |      Returns True if the replied flag of the message is set.
     |      
     |      This function is deprecated in favor of the 'replied' attribute.
     |  
     |  is_unread(...)
     |      is_unread() - checks if the message is unread
     |      
     |      Returns True if the unread flag of the message is set.
     |      
     |      This function is deprecated in favor of the 'unread' attribute.
     |  
     |  remove_tag(...)
     |      remove_tag(tag) - remove a tag from this message
     |      
     |      Remove a tag from this message. If the tag is not set, a KeyError exception is raised.
     |      If the tag does not exist, a ValueError exception is raised.
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  Cc
     |      Cc - the Cc header of the message
     |  
     |  FilePath
     |      FilePath - path and filename of the message
     |  
     |  Folder
     |      Folder - Folder in which the message is contained
     |  
     |  From
     |      From - the From header of the message
     |  
     |  MessageID
     |      MessageID - the Message-ID header of the message
     |  
     |  Subject
     |      Subject - the subject header of the message
     |  
     |  To
     |      To - the To header of the message
     |  
     |  forwarded
     |      forwarded - Forwarded-flag of the message
     |  
     |  locked
     |      locked - Locked-flag of the message
     |  
     |  marked
     |      marked - Marked-flag of the message
     |  
     |  new
     |      new - new-flag of the message
     |  
     |  replied
     |      replied - Replied-flag of the message
     |  
     |  unread
     |      unread - Unread-flag of the message
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes defined here:
     |  
     |  __new__ = 
     |      T.__new__(S, ...) -> a new object with type S, a subtype of T
    
    class Node(__builtin__.object)
     |  A general purpose tree container type
     |  
     |  Methods defined here:
     |  
     |  __init__(self)
     |  
     |  __str__(self)
     |  
     |  flat_list(self)
     |      flat_list() - get a flat list of the tree
     |      
     |      Returns a flat list of the tree, disregarding the nesting structure.
     |  
     |  get_str_list(self, level)
     |      get_str_list(level) - get a list of string-representations of the tree data
     |      
     |      The nesting of the tree elements is represented by various levels of indentation.
     |  
     |  traverse(self, callback, arg=None)
     |      traverse(callback [, arg=None]) - traverse the tree
     |      
     |      Traverse the tree, calling the callback function for each node element,
     |      with optional arg as user-data. The expected callback function signature is
     |      callback(node_data [, arg]).
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)

FUNCTIONS
    copy_messages(...)
        copy_messages(message_list, target_folder) - copy a list of messages to a target folder
        
        Copy a list of clawsmail.MessageInfo objects to a target folder.
        The target_folder argument has to be a clawsmail.Folder object.
    
    delete_tag(...)
        delete_tag(tag) - delete a tag
        
        This function deletes an existing tag.
        Raises a KeyError exception if the tag does not exist.
    
    folderview_select(...)
        folderview_select(arg) - select folder or a mailbox in folderview
        
        Takes an argument of type clawsmail.Folder or clawsmail.Mailbox, and selects the corresponding
        row in the folder view.
    
    folderview_select_folder(...)
        folderview_select_folder(folder) - select folder in folderview
        
        Takes an argument of type clawsmail.Folder, and selects the corresponding folder.
        
        DEPRECATED: Use folderview_select() instead.
    
    get_accounts(...)
        get_accounts() - get a tuple of all accounts that Claws Mail knows about
        
        Get a tuple of Account objects representing all accounts that are defined in Claws Mail.
    
    get_current_account(...)
        get_current_account() - get the current account
        
        Return the object representing the currently selected account.
    
    get_default_account(...)
        get_default_account() - get the default account
        
        Return the object representing the default account.
    
    get_folder_tree(...)
        get_folder_tree([root]) - get a folder tree
        
        Without arguments, get a list of folder trees for all mailboxes.
        
        If the optional root argument is a clawsmail.Folder, the function
        returns a tree of subfolders with the given folder as root element.
        
        If the optional root argument is a clawsmail.Mailbox, the function
        returns a tree of folders with the given mailbox as root element.
        
        If the optional root argument is a string, it is supposed to be a
        mailbox name. The function then returns a tree of folders of that mailbox.
        
        In any case, a tree consists of elements of the type clawsmail.Node.
    
    get_folderview_selected_folder(...)
        get_folderview_selected_folder() - get selected folder in folderview
        
        Returns the currently selected folder as a clawsmail.Folder or None if no folder is selected.
    
    get_folderview_selected_mailbox(...)
        get_folderview_selected_mailbox() - get selected mailbox in folderview
        
        Returns the currently selected mailbox as a clawsmail.Mailbox or None if no mailbox is selected.
    
    get_mailboxes(...)
        get_mailboxes() - get a tuple of all mailboxes that Claws Mail knows about
        
        Get a tuple of Mailbox objects representing all mailboxes that are defined in Claws Mail.
    
    get_mainwindow_action_group(...)
        get_mainwindow_action_group() - get action group of main window menu
        
        Returns the gtk.ActionGroup for the main window.
    
    get_mainwindow_ui_manager(...)
        get_mainwindow_ui_manager() - get ui manager of main window
        
        Returns the gtk.UIManager for the main window.
    
    get_summaryview_selected_message_list(...)
        get_summaryview_selected_message_list() - get selected message list
        
        Get a list of clawsmail.MessageInfo objects of the current selection.
    
    get_tags(...)
        get_tags() - get a tuple of all tags that Claws Mail knows about
        
        Get a tuple of strings representing all tags that are defined in Claws Mail.
    
    is_exiting(...)
        is_exiting() - test whether Claws Mail is currently exiting
        
        Returns True if Claws Mail is currently exiting. The most common usage for this is to skip
        unnecessary cleanup tasks in a shutdown script when Claws Mail is exiting anyways. If the Python
        plugin is explicitly unloaded, the shutdown script will still be called, but this function will
        return False.
    
    make_sure_tag_exists(...)
        make_sure_tag_exists(tag) - make sure that the specified tag exists
        
        This function creates the given tag if it does not exist yet.
        It is not an error if the tag already exists. In this case, this function does nothing.
        However, if a reserved tag name is chosen, a ValueError exception is raised.
    
    move_messages(...)
        move_messages(message_list, target_folder) - move a list of messages to a target folder
        
        Move a list of clawsmail.MessageInfo objects to a target folder.
        The target_folder argument has to be a clawsmail.Folder object.
    
    quicksearch_clear(...)
        quicksearch_clear() - clear the quicksearch
    
    quicksearch_search(...)
        quicksearch_search(string [, type]) - perform a quicksearch
        
        Perform a quicksearch of the given string. The optional type argument can be
        one of clawsmail.QUICK_SEARCH_SUBJECT, clawsmail.QUICK_SEARCH_FROM, clawsmail.QUICK_SEARCH_TO,
        clawsmail.QUICK_SEARCH_EXTENDED, clawsmail.QUICK_SEARCH_MIXED, or clawsmail.QUICK_SEARCH_TAG.
        If it is omitted, the current selection is used. The string argument has to be a valid search
        string corresponding to the type.
    
    rename_tag(...)
        rename_tag(old_tag, new_tag) - rename tag old_tag to new_tag
        
        This function renames an existing tag.
        Raises a KeyError exception if the tag does not exist.
        Raises a ValueError exception if the old or new tag name is a reserved name.
    
    summaryview_select_messages(...)
        summaryview_select_messages(message_list) - select a list of messages in the summary view
        
        Select a list of clawsmail.MessageInfo objects in the summary view.

DATA
    QUICK_SEARCH_EXTENDED = 3
    QUICK_SEARCH_FROM = 1
    QUICK_SEARCH_MIXED = 4
    QUICK_SEARCH_SUBJECT = 0
    QUICK_SEARCH_TAG = 5
    QUICK_SEARCH_TO = 2
    compose_window = None

-------------------------------------------------------------------------------