Sending email messages
:: services/mailing module

These methods allow you to send email messages

Methods

check_message_status Check detailed status of a message. (administrative)
check_messages_status Check status of a messages. (administrative)
send_simple_by_template Send multiple messages using a template. (administrative)
send_simple_message Send an email message. (administrative)
send_simple_messages Call send_simple_message multiple times in one call. (administrative)
system_status Get information on the status of the module.

services/mailing/check_message_status

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

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/mailing/check_message_status

Check for the detailed status of a previously sent message.

When you've used a method like send_simple_message, you have not - strictly speaking - "sent" the message. You have enqueued it to be sent. USOS API will try to send this message as fast as possible. You may check for the status of this operation here.
message_id required

ID of the message. You will need to sign your request with the same Consumer Key as the one you signed the original sending request with.

Please note, that currently messages are kept for a period of 7 days. After this time, you won't be able to reference your message.
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. Token is not required.

Returned value:

The method returns a dictionary of the following structure:

  • finished - true, if USOS API has finished working with this message; if false, then the message is still waiting in a queue,

  • sent_successfully - boolean:

    • true, if USOS API has finished sending the message and it has been sent to all recipients,
    • false if the mail server rejected at least one of the recipients.

    Please do not confuse "being sent" with "being delivered". Currently, you have no way of knowing, if your mail was successfully delivered to the final recipient. USOS API does not keep track of events like mail returns etc.

  • status_by_recipient - a dictionary, one entry for each recipient:

    • key - recipient email address,
    • value - one of pending, sent or error.

services/mailing/check_messages_status

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

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/mailing/check_messages_status

Check for the status of a previously sent messages.

When you've used a method like send_simple_message, you have not - strictly speaking - "sent" the message. You have enqueued it to be sent. USOS API will try to send this message as fast as possible. You may check for the status of this operation here.
message_ids required

Pipe-separated list of email addresses - recipients of the message IDs. You will need to sign your request with the same Consumer Key as the one you signed the original sending request with.

Please note, that currently messages are kept for a period of 7 days. After this time, you won't be able to reference your message.
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. Token is not required.

Returned value:

Returns a dictionary where your message_ids will be mapped to a dictionary of the following structure

  • sent - the number of recipients to which the message was correctly sent
  • errors - the number of recipients to which message was not sent, because an error occured while sending
  • pending - the number of recipients to which the message was not already send

services/mailing/send_simple_by_template

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

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/mailing/send_simple_by_template

Send multiple messages using a template.

This method calls send_simple_message multiple times, each time with different contents, derived from a given simple template. All messages will be from the "USOS Notifier" address.
subject_template required Subject of the message, might include template placeholders (see below). The length of each subject (after template substitution) might not exceed 200 characters.
content_template required

Content of the message, might include template placeholders. The length of each message content (after template substitution) might not exceed 15000 characters.

Template placeholders are substrings in a form of {var_name}. Such strings will be replaced with the content of the var_name variable, which you will provide below (recipients argument).

Keep in mind, that in order to use curly braces signs in your templates, you will need to escape them with one more curly brace ("{{" and "}}"). See here for more info on Python format strings.
recipients required

JSON-formatted, UTF-8 encoded list of dictionaries. Each dictionary represents one recipient and has the following structure:

  • email - email address of the recipient,
  • vars - a dictionary of template placeholder substitutions for this recipient (var_name -> replacement).
from_name optional

Default value: USOS

Name to be inserted into the From header (no more than 100 characters).
from_email optional Email to be inserted into the From header (no more than 100 characters). Valid only is passed along the from_name argument. If not given, this will be a default no-reply address.
send_summary_to optional Email address. If given, USOS API will send a summary report to this address. This report will contain any errors USOS API encountered while sending the message. Original message content and recipients might be included. These reports might be split in several parts.
lang optional

Default value: pl

Either pl or en - the language, in which USOS API will generate headers and signatures that might be added to your message prior to the sending. This will also be the language in which the optional summary report will be generated.
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. Token is not required.

Returned value:

A list of message IDs generated for your messages (one for each of the recipients).

services/mailing/send_simple_message

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

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/mailing/send_simple_message
Send an email message, to any given email address(es). USOS API will automatically set all headers, apply word-wrap and append USOS signature and/or comments.
subject required Subject of the message (no more than 200 characters).
content required Content of the message (no more than 15000 characters).
recipients required Pipe-separated list of email addresses - recipients of the message.
from_name optional

Default value: USOS

Name to be inserted into the From header (no more than 100 characters).
content_format optional

Default value: plain

Type of content argument. Valid ones:

  • plain - plain text (MIME text/plain)

    USOS API will apply word-wrap.

  • html - text with HTML markup (MIME text/html)

    USOS API will try to repair broken HTML. Some elements ( scripts, embedded objects, frames, forms) will be removed due to security reasons.
from_email optional Email to be inserted into the From header (no more than 100 characters). Valid only is passed along the from_name argument. If not given, this will be a default no-reply address.
send_summary_to optional Email address. If given, USOS API will send a summary report to this address. This report will contain any errors USOS API encountered while sending the message. Original message content and recipients might be included. These reports might be split in several parts.
lang optional

Default value: pl

Either pl or en - the language, in which USOS API will generate headers and signatures that might be added to your message prior to the sending. This will also be the language in which the optional summary report will be generated.
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. Token is not required.

Returned value:

The method returns a dictionary of the following structure:

  • success - currently always true ( if something goes wrong, you will get a HTTP 400 error),

  • message_id - an unique message ID generated for your message.

    Message IDs might be used to check the status of the message. Please note, that messages are kept for a period of 7 days. After this time, you won't be able to reference your message.

services/mailing/send_simple_messages

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

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/mailing/send_simple_messages
Call send_simple_message multiple times in one call. This is useful when you want to send bulk messages with different content.
param_sets required

JSON-formatted, UTF-8 encoded list of dictionaries. Each dictionary is the set of parameters with which the send_simple_message method is to be invoked with.
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. Token is not required.

Returned value:

This method never fails (always returns HTTP 200). All of your calls are executed sequentially. If one fails, others still will be executed.

Method will return a list of Message IDs. n-th element on this list corresponds to the n-th dictionary in the param_sets list.

If n-th call fails (invalid arguments will be passed), then the n-th element will contain a single boolean false. No additional explanation (as to the cause of the error) will be returned. If you need error message, use the send_simple_message method (call it multiple times).

services/mailing/system_status

Consumer: optional Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/mailing/system_status
Get information on the status of the mailing module.
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 optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required.

Returned value:

A dictionary of the following structure:

  • total_pending_message_count - number of all unsent messages in the queue (this includes all messages from all the consumers),
  • my_pending_message_count - number of unsent messages enqueued by the consumer who's making the request; this key will be present only if the request is signed with the consumer key.
  • daemon_running - true if email sending daemon is running correctly, false otherwise

Please note, that each recipient of one message is counted separately (i.e. if you send one message to 3 recipients, then the number of total unsent messages will increase by 3).
USOS API ver. 7.1.0.0-4, 0e1fe7fc (2024-08-27)