[Up]: Storage API : DropTo
Script path: /storage/bin/api/dropto.cgi
Description: Handle the dropping of items (files or folders) to one or more email addresses
INPUT (via GET or POST)
sid => the authenticated session id (must be valid)
item_list => list of file / folder to drop (must have at least one)
Cannot be too many (current limit: 100 items)
e.g. of items:
/Private/subfolder/thefile.doc
/Company Share/Sales/presentation.ppt
Specify multiple items in multiple cgi parameters of the same name "item_list".
item_list_json => another way of specifying the list of file / folder to drop using the JSON obj.
The JSON obj here is a single member named "item_list" whose value is a list of paths
to file (folder).
{ "item_list" : [ "/Private/subfolder/thefile.doc",
"/Company Share/Sales/presentation.ppt",
"/path/to/sub/item" ] }
item_list and item_list_json can be specified in combination or exclusively of one another.
Both list will be combined internally.
email_list => list of email to dropto / send to. (must have at least one)
Cannot be too many (current limit: 50 recipients)
e.g. of emails:
userid@hostname.com
"AB Chow" <abc@somewhere.org>
NameX <-- will be sent to NameX@domain-of-sender or if it represent the user's
distribution list (in Contacts), it will be replaced with the list's email addresses.
Specify multiple emails in multiple cgi parameters of the same name "email_list"
email_list_json => another way of specifying the list of email addresses to drop to using the JSON obj.
The JSON obj here is a single member named "email_list" whose value is a list of email addresses.
{ "email_list" : [ "userid@hostname.com",
"AB Chow <abc@somewhere.org>",
"NameX" ] }
email_list and email_list_json can be specified in combination or exclusively of one another.
Both list will be combined internally.
msg_subject => email subject line (default if empty)
Cannot be too long (current limit: 100 chars)
Defaults to something like this "Drop File Notification (from SenderName <sender@hostname.com>)"
addmsg => optional short message to be included in email to recipient
can be blank.
Cannot be too long (current limit: 1024 chars)
language => email language (english | chinese_simplified | chinese_traditional | bm )
if null, defaults to the sender's preferred language.
days_valid => N (N number of days to expiry)
defaults to 1 day, range from 1 to 31.
ack_pickup => if equal to 1, then notify sender when there is a dropfile pickup (download)
defaults to NOT notify
do_not_notify => If set to 1, then the NO email notification will be sent to the recipient(s).
The body of the notification email that WOULD BE SENT (or was SENT) is always returned by this API.
passphrase => (OPTIONAL) Sets a passphrase that will be required to match before the recipient
is allowed to access or download the item. This ONE passphrase applies to ALL files dropped to ANY number
of recipient. In other words, all recipient will need to know this SAME passphrase to access any of the files.
Characters allowed in a passphrase include all alphanumerics, upper and lower cases, space, common printable symbols
on the US-english keyboard. Max length is 100 chars.
ofmt => output format defaults to JSON format with minimal white spaces.
ofmt = jsonp means to produce JSON format in pretty printed way (easier to read)
OUTPUT (content-type: text/plain)
JSON output object:
{
"status" : true | false,
// true only if the API completes successfully
// false if otherwise
"errmsg" : error message, if status is false,
"errcode" : internal error code (alphanumeric),
"sent_to_list" : [ email0, email1, email2, ... ],
// list of emails successfully sent to
// only applicable when status is true
"email_msg_info":
[
{ email message info for email0 },
{ email message info for email1 },
{ email message info for email2 },
:
]
* Email message info:
Each of the email message information is a JSON object of this form:
{
"to" : recipient email
"from" : sender (API caller)
"subject" : email subject
"body" : email content
}
"error_items" : [
{ "isfolder" : is folder or not, "item_path" : path_to_item , "comments" => comment_on_error },
:
:
],
// items (file or folder) that this API had problems accessing.
// This API would have aborted if there is any error here.
// isfolder is true | false
"offending_addrs" :
[
{
"email" : the email address that has a problem,
"reason" : the reason for the problem
},
:
]
// e.g. do not appear to be a an email address.
// or as an alias/nickname, it cannot be expended to the list of emails it represents.
// Currently this API aborts on FIRST email address it has trouble with.
"dropitem_records" :
{
"count" : (number of drop links/records generated),
// (same as the number of elements in the list below)
// If all the drops were successful, then this number is no. of items x no. of recipients
"list" :
[
{ Drop item information, including links, itemname, passphrase, etc. (see further notes below) },
...
]
}
* Drop Item Information:
Each of the drop item information is a JSON object of this form:
{
"id " : the dropitem ID (alphanumeric)
"date" : the date/time when the drop was done (adjusted to user's timezone)
"date_gmt" : the date/time when the drop was done (GMT)
"expiry" : the date/time when the drop will expire (adjusted to user's timezone)
"expiry_gmt" : the date/time when the drop will expire (GMT)
"to_email" : the drop recipient's email address (or internal userid)
"to_email_fullname" : recipient's fullname, if any
"from_email" : the drop sender's email address (or internal userid)
"from_email_fullname" : recipient's fullname, if any
"spath" : the storage path to the item (could be a file or a folder)
"itemname" : the item's basename (the last component of spath)
"is_folder" : false | true
"desc" : the description of the item at the time of the drop
"size" : the size of the item at the time of the drop (if folder, the total file size it contains)
"pickup_url" : The URL that the recipient will use to access/download the dropitem
"passphrase" : The passphrase set for this dropitem, if any
}
} // end of JSON output object
In all cases, appropriate HTTP header status codes are also returned e.g. 200 OK, 401 Invalid user
profile, etc.