User Guide

Here you'll find some examples how you could use jamaila.

Install jamaila

All you have to do is to download the appropriate jar-File of Jamaila and put it in the classpath of your application.

The latest version you find here, this is built with a 5.0 compiler. If you're looking for older versions, have a look to the archive.

Configuring Jamaila

As jamaila is a mail api, it's goal is to send emails for you. Because jamaila is not an smpt-server itself, you have to configure jamaila which means telling her which mail-server to use, giving her authentication information and so on. This is normally done via the jamaila.properties file, which must be found in the root of your classapth. Alternatively, you can specify a custom JamailaPreferences instance with the appropriate properties set.

The following properties are currently supported:

PropertyOptional?Description, Default Value
jamaila.mail.hosttrue The smtp server which shall be used as mail exchanger.

Default value: localhost
jamaila.mail.authtrue If your mail host requires smtp-auth, you must set this to true, otherwise you could omit this property or set it to false.

If you have set this property to true, you must specify the properties jamaila.mail.auth.username and properties jamaila.mail.auth.password

Default value: false
jamaila.mail.auth.usernameDepends on jamaila.mail.authIf you have set jamaila.mail.auth to true, you must supply your username here.
jamaila.mail.auth.passwordDepends on jamaila.mail.auth If you have set jamaila.mail.auth to true, you must supply your password here.
jamaila.factory.clazznametrue If you want to use a custom factory (extend de.javakaffee.jamaila.MailFactory), then specify the classname here.

Default value: de.javakaffee.jamaila.MailFactoryDefaultImpl
jamaila.logger.clazznametrue If you want to inject a custom logger (implement de.javakaffee.jamaila.logging.MailLogger), then specify the classname here.

Default value: de.javakaffee.jamaila.logging.MailLoggerDefaultImpl
jamaila.msg.trim.leadingtrue Specifies, if leading spaces (whitespaces and tabs) shall be removed from the html message part. If this is set to true, and the property jamaila.msg.shorten.lines also is set to true, then first the leading spaces are removed.

Default value: true
jamaila.msg.shorten.linestrue Specifies, if lines of the content shall be wrapped after 72 characters. This is applied to both text and html.

Default value: true
A very simple example for jamaila.properties which uses another logger implementation:
jamaila.logger.clazzname=de.javakaffee.jamaila.logging.MailLoggerVerboseImpl
Another example for jamaila.properties including smtp-auth:
jamaila.mail.host=yourmailhost.com
jamaila.mail.auth=true
jamaila.mail.auth.username=username
jamaila.mail.auth.password=password
Getting default access to Jamaila (using the jamaila.properties):
import de.javakaffee.jamaila.Jamaila;

public class MyMailClient {
	
    public void foo() {
   	    Jamaila jamaila = Jamaila.getInstance();
    }

}
Getting access to Jamaila using a custom JamailaPreferences:
import de.javakaffee.jamaila.JamailaPreferencesImpl;
import de.javakaffee.jamaila.Jamaila;

public class MyMailClient {
	
    public void foo() {
    	JamailaPreferences prefs = new JamailaPreferences();
    	prefs.setUseAuth( true );
    	prefs.setUsername( "yourUsername" ); 
    	prefs.setPassword( "yourPwd" );
   	    Jamaila jamaila = Jamaila.init( prefs );
    }

}

Using Jamaila

Sending directly a simple email containing plain text:
import de.javakaffee.jamaila.Jamaila;

public class MyMailClient {
	
    public void foo() {
   	    Jamaila.getInstance().sendMail(
            "from@me.tld", "to@you.tld", "subject", "here is some text message." );
    }

}
You can also send a multipart email containing both plain text or html:
import de.javakaffee.jamaila.Jamaila;

public class MyMailClient {
	
    public void foo() {
        Jamaila.getInstance().sendMail(
            "from@me.tld", "to@you.tld", "subject", "here is some text message.",
            "this is some html content." );
    }

}
You can do the same by setting this properties on a de.javakaffee.jamaila.Mail implementation:
import de.javakaffee.jamaila.Jamaila;
import de.javakaffee.jamaila.Mail;

public class MyMailClient {
	
    public void foo() {
        Mail mail = Jamaila.getInstance().createMail();
        
        mail.setSender( "from@me.tld" );
        mail.setRecipient( "to@you.tld" );
        mail.setSubject( "subject" );
        mail.setText( "here is some text message." );
        mail.setHTML( "this is some html content." );
        
        Jamaila.getInstance().sendMail ( mail );
    }

}
You also have the possibility to use named recipients or senders:
import de.javakaffee.jamaila.Jamaila;
import de.javakaffee.jamaila.Mail;

public class MyMailClient {
	
    public void foo() {
        Mail mail = Jamaila.getInstance().createMail();
        
        mail.setSender( "from@me.tld", "Senders Name" );
        mail.setRecipient( "to@you.tld", "Recipients Name" );
        mail.setSubject( "subject" );
        mail.setText( "here is some text message." );
        mail.setHTML( "this is some html content." );
        
        Jamaila.getInstance().sendMail ( mail );
    }

}
Send a simple email with one ore more attachments:
import java.io.File;
import de.javakaffee.jamaila.Jamaila;
import de.javakaffee.jamaila.Mail;

public class MyMailClient {
    
    public void sendEmailWithAttachments() {
        Mail mail = Jamaila.getInstance().createMail( "from@me.tld",
                "to@you.tld", "subject", "here is some text message." );
        mail.addAttachment( new File("somefile.txt") );
        Jamaila.getInstance().sendMail ( mail );
    }

}
Send an email with a listener, so that you get notified when the email was sent successfully or an error occured:
import de.javakaffee.jamaila.Mail;
import de.javakaffee.jamaila.MailDeliveryListener;
import de.javakaffee.jamaila.Jamaila;

public class MyMailClient {
    
    public void sendEmailWithListener() {
        Mail mail = Jamaila.getInstance().createMail( "from@me.tld",
                "to@you.tld", "subject", "here is some text message." );
        mail.addListener( new MailDeliveryListener() {
            public void success() {
                // perform your success logic
            }
            public void failure( Exception e ) {
                // perform your failure logic
            }
        } );
        Jamaila.getInstance().sendMail ( mail );
    }

}