Isode Messaging APIs



Isode Messaging APIs

Summary This page describes how to use the Isode Tcl X.400 API to retrieve and submit messages using P7 into or out of a Message Store, or P3 directly into or out of an MTA

Content

X.400 Tcl API - Example Applications

Application Features

These examples show how to do the following using the Tcl API

  • submit X.400 messages,
  • submit delivery reports
  • submit IPNs
  • retrieve X.400 messages
  • retrieve delivery reports
  • retrieve IPNs

Messaging Configuration

Before running the P3/P7 applications you need run Mconsole to configure and run a messaging configuration including, (if you are using P7) an Isode Message Store.

You also need to configure a P3 or P7 user using the X.400 Mailbox View in Mconsole.

Configuring the Applications

You can set the default values in the session object in the same way as the C API. For example:

      
$c priority 94
$m original_encoded_information_types ia5-text

In the script, the variables which be usefully configured are between the lines 

# Start configuration
[...]
# End

Some of the values set are optional, but appear in the example to show you how they are set.

set connection_type "p7": configure whether you are using P3 or P7.

set hostname: The system on which the P7 server is running
set user_oraddr: The O/R Address of the P7 User as which to bind to the Message Store
set originator: The O/R Address to use as the originator of the message when sending (needs to be the same as user_oraddr).
set recipient1: The O/R Address to use as the recipient of the message when sending

Submission via the Message Store (P7)

  • x400_ms_send_message.tcl - Sends a simple text message to the Message Store, to one or more addresses
  • x400_ms_send_read_receipt.tcl - Sends a IPN (read receipt) to an address
  • x400_ms_send_non_read_receipt.tcl - Sends a IPN (non read receipt) to an address

Use the X.400 Mailbox view to setup the P7 Users.

Make sure that the users that are referred to in originator and recipient variables exist and the MTA knows how to route a message to them. To check the O/R address use the command line utility (or test user in Mconsole)

# ckadr -x "<O/R address>"

You may wish to configure recipient2 as an undeliverable address so you can cause Non-delivery reports to be generated. NB if the recipient is non-delivered by the MTA associated with the store, the submission will fail, so you should arrange for the recipient to be non-delivered by an MTA to which the message is relayed to generate the non-delivery report).

Retrieval from the Message Store (P7)

  • x400_ms_rcv_message.tcl [all] - Receives one (or all) messages that are waiting for a user in the Message Store, and shows the content on the screen. It can deal with simple text messages, delivery reports and IPNs.

Submission directly to the MTA (P3)

Connection to the MTA

This is configured in a similar way to P7 submission, except for the connection_type variable: 

set connection_type "p3"

The Presentation Address of the P3 Channel in the MTA, includes the Internet address of the machine where is running. Check in Mconsole the value used by your Message Store. To set the value change the following line (with the correct IP address or hostname of your store):

set pa \"3001\"/URI+0000+URL+itot://bevan.isode.net:3001"

The Credentials of the user are configured as a Message Store User (even though messages are being submitted and retrieved directly from the P3 channel). The credentials comprise an O/RName (DN and O/R address) and a password. Check in Mconsole the values used by your Message Store User.

The following entries are used to configure credentials. To make the originator the same as the bound user, set the O/R address as follows:

set user_oraddr $originator

The password of the user that is binding to the P3 channel to send or receive messages must be entered on the command line. You can check the user's password by editing its properties in Mconsole.

set user_password "l1password"

Retrieval directly from the MTA (P3)

Connection to the MTA

This is configured in the same way as for P7 Submission, except for the connection_type variable:

set connection_type "p3"

The Presentation Address of the P3 Channel in the MTA, includes the Internet address of the machine where is running. Check in Mconsole the value used by your Message Store. To set the value change the following line (with the correct IP address or hostname of the P3server on your MTA):

set pa \"593\"/URI+0000+URL+itot://bevan.isode.net"

The Credentials of the user are configured as a Message Store User (even though messages are being submitted and retrieved directly from the P3 channel). The credentials comprise an O/RName (DN and O/R address) and a password. Check in Mconsole the value used by your Message Store User.

The following entries are used to configure credentials. To make the originator the same as the bound user, set the O/R address as follows:

set user_oraddr $originator

The password of the user that is binding to the P3 channel to send or receive messages must be entered on the command line. You can check the user's password by editing its properties in Mconsole.

set user_password "l1password"

Running the Applications

Unix

To run the applications you simply run the script from the command line. No arguments are required.

Submitting a message:

  
# ./x400_ms_send_message.tcl
Message Sent:   message_identifier = [/PRMD=TestPRMD/ADMD=TestADMD/C=GB/;dhcp-164.i.1013701-080228.141118]
                message_submission_time=080228141118Z
                ipm_identifier=99999999.9999*/CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/<cn=Him, c=gb>

Retrieving a message

# ./x400_ms_rcv_message.tcl

Waiting for 60 seconds or for a message to arrive
done
******************* Read a message *********************
Message sequence number = 52
***Envelope attributes***
message_identifier = [/PRMD=TestPRMD/ADMD=TestADMD/C=GB/;dhcp-164.i.1018201-080228.141422]
content_type = 22
content_identifier = My-Test
original_encoded_information_types = ia5-text
priority = 1
message_submission_time = 080228141422Z
message_delivery_time = 080228141422Z
originator_return_address = /CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
or_address = /CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
start of DL expansion
Command failed: Missing attribute in message
***Recipients***
***recip_primary number 1***
or_address = /CN=P7User2/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
country_name = GB
admd_name = TestADMD
prmd_name = TestPRMD
organization_name = dhcp-164
organizational_unit_name_1 = Sales
common_name = P7User2
reply_requested = 0
***header_originator number 1***
or_address = /CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
country_name = GB
admd_name = TestADMD
prmd_name = TestPRMD
organization_name = dhcp-164
organizational_unit_name_1 = Sales
common_name = P7User1
***recip_envelope number 1***
or_address = /CN=P7User2/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
country_name = GB
admd_name = TestADMD
prmd_name = TestPRMD
organization_name = dhcp-164
organizational_unit_name_1 = Sales
common_name = P7User2
responsibility = 1
IPN attribute '0'
***Content attributes***
ipm_identifier = 99999999.9999*/CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/<cn=Him,c=gb>
subject = Test of sending from Tcl
replied_to_identifier = 1064840642.7877*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<cn=Him,c=gb>
obsoleted_ipms = 10.0001*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb> 10.0002*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb>
related_ipms = 10.0003*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb> 10.0004*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb>
expiry_time = 080929140419+1100
reply_time = 080929140419+1100
importance = 2
sensitivity = 1
num_attachments = 1
ia5text = Body of the message sent from the Tcl script

Windows

To run the applications you run tclsh to source the script from the command line. No arguments are required.

Submitting a message:

# tclsh -s x400_ms_send_message.tcl
Message Sent:   message_identifier = [/PRMD=TestPRMD/ADMD=TestADMD/C=GB/;dhcp-164.i.1013701-080228.141118]
                message_submission_time=080228141118Z
                ipm_identifier=99999999.9999*/CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/<cn=Him, c=gb>

Retrieving a message

# tclsh -s x400_ms_receive_message.tcl 

Waiting for 60 seconds or for a message to arrive
done
******************* Read a message *********************
Message sequence number = 52
***Envelope attributes***
message_identifier = [/PRMD=TestPRMD/ADMD=TestADMD/C=GB/;dhcp-164.i.1018201-080228.141422]
content_type = 22
content_identifier = My-Test
original_encoded_information_types = ia5-text
priority = 1
message_submission_time = 080228141422Z
message_delivery_time = 080228141422Z
originator_return_address = /CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
or_address = /CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
start of DL expansion
Command failed: Missing attribute in message
***Recipients***
***recip_primary number 1***
or_address = /CN=P7User2/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
country_name = GB
admd_name = TestADMD
prmd_name = TestPRMD
organization_name = dhcp-164
organizational_unit_name_1 = Sales
common_name = P7User2
reply_requested = 0
***header_originator number 1***
or_address = /CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
country_name = GB
admd_name = TestADMD
prmd_name = TestPRMD
organization_name = dhcp-164
organizational_unit_name_1 = Sales
common_name = P7User1
***recip_envelope number 1***
or_address = /CN=P7User2/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
country_name = GB
admd_name = TestADMD
prmd_name = TestPRMD
organization_name = dhcp-164
organizational_unit_name_1 = Sales
common_name = P7User2
responsibility = 1
IPN attribute '0'
***Content attributes***
ipm_identifier = 99999999.9999*/CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/<cn=Him,c=gb>
subject = Test of sending from Tcl
replied_to_identifier = 1064840642.7877*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<cn=Him,c=gb>
obsoleted_ipms = 10.0001*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb> 10.0002*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb>
related_ipms = 10.0003*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb> 10.0004*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb>
expiry_time = 080929140419+1100
reply_time = 080929140419+1100
importance = 2
sensitivity = 1
num_attachments = 1
ia5text = Body of the message sent from the Tcl script

Correlation of messages, delivery reports and IPNs

When a message is submitted via the Message Store API the MTA assigns it a message identifier. This value is then returned by the API in the message_identifier attribute of the message object.

When a report is generated by the destination MTA, the value of the original message identifier is set in the subject_identifier of the delivery report, allowing you to correlate the original message with the report.

When the recipient's X.400 user agent reads the message, an IPN should be created, with the message_identifier field set to the message_identifier of the original message.

Please note that the Tcl API example x400_ms_rcv_message.tcl does not generate an IPN when it reads a message.

When a message is transferred-in via the MT API, the message identifier is set by the API user.

When a report is generated by the MT API user, the value of the original message identifier has to be set in the subject_identifier of the delivery report, allowing the recipient to correlate the original message with the report.