Email class: Difference between revisions
mNo edit summary |
mNo edit summary |
||
| Line 1: | Line 1: | ||
The <var | The <var>Email</var> class is a high level, | ||
object oriented interface to client sockets that lets you write a <var class="product">User Language</var> SMTP | object oriented interface to client sockets that lets you write a <var class="product">User Language</var> SMTP | ||
(Simple Mail Transfer Protocol) | (Simple Mail Transfer Protocol) | ||
| Line 5: | Line 5: | ||
or the format of SMTP requests and responses. | or the format of SMTP requests and responses. | ||
The <var | The <var>Email</var> class methods let a <var class="product">User Language</var> program act as an SMTP client. | ||
SMTP clients send mail requests | SMTP clients send mail requests | ||
to an SMTP server, not directly to other SMTP clients. | to an SMTP server, not directly to other SMTP clients. | ||
The <var | The <var>Email</var> class methods only support communication with SMTP servers. | ||
An SMTP server will “store and forward” mail it receives. | An SMTP server will “store and forward” mail it receives. | ||
| Line 31: | Line 31: | ||
<div id="jport"></div> | <div id="jport"></div> | ||
You must define a Janus <var>[[JANUS CLSOCK|CLSOCK]]</var> port to use the <var | You must define a Janus <var>[[JANUS CLSOCK|CLSOCK]]</var> port to use the <var>Email</var> class. | ||
If you supply the IP address | If you supply the IP address | ||
of the server and the port number in the port definition, SMTP | of the server and the port number in the port definition, SMTP | ||
| Line 37: | Line 37: | ||
The following example defines a client socket port for use by SMTP applications. | The following example defines a client socket port for use by SMTP applications. | ||
For more detailed information about defining | For more detailed information about defining | ||
Janus client socket ports, see <var>[[JANUS DEFINE]]</var> and <var>[[JANUS CLSOCK]]</var>. | <var class="product">Janus</var> client socket ports, see <var>[[JANUS DEFINE]]</var> and <var>[[JANUS CLSOCK]]</var>. | ||
<p class="code"> JANUS DEFINE MYSMTP * CLSOCK 5 REMOTE 198.242.244.100 25 | <p class="code"> JANUS DEFINE MYSMTP * CLSOCK 5 REMOTE 198.242.244.100 25 | ||
</p> | </p> | ||
'''Note:''' | '''Note:''' | ||
To use the <var | To use the <var>Email</var> class objects, you must have licensed <var class="product">Janus Sockets</var> | ||
'''and''' <var class="product">[[Janus SOAP]]</var>. | '''and''' <var class="product">[[Janus SOAP]]</var>. | ||
The Sirius object-oriented alternative to $functions is designed for | The Sirius object-oriented alternative to $functions is designed for | ||
| Line 49: | Line 49: | ||
For details about the object syntax in this chapter, see | For details about the object syntax in this chapter, see | ||
[[Notation conventions for methods|"Notation conventions for methods"]]. | [[Notation conventions for methods|"Notation conventions for methods"]]. | ||
== | ==Email class summary== | ||
The following capabilities are provided by the <var | The following capabilities are provided by the <var>Email</var> class: | ||
<ul> | <ul> | ||
<li>Creating general purpose e-mail for SMTP | <li>Creating general purpose e-mail for SMTP | ||
| Line 59: | Line 59: | ||
<li>Access to status (error or confirmation messages) | <li>Access to status (error or confirmation messages) | ||
</ul> | </ul> | ||
You use the <var>Email</var> object to generate SMTP messages | |||
<var>Email</var> | |||
(e-mail) to send to an SMTP server. | (e-mail) to send to an SMTP server. | ||
To construct a request, you use <var>Email</var> methods to set and inspect | To construct a request, you use <var>Email</var> methods to set and inspect | ||
header information, content, and attachments. | header information, content, and attachments. | ||
To send e-mail, you use the <var>[[Mail (Email function)|Mail]]</var> method. | To send e-mail, you use the <var>[[Mail (Email function)|Mail]]</var> method. | ||
[[List of Email methods]] contains a list of all the methods in the <var>Email</var> class. | [[List of Email methods|"List of Email methods"]] contains a list of all the methods in the <var>Email</var> class. | ||
==SMTP examples== | ==SMTP examples== | ||
Examples follow in which <var>Email</var> objects are used to | Examples follow in which <var>Email</var> objects are used to | ||
create and send a request to an SMTP server. | create and send a request to an SMTP server. | ||
No Janus port definitions are shown. | No <var class="product">Janus</var> port definitions are shown. | ||
For comments about defining | For comments about defining <var class="product">Janus</var> ports for the <var>Email</var> class, see | ||
the [[#jport|earlier]] remarks. | the [[#jport|earlier]] remarks. | ||
===Basic e-mail example=== | ===Basic e-mail example=== | ||
Revision as of 19:12, 25 July 2011
The Email class is a high level, object oriented interface to client sockets that lets you write a User Language SMTP (Simple Mail Transfer Protocol) request without knowledge of socket level programming or the format of SMTP requests and responses.
The Email class methods let a User Language program act as an SMTP client. SMTP clients send mail requests to an SMTP server, not directly to other SMTP clients. The Email class methods only support communication with SMTP servers.
An SMTP server will “store and forward” mail it receives. This means that all messages are first received in entirety on the SMTP server, then the server attempts to deliver it to the recipients. Mail delivery can be delayed by a server that is down or too busy to accept connections. “Store and forward” gives the SMTP server the ability to retry delivery without making the SMTP client wait for completion.
A server might try to deliver a message for as long as a week or more. This, of course, makes it impractical for a client to wait for delivery confirmation, so the SMTP protocol does not provide such information. A “success” response from an SMTP server indicates only that the server has accepted the request and will attempt to deliver the mail to the recipients.
Most SMTP servers will at least confirm that any domain names in the recipient list are valid, but they cannot confirm that an actual recipient name is valid.
You must define a Janus CLSOCK port to use the Email class. If you supply the IP address of the server and the port number in the port definition, SMTP applications need only know the Janus port name to communicate with the server. The following example defines a client socket port for use by SMTP applications. For more detailed information about defining Janus client socket ports, see JANUS DEFINE and JANUS CLSOCK.
JANUS DEFINE MYSMTP * CLSOCK 5 REMOTE 198.242.244.100 25
Note: To use the Email class objects, you must have licensed Janus Sockets and Janus SOAP. The Sirius object-oriented alternative to $functions is designed for Janus SOAP applications only, and information about using Sirius objects is provided in "Janus SOAP User Language Interface" and "Getting started with object-oriented programming for User Language programmers". For details about the object syntax in this chapter, see "Notation conventions for methods".
Email class summary
The following capabilities are provided by the Email class:
- Creating general purpose e-mail for SMTP
- Sending general purpose e-mail via SMTP
- Setting e-mail content using Longstrings
- Sending MIME content (attachments and alternative content)
- Sending to multiple recipients
- Access to status (error or confirmation messages)
You use the Email object to generate SMTP messages (e-mail) to send to an SMTP server. To construct a request, you use Email methods to set and inspect header information, content, and attachments. To send e-mail, you use the Mail method.
"List of Email methods" contains a list of all the methods in the Email class.
SMTP examples
Examples follow in which Email objects are used to create and send a request to an SMTP server. No Janus port definitions are shown. For comments about defining Janus ports for the Email class, see the earlier remarks.
Basic e-mail example
This example uses most of the Email methods to send a simple message
to three recipients.
The local CLSOCK port used is named SPAM.
b %letter object Email %h longstring %t longstring %name longstring %nick string len 64 %letter = new %name = 'C_Coolidge@presidents.usa' %nick = 'SilentCal' %letter:AddRecipient(%name, %nick) %name = 'D_Eisenhower@presidents.usa' %nick = 'Ike' %letter:AddCc(%name, %nick) %name = L_Johnson@presidents.usa' %nick = 'LBJ' %letter:AddBcc(%name, %nick) %letter:Sender('a_huckster@bankandtrustme.com') %h = 'Subject:' %t = 'Lower Mortgage Rates' %letter:AddHeader(%h, %t) %h = 'Great deal of debt for you!' %letter:SetBody(%h) %letter:mail('SPAM', 0) print %letter:GetReplyCode with ' - ' with - %letter:GetReplyText %letter:discard end
E-mail with attachment
In the following example, an image is attached to a short e-mail message. The attachment is produced from a member of a local Model 204 procedure file using StringList class methods.
b %rolex is object Email %sl is object Stringlist %procdata is object Stringlist %jpg longstring %t longstring %temp string len 255 %procfile string len 10 %procname string len 63 %q float %rc float %rolex = new %sl = new %t = 'jbgood@netscape.net' %rolex:AddRecipient(%t, 'JB') %t = 'cberry@ucantbee-sirius.com' %rolex:Sender(%t) %rolex:AddHeader('Subject:', 'watch this...') text to %sl I want an authentic imitation Rolex watch. Something like the one shown in this image. Know anyone who's got one? end text %rolex:SetBody(%sl, encoding='none', type='text/plain') %procfile = 'MYPROC' %procname = 'FAKE5.JPG' %rc = $procopn(%procname, %procfile) if %rc ne 0 then print 'Cant open procedure ' with %procname - with ' in file ' with %procfile with ', rc = ' - with %rc stop end if %procdata = new %procdata:appendOpenProcedure %jpg = %procData:binaryProcedureDecode %rolex:AddPart(%jpg, type='image/jpg', name='Rolex1.jpg') print %rolex:mail('MYSMTP', 0) ' is return from Mail method' print %rolex:GetReplyCode ' is return from GetReplyCode' print %rolex:GetReplyText %rolex:discard end
If the request is successful, results like the following display at the terminal:
0 is return from Mail method 221 is return from GetReplyCode ucantbee-sirius.com running IBM VM SMTP Level 320 closing connection