This page fully documents adding, removing, and renaming both users and groups. It also covers what happens when a user is added or removed from your RL. The commands explained are ADD, REM, REA, ADG, RMG, and REG.

The information on this page logically belongs with the rest of the Contact Lists page, but in order to keep that page from growing too large, it has been divided into these two pages. This page covers every contact list command that is not used in SYN.

Adding and Removing Users

Adding Users (ADD)

To add a user, the client must send the ADD command.

The first parameter is the list you want to add the user to.
The second parameter is the user's account name.
The third parameter is a nickname you assign to the user. The official client always uses the user's account name as the nickname, and that is why when you add a user, his or her name always shows as his or her account name until he or she logs on and you receive an updated friendly name. More information about nicknames is discussed in the Names page.
If you are adding a user to your FL, there may be a fourth parameter specifying the group ID that you are adding the user to. If you do not specify a group ID, zero is implied. You may add the same user to your FL later specifying another group to have the user in multiple groups. BPRs will not be sent in response to these additional ADDs.

There are a few things you cannot do.

You cannot add users to your RL, and if you attempt to, you will be immediately disconnected.
If you try to add a user to both your AL and your BL, you will receive error 219.
If you try to add more than 150 users (the maximum as of March 23, 2003) to your FL, you will receive error 210.
If you try to add an invalid email address, you will receive error 201.
If you try to add a valid email address that does not exist, you will receive error 205.
If you try to add a user to your FL in a nonexistent group, you will receive error error 224.
If you try to add a user to a list (or group within the FL) that they are already in, you will receive error 215.
Errors 201 and 205 take priority over 224.

In addition, as of March 29, 2003, if the nickname is longer than 387 bytes (a three-byte URL-encoded character counts as three bytes, not one), you will be immediately disconnected. This is the same maximum length for setting nicknames with the REA command described below. However, the official client will not properly display names with more than 129 characters (a three-byte URL-encoded characters counts as one character). Note that 129 multiplied by 3 is 387.

If your ADD was successful, the server will reply with another ADD with the same exact parameters, except it will add the new list version in between the list type and the account name.

If you are adding a user to your FL, you will receive the four BPRs after the ADD response. These BPRs will all be blank (except MOB which is N) even if the user has phone numbers set. Note that you do not receive BPRs if you have not sent the SYN command in the current session.

Also, if the user is online when you add them to your FL, and you are already on their AL, you will receive an ILN with the same TrID as your ADD showing their initial status. Otherwise, you will receive an NLN if and when they add you to their AL. Note that if they're offline, this might take some time.

Below are some example of using ADD.

>>> ADD 18 AL a@b a@b\r\n

<<< 201 18\r\n

>>> ADD 19 FL non_existent_account@passport.com non_existent_account@passport.com\r\n

<<< 205 19\r\n

>>> ADD 20 AL example@passport.com example@passport.com\r\n

<<< ADD 20 AL 1200 example@passport.com example@passport.com\r\n

>>> ADD 21 BL example@passport.com example@passport.com\r\n

<<< 219 21\r\n

>>> ADD 22 AL example@passport.com example@passport.com\r\n

<<< 215 22\r\n

>>> ADD 23 FL myname_123@hotmail.com myname_123@hotmail.com 1\r\n

<<< ADD 23 FL 1201 myname_123@hotmail.com myname_123@hotmail.com 1\r\n <<< BPR 1201 myname_123@hotmail.com PHH\r\n <<< BPR 1201 myname_123@hotmail.com PHW\r\n <<< BPR 1201 myname_123@hotmail.com PHM\r\n <<< BPR 1201 myname_123@hotmail.com MOB N\r\n

>>> ADD 24 FL user@msn.com user@msn.com 15\r\n (nonexistent Group)

<<< 224 24\r\n

>>> ADD 25 RL user@msn.com user@msn.com\r\n

<o> Server Closes Connection

Removing Users (REM)

To remove a user, the client must send the REM command. This works almost exactly the same way as the ADD command, except that there is no nickname parameter.

If you are removing a user from your FL and you want to remove the user from a specific group, you may specify the group ID in the same way you did with the ADD command.

If your REM was successful, the server will reply with another REM with the same exact parameters, except it will add the new list version in between the list type and the account name. Listed below are some situations which will cause problems:

If you remove a user that is not on your list, whether or not it is a valid account name, you will receive error 216.
If you attempt to remove a user from your RL, you will be immediately disconnected.
If you try to remove a user from a nonexistent group, you will receive error 224.
If you try to remove a user from an existent group that they do not belong to, you will receive error 225.
Error 216 takes priority over 225, and 224 takes priority over 216.

Below are some example of using REM.

>>> REM 26 AL a@b\r\n

<<< 216 26\r\n

>>> REM 27 FL non_existent_account@passport.com\r\n

<<< 216 27\r\n

>>> REM 28 FL valid_account@hotmail.com\r\n (User Not In List)

<<< 216 28\r\n

>>> REM 29 FL user123@msn.com 15\r\n (nonexistent Group)

<<< 224 29\r\n

>>> REM 30 FL user321@msn.com 3\r\n (User Not In Group)

<<< 225 30\r\n

>>> REM 31 FL myname_123@hotmail.com\r\n

<<< REM 31 FL 1202 myname_123@hotmail.com\r\n

>>> REM 32 FL user@msn.com 1\r\n

<<< REM 32 FL 1203 user@msn.com 1\r\n

>>> REM 33 AL user@msn.com\r\n

<<< REM 33 AL 1204 user@msn.com\r\n

>>> REM 34 RL user@msn.com\r\n

<o> Server Closes Connection

Moving Users Between Groups

To move a user from one group to another, just use the REM command to remove him or her from the original group, and use the ADD command to add him or her to the target group. Because users can be in more than one group at a time, it does not matter which order you do this in. Below is an example:

>>> REM 35 FL user@msn.com 1\r\n

>>> ADD 36 FL user@msn.com user@msn.com 2\r\n

<<< REM 35 FL 1205 user@msn.com 1\r\n

<<< ADD 36 FL 1206 user@msn.com user@msn.com 2\r\n

MSN also supports having a user in multiple groups. To do this, just send the ADD command multiple times, and include a group ID each time for the additional group you would like the user to be in.

Reverse List Changes

When a user adds/removes you from their forward list, they are added/removed from your reverse list. You will receive an ADD or REM from the server telling you that. It will have a TrID of zero. The first parameter will always be RL. The second parameter will be the new list version. The third parameter will be the user's account name. And if it is an ADD, there will be a fourth parameter with the user's friendly name. This parameter does not exist in REM's. Below are some examples:

<<< ADD 0 RL 3049 example@passport.com My%20Name\r\n

<<< REM 0 RL 3050 example@passport.com\r\n

The official client will respond by seeing if that user is in the AL or the BL (note that no commands are used to check since the client already has a cached version of the lists). If the user is in either one, the client will not notify the user of anything. Otherwise, it will consult the GTC value. If the value is "A", it should ask the user what to do. If the value is "N", it should automatically add the user to the AL.

<<< ADD 0 RL 3051 myname_123@hotmail.com My%20Name\r\n

>>> ADD 25 AL myname_123@hotmail.com My%20Name\r\n

<<< ADD 0 RL 3052 user@msn.com User\r\n

>>> ADD 26 BL user@msn.com User\r\n

Blocking Users

To block a user, first remove him or her from your AL if he or she is are already there. Then add him or her to your BL.

>>> REM 27 AL user@msn.com\r\n

<<< REM 27 AL 3053 user@msn.com\r\n

>>> ADD 28 BL user@msn.com user@msn.com\r\n

<<< ADD 28 BL 3054 user@msn.com user@msn.com\r\n

Renaming Users (REA)

Read this for how to set your friendly name as well.

To set the nickname of any user already in any of your lists, you must use the REA command. The REA command has two parameters: the account name of the user you want to modify, and the new URL-encoded nickname that you want to assign to that user. If successful, the server will respond with another REA with a new list version, the user's account name, and the user's new nickname.

If you use your own account name for the account name parameter, this command will officially change your friendly name and inform all other online users with a new NLN (unless you are appearing offline or blocking those users). If you attempt to change your friendly name too rapidly, you may receive error 800 in response to some REAs. Note that this does not apply to renaming other users.

As in the ADD command, if the nickname you assign is longer than 387 bytes (as of March 29, 2003), you will be immediately disconnected. However, the official client will not allow users to set names to more than 129 characters (a three-byte URL-encoded character counts as one character) and will not properly display names with more than 129 characters. If you try to rename a user that is not in any of your lists, you will receive error 216. This even applies if the account name is an invalid email address.

If MSN for some reason does not like the new nickname has words that MSN does not allow to be in nicknames, the server will send error 209. The server will also send this error if you attempt to change your own friendly name with this command and your Passport has not yet been verified. (When you sign up for a Passport, you receive an email where you must click on a link to verify your Passport.) Note that error 209 has priority over error 216 when giving invalid users invalid nicknames.

Some well-known restricted words in nicknames are "msn" and "microsoft". It is very easy to get around this restriction on nicknames. When you set a nickname, just URL-encode all or some of the letters in a restricted word, and MSN will not detect that the nickname is invalid. For example, instead of setting a nickname to "MSN%20SUCKS", set it to "%4DSN%20SUCKS", or your client could even encode every single character. Note that %4D is "M" and %20 is the space character.

Below are some examples of setting nicknames:

>>> REA 101 random_user@randomdomain.com nickname\r\n (User Not In List)

<<< 216 101\r\n

>>> REA 102 mypassport@passport.com msn%20help\r\n

<<< 209 102\r\n

>>> REA 103 mypassport@passport.com new%20name\r\n

<<< REA 103 3055 mypassport@passport.com new%20name\r\n

Groups

Groups are a recent addition to the MSN protocol and are new in MSNP7. Every user on your FL can belong to one or more groups. If no group is specified, the user automatically belongs to group zero. Each group has a name and a group ID, and groups are always referred to by their IDs. The group name is solely for end-user display purposes.

Adding Groups (ADG)

To add a group to your contact list, send the ADG command. The first parameter will the be URL-encoded choice for the name of the group, and the second parameter is a zero.

If the length of the group name is longer than 128 bytes (as of March 29, 2003), the server will immediately disconnect you.
If the length of the group name is greater than 61 bytes (as of March 29, 2003), you will receive error 229. Note that %20 counts as three bytes, not one (and the same idea applies for all similar entities).
If you try to add a 31st group (30 is the maximum as of March 29, 2003), you will receive error 223. Note that group zero counts as a one of the 30 groups.

If the ADG was successful, the server will respond with an ADG. The first parameter will be your new list version. The second parameter will be the group name (should be the same one you specified). The third parameter will be the group ID. The fourth parameter should be a zero.

Here are some examples of using the ADG command:

>>> ADG 37 this%20group's%20name%20is%20sixty%20two%20bytes%20in%20length 0\r\n

<<< 229 37\r\n

>>> ADG 38 My%20New%20Group 0\r\n

<<< ADG 38 4029 My%20New%20Group 4 0\r\n

>>> ADG 39 thirtyfirst%20group 0\r\n (31st Group)

<<< 223 39\r\n

Because every group is represented by a group ID, you may have multiple groups with the same name. Make sure your client can deal with that. Also, because you cannot have more than 30 groups, all group IDs will be between 0 and 29. Group IDs are recycled (if you have thirty groups, and remove group 3, and add another group, it will become group 3). But don't rely on this, and assume group IDs can be of any reasonable size.

The final parameter in ADG is a little weird. At earlier dates (still with MSNP7), the server would reply with a weird string instead of another zero. If you specify another number instead of a zero, nothing will be done differently, but the server will respond with that same number. I'm not sure what this parameter is for, and if you have any clues, I'd like to hear about it.

Removing Groups (RMG)

To remove a group from your contact list, send the RMG command with the only parameter being the group ID. The server will respond with an RMG with the list version as the first parameter and the group ID as the second parameter. If the group doesn't exist, the server will respond with error 224. If you try to remove group zero, you will receive error 230.

If you remove a group, remember that every user that is in that group is no longer in that group. If a user was in multiple groups, he or she will still be in the other groups. But if it was his or her only group, he or she will be erased from the FL.

>>> RMG 40 4\r\n

<<< RMG 40 4030 4\r\n

>>> RMG 41 4\r\n

<<< 224 41\r\n

>>> RMG 42 0\r\n

<<< 230 42\r\n

Renaming Groups (REG)

To rename a group, send the REG command. The first parameter is the ID of the group you want to rename. The second parameter is the URL-encoded name that you want to group to be renamed to. The third parameter is exactly the same as the final parameter in ADG: The client always sends zero, but you can send other numbers and nothing changes.

Just like in the ADG command, if you rename a group to have more than 128 characters (as of March 29, 2003), you will be immediately disconnected. However, there is no error on names of any less length. So if you want to have a group with 127 characters, you must first add the group to be 61 or less characters, and then rename it to have 127. If you try to rename a nonexistent group, you will get error 224. Because of the 30-group limit, if you try to rename a group with a group ID greater than 29, you will be immediately disconnected. This is not true for removing groups. Also, there is nothing wrong with renaming the group with the ID of zero.

If the REG was successful, the server will respond with an REG. The first parameter will be your new list version. The second parameter will be the group ID. The third parameter will be the new group name (should be the same one you specified). And the fourth parameter is the same as in the ADG command (normally a zero).

Below are some examples of using the REG command:

>>> REG 43 3 My%20New%20Name 0\r\n

<<< REG 43 4031 3 My%20New%20Name 0\r\n

>>> REG 44 20 NewName 0\r\n (Group Does Not Exist)

<<< 224 44\r\n

>>> REG 45 30 NewName 0\r\n

<o> Server Closes Connection