24FEB15: XML FEED FOR INGAME MAIL |
Post Reply |
Author | ||||||||
GM Stormcrow
Moderator Group GM Joined: 23 Feb 2010 Location: Illyria Status: Offline Points: 3926 |
Post Options
Thanks(0)
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
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):
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 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:
and so, using the example above, your query would be (please note that this link will not work as the key is invalid):
WHAT DOES THE PAGE RETURN? Sample:
(You may need to scroll the page to the right, from the bottom of the post, to see the full text)
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:
... 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:
So to retrieve a specific message from the example above (let's say <msg id> 530, the URL would be:
(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:
All the fields in this are the same as in the previous mailbox example, except an additional last field:
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 |
||||||||
kodabear
Postmaster General Player Council - Astronomer Joined: 18 Jun 2013 Location: Lucerna Status: Offline Points: 1515 |
Post Options
Thanks(0)
|
|||||||
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 |
||||||||
GM Stormcrow
Moderator Group GM Joined: 23 Feb 2010 Location: Illyria Status: Offline Points: 3926 |
Post Options
Thanks(0)
|
|||||||
Koda - I strongly recommend you generate a new key immediately.
|
||||||||
Aurordan
Postmaster Player Council - Ambassador Joined: 21 Sep 2011 Location: United States Status: Offline Points: 982 |
Post Options
Thanks(0)
|
|||||||
Lol. Koda is just a very open person.
|
||||||||
abstractdream
Postmaster General Joined: 02 Oct 2011 Location: TEXAS Republic Status: Offline Points: 1865 |
Post Options
Thanks(0)
|
|||||||
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.
|
||||||||
|
||||||||
kodabear
Postmaster General Player Council - Astronomer Joined: 18 Jun 2013 Location: Lucerna Status: Offline Points: 1515 |
Post Options
Thanks(0)
|
|||||||
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
|
||||||||
abstractdream
Postmaster General Joined: 02 Oct 2011 Location: TEXAS Republic Status: Offline Points: 1865 |
Post Options
Thanks(0)
|
|||||||
And if I'm not on Windows?
|
||||||||
|
||||||||
kodabear
Postmaster General Player Council - Astronomer Joined: 18 Jun 2013 Location: Lucerna Status: Offline Points: 1515 |
Post Options
Thanks(0)
|
|||||||
not sure but you maybe able to right link it and hit save and than upload it on Excel
|
||||||||
abstractdream
Postmaster General Joined: 02 Oct 2011 Location: TEXAS Republic Status: Offline Points: 1865 |
Post Options
Thanks(0)
|
|||||||
I'm on a mobile device. No Excel. What I need is a Google doc (or similar) that has the ability to do this.
|
||||||||
|
||||||||
Post Reply | |
Tweet
|
Forum Jump | Forum Permissions You cannot post new topics in this forum You cannot reply to topics in this forum You cannot delete your posts in this forum You cannot edit your posts in this forum You cannot create polls in this forum You cannot vote in polls in this forum |