Mail client
:: services/mailclient module

This is a BETA module. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this module, please let us know. Then, we will work with you and move it out of beta as soon as we can.

This module provides high-level interface for sending email messages, as opposed to the services/mailing module. It allows to store unfinished messages, check progress of sending messages and browse the history.

In order to send a message you have to create first a draft using create_message. Under the hood each message is accompanied by an anonymous custom group which can be modified using update_recipients_group. You will call this method whenever you want to change the recipients of the message. This means, however, that an actual list of recipients may change in time, because each group can contain other groups and some of them are dynamically generated, like course group participants. In order to overcome this difficulties we keep, along with the recipients group, a frozen list of recipients (returned by recipients method). This list is not automatically refreshed once you update the group - instead you have to manually call refresh_recipients to regenerate the list. If you forgot to do so, you will not be able to send the message. The list will be treated as invalid also if it was generated more than 24 hours ago.

You can optionally add some attachments to the message. However, attached files will not be sent along with we message - instead a list of links will be appended to the end of the message. These links will stay valid for a specified period of time (see attachments_lifetime argument in create_message and update_message).

Methods

attachment BETA Get information on a given attachment. (administrative)
attachments BETA Get information on multiple attachments. (administrative)
copy_message BETA Create a copy of a message. (administrative)
create_message BETA Create a new message. (administrative)
delete_attachments BETA Delete message attachments. (administrative)
delete_messages BETA Delete messages. (administrative)
message BETA Get information on a given message. (administrative)
messages BETA Get information on multiple messages. (administrative)
put_attachment BETA Upload an attachment. (administrative)
recipients BETA Get a list of recipients. (administrative)
recipients_group BETA Get information on a given recipients group. (administrative)
refresh_recipients BETA Regenerate recipients list. (administrative)
retry_send_message BETA Retry sending a message. (administrative)
send_message BETA Send a message. (administrative)
update_attachment BETA Update an attachment. (administrative)
update_message BETA Update a message. (administrative)
update_recipients_group BETA Update a recipients group. (administrative)
user BETA Get user's messages. (administrative)

services/mailclient/attachment

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Get information on a given attachment.

attachment_id required

Attachment ID.

fields optional

Default value: id|filename

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - attachment ID;

  • filename - filename of the attachment;

  • size - size of the attachment (in bytes);

  • description - description of the attachment;

  • url - URL address of the attachment.

Thrown errors:

  • object_not_found - attachment could not be found; param_name is equal to attachment_id.

services/mailclient/attachments

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Get information on multiple attachments.

attachment_ids required

List of attachment IDs.

fields optional

Default value: id|filename

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of attachment method.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary mapping attachment IDs to dictionaries describing the attachments (as returned by attachment method). If specified message could not be found, null is returned instead of a dictionary.

services/mailclient/copy_message

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Create a copy of a given message. The new message will have status draft and will not contain any attachments.

message_id required

Message ID.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of the following structure:

  • message_id - message ID of the copy.

Thrown errors:

  • object_not_found - message could not be found; param_name is equal to message_id.

services/mailclient/create_message

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Create a new message.

subject optional

Default value: (empty string)

Subject of the message. No more than 200 characters.

from_inst_address_id optional

Default value: (empty string)

Institutional address ID from which the message should be sent, or null if user's email address should be used instead.

Most users do not have any institutional address assigned so in most cases this value will be null.

content optional

Default value: (empty string)

Content of the message. No more than 15000 characters.

content_format optional

Default value: plain

Format of the message content.

Possible values: plain, html.

send_summary optional

Default value: false

Should the summary report (as described in services/mailing/send_simple_message method) be sent to the user?

send_to_myself optional

Default value: false

Should the copy of the message be sent to the user?

attachments_lifetime optional

Default value: 14

The number of days the attachments should be available for.

The time starts counting from the moment the message is sent. After this time attachments will be automatically deleted.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of the following structure:

  • message_id - created message ID.

Thrown errors:

  • object_forbidden - access to institutional address denied.

    Possible reasons:

    • inst_address_unassigned - institutional address was not assigned to you.

  • object_not_found - institutional address could not be found; param_name is equal to from_inst_address_id.

services/mailclient/delete_attachments

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Delete attachments of messages.

This method works only with messages with status draft.

attachment_ids required

List of attachment IDs.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of the following structure:

  • matched - a list of message IDs which were actually deleted.

services/mailclient/delete_messages

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Delete messages.

message_ids required

List of message IDs which should be deleted.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of the following structure:

  • matched - a list of message IDs which were actually deleted.

services/mailclient/message

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Get information on a given message.

message_id required

Message ID.

fields optional

Default value: id|subject

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • Primary:

    • id - message ID;

    • from_inst_address - dictionary describing institutional address, which this message will be sent from, or null if user's email address should be used instead.

      This field references objects returned by services/instaddr/inst_address method. See its returns section for possible subfields (only primary are allowed).

    • subject - subject of the message;

    • status - status of the message.

      Possible values:

      • draft - message is a draft;

      • pending - send_message has been called, but a sending process has not finished yet;

      • error - the sending process has been completed, but USOS API encountered problems for some of the recipients;

      • sent - the message has been successfully sent to all recipients.

    • date - the date of last modification; in case of sent messages this will be the date the message was sent.

  • Secondary:

    • send_summary - true if the summary report (as described in services/mailing/send_simple_message method) should be sent to the user, false otherwise;

    • send_to_myself - true if the copy of the message be sent to the user, false otherwise;

    • content - content of the message;

    • content_format - format of the message content - either plain or html;

    • attachments_lifetime - the number of days the attachments are available for;

    • recipients_valid - is the list of recipients up-to-date? (always true for sent messages);

    • recipients_count - the total number of recipients of the message; this includes users who do not have an email address;

    • emails_count - the number of recipients the message will be (or was) really sent; this excludes users who do not have an email address;

    • attachments - a list of dictionaries describing message attachments.

      This field references objects returned by attachment method. See its returns section for possible subfields.

Thrown errors:

  • object_not_found - message could not be found; param_name is equal to message_id.

services/mailclient/messages

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Get information on multiple messages.

message_ids required

List of message IDs.

fields optional

Default value: id|subject

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of message method.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary mapping message IDs to dictionaries describing the messages (as returned by message method). If specified message could not be found, null is returned instead of a dictionary.

services/mailclient/put_attachment

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Upload an attachment.

This method works only with messages with status draft.

message_id required

Message ID.

data required

The file to be attached.

Important: Currently there are no size limits for the attachments, but they might be in the future! However, you may assume that the maximum allowed size for a single attachment will never drop below 100 MB.

filename optional

The name of a file. No more than 100 characters. If omitted, the value will be taken from data field, but still character limit is implied.

content_type optional

Uploaded file content type. If you omit this argument, USOS API will try to guess it.

description optional

Default value: (empty string)

Attachment description. No more than 200 characters.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of the following structure:

  • attachment_id - attachment ID.

Thrown errors:

  • object_invalid - message is in invalid state.

    Possible reasons:

    • attachment_limit_exceeded - maximum number of attachments (10) exceeded;

    • draft_required - message is not a draft.

  • object_not_found - message could not be found; param_name is equal to message_id.

services/mailclient/recipients

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Get a list of recipients of a given message.

message_id required

Message ID.

fields required

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A list of dictionaries of the following structure:

  • email - email of the recipient or null if the email could not be determined;

  • user - dictionary describing user or null if the recipient does not refer to any user.

    This field references objects returned by services/users/user method. See its returns section for possible subfields.

  • status - the status of the sending process for this specific recipient.

    Possible values:

    • null - the message is not being currently sent to the recipient (it is a draft or email is null)
    • pending - the message is waiting to be sent to the recipient;
    • error - the message could not be sent to the recipient;
    • sent - the message has been successfully sent to the recipient.

Note that always at least one of email and user values is not null. If email is null, then the corresponding user exists but does not have an email. If, on the other hand, user is null, then the dictionary was created based on an individual email, hence email is not null.

Thrown errors:

  • object_not_found - message could not be found; param_name is equal to message_id.

services/mailclient/recipients_group

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Get information on a given recipients group.

message_id required

Message ID.

fields required

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • primary_groups - list of dictionaries describing primary groups that were added to this group.

    This field references objects returned by services/prgroups/primary_group method. See its returns section for possible subfields (only primary are allowed).

  • custom_groups - list of dictionaries describing custom groups that were added to this group; each dictionary contains primary fields described in this section.

    This field references objects returned by services/csgroups/custom_group method. See its returns section for possible subfields (only primary are allowed).

  • users - list of dictionaries describing users that were added to this group.

    This field references objects returned by services/users/user method. See its returns section for possible subfields.

  • emails - list of individual email addresses added to this group.

Thrown errors:

  • object_not_found - message could not be found; param_name is equal to message_id.

services/mailclient/refresh_recipients

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Regenerate recipients list based on recipient group contents.

Depending on complexity of message recpients group, this method may take longer time to complete. You should take this into account and probably call this method asynchronously in your application.

This method works only with messages with status draft.

message_id required

Message ID.

email_source optional

Default value: primary_only

Choose which email addresses will be used to send a message. Possible choices:
  • primary_only (default) - user's primary email;
  • alt_only - user's alternative email (see method services/users/user for details);
  • primary_preferred - if user doesn't have a primary email, alternative will be used;
  • alt_preferred - if user doesn't have an alternative email, primary will be used
format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

An empty dictionary returned if the method has been executed successfully. Some keys may be added in the future.

Thrown errors:

  • object_invalid - message is in invalid state.

    Possible reasons:

    • draft_required - message is not a draft;

    • recipients_group_modified - recipients group has been modified concurrently.

  • object_not_found - message could not be found; param_name is equal to message_id.

services/mailclient/retry_send_message

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Retry sending a message.

message_id required

Message ID.

lang optional

Default value: pl

Language of headers and signatures added by USOS API to the message before sending. Accepted values are pl and en.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

An empty dictionary returned if the method has been executed successfully. Some keys may be added in the future.

Thrown errors:

  • object_forbidden - access to institutional address denied.

    Possible reasons:

    • inst_address_unassigned - institutional address was not assigned to you.

  • object_invalid - message is in invalid state.

    Possible reasons:

    • error_required - message does not have status error.

  • object_not_found - message could not be found; param_name is equal to message_id.

services/mailclient/send_message

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Send a given message. Following conditions must be all true in order to be able to send the message:

  • subject must not be empty;

  • content must not be empty;

  • recipients list must not be outdated (see recipients_valid field in the returns section of message method);

  • recipients list must not be empty, even if send_to_myself is set to true;

  • access to institutional address (if used) could not be revoked;

  • message must have status draft.

message_id required

Message ID.

lang optional

Default value: pl

Language of headers and signatures added by USOS API to the message before sending. Accepted values are pl and en.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

An empty dictionary returned if the method has been executed successfully. Some keys may be added in the future.

Thrown errors:

  • object_forbidden - access to institutional address denied.

    Possible reasons:

    • inst_address_unassigned - institutional address was not assigned to you.

  • object_invalid - message is in invalid state.

    Possible reasons:

    • content_required - message content is empty;

    • draft_required - message is not a draft;

    • recipients_outdated - list of recipients is outdated;

    • recipients_required - list of recipients is empty;

    • subject_required - message subject is empty.

  • object_not_found - message could not be found; param_name is equal to message_id.

services/mailclient/update_attachment

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Update information on a given attachment. Note that only description can be changed. If you want to update other fields, you have to delete the old attachment and upload the new one.

This method works only with messages with status draft.

attachment_id required

Attachment ID.

description required

Attachment description. No more than 200 characters.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

An empty dictionary returned if the method has been executed successfully. Some keys may be added in the future.

Thrown errors:

  • object_invalid - message is in invalid state.

    Possible reasons:

    • draft_required - message is not a draft.

  • object_not_found - attachment could not be found; param_name is equal to attachment_id.

services/mailclient/update_message

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Update a message.

This method works only with messages with status draft.

message_id required

Message ID.

subject optional

Default value: (unchanged)

Subject of the message. No more than 200 characters.

from_inst_address_id optional

Default value: (unchanged)

Institutional address ID from which the message should be sent, or null if user's email address should be used instead.

Most users do not have any institutional address assigned so in most cases this value will be null.

content optional

Default value: (unchanged)

Content of the message. No more than 15000 characters.

content_format optional

Default value: (unchanged)

Format of the message content.

Possible values: plain, html.

send_summary optional

Default value: (unchanged)

Should the summary report (as described in services/mailing/send_simple_message method) be sent to the user?

send_to_myself optional

Default value: (unchanged)

Should the copy of the message be sent to the user?

attachments_lifetime optional

Default value: (unchanged)

The number of days the attachments should be available for.

The time starts counting from the moment the message is sent. After this time attachments will be automatically deleted.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

An empty dictionary returned if the method has been executed successfully. Some keys may be added in the future.

Thrown errors:

  • object_forbidden - access to institutional address denied.

    Possible reasons:

    • inst_address_unassigned - institutional address was not assigned to you.

  • object_invalid - message is in invalid state.

    Possible reasons:

    • draft_required - message is not a draft.

  • object_not_found - institutional address could not be found; param_name is equal to from_inst_address_id;

  • object_not_found - message could not be found; param_name is equal to message_id.

services/mailclient/update_recipients_group

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Update a recipients group.

Remember to call refresh_recipients method after executing this method or you will not be able to send the message.

This method works only with messages with status draft.

message_id required

Message ID.

primary_group_ids optional

Default value: (unchanged)

List of primary group IDs that are part of this group.

custom_group_ids optional

Default value: (unchanged)

List of custom group IDs that are part of this group.

user_ids optional

Default value: (unchanged)

List of user IDs that are part of this group.

emails optional

Default value: (unchanged)

List of email addresses that are part of this group.

strict optional

Default value: true

Should a nonexistent object referenced by primary_group_ids, custom_group_ids or user_ids argument cause an error? If set to false, all invalid references will be silently discarded.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

An empty dictionary returned if the method has been executed successfully. Some keys may be added in the future.

Thrown errors:

  • object_invalid - message is in invalid state.

    Possible reasons:

    • draft_required - message is not a draft.

  • object_not_found - custom group could not be found; param_name is equal to custom_group_ids;

  • object_not_found - message could not be found; param_name is equal to message_id;

  • object_not_found - primary group could not be found; param_name is equal to primary_group_ids;

  • object_not_found - user could not be found; param_name is equal to user_ids.

services/mailclient/user

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Get a list of user's messages. You can optionally filter the list by message status.

fields optional

Default value: id|subject

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of message method.

status optional

List of status values (draft, pending, sent, error). All messages with different status will be filtered out.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A list od dictionaries describing messages. Each dictionary contains keys listed in the fields argument.

USOS API ver. 6.1.2.0-bc1aa53 (2016-06-07)