Attention! This is a draft version of the program documentation.

If you feel that you could help in improving it, please contact us.

Please visit http://www.xrayapp.com/xray/help/ for latest version of help file.

1. Overview

2. Program interface description.

3. Configuration and tuning.

3.1 Tab «Servers»

3.2 Tab «Filters»

3.2.1 X-Ray macros reference

3.2.2 Special

3.3 Tab «SMTP Autoselect»

3.4 Tab «SNTP Sync»

3.5 Tab «Settings».

3.6. Tab «Statistics».

1. Overview

X-Ray was created to make possible mail message header editing.

The program consists of 3 main parts:

 

This was done to optimize system resource usage. Thus, if Interface Library or Control Center is not needed at the moment, they can be unloaded.

2. Program interface description.

This is how main program menu looks like:

{place a screenshot here}

It is available after right click on program icon in system tray.

3. Configuration and tuning.

Program configuration dialog can be opened via item Options in program main menu.

3.1 Tab «Servers»

This tab is for setting parameters of mail servers, which will use X-Ray.

Server type: server type: SMTP or POP3;

Local port: number of local port on which X-Ray will listen for connection;

Host/IP: name or IP address of a mail server, to which X-Ray will forward all incoming connections.

Port: port number of the mail server;

Alias: server title;

Username: username for authentication on the mail server;

Password: password for authentication on the mail server;

Confirm: password confirmation field;

Note: For now authentication is available for POP3-servers only.

Note: If «Use APOP if possible» option is enabled and POP3-server supports APOP authentication, but mail-client tries to use regular login/password authentication schema, X-Ray will use APOP authentication.

Notes:

· If the port number is different from «default» port for this protocol (for SMTP default port number is 25, for POP3 - 110. Defaults can be changed on tab Settings), then only one server will be active and all other servers will be ignored (X-Ray will show message box with a warning).

· If the port number is «default» port, then all servers with this port will be accessible in SMTP/POP Servers submenu of main program menu and it will be possible to switch servers «on fly». Moreover, if proper option is enabled, then extended actions will be performed: SMTP servers will be used for SMTP Autoselect, and POP servers will be used for Cyclic change.

 

3.2 Tab «Filters»

Filtering is the primary task, which should perform X-Ray, so this tab is fundamental. For now, X-Ray can filter only mail headers, but we have plans for adding capabilities to work with all parts of mail message.

If you think that important and useful actions still not implemented in the program, please let us know and we'll try to implement it.

Filter is defined with its properties. Not all properties have sense (and will be active) for all filter types. Let's have a closer look.

3.2.1 X-Ray macros reference.

Couple of words to explain how to use macroses.

For now X-Ray has a short list of string manipulation functions( Maybe it will

beextended in future -- it depends on user input ;-) ).

I. Syntax:

1. It is VERY simple. :-)

2. Function arguments should be enclosed in brackets.

3. Function arguments should be separated with commas.

4. All arguments are string -- no other data types.

4.1. There is no need to put quotes (") to define a string.

4.1.1. Quote will be treated as part of the string.

5. Spaces before and after string will be truncated.

6. All headers in a message are accessible by $header_name.

Example: $Date, $Subject, $X-Mailer, etc.

7. Function result can be used as an argument for another function ("nested

function calls").

8. Functions names are CASE_SENSITIVE! So $POS or $pos will NOT work!

II. Description:

· $CurDate() -- will insert Current date and time in regular mail format ( "Thu, 11 Oct 2001 17:05:44 +0400").

· $RawHeader() - now X-Ray could decode header value if it is encoded in Base64/QuotedPrintable form. This macros will return header value as it is. Could be useful in very rare and not trivial cases.

Example: $RawHeader($Subject).

 

· $Pos(string, substring) -- returns zero-based position of "substring" inside of "string".

Example: $Pos(test[here], [) will return "4".

 

· $RPos(string, substring) -- returns zero-based position of last "substring" inside of "string". If there is only one "substring", than $RPos is equal to $Pos).

Example: $RPos(test[here]and[here], [) will return "13".

 

· $SubStr(string, begin, end) -- returns part of "string" which starts on position "begin" and ends on position "end" of original string.

Example: $SubStr(test-this-now, 4, 9) will return "this".

 

· $Cut(string, begin, end) -- invertion of $SubStr. Will return all characters of original string except for characters on position from "begin" to "end".

 

Example:$ SubStr(test-this-now, 4, 9) will return "testnow".

 

Note, that characters located on position "begin" and "end" will also be cut out! (It was done intentionally to remove square bracket symbols --'[' and ']', etc.).

 

· $CutStr(string, substring) -- Will return "string" without "substring" (if

"substring" exists inside of "string").

Example: $CutStr(is this test, is) will return " this test".

 

· $CutRStr(string, substring) -- Will return "string" without last "substring" (if "substring" exists more than once inside of "string". If there is only one "substring", than $CutRStr is equal to $CutStr).

Example: $CutRStr(is this test, is) will return "is th test".

III. Application.

These functions can be used in a lots of different ways.

1. Delete known list name from subject line.

Use $CutStr($Subject, your_list_name).

Example: $CutStr($Subject, [KerridwensKessel]).

In this case a separate filter should be created for every list.

2. If it is known, that mail list name is enclosed in square brackets, $Pos/$RPos can be used to find position of opening ('[') and closing (']') bracket and supply it as argument for $Cut.

Example: $Cut($Subject, $RPos($Subject, [ ), $RPos($Subject, ] ) ).

This construction needs to be explained.

This is $Cut($Subject, start, end), where

"start" is "$RPos($Subject, [ )"

and

"end" is $RPos($Subject, ] )

Please note, that $RPos was used instead of just $Pos. It was done to handle cases like this: "Re[2]: [AX-Le] Pattern destruction and energy release", so "[AX-Le]" will be cut out and [2] -- won't.

It is necessary to remove more than one similar string (pair of brackets, for example), two identical filters should be created (If X-Ray will complain that one such a filter already exists, just add a space to make it little bit different :-). But don't forget to set "Continue processing" checkbox to let more than one filter process a header!

If more than one filter for a header was created, set "Continue processing" checkbox on!!!

3.2.2 Filter Action - Special

The "Special" tab allows you to actively add new headers by analyzing the values of those already in your email. Let's discuss an example that's already set up in X-Ray.

Suppose that you don't have Usenet (Newsgroup) access at work, and so in order to post to your favorite discussion group during the day, you need to write, using The Bat! and a mail-to-news gateway, an email message to be relayed to the newsgroup. It is necessary to add a "Newsgroups:" header with the name of newsgroup (or several newsgroups if you cross-post) as the value of header. Most mail programs do not allow you to edit message headers, and most of those that do make it inconvenient. With the help of X-Ray this task can be automated in this way:

  1. On "Special" tab create a new element with settings:
    1. Signal string: "newsgroup"
    2. Separator: "#"
    3. New header name: "Newsgroups:" (The colon will be added automatically if you forget it.)
  2. On "Headers" tab add new element with fields:
    1. Header: 'To:'
    2. Change to 'Special header' and choose the rule 'newsgroup' (created on previous step) from combo-box (signal string is a name of rule).

In plain English, you are telling X-Ray to filter the "To:" field using the "newsgroup" rule."

[Note that X-Ray allows you to have several rules with same signal string.]

That's all.

Now, when you send a message to address like

newsgroup#newsgroup.name # mail2news@news-by-email.com

your message will be sent to the server "news-by-email.com," and to your message's headers will be added the string: "Newsgroups: newsgroup.name".

When you cross-post, it is necessary to separate the newsgroup names with commas and put the whole string in quotes, otherwise your mail will be rejected by the mail server:

"newsgroup#newsgroup1.name,newsgroup2.name#" mail2news@news-by-email.com

(Even if your server doesn't reject it, one of the many servers that you mail passes through on its path will. Use the quotes!)

Did you notice that the separator character must come after BOTH the signal string ("newsgroup") and the value string? ("newsgroup1.name,newsgroup2.name") X-Ray must be able to recognize where your special header ends and the regular headers resume.

3.3 Tab «SMTP Autoselect»

Theory

To avoid sending of 'junk mail' (or 'spam') via their mail servers, a lot of internet providers require users to authenticate themselves before mail sending. Contemporary mail clients can be easily configured to work with most types of authentication (POP before SMTP, MD5, RFC 2554, etc.). But sometimes SMTP server allows sending a mail only for client, which IP-address is in specified range (usually this is IP-range assigned to the provider). So it won't be possible to connect via one provider and send mail via SMTP-server of another.

X-Ray could automatically select SMTP-server from a specified list accordingly to current IP address. It is necessary to create a record for every IP-range with values:

Repeat the process for every provider that will be used with SMTP Autoselect. Don't forget to switch on «SMTP Autoselect» option (dialog «Options/Settings», or menu SMTP Servers/ SMTP Autoselect) and X-Ray will select SMTP server for automagically!

3.4 Tab «SNTP Sync»

Time synchronization feature will keep local clock precise. There are number of internet time servers. You could load some of them from this page http://www.google.com/search?q=internet+time+servers.

To let X-Ray synchronize time, checkbox 'Enable time synchronization' should be set on.

Please note that correct time zone should be set on a computer, otherwise invalid time will be set. To avoid this effect, Under hour correction checkbox can be used. With it program assumes, that your computer clock could differ from SNTP server for not more than 1 hour.

In the program every time server has priority value associated with it. This value is number from 0 to 10, highest number means top priority. When created, server priority value is assigned to 5 (medium). When X-Ray is going to connect to a SNTP server it will pick a server with highest priority value of all. If there are more than one server with this priority level, they will be picked in round-robin manner.

Dynamically update priorities checkbox will make X-Ray to change a server priority value depending on server delay time. So servers, which are faster for you, will eventually have higher priority (and X-Ray will use them for time updates) than servers, to which you have a slow access. It is possible tune this process with Minimum/Maximum delay settings: if server delay time is less than Minimum delay, server's priority will be increased by 1; if server delay time is more than Maximum delay, server's priority will be decreased by 1. If the delay is somewhere in between, it won't be changed at all.

For a new SNTP server these values could be specified:

3.5 Tab «Settings».

This tab is for setting general program settings, such as:

Network:

Start & Stop:

3.6. Tab «Statistics».

This tab contains statistical information about X-Ray. Currently there are two smaller tabs: Mail and Time.

Mail tab contains data about messages being received/sent/filtered:

Time contains data about time synchronization (see Tab «SNTP Sync»):