MSN Messenger Protocol

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 friendly 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.

In MSNP2, the profile only consists of one field (other than the MIME-Version and Content-Type). This LoginTime field represents the UNIX time (the number of seconds since midnight, January 1, 1970, UTC) at which the client just logged on. The message should look something like this:

MSG Hotmail Hotmail 95\r\n
MIME-Version: 1.0\r\n
Content-Type: text/x-msmsgsprofile; charset=UTF-8\r\n
LoginTime: 1050223025\r\n
\r\n


There are a lot more fields in the later protocol versions. The format is exactly the same in every version between MSNP3 and MSNP7. Below is an example profile message:

MSG Hotmail Hotmail 440\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: user@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
\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 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)

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 user 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.

MSNP8 adds two additional fields: ClientIP and ClientPort to the bottom. More information on these fields can be found in the MSNP8 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 status. This message will only be sent if you have unread emails in your inbox or other folders (with the exception of trash).

Initial email notification messages are the same for all versions of the protocol up to MSNP7, with one minor exception. The Content-Type field in MSNP2 is set to application/x-msmsgsemailnotification instead of the newer text/x-msmsgsinitialemailnotification. 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 user 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. As with the initial email notification message, the MSNP2 version is somewhat different from the version used in the rest of the protocols up to MSNP7. Below is an example of the MSNP2 version:

MSG Hotmail Hotmail 288\r\n
MIME-Version: 1.0\r\n
Content-Type: application/x-msmsgsemailnotification\r\n
\r\n
From: Mike Mintz\r\n
Message-URL: /cgi-bin/getmsg?msg=MSG1050452041.12​&start=3412&len=2401\r\n
Post-URL: http://www.hotmail.com\r\n
Subject: =?"us-ascii"?Q?mysubject?=\r\n
Dest-Folder: ACTIVE\r\n
From-Addr: example@passport.com\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

Most of the time, messages arrive in the inbox. ACTIVE is the name for the inbox. However, filters may cause messages to arrive in other folders.

Here is an example of a new email notification message in protocol versions from MSNP3 to MSNP7:

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 user is notified on MSN Messenger with a message with the Content-Type of text/x-msmsgsactivemailnotification. Fortunately, the format of this message is almost exactly the same for every protocol up to MSNP7. 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.

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 argument 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 argument you receive in reply to a URL "INBOX", "FOLDERS", or "COMPOSE" command.
• sl derives from LoginTime (in your profile) minus the current Unix time. It's generally agreed that "sl" means "session-length". Personally, I suspect it means "salt", but there's no real evidence either way.
• 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=user%40hotmail%2ecom to skip straight to a window composing a message to "user@hotmail.com" with subject "Hi Dave".
• auth derives from the MSPAuth value from your profile.
• creds is the MD5 hexidecimal digest of the concatenated strings MSPAuth + sl + password.

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.