Service: zimbraMail

Command: GetContacts
Namespace: urn:zimbraMail
Description: Get contacts
Contact group members are returned as <m> elements.
If derefGroupMember is not set, group members are returned in the order they were inserted in the group.
If derefGroupMember is set, group members are returned ordered by the "key" of member.
Key is: Contact group members are returned as sub-elements of <m>. If for any(transient or permanent) reason a member cannot be dereferenced, then there will be no sub-element under <m>.

For example:
 <GetContactsResponse xmlns="urn:zimbraMail">
   <cn id="680" fileAsStr="group1" d="1308612784000" rev="900" l="7">
     <a n="nickname">group one</a>
     <a n="type">group</a>
     <a n="fileAs">8:group1</a>
     <m value="user@zimbra.com" type="I"/>
     <m value="282" type="C">
       <cn id="282" fileAsStr="Smith, John" d="1308547353000" rev="27" l="7">
         <a n="lastName">Smith</a>
         <a n="email">jsmith@example.zimbra.com</a>
         <a n="workURL">http://www.example.zimbra.com</a>
         <a n="company">Zimbra</a>
         <a n="workCountry">US</a>
         <a n="workState">CA</a>
         <a n="workPhone">(408) 123-4567</a>
         <a n="firstName">Mark</a>
       </cn>
     </m>
     <m value="uid=user1,ou=people,dc=phoebe,dc=mbp" type="G">
       <cn id="2a692f57-1a5b-4542-9f8e-28dfdd0e3f43:260" fileAsStr="Demo User One" d="1308626790000" rev="22" l="257">
         <a n="createTimeStamp">20110620052132Z</a>
         <a n="lastName">user1</a>
         <a n="email">user1@phoebe.mbp</a>
         <a n="zimbraId">b4bf7953-c10f-449e-b7fe-3df48eea36f8</a>
         <a n="objectClass">inetOrgPerson</a>
         <a n="objectClass">zimbraAccount</a>
         <a n="objectClass">amavisAccount</a>
         <a n="fullName">Demo User One</a>
         <a n="dn">uid=user1,ou=people,dc=phoebe,dc=mbp</a>
         <a n="workPhone">+1 650 555 1111</a>
         <a n="modifyTimeStamp">20110620052229Z</a>
         <a n="fileAs">8:Demo User One</a>
       </cn>
     </m>
   </cn>
 </GetContactsResponse>
 
Properties:
Authorization token required true
Admin Authorization token required false

GetContactsRequest

    <GetContactsRequest [sync="{return-mod-date-flag} (0|1)"] [l="{folder-id}"] [sortBy="{sort-by}"]
                           [derefGroupMember="{deref-group-member} (0|1)"] [memberOf="{include-member-of} (0|1)"]
                           [returnHiddenAttrs="{return-hidden-attrs} (0|1)"]
                           [returnCertInfo="{return-certificate-info} (0|1)"] [wantImapUid="{want-imap-uid} (0|1)"]
                           [maxMembers="{max-members} (Long)"]> ## GetContactsRequest
        (<a n="{attribute-name}" /> ## AttributeName)*
        (<ma n="{attribute-name}" /> ## See /a [ ## AttributeName])*
        (<cn [id="..."] /> ## Id)*
    </GetContactsRequest>

elements and attributes you can define within a <GetContactsRequest> element:

XPath Required / Optional Description
@sync Optional (0 or 1) Type: 0|1
If set, return modified date (md) on contacts.
@l Optional (0 or 1) Type: String
If is present, return only contacts in the specified folder.
@sortBy Optional (0 or 1) Type: String
Sort by
@derefGroupMember Optional (0 or 1) Type: 0|1
If set, deref contact group members.
Contact members can be:
  • inline data of name and email address
  • a reference to a local contact or a shared contact
  • a GAL entry
Note: for performance reason, derefGroupMember is supported only when specific contact ids are specified.
@memberOf Optional (0 or 1) Type: 0|1
If set, Include the list of contact groups this contact is a member of.
Note: use sparingly, there is a performance penalty associated with computing this information
@returnHiddenAttrs Optional (0 or 1) Type: 0|1
Whether to return contact hidden attrs defined in zimbraContactHiddenAttributes
ignored if <a> is present.
@returnCertInfo Optional (0 or 1) Type: 0|1
Whether to return smime certificate info
@wantImapUid Optional (0 or 1) Type: 0|1
Set to return IMAP UID. (default is unset.)
@maxMembers Optional (0 or 1) Type: Long
Max members
/a Optional (0 or more) Attrs - if present, return only the specified attribute(s).
/a@n Required (only 1) Type: String
Attribute name
/ma Optional (0 or more) If present, return only the specified attribute(s) for derefed members, applicable only when derefGroupMember is set.
See /a for more details.
/cn Optional (0 or more) If present, only get the specified contact(s).
/cn@id Optional (0 or 1) Type: String
ID

GetContactsResponse

    <GetContactsResponse> ## GetContactsResponse
        (<cn [sf="{contact-sort-field}"] [exp="{can-expand} (0|1)"] id="{contact-id}" [i4uid="{imap-uid} (Integer)"]
                 [l="{contact-folder-id}"] [f="{contact-flags}"] [t="{contact-tags}"] [tn="{contact-tag-names}"]
                 [md="{contact-modified-date-secs} (Long)"] [ms="{contact-modified-seq} (Integer)"]
                 [d="{contact-date-millis} (Long)"] [rev="{saved-sequence-number} (Integer)"]
                 [fileAsStr="{contact-file-as}"] [email="{contact-email}"] [email2="{contact-email2}"]
                 [email3="{contact-email3}"] [type="{contact-type}"] [dlist="{contact-dlist}"]
                 [ref="{contact-gal-entry-ref}"] [tooManyMembers="{contact-too-many-members} (0|1)"]> ## ContactInfo
            (<meta [section="{section}"]> ## MailCustomMetadata
                (<a n="{key}">{value}</a> ## KeyValuePair)*
              </meta>)*
            (<a [part="{contact-part-id}"] [ct="{contact-content-type}"] [s="{contact-size} (Integer)"]
                    [filename="{contact-content-filename}"] n="{key}" /> ## ContactAttr)*
            (<m type="{member-type}" value="{member-value}"> ## ContactGroupMember
                <cn> ... </cn> ## See /cn [ ## ContactInfo] # [inside itself]
              </m>)*
            <memberOf>{memberOf} (String)</memberOf>
          </cn>)*
    </GetContactsResponse>

elements and attributes you can define within a <GetContactsResponse> element:

XPath Required / Optional Description
/cn Optional (0 or more) Contact information
/cn@sf Optional (0 or 1) Type: String
Sort field value
/cn@exp Optional (0 or 1) Type: 0|1
Set if the user can (has right to) expand group members. Returned only if needExp is set in the request and only on group entries (type=group in attrs on a <cn>).
/cn@id Required (only 1) Type: String
Unique contact ID
/cn@i4uid Optional (0 or 1) Type: Integer
IMAP UID
/cn@l Optional (0 or 1) Type: String
Folder ID. When creating a contact, this is the ID of the folder to create the contact in
/cn@f Optional (0 or 1) Type: String
Flags. {flags} = (f)lagged, has (a)ttachment
/cn@t Optional (0 or 1) Type: String
Tags - Comma separated list of integers. DEPRECATED - use "tn" instead
/cn@tn Optional (0 or 1) Type: String
Comma-separated list of tag names
/cn@md Optional (0 or 1) Type: Long
Modified date in seconds
/cn@ms Optional (0 or 1) Type: Integer
Modified sequence
/cn@d Optional (0 or 1) Type: Long
Date in milliseconds
/cn@rev Optional (0 or 1) Type: Integer
Saved sequence number
/cn@fileAsStr Optional (0 or 1) Type: String
Current "file as" string for display/sorting purposes; cannot be used to set the file-as value
/cn@email Optional (0 or 1) Type: String
Contact email address
/cn@email2 Optional (0 or 1) Type: String
Contact email address 2
/cn@email3 Optional (0 or 1) Type: String
Contact email address 3
/cn@type Optional (0 or 1) Type: String
Contact type
/cn@dlist Optional (0 or 1) Type: String
Contact dlist
/cn@ref Optional (0 or 1) Type: String
GAL entry reference
/cn@tooManyMembers Optional (0 or 1) Type: 0|1
If number of members on a GAL group is greater than the specified max, do not return any members for the entry. Instead, set "tooManyMembers.
/cn/meta Optional (0 or more) Custom metadata information
/cn/meta@section Optional (0 or 1) Type: String
Section.
Normally present. If absent this indicates that CustomMetadata info is present but there are no sections to report on.
/cn/meta/a Optional (0 or more) Type: {value}
Key value pairs
Description for element text content:Value
/cn/meta/a@n Required (only 1) Type: String
Key
/cn/a Optional (0 or more) Attributes
/cn/a@part Optional (0 or 1) Type: String
Part ID.
Can only specify a {contact-part-id} when modifying an existent contact
/cn/a@ct Optional (0 or 1) Type: String
Content type
/cn/a@s Optional (0 or 1) Type: Integer
Size
/cn/a@filename Optional (0 or 1) Type: String
Content filename
/cn/a@n Required (only 1) Type: String
Key
/cn/m Optional (0 or more) Contact group members
/cn/m@type Required (only 1) Type: String
Member type
C reference to another contact
G reference to a GAL entry
I inlined member (member name and email address is embeded in the contact group)
/cn/m@value Required (only 1) Type: String
Member value
type="C" Item ID of another contact. If the referenced contact is in a shared folder, the item ID must be qualified by zimbraId of the owner. e.g. {zimbraId}:{itemId}
type="G" GAL entry reference (returned in SearchGalResponse)
type="I" name and email address in the form of: "{name}" <{email}>
/cn/m/cn Optional (0 or 1) Contact information for dereferenced member.
See /cn for more details.
/cn/memberOf Optional (0 or 1) Type: {memberOf} (String)
Comma separated list of IDs of contact groups this contact is a member of.
Only provided if requested