April 23-27, 2002 - Version 1 - Draft 2

MSN Instant Messenger Protocol

Overview Basics Connecting Session Messaging File Transfer Other FAQ Research


Dispatch Server

The first step of connecting is to connect to the dispatch server. Open a TCP socket and connect to messenger.hotmail.com port 1863. When the connection is established, send the VER command, with MSNP7 MSNP6 MSNP5 MSNP4 CVR0 (the latest protocol version) as the parameter. Alternatively, use MSNP2 to identify as using the original protocol (avoids challenges).

When a response from the server is received, if the first term of the parameter (not the transaction ID) is not a 0, then the protocol version has been approved. Next, send INF with no parameter to request the authentication protocol from the server.

Hopefully, the server will respond with a INF command with a parameter of MD5. If the server sends some other parameter, something is wrong. Reply to this with the USR command with MD5 I user@host as the parameter, where user@host is the Passport of the user logging in.

The server should respond with XFR with the parameter NS W.X.Y.Z:1863 0 A.B.C.D:1863, where W.X.Y.Z:1863 is the IP address and port (usually 1863) of the specified notification server and A.B.C.D:1863 is the IP address and port of the current server. Close the current connection to the dispatch server and open a new connection to the specified notifcation server.

Below is an example of a conversation between a client and a dispatch server.

<o> Connect: messenger.hotmail.com 1863



>>> INF 1

<<< INF 1 MD5

>>> USR 2 MD5 I example@passport.com

<<< XFR 2 NS 0

<o> Client Disconnects

Notification Server

Connecting to the notification server works exactly the same way as connecting to the dispatch server for the first three steps (everything before the server responds with XFR). When the server receives the user's Passport from USR, it will either reply with an XFR (if the server is overloaded) or another USR with MD5 S #.#, where #.# is an MD5 hash.

In order to successfully login, a client must support MD5. Respond to this command with another USR with the parameter MD5 S *, where * is the lowercase hexadecimal digest of the MD5 hash received from the server concatenated with the user's login password. Using MD5 ensures that the password is never sent as plaintext.

The notification server should respond to this with USR with a parameter of OK user@host NAME 1, where user@host is the user's Passport, and NAME is the user's screen name (URL quoted of course). The 1 represents the fact that the user's Passport account has been verified (via replying to an email). Otherwise, it will be a 0. Note that hotmail.com accounts are automatically verified upon signing up. If the login fails, the server will reply with error code 911.

After the login is successful, send CHG with a three letter status code as the parameter. This will set the initial status, and is the final step of logging in. The server should echo your status message back to verify that your status has been set. The official MSN client always logs in with the status code NLN, but the servers allow for any of the 9 statuses. When logging in as FLN, syncing contact lists is the only activity allowed. When logging in as HDN, a client can do anything except for connecting to the switchboard (although it used to be allowed).

Below is an example of a conversation between a client and a notification server.

<o> Connect: 1863



>>> INF 4

<<< INF 4 MD5

>>> USR 5 MD5 I example@passport.com

<<< USR 5 MD5 S 1013928519.693957190

>>> USR 6 MD5 S 23e54a439a6a17d15025f4c6cbd0f6b5

<<< USR 6 OK example@passport.com My%20Screen%20Name 1

>>> CHG 7 NLN

<<< CHG 7 NLN

<o> Continue Session . . .

Initial Messages

After successfully logging in, the MSN servers may send two messages (MSG) over the notification server session. One of them contains the user's Passport profile information. I'm not really sure what the point of it is. The server will also send a new email notification if the user is using a Hotmail account and there are unread emails. These messages may be sent before or after the server verifies your initial status, but I have found that it sends the profile before it verifies your initial status, and it sends the email notification (if there is one) afterwards.

The profile message has a MIME content type of text/x-msmsgsprofile. The profile information is displayed as part of the MIME header, and the message has no body. Below is an example of what a profile message might look like.

If your client is behind a NAT firewall (where the actual IP address of the client is hidden), the server will send back two more fields: ClientIP and ClientPort, which are the IP and port the server thinks you're on.

MSG Hotmail Hotmail 363
MIME-Version: 1.0
Content-Type: text/x-msmsgsprofile; charset=UTF-8
LoginTime: 1016941010
EmailEnabled: 1
MemberIdHigh: 41922
MemberIdLow: -619232012
lang_preference: 1033
preferredEmail: example@passport.com
country: US
PostalCode: 12345
Gender: M
Kid: 0
sid: 507
kv: 2
MSPAuth: 2AAAAAAAADMoV8ORoz64BVwmjtksIg!kmR!Rj5tBBqEaW9hc4YnPHSOQ$$

The new email notification message has a MIME content type of text/x-msmsgsinitialemailnotification;. The MIME header only has the two basic lines, and the body of the message displays the number of unread messages, and where to download them (I'm not sure how to use the URLs though). Below is an example of what a new email message might look like.

MSG Hotmail Hotmail 223
MIME-Version: 1.0
Content-Type: text/x-msmsgsinitialemailnotification; charset=UTF-8

Inbox-Unread: 21
Folders-Unread: 33
Inbox-URL: /cgi-bin/HoTMaiL
Folders-URL: /cgi-bin/folders
Post-URL: http://www.hotmail.com

Other Server Messages

Besides the two initial messages that are received when logging in, the server can also send other types of messages during the session. I have found two of these so far: text/x-msmsgsemailnotification and text/x-msmsgsactivemailnotification. The first one notifies you when a new email has been received. The second notifies you when an email has been deleted (or maybe something else also). Below is an example of a new email being received.

MSG Hotmail Hotmail 340
MIME-Version: 1.0
Content-Type: text/x-msmsgsemailnotification; charset=UTF-8

From: Mike Mintz
Message-URL: /cgi-bin/getmsg?msg=MSG1029401739.3&start=1610592&len=402&curmbox=ACTIVE
Post-URL: https://lc1.law13.hotmail.passport.com/ppsecure/domessengerlogin/EN
Subject: Hi
Dest-Folder: ACTIVE
From-Addr: example@passport.com
id: 2

Below is an example of when I erase a message in my inbox.

MSG Hotmail Hotmail 145
MIME-Version: 1.0
Content-Type: text/x-msmsgsactivemailnotification; charset=UTF-8

Src-Folder: ACTIVE
Dest-Folder: trAsH
Message-Delta: 1

Initial Statuses

In addition to profile and new email messages, the server should send you the initial statuses of users on your contact list after successfully logging in. These commands use the command name ILN, and use the transaction ID of your initial status command (CHG). This command has 3 parameters: three letter status code, passport id, and URL quoted screen name. Below are some examples.

<<< ILN 7 AWY example@passport.com Mike
<<< ILN 7 NLN name_123@hotmail.com Name_123
<<< ILN 7 BSY myname@msn.com My%20Name

Contact List

After logging in, a client will usually sync its contact list. This will be explained in the session section.

Copyright ©2002-2003 to Mike Mintz.