Available Plugin Hooks

The registered callback function receives a hash array as single argument which contains hook specific data (called Arguments in the following list). It can then alter some of these values (listed as Return values) by returning a hash array containing the modified values.

Global Hooks

startup

When the application is initialized.
This is the place where task and action arguments can be altered.

Arguments:

• task
• action

Return values:

• task
• action

authenticate

Before the user login on the IMAP server is performed.

Arguments:

• host
• user

Return values:

• host
• user
• pass

login_after

Triggered after a user successfully logged in.
This hook allows a plugin to control the redirect after the login form was submitted. Information about the current user can be obtained from the rcube_user object at rcmail::get_instance()->user

Arguments:

• task

Return values:

• task
• action
• [more url parameters]

login_failed

Triggered if user authentication failed.
Could be useful for logging or to give more detailed feedback to the user why the login failed.

Arguments:

• host
• user
• code

Return values:

none.

create_user

When a somebody logs in the first time and a local user is created.
Return values will also be used to create the default identity for this new user.

Arguments:

• user
• user_name
• user_email

Return values:

• user_name
• user_email
• alias

list_mailboxes

Triggered whenever a list of the mailboxes is requested from the IMAP class.
If no plugin returns a list, the default list is retrieved.

Arguments:

• root
• filter

Return values:

• folders: Folders list to be used

render_mailboxlist

When the mailbox list is about to be rendered.
This hook allows plugins to alter the folder tree or to localize folder names,

Arguments:

• list: The hierarchical list of mailboxes
• delimiter: The full message body as text

Return values:

• list

---

Task "mail"

imap_init

This hook allows you to configure some IMAP communications options.

Arguments:

• fetch_headers: String appended to the FETCH HEADER.FIELDS () list

Return values:

• fetch_headers: String with additional headers to be fetched (separated by space)

message_load

Triggered when a message is loaded from the server, namely when creating a new rcube_message object.
This allows one to analyze the structured message object and find specific attachments, headers or contents for further actions.

Arguments:

• object: The rcube_message instance

Return values:

none.

message_read

Triggered when a message is loaded and its SEEN flag is set.
The message argument will give you access to all the message headers and its structure.

Arguments:

• uid
• mailbox
• message: The according rcube_message instance

Return values:

none.

message_part_before

Triggered before a message part (text or html) is cleaned/formatted.

Arguments:

• type
• body
• safe
• plain
• inline_html

Return values:

• type
• body
• safe
• plain
• inline_html

message_part_after

After message text part formatting.

Arguments:

• type
• body
• safe
• plain
• inline_html

Return values:

• body

message_headers_output

Triggered when building the message headers table for display.
If you want to add more headers, you need to fetch them at the imap_init hook.

Arguments:

• output: Hash array with all the headers to be put into the html table
• headers: Message headers object

Return values:

• output: Altered headers array

upload_attachment

Triggered every time a user uploads an attachment in message compose mode.
This hook is mainly used by core plugins that handle the storage of the uploaded files.

Arguments:

• path: Temporary file path to the uploaded file
• name: The original file name
• mimetype: Detected mime-type

Return values:

• status: True if the file was successfully stored (required)
• error: Error message in case a plugin rejects the upload and sets the abort flag
• id: The unique ID of the file to get retrieve it later on (required)
• name
• mimetype

outgoing_message_headers

Before a mail message is sent, this hooks allows you to set additional mail headers.

Arguments:

• headers: Hash array with current message headers

Return values:

• headers

outgoing_message_body

Before a mail message is composed, this hooks is triggered before assing the message body contents.

Arguments:

• body: The message body to be added
• type: html|plain|alternative
• message: Reference to current MailMime? object

Return values:

• body

smtp_connect

Triggered when before opening an SMTP connection to send a message.
Some SMTP related config options are passed as arguments and can be altered by a plugin.

Arguments:

• smtp_server
• smtp_port
• smtp_user
• smtp_pass
• smtp_auth_type
• smtp_helo_host

Return values:

all arguments

message_sent

Triggered when a message is finally sent
This hook can doesn't have any return values but can be used for logging or notifications.

Arguments:

• headers: Hash array with all message headers
• body: The full message body as text

Return values:

none.

---

Task "addressbook"

address_sources

Triggered when building the list of address sources in the address book view.
Each entry in the sources list needs to hold the following fields: id, name, readonly.

Arguments:

• sources: Hash array with list of available address books

Return values:

• sources

get_address_book

This hook is triggered each time an address book object is requested.
The id parameter specifies which address book the application needs. If it's the ID of the plugins' address book, this hooks should return an according instance of a rcube_addressbook implementation.

Arguments:

• id

Return values:

• instance: Instance of an address book implementation derived from rcube_addressbook

create_contact

Triggered when an address book record is saved.
A plugin can prevent the contact to be created by setting the abort field to true. The user is then rejected back to the input form.

Arguments:

• record: Hash array with record fields
• source: Address book identifier

Return values:

• record
• abort

save_contact

Triggered when an address book record is saved.
As in the create_contact hook this action can be aborted by setting the abort field to true.

Arguments:

• id
• record: Hash array with record fields
• source: Address book identifier

Return values:

• record
• abort

delete_contact

Triggered when an address book record is to be deleted.
To abort the deletion a plugin can set the abort field to true.

Arguments:

• id
• source: Address book identifier

Return values:

• abort

---

Task "settings"

manage_folders

Allows a plugin to modify the main table on the manage folders screen

Arguments:

• table: reference to an html_table object

Return values:

none.

save_preferences

Allows a plugin to inject data into the array of preferences about to be saved

Arguments:

• prefs: Hash array with prefs to be saved

Return values:

• prefs

user_preferences

Allows a plugin to modify the user preferences table.
This hook is triggered for each block of the user prefs pane. The block is denoted in the section parameter. Possible values are general, mailbox, mailview, compose, folders, server

Arguments:

• section: which block of the prefs pane
• table: reference to an html_table object

Return values:

none.

list_identities

Triggered when a users identities are listed.

Arguments:

• list: The list of identity records
• cols: List of cols to be displayed

Return values:

• list
• cols

create_identity

Triggered when a user attempts to create a new sender identity.
A plugin can prevent the record to be created by setting the abort field to true. The user is then rejected back to the input form.

Arguments:

• login: True if triggered at login when a new user is created
• record: Hash array with identity record fields

Return values:

• record
• abort

save_identity

Triggered when a user changes one of his sender identities.
As in the create_identity hook this action can be aborted by setting the abort field to true.

Arguments:

• id
• record: Hash array with identity record fields

Return values:

• record
• abort

delete_identity

Triggered when a sender identity is to be deleted.
To abort the deletion a plugin can set the abort field to true.

Arguments:

• id

Return values:

• abort

---

Template Hooks

The RoundCube skin retrieves certain parts (e.g. message list, folders list, etc.) from the application with special tags within the HTML templates: <roundcube:object name="someobject" ... />. Template hooks are triggered once a template object is rendered. A plugin can alter or extend the html content of a template object.

The hooks are named template_object_* where * is the name of the object. A list of all available template objects is given in Doc_TemplateObjects?.

Arguments:

• content
• [tag attributes]

Return values:

• content

render_page

Triggered after a tempalte was parsed, just before sending the HTML page to the client.
This is the place where plugins can add additional content to the page which is not related to any template object. Use $rcmail->output->add_footer() or $this->include_script() to extend the html page. Of course it's also possible to directly alter the content attribute.

Arguments:

• template: Name of the rendred template
• content: The HTML source

Return values:

• content