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" rel="nofollow - 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:- The standard Server Identification snippet, followed by
- 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
- 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 MAILBOXYou 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 AVAILABLEIt'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
|