WebApp: Recipient properties

October 10, 2012 by Saket Patel   Comments (0)

, , , ,

Whenever we need to show the email address and display name of a receiver/sender, we tend to forget some corner cases which actually changes the meaning of these email properties. This is especially important when dealing with delegation, in which cases the meaning of various "standard" properties changes.


But before we jump into these corner cases, we'll take a look at some basic information about email properties.

MAPI

Any set of email properties contains these basic properties: PR_EMAIL_ADDRESS, PR_SMTP_ADDRESS, PR_ADDRTYPE, PR_SEARCH_KEY, PR_ENTRYID, PR_DISPLAY_NAME.

  • PR_DISPLAY_NAME - this property stores the display name of the sender/receiver. Example: Michael Moore
  • PR_ENTRYID - this property stores the entryid of the sender/receiver, if the sender/receiver is zarafa internal user then it will contain entryid of the user from addressbook; if the user is external user then this will contain a so-called one-off entryid. One-off entryids are created by combining PR_ADDRTYPE, PR_SMTP_ADDRESS and PR_DISPLAY_NAME, but for creating this one-off entryid you need to use some functions.  Example: 00000000AC21A95040D3EE48B319FBA7533044250100000006000000040000004D5441774D513D3D00000000
  • PR_SEARCH_KEY - this is a special binary property which can be created by combining PR_ADDRTYPE and PR_SMTP_ADDRESS. The format of this property is SMTP:MICHAEL@ZARAFA.LOCAL where SMTP is PR_ADDRTYPE and michael@zarafa.local is PR_SMTP_ADDRESS. Example: ZARAFA:MICHAEL@ZARAFA.LOCAL
  • PR_ADDRTYPE - this property contains the address type of the sender/receiver email. possible values are SMTP, ZARAFA and MAPIPDL. Where SMTP indicates that sender/receiver is external to zarafa server, and ZARAFA means it is an internal user of zarafa. MAPIPDL is used in distribution lists and is irrelevant for this topic.  Example: ZARAFA
  • PR_SMTP_ADDRESS - this property contains the smtp address of sender/receiver. Smtp address means an email address with the full domain name in it. Example:  michael@zarafa.local
  • PR_EMAIL_ADDRESS - this property contains the email address of the sender/receiver. Email address means the user name of the sender/receiver. Example: michael

Use of PR_SMTP_ADDRESS and PR_EMAIL_ADDRESS is a little bit confusing, because it's hard to tell which property should be used in which condition. But a generalized rule of thumb would be to use PR_SMTP_ADDRESS when PR_ADDRTYPE is SMTP (and ignore PR_EMAIL_ADDRESS) and use PR_EMAIL_ADDRESS when PR_ADDRTYPE is ZARAFA (and ignore PR_SMTP_ADDRESS). There could be exceptions as well for using these properties.

Now there are four sets of properties in an e-mail message that are useful for showing email addresses.

  • PR_SENDER_* properties - This set of properties is used for storing sender information.
  • PR_SENT_REPRESENTING_* properties - This set of properties is used for storing sent representing information. For normal e-mails, these properties will have the same information as the PR_SENDER_* properties, but these properties are really important when dealing with delegates. So if a secreatry has sent an e-mail on behalf of her boss, then the PR_SENT_REPRESENTING_* properties will contain information about the boss and PR_SENDER_* properties will contain information of the secretary.
  • PR_RECEIVED_BY_* properties - This set of properties indicates who has received this e-mail. For normally received e-mails, this will contain information about the user who has sent the e-mail.
  • PR_RCVD_REPRESENTING_* properties - This set of properties is used to store information about received representing user. For normal e-mails, these properties will be the same as the PR_RECEIVED_BY_* properties, but these properties are really useful when dealing with delegates; when a boss has configured to redirect all meeting related messages to his secretary, then in the secretary's inbox, PR_RCVD_REPRESENTING_* properties will contain information about the boss and PR_RECEIVED_BY_* properties will contain information about the secretary. 

WebApp

If you want to use these properties in the server-side PHP code of WebApp, then you can use the names mentioned above directly. On the other hand, if you plan to use it in the client-side Javascript code, then you need to use different names to access them. The following lists all the server side properties and their client-side equivalents:

PR_SENT_REPRESENTING_NAME => sent_representing_name,
PR_SENT_REPRESENTING_EMAIL_ADDRESS => sent_representing_email_address,
PR_SENT_REPRESENTING_ADDRTYPE => sent_representing_address_type,
PR_SENT_REPRESENTING_ENTRYID => sent_representing_entryid,
PR_SENT_REPRESENTING_SEARCH_KEY => sent_representing_search_key,
PR_SENDER_DISPLAY_NAME => sender_name,
PR_SENDER_EMAIL_ADDRESS => sender_email_address,
PR_SENDER_ADDRTYPE => sender_address_type,
PR_SENDER_ENTRYID => sender_entryid,
PR_SENDER_SEARCH_KEY => sender_search_key,
PR_RECEIVED_BY_DISPLAY_NAME => received_by_name,
PR_RECEIVED_BY_EMAIL_ADDRESS => received_by_email_address,
PR_RECEIVED_BY_ADDRTYPE => received_by_address_type,
PR_RECEIVED_BY_ENTRYID => received_by_entryid,
PR_RECEIVED_BY_SEARCH_KEY => received_by_search_key,
PR_RCVD_REPRESENTING_DISPLAY_NAME => received_representing_name,
PR_RCVD_REPRESENTING_EMAIL_ADDRESS => received_representing_email_address,
PR_RCVD_REPRESENTING_ADDRTYPE => received_representing_address_type,
PR_RCVD_REPRESENTING_ENTRYID => received_representing_entryid,
PR_RCVD_REPRESENTING_SEARCH_KEY => received_representing_search_key

To access these properties in Javascript, you need to have an instance of Zarafa.core.data.IPMRecord or one of it's child classes, but if you want to use PR_RECEIVED_BY_* or PR_RCVD_REPRESENTING_*, you need to have an instance of Zarafa.core.data.MessageRecord or one of its child classes. Just like accessing any other property of a record, we can use code like this:

        record.get('sender_name');

Links
http://community.zarafa.com/webapp/ - the WebApp API documentation
http://community.zarafa.com/php-ext/ - the PHP-MAPI bindings used for accessing MAPI through PHP