Since March 10, 2003 - Version 2.1
hypothetic.org

MSN Messenger Protocol

Home Page

Forum

About
Contact us

Resources

Research

Documentation
 General
 Notification
 Switchboard
 Client
 Reference

Validate XHTML
Validate CSS
Notification - Messages
Printable Version

Overview

Messages (MSG), as explained in the Payload Commands page, can be sent from the NS to the client. The DS never sends messages. A client can never send messages to the NS or DS, and if it tries, the server will immediately close the connection.

Messages are sent to give the client information such as system messages, email notifications, and profile information. These messages are independent from the instant messages sent over the switchboard that use the same command.

All messages from the NS are sent from the account name Hotmail and the display name Hotmail. However, there is no rule governing this, so a client must expect a message to come from any source.

Initial Messages

After successfully logging in, the NS will always send a profile message to the client. In addition, if the client is logged on with a Hotmail account and the user has unread messages in his or her inbox, the NS will send an initial email notification message.

Profile Messages

In all known cases, immediately after sending the final USR, the NS will send a profile message. This is a message with a Content-Type of text/x-msmsgsprofile. This message has a large header with lots of fields, and no body.

Microsoft have a history of changing the fields sent in this message from time to time. The following example was checked on 17th November 2003. You shouldn't assume that all of these fields will be sent, or that they'll be sent in this order.

MSG Hotmail Hotmail 425\r\n
MIME-Version: 1.0\r\n
Content-Type: text/x-msmsgsprofile; charset=UTF-8\r\n
LoginTime: 1050223062\r\n
EmailEnabled: 0\r\n
MemberIdHigh: 85040\r\n
MemberIdLow: -517030579\r\n
lang_preference: 1033\r\n
preferredEmail: example@hotmail.com\r\n
country: US\r\n
PostalCode: 90201\r\n
Gender: m\r\n
Kid: 0\r\n
Age: \r\n
BDayPre: 5\r\n
Birthday: 0\r\n
Wallet: 0\r\n
Flags: 1027\r\n
sid: 507\r\n
kv: 4\r\n
MSPAuth: 4sCuECZ4UsAaBIy0AIsk!c9bWcuATTmuQ$$\r\n
ClientIP: 1.2.3.4\r\n
ClientPort: 516.\r\n
\r\n

Many of the fields are necessary for automatically logging into Hotmail, some are just informational, and some we don't yet understand.

  • LoginTime - Unix time you logged in - that is, in seconds since midnight UTC on January 1st, 1970.
  • EmailEnabled - Whether or not the user's account has email notification (currently just activated Hotmail and MSN.com accounts) - 1 or 0
  • MemberIdHigh - Unknown
  • MemberIdLow - Unknown
  • lang_preference - Preferred language number
  • preferredEmail - User's primary email address
  • country - Two-digit country code
  • PostalCode - User's post-code (or zip code, in the U.S.)
  • Gender - User's gender (m, f, or U if unspecified)
  • Kid - Whether your account is a Kids Passport (0 or 1)
  • Age - Your given age in years
  • BDayPre - Unknown
  • Birthday - Numerical birthday
  • Wallet - Whether you have an MS Wallet? (0 or 1)
  • Flags - Unknown
  • sid - A number needed for Hotmail login
  • kv - Another number needed for Hotmail login
  • MSPAuth - Incredibly long string used for Hotmail login (90 bytes, but it could change)
  • ClientIP - The IP address the server thinks you're connecting from
  • ClientPort - The port you're connecting from... sort of. See below for details

The MSPAuth value has been cut short to prevent horizontal scrolling. Most of this information seems pretty useless, with the exception of the variables needed for automatic Hotmail login.

Note that the same variables are used on MSN.com accounts. But for some reason, in MSN.com accounts, the client will receive two profile messages: one with EmailEnabled set to 0, and the other with it set to 1 but missing the LoginTime field. Other than that, the messages are completely identical.

ClientIP and ClientPort

The "ClientIP" and "ClientPort" fields tell the client about the IP address and source port the server believes the client is connecting from. The source port for a connection is the port on the client computer, whereas the destination port (usually 1863 in MSN Messenger sessions) is the port the server listens on. Unfortunately, a bug in the MSN Messenger server mangles the "ClientPort" value, and you need to do some work to get the actual port number.

The technical term is that the value has been "byte-swapped", and an explanation of what exactly has happened is beyond the scope of this page. There are several ways to get the correct number back, but the recommended method (using bitwise AND) is to calculate ((ClientPort AND 255) * 256) + ((ClientPort AND 65280) / 256) - there are neater ways to write that function, but they would take a much deeper understanding of binary arithmetic to explain. If your program will only run on PCs, you could use a function called ntohc instead, but this function doesn't exist in all programming languages, and doesn't work on all hardware architectures (for example, it won't work on Apple computers), so you shouldn't use it.

The client port and IP address can be used to guess whether the connection to the server is going through some kind of network address translation ("NAT") or proxy server. In MSNP8, this information is only used to decide the value of the "Connectivity" field during file transfer, but more advanced handling of this information - this is covered on the MSNP9 page.

Initial Email Notifications

If your account supports email notifications (currently, this means an activated Hotmail or MSN.com account), you may receive an initial email notification message after setting your initial presence. This message will only be sent if you have unread emails in your inbox or other folders (with the exception of trash). Unlike the profile message, the information is stored in fields in the body of the message. Note that the body ends with a blank line. Below is an example:

MSG Hotmail Hotmail 221\r\n
MIME-Version: 1.0\r\n
Content-Type: text/x-msmsgsinitialemailnotification; charset=UTF-8\r\n
\r\n
Inbox-Unread: 1\r\n
Folders-Unread: 0\r\n
Inbox-URL: /cgi-bin/HoTMaiL\r\n
Folders-URL: /cgi-bin/folders\r\n
Post-URL: http://www.hotmail.com\r\n
\r\n

  • Inbox-Unread - Number of unread messages in your inbox (can be zero if there are unread messages in other folders)
  • Folders-Unread - Number of unread messages in folders apart from inbox and trash (can be zero if there are unread messages in the inbox)
  • Inbox-URL - Used for automatic Hotmail login
  • Folders-URL - Used for automatic Hotmail login
  • Post-URL - Used for automatic Hotmail login

Realtime Email Notification

During the NS session, a client might receive a number of additional email notifications. These notifications come when new emails are received, and when outside forces (such as the user moving and erasing messages in his or her account) cause the number of unread messages in the inbox or other folders to change.

Folder names are sent with all of these commands. Folder names are just the names you assign folders. These names are not URL-encoded. However, certain folders have special names:

  • ACTIVE - Inbox
  • sAVeD - Sent Mail
  • drAfT - Drafts
  • trAsH - Trash
  • HM_BuLkMail_ - Junk Mail

New Email Notification

When a new email arrives, a notification message will arrive. Most of the time, messages arrive in the inbox, but filters may cause messages to arrive in other folders. Here is an example of a new email notification message:

MSG Hotmail Hotmail 355\r\n
MIME-Version: 1.0\r\n
Content-Type: text/x-msmsgsemailnotification; charset=UTF-8\r\n
\r\n
From: Mike Mintz\r\n
Message-URL: /cgi-bin/getmsg?msg=MSG1050451140.21​&start=2310&len=2059&curmbox=ACTIVE\r\n
Post-URL: https://loginnet.passport.com/ppsecure/​md5auth.srf?lc=1038\r\n
Subject: =?"us-ascii"?Q?newsubject?=\r\n
Dest-Folder: ACTIVE\r\n
From-Addr: example@passport.com\r\n
id: 2\r\n

  • From - The name of the person who sent the email
  • Message-URL - Used for automatic Hotmail login
  • Post-URL - Used for automatic Hotmail login
  • Subject - Subject parameter of the email
  • Dest-Folder - Name of the folder the email arrived in
  • From-Addr - Email address of the person who sent the email
  • id - Used for automatic Hotmail login

Other Mailbox Activity

When unread messages are read, moved around, or removed in a user's Hotmail (or MSN.com) account, the client is notified on MSN Messenger with a message with the Content-Type of text/x-msmsgsactivemailnotification. Below is an example of removing two messages from the inbox (actually just moving them to the trash folder):

MSG Hotmail Hotmail 145\r\n
MIME-Version: 1.0\r\n
Content-Type: text/x-msmsgsactivemailnotification; charset=UTF-8\r\n
\r\n
Src-Folder: ACTIVE\r\n
Dest-Folder: trAsH\r\n
Message-Delta: 2\r\n

  • Src-Folder - The name of the folder that the message was originally in
  • Dest-Folder - Used name of the folder that the message was moved to
  • Message-Delta - The number of messages affected by this action

These notification messages are only sent about unread messages. If a message is read, the Src-Folder and Dest-Folder values will be the same, and your client will know that there is one or more fewer unread messages in that particular folder.

For some reason, at least in my experimentation, messages that are automatically sent to the junk mail folder are not reported. However, when unread messages become read in the junk mail folder, that action is reported.

When the trash or the junk mail folder is emptied by the user, the Src-Folder value will be either trAsH or HM_BuLkMail_ and the Dest-Folder value will always be .!!trAsH. As always, the Message-Delta shows only the number of unread messages affected. Below is an example of emptying the trash and 4 unread messages are removed:

MSG Hotmail Hotmail 147\r\n
MIME-Version: 1.0\r\n
Content-Type: text/x-msmsgsactivemailnotification; charset=UTF-8\r\n
\r\n
Src-Folder: trAsH\r\n
Dest-Folder: .!!trAsH\r\n
Message-Delta: 4\r\n

Automatic Hotmail and MSN.com Login

Hotmail (http://www.hotmail.com) is, of course, Microsoft's web-mail system. To access Hotmail without re-entering your password, you must generate a temporary file on your local computer and open the page in a web browser. The page redirects the browser to Hotmail. If your account is at MSN.com, this technique should work in the same way.

This was discussed in the forum thread Go to Hotmail Inbox. Credit should go to the hard work of the contributors to that forum, and to the authors of Gaim, who worked out how to generate the "cred" field.

An example page is given below. The page you create should contain at least these elements. Please note that the value of the auth field has been cut to prevent horizontal scrolling on this page so is therefore shorter than a true one.

<html>
 <head>
  <noscript>
   <meta http-equiv=Refresh content="0; url=http://www.hotmail.com">
  </noscript>

 </head>

 <body onload="document.pform.submit(); ">
  <form name="pform" action="https://loginnet.passport.com/​ppsecure/md5auth.srf?lc=1033" method="POST">
   <input type="hidden" name="mode" value="ttl">
   <input type="hidden" name="login" value="chrisshucksmith">

   <input type="hidden" name="username" value="chrisshucksmith@hotmail.com">
   <input type="hidden" name="sid" value="507">

   <input type="hidden" name="kv" value="4">
   <input type="hidden" name="id" value="2">

   <input type="hidden" name="sl" value="9">
   <input type="hidden" name="rru" value="/cgi-bin/HoTMaiL">
   <input type="hidden" name="auth" value="4wn8Flsh2DXiHWLa​lsdfgdssdfgfgsgfG4mzp2Vu2du3I3*cLC8DUP$$">
   <input type="hidden" name="creds" value="c1252ecb80b52af6becba4533d12828f">

   <input type="hidden" name="svc" value="mail">
   <input type="hidden" name="js" value="yes">
  </form>
 </body>
</html>

Below is a list of how to deal with each highlighted variable.

  • The URL in the meta element derives from the Post-URL in the initial email notification.
  • The value of the action tag in the form element derives from the URL command with an parameter of "INBOX", "FOLDERS" or "COMPOSE" (specifially, from the second reply-parameter).
  • login - is your email address.
  • sid - and kv derive from the sid and kv values in your profile.
  • id - derives from either the new email notification or the third parameter you receive in reply to a URL "INBOX", "FOLDERS", or "COMPOSE" command.
  • sl - ("session-length") derives from the number of seconds since you received the initial profile message. You shouldn't use the value of the LoginTime field in your profile to calculate this, in case your local clock is inaccurate.
  • rru - can be any one of Inbox-URL, Folders-URL, Message-URL, or Compose-URL. These can be retrieved from an initial email notification, a new email notification, or the first reply-parameter of a URL "INBOX", "FOLDERS", or "COMPOSE" command. If you choose the Compose-URL, you can specify some variables in the e-mail you compose, including "mailto" (which must be set to 1), "subject" and "to". So you can specify something like /cgi-bin/compose?mailto=1&subject​=Hi%20Dave&to=example%40hotmail%2ecom to skip straight to a window composing a message to "example@hotmail.com" with subject "Hi Dave".
  • auth - derives from the MSPAuth value from your profile.
  • creds - is the MD5 hexadecimal digest of the concatenated strings MSPAuth + sl + password. MD5 is discussed on the pings/challenges page.

All other values are constant.

System Messages

System messages are messages from the NS with a Content-Type of application/x-msmsgssystemmessage. We have only seen one type of system message, which informs the client that the server will be going down for maintenance.

Format

The header of a system message is always just type MIME-Version: 1.0 and the Content-Type field. The header should always look like this:

MIME-Version: 1.0\r\n
Content-type: application/x-msmsgssystemmessage\r\n
\r\n

The body of a system message has a Type field and possibly some additional fields. The Type field specifies the type of system message. There is always a newline at the end.

We have only seen system messages with a Type of 1. This type of system message always means that "the server is going down for maintenance in Arg1 minutes". The Arg1 field is always the number of minutes that the server is going to go down in for Type 1 messages. Below is an example of the body of a system message that states that the server is going down in 5 minutes.

Type: 1\r\n
Arg1: 5\r\n

The full system message that says that the server is going down in 5 minutes will look like this:

MSG Hotmail Hotmail 88\r\n
MIME-Version: 1.0\r\n
Content-type: application/x-msmsgssystemmessage\r\n
\r\n
Type: 1\r\n
Arg1: 5\r\n

After receiving a Type 1 system message, you will probably receive an OUT SSD after the specified number of minutes as described in the DS/NS Authentication page.

Other System Message Types

It is quite possible that other system message types exist that we just haven't noticed when watching network traffic. In forum thread Server Messages, JD suggested that some answers might lie in the official client's string-table.

Search website:


Copyright©2002-2004 to Mike Mintz.