SMTPSync

Home > Books > NetKernel API and Services Reference > Accessor Listing > SMTP Email Service > SMTPSync

Module

The SMTPSync accessor is exported by the urn:org:ten60:netkernel:mod:smtp module. Import this module to gain access to the accessor.

Syntax

URI

active:SMTPSync

Argument	Rules	Description
operand	Mandatory	Email Metadata
operator	Optional	Force Reconfiguration
part1	Mandatory	Email multipart
part2	Optional	Email multipart

Example Usage

DPML

<instr>
  <type>SMTPSync</type>
  <operand>
    <email>
      <to>[email protected]</to>
      <cc>[email protected]</cc>
      <subject>License Enquiry</subject>
      <from>[email protected]</from>
    </email>
  </operand>
  <message>messagebody.html</message>
  <target>this:response</target>
</instr>

NetKernel Foundation API

req=context.createSubRequest("active:SMTPSync");
req.addArgument("operand", [resource representation, aspect, or URI] );
req.addArgument("part1", [resource representation, aspect, or URI] );
result=context.issueSubRequest(req);

Purpose

The SMTPSync accessor is an email SMTP client. SMTPSync is synchronous, messages posted via SMTPSync are immediately dispatched to the target SMTP gateway - retry and message delivery is delegated to the SMTP gateway. If a message cannot be delivered to the SMTP gateway an exception is thrown. An alternative asynchronous SMTP client SMTPServer is provided.

Multipart MIME messages are supported.

Usage

All message content is supplied as arbtrarily named arguments to the accessor. There may be any number of argument resources each of which will be attached, in declaration order, to the multi-part email message. Generally the first argument should be for a resource with a text mimetype (eg text/plain, text/html)- this will appear as the primary email message. Any resource that is not a text mimetype will be attached as a base64 encoded attachment.

The SMTPSync requires email header information. This is supplied in an "email" document supplied as the operand - it has the following structure.

<email>
  <to>[email protected]</to>
  <cc>[email protected]</cc>
  <bcc>[email protected]</bcc>
  <subject>Some subject</subject>
  <from>[email protected]</from>
  <attachment>
    <name>part1</name>
    <filename>invoice.pdf</filename>
  </attachment>
</email>

to an email address to send the message to
cc an email address to cc the message to
bcc an email address to bcc the message to
subject the email subject
sender the email address to use as sender
attachment an optional container for attachment metadata
name the name of the argument holding the attachment.
filename the filename to use for the attachment..

Multiple to, cc, bcc fields may be provided.

The attachment field is an optional tag to specify the filename to use for a given attachment. The filename will be assigned to the argument with the same name as in the attachment/name element. If no attachment field is provided an attachment will get the argument name as its filename.

Configuration

The configuration is read from a config file ffcpl:/etc/SMTPConfig.xml which should be present in the module which uses SMTPSync . The config file should look like...

<SMTPConfig>
  <SMTPGateway>smtp.some-domain.com</SMTPGateway>
  <SMTPUser />
  <SMTPPassword />
  <SMTPPort>25</SMTPPort>
  <sender>[email protected]</sender>
  <pollInterval>10000</pollInterval>
  <maxRetrys>3</maxRetrys>
</SMTPConfig>

SMTPGateway an SMTP server name
SMTPUser a user name (blank for anonymous SMTP server)
SMTPPassword a password (blank for anonymous SMTP server)
SMTPPort an optional port setting - will default to 25 if not specified
sender the default email to use as sender - can be overridden in the operand.
pollInterval the period in milli-seconds at which the mail queue will be polled
maxRetrys for failed deliveries the maximum number of times to try resending.

To force the SMTP Server to send all currently queued messages and update the configuration pass an operator with an xml fragment <reconfigure/>.