Mail client
:: services/mailclient module

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 Get information on a given attachment.
attachments Get information on multiple attachments.
case_category Get a single case category
cases_categories Get emails of cases categories.
copy_message Create a copy of a message.
create_and_send_message Create and send a simple message.
create_message Create a new message.
delete_attachments Delete message attachments.
delete_messages Delete messages.
message Get information on a given message.
messages Get information on multiple messages.
put_attachment Upload an attachment.
recipients Get a list of recipients.
recipients_group Get information on a given recipients group.
refresh_recipients Regenerate recipients list.
retry_send_message Retry sending a message.
send_message Send a message.
update_attachment Update an attachment.
update_message Update a message.
update_recipients_group Update a recipients group.
user Get user's messages.

services/mailclient/attachment

Consumer: required Token: required Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/attachment

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

Consumer: required Token: required Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/attachments

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/case_category

Consumer: required Token: optional Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/case_category

Get a single case category
case_category_id required ID of case category
fields optional

Default value: id|name|description

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 optional oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - ID of case category;

  • name - LangDict, name of category;

  • description - LangDict, description.

services/mailclient/cases_categories

Consumer: required Token: optional Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/cases_categories

Get emails of cases categories.
active_only optional

Default value: true

Filter only to active emails
fields optional

Default value: id|email|email_description|is_active|faculty

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 optional oauth_token for Token authorization.

Returned value:

List of dictionaries of selected fields and their values.

Available fields:

  • id - Id;

  • email - Email;

  • email_description - LangDict, email description;

  • is_active - boolean, is email active;

  • faculty - an associated faculty.

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

  • case_category - dictionary describing case category.

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

services/mailclient/copy_message

Consumer: required Token: required Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/copy_message

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_and_send_message

Consumer: required Token: optional Scopes: mailclient SSL: required
https://api.usos.tu.kielce.pl/services/mailclient/create_and_send_message

Send simple plain text message in the name of a user.

This method bypasses the "regular" way of using the mailclient module. Instead of requiring you to create the message first (via the create_message method), and sending it afterwards (via the send_message method), it allows you to do both - create it and send it - in a single request. You will need to meet all requirements described in both of these methods, otherwise the new message won't be sent (nor saved).

Unlike most other methods in this module, this method is accessible to regular consumers - you don't need to be an administrative consumer in order to use it. In a long run, more mailclient methods may become accessible to the public, but - at this moment - only this method is.

Note, that this method may put some additional restrictions upon you and your users to prevent abuse (i.e. mass mailing). If we detect possible abuse, PotentialSpam error may be raised. Eventually, both you (the consumer), or your user, may be banned from sending messages (resulting in UserBanned and ConsumerBanned errors respectively).
subject required

Subject of the message. No more than 200 characters.
content required

Content of the message. No more than 15000 characters.
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.
primary_group_ids optional

List of primary group IDs that should be included in recipients list.
custom_group_ids optional

List of custom group IDs should be included in recipients list.
user_ids optional

List of user IDs that should be included in recipients list.
emails optional

List of email addresses that are part of this group.
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?
content_format optional

Default value: plain

Format of the message content.

Possible values: plain, html.
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 optional oauth_token for Token authorization.

Returned value:

Dictionary with a single message_id key - the ID of the newly sent message. In case of bad request, you will get HTTP 400 with error description.

Thrown errors:

  • object_invalid - message is in invalid state.

    Possible reasons:

    • consumer_banned - application was banned from sending messages;

    • content_required - message content is empty;

    • potential_spam - message was rejected as potential spam;

    • recipients_required - list of recipients is empty;

    • subject_required - message subject is empty;

    • user_banned - you were banned from sending messages.

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

  • 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/create_message

Consumer: required Token: required Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/create_message

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

Consumer: required Token: required Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/delete_attachments

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

Consumer: required Token: required Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/delete_messages

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

Consumer: required Token: optional Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/message

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 optional 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

Consumer: required Token: required Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/messages

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

Consumer: required Token: required Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/put_attachment

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 for non-administrative consumers (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

Consumer: required Token: optional Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/recipients

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 optional 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

Consumer: required Token: required Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/recipients_group

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

Consumer: required Token: optional Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/refresh_recipients

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 optional 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

Consumer: required Token: required Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/retry_send_message

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

Consumer: required Token: optional Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/send_message

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 optional 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

Consumer: required Token: required Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/update_attachment

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

Consumer: required Token: required Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/update_message

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

Consumer: required Token: optional Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/update_recipients_group

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 optional 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

Consumer: required Token: required Scopes: mailclient SSL: not required
https://api.usos.tu.kielce.pl/services/mailclient/user

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. 7.1.0.0-4, 0e1fe7fc (2024-08-27)