Pages

Creating a xMail Plugin

Creating an xMail plugin

Setting up your code

To use the xMail API you will need to make sure xMail is loaded before your plugin. To do this simply make xMail a dependency in your plugin.yml.

Then all you have to do is this: XMailAPI api = new XMailAPI();

It's not all that hard :)

Sending mail

To send a basic mail object (no attachments) to someone is as easy as this:

XMailAPI api = new XMailAPI();
Mail mail = api.createMail("turt2live", "Hi there!"); // This creates a mail message to turt2live from the console with the message "Hi there!"
ServerResponse response = api.send(mail);
if(response != ServerResponse.FAILED && response.status = Status.OK){
    // Sent!
}else{
   // Not sent :(
}

Adding attachments

Let's say we wanted to add 10 stone, 3 diamonds, and $40.25 to a mail message. Here's how you'd do it:

XMailAPI api = new XMailAPI();
Attachment stone = new ItemAttachment(new ItemStack(Material.STONE, 10));
Attachment diamond = new ItemAttachment(new ItemStack(Material.DIAMOND, 3));
Attachment money = new MoneyAttachment(40.25);
Mail mail = api.createMail("turt2live", "Here's the items and money you wanted", stone, diamond, money);
ServerResponse response = api.send(mail);
if(response != ServerResponse.FAILED && response.status = Status.OK){
    // Sent!
}else{
   // Not sent :(
}

That easy!

Changing who the message is from

It's just a simple argument change. Let's take out example from simply sending mail like so:

// ...
Mail mail = createMail("turt2live", "Hi there!");
// ...

and simply change it to this:

Mail mail = createMail("player", "turt2live", "Hi there!"); // Mail is now from "player"

That's it! All the createMail() methods have the option for sending the mail as someone else.

Telling the user it was sent / Telling the receiver they have mail

Taking the example from simply sending mail, we end up with this snippet:

Mail mail = api.createMail("turt2live", "Hi there!"); // This creates a mail message to turt2live from the console with the message "Hi there!"
ServerResponse response = api.send(mail);

All we have to do is add a listener to the mail, this applies for both mail with and without attachments.

Keep in mind, xMail will tell them if they have new mail, this code will just give them a more personalized "You have new mail from <player>" message!

Mail mail = api.createMail("turt2live", "Hi there!"); // This creates a mail message to turt2live from the console with the message "Hi there!"
Player to = Bukkit.getPlayer("turt2live");
if(to != null){
    mail.addListener(new PlayerMailListener(PlayerListenerType.RECEIVE, to)); // This tells "turt2live" he has new mail
}
XMailEntity console = api.getConsole(); // This is the from field by default
mail.addListener(new PlayerMailListener(PlayerListenerType.SEND, console.getOwner()); // This tells the console the mail was sent
ServerResponse response = api.send(mail);

Extra stuff you can do with the API (examples coming soon)

  • Create a new mailbox for a player
  • Import mail from xMail (and into xMail!)
  • Listen to xMail events and react on those
  • Send letters to players (snail mail)

Suggestions / Comments

Let me know if you have any suggestions, comments, or concerns about the xMail API!

Comments

Posts Quoted:
Reply
Clear All Quotes