Play Now Login Create Account
illyriad
  New Posts New Posts RSS Feed - 24FEB15: XML FEED FOR INGAME MAIL
  FAQ FAQ  Forum Search   Register Register  Login Login

24FEB15: XML FEED FOR INGAME MAIL

 Post Reply Post Reply
Author
GM Stormcrow View Drop Down
Moderator Group
Moderator Group
Avatar
GM

Joined: 23 Feb 2010
Location: Illyria
Status: Offline
Points: 3926
Post Options Post Options   Thanks (0) Thanks(0)   Quote GM Stormcrow Quote  Post ReplyReply Direct Link To This Post Topic: 24FEB15: XML FEED FOR INGAME MAIL
    Posted: 24 Feb 2015 at 18:01
API KEY AND XML FEED FOR INGAME MAIL

For those of you who are building new third-party tools, you might be glad to know that there is now an API Key XML feed in place for Ingame mail (IGMs).

For those of you who don't know what an API Key is, it's essentially a way you can share specific data from your account (in this case your player accounts' ingame mailbox and individual mails, both mails sent and mails received) with a trusted third party - but without giving them sitting rights to your account.  

To be a bit more specific, by sharing your IGM Key you are saying "I don't mind you (and anyone you share my key with) from reading my account's ingame mailbox and each individual mail, without any further permissions from me, but that's all, and I reserve the right to revoke this key at any time, which will preventeveryone who has that revoked key from accessing any new IGMs sent or received by my Player account from the moment I revoke the key."

The IGM key is something that an individual player can generate, and revoke (or more specifically, generate a new key which instantly revokes the previous key) from their Account & Preferences page in the "API Keys" submenu.

ISSUING & REVOKING YOUR INGAME MAIL API KEY
  • Go to your Account & Preferences page and click on the API submenu.

    Direct link to that page here:  http://elgea.illyriad.co.uk/#/Player/Account?page=api

  • You will have a list of keys here - or, on your first visit, the option to issue a different kinds of API Keys for the first time.

  • To create an API Key for IGMs, press the "Generate" button next to the words "Ingame Mail".  Your Ingame Mail API Key will appear above.

  • If you already have a key, pressing "Generate" will instantly disable your current key for this API Type, and generate a new one for you; thereby preventing continued access to your API data by anyone who knows your old key.

  • You can then choose to share the new key with anyone you trust to access your mailbox.

Account sitters can generate and/or revoke API keys.

USING THE API KEY TO GET AN XML LIST OF AVAILABLE INGAME MAILS AND TO RETRIEVE INDIVIDUAL IGMs - A PROGRAMMERS' GUIDE

If you're not a programmer, then the following is probably not relevant, and you can skip over the next couple of sections!

The API Key is in the format:

<ServerName>-<KeyType>-<Key>

This helps you identify which server to query (we currently only have elgea) and what page to query with the key.

A sample full Ingame Mail API key might look like this (please note that this key is not valid and will return no data):


elgea-IMAIL-AQAAAF5M6Injvq4btMtWnFB-DvbfckWGKsgKM3ZEa4Ry-jwA4Ks3771QGuDUGQmWHhF9rmiiWjuZReUk

This identifies this key as being good for pulling data from ServerName "elgea" (which includes Broken Lands) for Ingame Mail "IMAIL", and the remainder of the key is an encrypted piece of data that identifies the player to us (twinned with the rights he has given to this key).

Unlike with notifications, this is a two step process.
  • STEP 1: RETRIEVING THE LIST OF AVAILABLE SENT AND RECEIVED MAILS
  • STEP 2: RETRIEVING AN INDIVIDUAL MAIL
STEP 1: RETRIEVING THE LIST OF AVAILABLE SENT AND RECEIVED MAILS
To query a key for the first time, call the following page (please note that this page will not work, as the key is invalid) with the key attached after the last forward slash:

http://elgea.illyriad.co.uk/external/mailapi/


and so, using the example above, your query would be (please note that this link will not work as the key is invalid):

http://elgea.illyriad.co.uk/external/mailapi/elgea-IMAIL-AQAAAF5M6Injvq4btMtWnFB-DvbfckWGKsgKM3ZEa4Ry-jwA4Ks3771QGuDUGQmWHhF9rmiiWjuZReUk


WHAT DOES THE PAGE RETURN?

Sample:

<mailapi>
<server>
<name>elgea</name>
<servercountrycode>gb</servercountrycode>
<serverlanguagecode>en</serverlanguagecode>
<serverlivedate>2010-02-21T21:53:01.190</serverlivedate>
<datagenerationdatetime>2015-02-24T17:22:30.100</datagenerationdatetime>
</server>
<player id="1"/>
<playerapikey id="elgea-IMAIL-AQAAAF5M6Injvq4btMtWnFB-DvbfckWGKsgKM3XEa4Ry-jwA4Ks3771QGuDUGQmWHhF9rmiiWjuZReUk"/>
<mails>
<mail>
<msg id="432"/>
<msgcategory id="1">Player</msgcategory>
<msgdirection>Sent</msgdirection>
<sentbyplayer id="1">GM Stormcrow</sentbyplayer>
<receivedbyplayer id="2">GM Thundercat</receivedbyplayer>
<noreplyYN id="0"/>
<readYN id="1"/>
<alliancemsgYN id="0"/>
<maildatetime>2010-02-25T14:49:18.287</maildatetime>
<msgsubject>Alliance</msgsubject>
</mail>
<mail>
<msg id="530"/>
<msgcategory id="1">Player</msgcategory>
<msgdirection>Sent</msgdirection>
<sentbyplayer id="1">GM Stormcrow</sentbyplayer>
<receivedbyplayer id="2">GM ThunderCat</receivedbyplayer>
<noreplyYN id="0"/>
<readYN id="1"/>
<alliancemsgYN id="0"/>
<maildatetime>2010-02-25T19:21:03.167</maildatetime>
<msgsubject>Re: Mail test...</msgsubject>
</mail>
</mails>
</mailapi>

(You may need to scroll the page to the right, from the bottom of the post, 
to see the full 
text)

Breaking it down, you have:
  1. The standard Server Identification snippet, followed by

  2. The <player id> who this Key belongs to (so you can match this to the existing Player Data feed) , and the exact key you just used

  3. A list of IGMS that this player currently has in their mailbox, comprising:
  • the <msg id> identifier (this is a bigint linear, incrementing number for all players)

  • the <msgcategory id> which identifies which inbox category it is in along with a textual description (eg "Player", "Military", "Diplomacy"), an int and a varchar(255) respectively.  

  • the <msgdirection> which will either be "Sent" or "Received"

  • The <sentbyplayer id> an int which identifies is who the mail is from

  • The <receivedbyplayer id> an int which identifies who the mail went to

  • <noreplyYN> a bit field either 0 or 1 which indicates whether the recipient can reply to the mail or not.  System mails, for example, have this sent to 1, meaning you cannot reply to the mail.

  • <readYN> a bit field either 0 or 1 which indicates whether the recipient has opened the mail or not

  • <alliancemessageYN> a bit field either 0 or 1 which indicates whether the mail was sent Alliance-wide

  • the <maildatetime> which is the sent timestamp on the mail itself, in the format yyyy-mm-ddThh:mm:ss.SSS 

  • the <msgsubject> which is a varchar(255) and is the subject line of the mail
The list of available emails is sorted by <msg id> ascending, so the most recent emails will be at the bottom of the list.

HOW TO MAKE SUBSEQUENT QUERIES OF THE MAILBOX
You don't need to query the complete player's mailbox every time!  Obviously we don't want you to be querying a complete player history every time you pull the Ingame Mail API, and you probably don't want to be parsing it only to discard, either.

So there is an additional parameter we'd like you to pass when you subsequently query the Ingame Mail API - this integer parameter is called <LastMsgID>, and should be added after the Key, separated by a "?".

<LastMsgID> is a bigint based on a linear numbering of Ingame mails sent, so it will be an historic record.

For each player, you only need to query mails from the last ingame mail you received for that player, therefore, this should be set to the most recent <msg id> for the <player id> whose key you are using.

So if you've retrieved a specific players' mailbox, and now want to see all new mails for that player's API Key since their last mail (in the example above <msg id> 530) then you query: 
http://elgea.illyriad.co.uk/external/mailapi/elgea-IMAIL-AQAAAF5M6Injvq4btMtWnFB-DvbfckWGKsgKM3ZEa4Ry-jwA4Ks3771QGuDUGQmWHhF9rmiiWjuZReUk?LastMsgID=530


... which will only return those new mails related to the player since (and including) the last mail with the supplied <LastMsgID>.  So you should have one duplicate mail with each query, comprising the ID you had last (the <LastMsgID> parameter).

HOW OFTEN CAN I QUERY A PLAYER'S API KEY?

For the purposes of development, we haven't yet set a limit.

However, we will probably impose a limit for a particular key query (from the same querying source) at some point in the future, simply to preserve server resources and bandwidth.  It all rather depends on how you player-programmers choose to use the API key system!

WHAT DATA IS AVAILABLE
It's everything in the current player's mailbox.  This list is archived quite regularly, as messages pile up reasonably quickly, and players do regularly delete mails; so we expect this list to change regularly.  It's best to view it as a snapshot of whatever you would currently see if you logged into that player's account and looked at the inbox and sent items.  We are not providing access to the archive at present, however, if you supply a <LastMsgID> and do not receive the (duplicate) data for that specific MsgID, then you know it's been archived - or deleted by the player.  

STEP 2: RETRIEVING AN INDIVIDUAL MAIL
Once you have your list of emails, you retrieve an individual email from a different URL, still using the API Key, and also supplying the specific Message ID for that mail.

The URL is:
http://elgea.illyriad.co.uk/external/messageapi/

So to retrieve a specific message from the example above (let's say <msg id> 530, the URL would be:

http://elgea.illyriad.co.uk/external/messageapi/elgea-IMAIL-AQAAAF5M6Injvq4btMtWnFB-DvbfckWGKsgKM3ZEa4Ry-jwA4Ks3771QGuDUGQmWHhF9rmiiWjuZReUk?MsgID=530

(please note that this is a sample URL and will not work - I'm not giving you access to my mailbox XD)

This would return:
<mailapi>
<server>
<name>elgea</name>
<servercountrycode>gb</servercountrycode>
<serverlanguagecode>en</serverlanguagecode>
<serverlivedate>2010-02-21T21:53:01.190</serverlivedate>
<datagenerationdatetime>2015-02-24T17:48:53.063</datagenerationdatetime>
</server>
<player id="2"/>
<playerapikey id="elgea-IMAIL-AQAAAF5M6Injvq4btMtWnFB-DvbfckWGKsgKM3ZEa4Ry-jwA4Ks3771QGuDUGQmWHhF9rmiiWjuZReUk"/>
<mails>
<mail>
<msg id="530"/>
<msgcategory id="1">Player</msgcategory>
<msgdirection>Received</msgdirection>
<sentbyplayer id="1">GM Stormcrow</sentbyplayer>
<receivedbyplayer id="2">GM ThunderCat</receivedbyplayer>
<noreplyYN id="0"/>
<readYN id="1"/>
<alliancemsgYN id="0"/>
<maildatetime>2010-02-25T19:21:03.167</maildatetime>
<msgsubject>Re: Mail test...</msgsubject>
<msgbody>
Brilliant - seems to be working fine.
</msgbody>
</mail>
</mails>
</mailapi>

All the fields in this are the same as in the previous mailbox example, except an additional last field:
  • <msgbody> is a varchar(max) field that contains the exact body text of the mail, with formatting as supplied ingame.
Please do let us know any issues you might experience with the mail API.

Enjoy!

SC


Edited by GM Stormcrow - 24 Feb 2015 at 18:13
Back to Top
kodabear View Drop Down
Postmaster General
Postmaster General
Avatar
Player Council - Astronomer

Joined: 18 Jun 2013
Location: Lucerna
Status: Offline
Points: 1515
Post Options Post Options   Thanks (0) Thanks(0)   Quote kodabear Quote  Post ReplyReply Direct Link To This Post Posted: 24 Feb 2015 at 20:16
Koda sir, contact us via petitions.

Unless you want everyone in the world reading your entire email, best not to share your key publically!

SC


Edited by GM Stormcrow - 24 Feb 2015 at 20:39
Back to Top
GM Stormcrow View Drop Down
Moderator Group
Moderator Group
Avatar
GM

Joined: 23 Feb 2010
Location: Illyria
Status: Offline
Points: 3926
Post Options Post Options   Thanks (0) Thanks(0)   Quote GM Stormcrow Quote  Post ReplyReply Direct Link To This Post Posted: 24 Feb 2015 at 20:40
Koda - I strongly recommend you generate a new key immediately.

Back to Top
Aurordan View Drop Down
Postmaster
Postmaster
Avatar
Player Council - Ambassador

Joined: 21 Sep 2011
Location: United States
Status: Offline
Points: 982
Post Options Post Options   Thanks (0) Thanks(0)   Quote Aurordan Quote  Post ReplyReply Direct Link To This Post Posted: 24 Feb 2015 at 20:57
Lol.  Koda is just a very open person. 
Back to Top
abstractdream View Drop Down
Postmaster General
Postmaster General
Avatar

Joined: 02 Oct 2011
Location: TEXAS Republic
Status: Offline
Points: 1865
Post Options Post Options   Thanks (0) Thanks(0)   Quote abstractdream Quote  Post ReplyReply Direct Link To This Post Posted: 25 Feb 2015 at 23:38
Does anyone have a link wherein we can download our IGMs to store them off sight? I'm really hoping that can be done soon. Thanks in advance.
Bonfyr Verboo
Back to Top
kodabear View Drop Down
Postmaster General
Postmaster General
Avatar
Player Council - Astronomer

Joined: 18 Jun 2013
Location: Lucerna
Status: Offline
Points: 1515
Post Options Post Options   Thanks (0) Thanks(0)   Quote kodabear Quote  Post ReplyReply Direct Link To This Post Posted: 25 Feb 2015 at 23:42
if you are on windows hold down that alt key and than click the link to the IGM XML thing and that will download the file and if you have Excel you can upload it there


Back to Top
abstractdream View Drop Down
Postmaster General
Postmaster General
Avatar

Joined: 02 Oct 2011
Location: TEXAS Republic
Status: Offline
Points: 1865
Post Options Post Options   Thanks (0) Thanks(0)   Quote abstractdream Quote  Post ReplyReply Direct Link To This Post Posted: 26 Feb 2015 at 00:03
And if I'm not on Windows?
Bonfyr Verboo
Back to Top
kodabear View Drop Down
Postmaster General
Postmaster General
Avatar
Player Council - Astronomer

Joined: 18 Jun 2013
Location: Lucerna
Status: Offline
Points: 1515
Post Options Post Options   Thanks (0) Thanks(0)   Quote kodabear Quote  Post ReplyReply Direct Link To This Post Posted: 26 Feb 2015 at 00:09
not sure but you maybe able to right link it and hit save and than upload it on Excel 
Back to Top
abstractdream View Drop Down
Postmaster General
Postmaster General
Avatar

Joined: 02 Oct 2011
Location: TEXAS Republic
Status: Offline
Points: 1865
Post Options Post Options   Thanks (0) Thanks(0)   Quote abstractdream Quote  Post ReplyReply Direct Link To This Post Posted: 26 Feb 2015 at 00:36
I'm on a mobile device. No Excel. What I need is a Google doc (or similar) that has the ability to do this.
Bonfyr Verboo
Back to Top
 Post Reply Post Reply
  Share Topic   

Forum Jump Forum Permissions View Drop Down

Forum Software by Web Wiz Forums® version 12.03
Copyright ©2001-2019 Web Wiz Ltd.