Humble Web Servant - User Documentation

Mail Commands

HWS can be controlled and configured remotely via E-Mail messages that contain commands either in subject line or message body.

There are three types of mail message structure that will be properly processed by HWS:

Web Content Request

As logical extension to procedural web content sending used in "Time" and "Periodic" mode tasks, additional requests are possible via "Request" E-Mail messages sent to "Request" mode tasks. Any mail sent to account set to "Request" working mode and starting with "REQ:" will be processed as additional web content request. Subject line must contain valid Unified Resource Locator (URL) to existing web content (web page, file accessible via URL or any other valid hyperlink). HWS will read all incoming mails from "Request" mode accounts and try to download content specified in URL from message subject. Then web contents will be sent to specified mail addresses listed in "Recipients" section of request task. Making additional requests is easy as all hyperlinks in prior sent web contents are already changed to issue mail request back to HWS for additional content. However, mail subject with request can be written like in this example:

REQ: http://www.google.com/search?hl=en&q=humble&lr=

Upper link will instruct HWS to contact GOOGLE site and return search results for word "humble", while

REQ: http://www.pleskina.com

would of course tell HWS to read and send back contents of pleskina.com site. Simple and easy.

However, when manually writing additional content requests, you must replace some special characters like ampersand (&) and questionmark (?) with special character sequences (HWS does that automatically when processing hyperlinks, but you must do that by yourself when requesting via E-Mail), as for the above example:

REQ: http://www.google.com/search_q_m_hl=en_a_s_q=humble_a_s_lr=

Ampersand (&) should be changed to _a_s_
Question mark (?) should be changed to _q_m_

This can seem a little complicated but helps to prevent various URL preprocessors and rewriters from changing URL to something unreadable or disable for sake of paranoic security settings. Also try to always include protocol (i.e. http://, https://) in requested URL.

When URL is not fould in subject line (subject is only REQ: and nothing else) of request mail message, HWS will search for properly shaped requests in message body. Each line which starts with "REQ:" will be processed as additional single request.

Remote Administration

HWS can parse message body and search for understandable "commands". Some commands are considered "global" (not connected to specific task) while other are task-related. A task must be properly selected using #TASK command. If a task has not been selected, an error message will appear in attempt to execute task-related command. Commands can be used to:

Administrative mail will only be parsed and executed if sent to Administrative Account with subject line starting with "ADM!" (without quotes, exclamation mark required). Administrative requests sent to any non-administrative account will not be processed, but will be logged as illegal adminstration requests.

All processed commands and results of their execution are written into log file and sent back as an E-Mail message to administration mail sender.

Commands are formated as:
#command [p1] [p2] .. [pN]
Any message body line which does not start with "#" sign will be ignored. Parameters MUST be enclosed in square brackets ([]). Spaces between parameters are ignored. Some commands do not require additional parameters while others do.

Supported commands with syntax and usage explanation follow.

Global commands
CommandSyntaxDescriptionExample
#TIMER #TIMER [minutes] Sets global HWS timer to specified number of minutes. This commands tells how many minutes should pass before next task processing. If command was sucessful, HWS returns confirmation in response message. #TIMER [10]
Tells HWS to process tasks every 10 minutes.
#LIST (no parameters required) Sends a list of defined tasks and their main properties and status information as an answer. This command is necessary to find which tasks exist in current HWS configuration. Task ID's are required to execute any task-related command. #LIST
Send list of all defined tasks.
#SHUTDOWN (no parameters required) Shuts down HWS. HWS will stop working upon receipt of this command. #SHUTDOWN

Task related commands
CommandSyntaxDescriptionExample
#TASK #TASK [id] Sets "active" task to task #id. ID is unique ID of specific task, assigned by HWS during task creation. If task exists, HWS will respond that task #id is now active task. After selecting "active" task, all following task-related commands will affect that selected task. #TASK [20050707095838179]
Selects task #20050707095838179 as active task.
#SHOW (no parameters required) Shows all information about selected task, including list of sites, acounts and recipients. #SHOW
#ENABLE (no parameters required) Enables selected task. Task will be processed in following periodic processings. #ENABLE
#DISABLE (no parameters required) Disables selected task. Task will not be processed next time. #DISABLE
#REMOVE (no parameters required) Removes selected task from current HWS configuration. Instead of removing tasks, you could rather use #DISABLE as you can later reuse stored information. #REMOVE
#SITE_ADD SITE_ADD [site_name] [URL] Adds a new site for content sending. You must specify unique site name (for example: Excite) and valid URL (example: http://www.excite.com). If a site with site_name already exists, error message is returned. #SITE_ADD [Excite] [http:/www.excite.com]
Adds site "Excite" to content sending list.
#SITE_CHANGE #SITE_CHANGE [site_name] [new_site_name] [new_URL] Changes existing site and sets name to new_site_name and URL to new_URL. If site does not exist, error message is returned. #SITE_CHANGE [Excite] [Excite once again] [http://www.excite.com/index2.html]
Changes site name of "Excite" to "Excite once again" and its URL to http://www.excite.com/index2.htm
#SITE_REMOVE #SITE_REMOVE [site_name] Removes site from selected task's site list. If site is not found, an error message is returned. #SITE_REMOVE [Excite]
Removes site [Excite] from list of sites for selected task.
# (no parameters required) #



Help Request

When sent with "HELP!" (without quotes) in subject line to any "Request" or administrative mode account, E-Mail will instruct HWS to send this HTML file in shape of E-Mail message back to Sender. You can always use this command to get help on supported commands.