GroupWise is an email system.  You'd expect that one of the most common things people do with it is send email, right?  So, it stands to reason that if there are API's that allow developers to use/control the system, the API's should support this ability.  Am I right?  Yes.  Yes I am.  But wait!  Read on...

You would think that the folks at Novell would do at least one of two things, if not both of them:

1. Make it incredibly straightforward and easy to create new email using the API.
2. Document the process of creating email using the API.

But, as it turns out, they have done NEITHER of these with the GWSOAP API.  If you try to figure it out by reading the documentation, you ARE going to be frustrated, and probably suffer a little mental illness, at least for a while.  So, instead, learn how to do it here:

As with most things in the SOAP API, sending email involves this basic pattern:

1. Create a "request" object.
2. Call the related "request" method, passing it the request object.
3. Get and examine/use the "response" object that is returned.

There are two steps to sending email using the SOAP API.  Each step follows this pattern (outlined above).  The two steps are:

1. Create an email message. 
2. Send the email message.
   

There are three ways to create email in GroupWise (both through the clients, as well as through the API's):

1. Create a new message.
2. Reply to an existing message.
3. Forward an existing message.

All three of these methods have corresponding "request" objects and methods, and "response" objects.

We will address replies and forwards later.  Let's focus on sending a new email for now.

Step 1: Create a new message

This sounds like a fairly innocuous step.  But it can be quite involved.  There are a lot of metadata elements on a message that must be tended to, including who it's addressed to, attachments, etc.

In order to create a new message, you simply instantiate a message object from among the object classes that were created when you "imported" (or compiled) the GroupWise Web Services WSDL.  Class names may vary a bit, but generally the names should match the object class names in the GroupWise SOAP documentation.

The following item types may be "sent" as new emails:

• Mail
• Appointment
• Task
• Note
• PhoneMessage

Once you have your shiny new object in memory, the next step is to populate it with any meaningful metadata you have:

Step 2: Edit the message

There are a lot of intricate details to this step.  Indeed, this is where most of the "work" and complexity come in.  For most email messages, there are four basic things to modify:

1. The subject
2. The distribution list
3. The message body
4. Attachments

These elements are common to all of the types you could send, so we will cover these here.  Other elements that are specific to the other message types (such as appointment start and stop times, task priority, and phone message phone number) are fairly straightforward, and are documented fairly well.

For now, let's assume we are sending an email message.  In C# (sorry, that's what I use a lot), we would create our new Mail message like this:

Mail newMail = new Mail();

Now, what to do with it...

Subject

First we will set the subject.  This is easy:

newMail.subject = "test subject";

Distribution List

Next, we will address the message.  This is a little more involved.

The "distribution list" property of the mail message is an object of type Distribution.  The field name on the Mail message is "distribution".  After you create a new mail message, this field is null.  So we must instantiate a Distribution object and assign it to our Mail message:

newMail.distribution = new Distribution(); 

Next, we need to add recipients to our distribution list.  The Distribution class has a number of properties on it.  One is an array object of type Recipients[].  Similar to the "Mail.distribution" property, the Distribution.recipients property is null for a newly created Distribution object.  So we have to create the array.  This is actually good, because it allows us to create an efficient array of the exact size we need.  (I assume that you won't create the Recipients[] array until you know all the recipients you plan to send to...) :

newMail.distribution.recipients = new Recipient[1];

As you can see, in our case, we plan to send to a single recipient.

Note that while we  now have Recipients array, we don't yet have any Recipient objects in that array.  We have to create them:

newMail.distribution.recipients[0] = new Recipient();

Now, we are ready to populate our recipient with information:

newMail.distribution.recipients[0].email = "
 This e-mail address is being protected from spam bots, you need JavaScript enabled to view it
 ";
newMail.distribution.recipients[1].distType = DistributionType.TO;  // this could be .CC or .BC as well
newMail.distribution.recipients[0].displayName = "Sean Kirkby";

So, as you can see, we are addressing our message to Sean Kirkby, This e-mail address is being protected from spam bots, you need JavaScript enabled to view it (as a "TO" recipient).

So now we have our distribution list... on to the message body.

Message Body

<Coming soon...>

Next, we look at adding attachments...

Attachments

<Coming soon...>

Now that we have our completed message, with Subject, Distribution List, Message Body, and Attachments, we are ready to actually send the item.

Sending The Item

To send an item that you have created in memory, you need to create a "sendItemRequest" object, and pass it to the "sendItemRequest" method of your GroupWiseBinding object.  In our sample case, the GroupWiseBinding object is called "gw".  Here is how it's done:

The sendItemRequest object we create will need a reference to the Mail object we've created.  This is the sendItemRequest.item property.  It is of type "Item", so it can take any of "Item's" decendants, i.e. Mail, Appointment, Task, Note, and PhoneMessage.

sendItemRequest sendReq = new sendItemRequest();
sendItemResponse sendResp;
sendReq.item = newMail;
sendResp = gw.sendItemRequest(sendReq);

That's it!  Our message is now on it's way.  You can examine the "sendResp.status" object (it's "code" and "description" properties are particularly meaningful) to see if the send request succeeded, etc.

In future articles, we will address sending to groups, sending to items from the address book, metadata for calendar items, and sending recurring items.  But hopefully this will get you on your way for now...