Using SailBlogs Remote
If your SailBlogs account has been "remote enabled," you will be able to create log entries, including entries with images, by simply sending email. This document will outline some of the basics required for doing this, and some of the options available.
PLEASE REVIEW THIS DOCUMENT CAREFULLY BEFORE SENDING EMAIL TO THE SYSTEM.
This document also assumes that you are already familiar with using SailBlogs through the web interface.
Contents
Setup
Email Account
Your weblog will be assigned a unique email address for the purpose of receiving weblog posts. This not a "normal" email address, meaning you will not be able to interact with this account. You will not be able to login to this account, send mail from this account, or read any mail that arrives in this box. Any mail not related to SailBlogs will be purged on a monthly basis.
DO NOT give this email address to anyone who will not be posting to the weblog. This email address could enable someone to post messages to your weblog. Treat this address like a password.
Your email address will appear in a separate message.
Plain Text
Make sure that you set your mail client to send in PLAIN TEXT when submitting journal entries, not HTML or Rich Text. Refer to your mail client preferences for this setting.
Subject Key
The subject of your email, along with the address itself, comprise authentication for processing remote posts. Treat this key like a password. Do not confuse this with the title of your journal post. This is the subject of the email message, not the title of the entry.
In order for a weblog entry to get entered into the weblog the remote processor will only look at those messages arriving in your mail account that have this subject. This will filter out any junk that could happen to make its way into your weblog mailbox. You will receive the subject key when you receive your email account. It is also listed under the 'Properties' tab of the Blog Manager.
General Information
Date & Time
If you want the post to go live as soon as it is processed, you can leave out the data and time and it will be date stamped with the current time. If you wish to assign a specific date and time to your post, submit the time in UNIVERSAL TIME (aka GMT or Zulu) in the following format:
DATE:YYYY-MM-DD HH:MMZ
Note the addition of the "Z" at the end of the time. This is important as that indicates the time is UT. Without the Z the post will go into the system as Central Time (where the server is located). CT is 5 or 6 hours (depending on season) behind UT, so submitting a universal time without the Z will assign the post 5-6 hours ahead of the server.
Template
SailBlogs Remote looks for the body of the email message to be structured in a specific way. This enables the remote processor to identify the components of a weblog entry (date, title, author, etc.). There are two mail body templates that can accomplish this: the standard template and the short version template. After getting comfortable with remote posting, most users use the short version for posting, as it requires less keystrokes.
The Standard Template:
COMMAND1: COMMAND2: DATE: TITLE: LOCATION: AUTHOR: VIEW: BODY: ###
The Short Template:
[s] [c1] [c2] [d] [t] [l] [a] [v] [b] ###
Note that the short template always begins with the key "[s]" - this tells the remote processor to look for the short keywords.
The keys correspond to the weblog post fields you should already be familiar with. In addition, there are two command fields, which can be used to send commands to the remote processor. See the "Remote Commands" section later in the document for information on how to use these fields.
As with the web interface, the only required fields are title and body (technically, "date" is required as well, but if the date is omitted, the current system date and time is used). Unused keywords can be omitted from the mail body.
All fields with the exception of the body terminate on the end of a single line.
###
The symbol "###" can be used to indicate the end of the post body. If omitted, the processor will take all information to the end of the mail body. This symbol is useful for those mailers and mailing systems that automatically add a footer to mail messages - such as free email accounts or text messaging from mobile phones. Using this can strip this footer from messages sent from those accounts.
Keyword Sequence
The keywords can appear in any order, but if a keyword appears in sequence after the body, the body must include the "###" end indicator else the body that displays to the user will also include any codes that come after the body. In practice, its good to simply get in the habit of having the body be the final key of a remote post.
Composing a Simple Remote Entry
Posting remotely is as simple as sending an ordinary email message. In your desired email client compose a message as you normally would. (See the section ATTACHMENTS & IMAGES for information about tested mail clients.)
Address the email to the address you were assigned for your weblog.
In the subject, type in the subject key you were provided for your weblog.
In the body or the email, add the desired weblog post information after the proper keywords:
COMMAND1: COMMAND2: DATE: 4/2/03 TITLE: This is a test remote post LOCATION: My Office AUTHOR: Tim Harincar BODY: This is a test of the remote processor. If all goes well, this message will appear in my weblog very shortly. ###
Send the mail. The remote processor will process the message within a minute or so and send back a confirmation email that the post was accepted and added to your weblog.
Here is the same post, using the short version (and dropping unused keywords) of the template:
[s] [d]4/2/03 [t]This is a test remote post [l]My Office [a]Tim Harincar [b]This is a test of the remote processor. If all goes well, this message will appear in my weblog very shortly. ###
The View Option
The view option (VIEW or [v]) is the same as the display switch in the web interface (we didn't want to confuse it with [d] for date). This will allow you to send a message into the system and have it not appear on the web site, or change the display value of a post already in the system.
When using short commands, this is the proper method:
[v]off
When using long commands, use:
VIEW:off
Leaving the view tag out of the post, or setting it to anything other than "off" or 0 (zero) will result in the post being visible to the world.
Attachments & Images
Allowable attachments are web-standard images, GIF, JPEG and PNG files. Any other attachments will be rejected, though the post will still be accepted. SailBlogs Remote has been tested with numerous web-based email clients, Microsoft Outlook, Lotus Notes, and Apple Mail, and should work with most standard mail clients. However, not every mail client has been tested and some mail clients create multipart mail messages (messages with attachments) in strange ways, so we cannot guarantee that the remote processor will recognize attachments from all email clients. Best to test your favorite client. If you do find a client behaving strangely, notify the SailBlogs dev team and we'll see if it can be made to work.
As with the web-based administration tool, you can attach a single image to a weblog entry that is posted via email. If more than one image is attached, the remote processor will accept the first image in the message sequence (note that the message sequence may order the attachments differently than you added them to the email with the client - best to only add a single image).
The remote processor will check the attachment to verify that it is a web allowable image, and that is does not exceed the image size limits set in the weblog properties (refer to information on configuring your weblog). The attachment will be deleted if it is not a valid image.
Commands
SailBlogs Remote is designed to be used in replacement of, not just in addition to, the web-based administration. As such, you can do many of the same things through Remote that you can do via the web admin interface. You can add, update and delete posts as well as add or remove images. You can also request a copy of this document (help) or get a copy of the template.
A command will have the following structure:
COMMAND1:keyword[:option]
or
[c1]keyword:option
Where the keyword is the command you wish to execute, and the option is a parameter to the keyword, if the keyword accepts parameters. For example, the following line would instruct the remote processor to update weblog entry #27:
COMMAND1:update:27
Command Keywords
help
help | h : emailAddress
Requests a copy of this help file. Email address is optional, if used the template will be sent to the indicated address.
template
template | t : emailAddress
Requests a copy of the template. If the short key ("t") is sent, the short template will be returned. Email address is optional, if used the template will be sent to the indicated address.
fetch
fetch | f : recordNumber
Will request the remote processor to return the weblog entry of recordNumber, formatted for an update. Passing 0 for a recordNumber will cause the processor to send back a list of recordNumbers and Titles currently in the weblog.
Example 1:
COMMAND1:fetch:27
Example 2 (short template):
[c1]f:27
update
update | u : recordNumber
Tells the remote processor to take the information in this message and update the record specified with recordNumber.
Example 1:
COMMAND1:update:27
Example 2 (short template):
[c1]u:27
position
position | p : coords
Will pass the coordinate information to the XPlot mapping system and request an update of the associated map. (Requires XPlot to be configured). Coordinates cannot be updated or deleted via the SailBlogs Remote system, only posted. Coordinates must be latitude:longitude and be in the format of degrees + decimal minutes with a direction flag (N,S,E,W). Coordinates can be posted with or without a full journal entry.
Example 1:
COMMAND1:position:70 0.0'N:45 0.0'W
Example 2 (short template):
[c1]p:70 0.0'N:45 0.0'W
pdata
pdata | pd : position data
The pdata command is a C2 command ONLY that can be used when submitting a position with the C1 command. It allows the inclusion of additional data associated with the position. The data is course, speed, and three additional data fields. The fields are separated by a pipe "|" character. Data3 is a custom field for Pro users only. The format is as follows:
[c2]pd:course|speed|data1|data2|data3a~data3b~data3c
NOTE - for SailBlogs, data1 is always wind speed, data2 is always wind direction.
Example 1:
COMMAND1:position:70 0.0'N:45 0.0'W COMMAND2:pdata:131|7.3|16|216
Example 2 (short template):
[c1]p:70 0.0'N:45 0.0'W [c2]pd:131|7.3|16|216
Confirmation Messages
If confirmation messages are enabled in the Blog Properties, the server will replay by email to the sending email address with a notice that either the message was accepted or there was an error (and a possible reason for the error).
Successful confirmation messages will include the message ID post title and image name (if attached) if the post was successful:
Successfully processed SailBlogs Remote post: 16533 | Sample Remote Post | b4580_110091.jpg
An error message will be like this:
ERROR processing SailBlogs Remote post: Some common errors: - if using short keywords, be sure the first line of the message body is [s] For additional assistance, forward this message to support@sailblogs.com.com MSG: Title field cannot be empty.
Remote Errors
Missing Fields
With Remote posting, both title and body are required fields, other items can be left blank. If Date is left blank, the current system time is used.
In addition, some other errors will result in a field cannot be empty error. If you send the message in HTML format, for example, the system will not be able to parse the text and it will generate a missing field error. Also, using incorrect keyword syntax, for example using parenthesis around short keywords, e.g. "(s)" instead of square brackets [s], will result in a missing field error since the parse cannot find the required keyword.
Incorrect Date
If the system returns a successful confirmation message, yet the post does not appear in the proper date sequence of the blog, there are two possible problems:
- Future. The server is in Central Time, so if you do not use GMT (Z) the system assumes the date is in CT. If you are posting from EAST of the central time zone and you include the local time information, the system will place the message into the system as ON-Future and so will not appear in the blog. Avoid this problem by either leaving off the dates or posting in GMT.
- The date format was invalid. The only truly invalid date format looks like:
02-03-2008
The system cannot parse a date with dashes since it doesn't know which element is the month and which is the day. Use an unambiguous date format like 02-feb-2008 or Feb 2, 2008 to ensure the system can read it properly.
Position-Only Reports
If a remote post has only a latitude and longitude, the system will accept that as a Position-Only Report if the member has XPlot mapping enabled. This is an example of a valid Position-Only Report:
[s] [c1]p:70 0.0'N:45 0.0'W
In this case the system would respond with a successful confirmation message.
SailMail Users
SailMail users refer to SailMail Setup Information for sending remote posts via the built-in features.
