Protocols/MSNP/Notification/Messages

MSNP Protocol

Introduction • Terms • Clients

Reference

Error List • Commands • Relying Party Suite • Spotlife

Services

XMPP • HTTP Gateway • Tabs • Activities

Documentation

Development Tools • MSNP Grid

Polygamy • URLs used by MSN

Documents

Protocol Versions

Version 21

Version 18

Version 16

Version 15

Version 14

Version 13

Version 12

Version 11

Version 9

Version 8

Version 2

MSNC

Introduction • P2P • Object Descriptor • Display Pictures • File Transfer

Scenarios

Microsoft Messenger for Mac

MSNP on WebTV (MSNTV)

Overview

Messages (MSG) 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 in 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 17 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 1 January 1970
• EmailEnabled - Whether or not the user's account has email notification (currently just activated Hotmail and MSN.com accounts) - 1 or 0
• MemberIdHigh - High 32 bits of the Protocols/MSNP/Passport Unique ID
• MemberIdLow - Low 32 bits of the Protocols/MSNP/Passport Unique ID
• lang_preference - Preferred language number
• preferredEmail - User's primary email address
• country - Two-character 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 - Birthday Preference, Numbered 0 to 5 (see below)
• 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.

BDayPre can be numbered 0 to 5. These numbers indicate the following information:

0 - No Information
1 - User is 18+, no specified Day or Month for Birthday.
2 - User is 18+, filled out full Day, Month and Year for Birthday.
3 - User is under 18
4 - User is under 13
5 - User is between the ages of 13 and 18 (or is 13 exactly)

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 a router, network address translator (NAT), or proxy server. In Protocols/MSNP/MSNP8, this information is only used to decide the value of the 'Connectivity' field during file transfer.

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