Skip to content

Instantly share code, notes, and snippets.

@MattMencel

MattMencel/zimbra-soap.txt

Created June 7, 2010 17:37
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save MattMencel/428946 to your computer and use it in GitHub Desktop.
Save MattMencel/428946 to your computer and use it in GitHub Desktop.
Download ZIP
Zimbra 6.0.4 soap.txt file from docs
Raw
zimbra-soap.txt
REST URL for requesting content:
http://server/service/home/[˜][{username}]/[{folder}]?[{query-params}]
fmt={ics, csv, etc}
id={item-id}
imap_id={item-imap-id}
part={mime-part}
query={search-query}
types={types} // when searching
auth={auth-types}
start={time}
end={time}
sync="1"
{types} = comma-separated list. Legal values are:
appointment|chat|contact|conversation|document|
message|note|tag|task|wiki
(default is "conversation")
{auth-types} = comma-separated list. Legal values are:
co cookie
ba basic auth
nsc do not set a cookie when using basic auth
(default is "co,ba", i.e. check both)
{time} = (time in milliseconds) |
YYYY/dd/mm |
mm/dd/YYYY |
[-]nnnn{minute,hour,day,week,month,year} // relative
----------------------
URL for posting to SOAP is:
/service/soap/
-------------------------------
urn:zimbra -- top-level namespace for global attributes/elements
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
<soap:Header>
<context xmlns="urn:zimbra">
<authToken>...</authToken>
[<session [id="{returned-from-server-in-last-response}" [seq="{highest_notification_received}"]]/>]
[<account by="name|id">{account-name-or-id}</account>]
[<change token="{change-id}" [type="mod|new"]/>]
[<targetServer>{proxy-target-server-id}</targetServer>]
[<userAgent name="{client-name}" [version="{client-version}"]/>]
[<format type="{response-format}" />]
</context>
</soap:Header>
<soap:Body>
<FooRequest ... [requestId="{client-generated-id}"]>
</FooRequest>
</soap:Body>
</soap:Envelope>
Notification Reliability
To ensure that the client receives all notifications, the client
must send the highest known notification ID (the highest <notify>
block that the client has received and processed) so that the server
can discard them once it knows they have been received. If the client
is capable of sending multiple overlapping requests, the client is
responsible for making sure that notifications are not applied more
than once even if they are received more than one time.
Race Conditions
To avoid race conditions, the client may specify the highest change ID
that it knows about in the <change> header element. The default behavior
(type="mod") will cause mail.MODIFY_CONFLICT to be thrown if we try to
modify an object that has been touched (flags, tags, folders, etc.) since
the specified change ID. Alternatively, type="new" will throw
mail.MODIFY_CONFLICT if we try to modify an object that has been created
or whose content has been modified since the specified change ID.
In general, the sync client will use type="mod" and the web client will
use type="new".
Proxy Mechanism
The targetServer info is a proxy mechanism to allow a browser client to
send requests to multiple servers. This is primarily useful for admin
commands, but the mechanism is available for all commands. Proxying is
needed because some admin commands must be sent to the server being
affected but the browser admin client can only talk to the server it
originally logged on to. (JavaScript security restriction) If
<targetServer> element is missing, the command is executed on the local
server. If the target server specified is the local server, the command
is executed locally. Otherwise, it is proxied. The server is specified
by id, not by name.
Sessions
The server's default is disabling sessions for every SOAP request.
Clients that desire notification must explicitly request that the server
maintain a session for them. This is done by specifying a <session/>
element in the request.
When sessions are explicitly requested by the client, the server
will return the client's active session ID in the response's <session/>
header element. If this session ID is different from the one sent by the
client (or if the client requested a new session by including just a bare
"<session/>" inn the header), the client should assume the old session
(if any) has expired and immediately start using the returned session ID.
If a new session is created (due to no session ID being supplied in the request
or the old session timing out), the response context header will contain a
<refresh> block containing the current set of tags and folders. If there
have been any changes to the mailbox since the last soap operation (including
changes made due to this operation), there will also be a <notify> block in
the response context containing information on the deleted, created, and
modified items in the mailbox. (Note that a session will not return any
notifications if <nonotify/> was ever specified in a <context> request
element involving the session.) If there is a session, there will be a
<change> element specifying the last change ID on the server.
- deleted has just id
- created has full ToXML item dump
- modified has type/id, modified fields
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
[<soap:Header>
<context xmlns="urn:zimbra">
<session id="{session-id}" [type="admin"]/>
<change token="{change-id}"/>
[<refresh>
<version>{server-version-string}</version>
<mbx s="{bytes-used}" [acct="{remote-mailbox-owner-id}"]/>
<tags>
<-- all tags listed -->
</tags>
<folder id="1">
<folder .../>
<folder ...>
<folder .../>
</folder>
<folder .../>
</folder>
</refresh>]
[<notify seq="sequence-number">
<deleted id="665,66,452,883"/>
<created>
<tag id="66" name="phlox" u="8"/>
<folder id="4353" name="a&p" u="2" l="1"/>
<folder id="4356" name="subfoldre" u="2" l="4353"/>
<link id="1" name="new-mount-point" l="1" n="6" u="1" f="u" owner="user1@example.com" zid="151bd192-e19a-40be-b8c9-259b21ffac48" rid="2">
<folder id="151bd192-e19a-40be-b8c9-259b21ffac48:260" name="remote-subfolder" n="43" l="151bd192-e19a-40be-b8c9-259b21ffac48:2"/>
</link>
</created>
<modified>
<tag id="65" u="0"/>
<m id="553" f="ua"/>
<note id="774" color="4">
This is the new content.
</note>
</modified>
</notify>]+
</context>
<soap:/Header>]
<soap:Body>
<FooResponse ... [requestId="{client-generated-id}"]>
</FooResponse>
</soap:Body>
</soap:Envelope>
NOTES: The requestId="..." attribute is optional in the request body. If present, the server will
include it in the response body element.
batch requests:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
<soap:Header>
<context xmlns="urn:zimbra">
<authToken>...</authToken>
[<session [id="{returned-from-server-in-last-response}"]/>]
[<account by="name|id">{account-name-or-id}</account>]
[<change token="{change-id}" [type="mod|new"]/>]
</context>
</soap:Header>
<soap:Body>
<BatchRequest xmlns="urn:zimbra" onerror="continue*|stop">
<FooRequest requestId="1">
</FooRequest>
<BarRequest requestId="2">
</BarRequest>
</BatchRequest>
</soap:Body>
</soap:Envelope>
response:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
[<soap:Header>
<context xmlns="urn:zimbra">
<session id="{session-id}" [type="admin"]>
[<refresh>
<mbx s="{bytes-used}" [acct="{remote-mailbox-owner-id}"]/>
<tags>
<-- all tags listed -->
</tags>
<folder id="1">
<folder .../>
<folder ...>
<folder .../>
</folder>
<folder .../>
</folder>
</refresh>]
[<notify seq="sequence-number">
<deleted ids="665,66,452,883"/>
<created>
<tag id="66" name="phlox" u="8"/>
<folder id="4353" name="a&p" u="2" l="1"/>
</created>
<modified>
<tag id="65" u="0"/>
<m id="553" t="ua"/>
<note id="774" color="4">
This is the new content.
</note>
</modified>
</notify>]+
</context>
<soap:/Header>]
<soap:Body>
<BatchResponse xmlns="urn:zimbra">
<soap:Fault requestId="1">
</soap:Fault>
<BarResponse ... requestId="2">
</BarResponse>
</BatchResponse>
</soap:Body>
</soap:Envelope>
User Agent
userAgent is an optional context element that is used for identifying the
type of SOAP client that's making the request. The user agent is written
to mailbox.log messages with the context string "ua".
Request and Response Formats
The requests and responses can be specified in XML or JSON format. The
server determines the request format automatically but JSON requests
MUST follow these requirements:
* request encoded in UTF-8
* start with '{' for server to identify JSON content
* do not include "Envelope" object
* elements specified as "name": { ... }
* attributes specified as "name": "value"
* namespace attribute specified as "_jsns": "ns-uri"
* element text content specified as "_content": "content"
* element list specified as "name": [ ... ]
Example:
{
"Header": {
"context": {
"_jsns": "urn:zimbra",
"authToken": {
"_content": "0_3e761bdc...303b"
}
}
},
"Body": {
"FooRequest": {
"_jsns": "urn:zimbra",
"name": "attribute content",
"_content": "element content"
}
}
}
The response format is XML by default. To change, specify a "format"
element in the request's Header element with a "type" attribute. The
value must be either "xml" or "js".
SOAP request with JSON response:
<soap:Envelope ...>
<soap:Header>
...
<format type='js' />
</soap:Header>
...
</soap:Envelope>
JSON request with XML response:
{
"Header": {
...
"format": { "type": "xml" }
},
...
}
-----------------------------
SOAP 1.2
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
<soap:Body>
<soap:Fault>
<soap:Code>
<soap:Value>soap:Sender</soap:Value>
</soap:Code>
<soap:Reason><soap:Text>...</soap:Text><soap:Reason>
<soap:Detail>
<Error xmlns="urn:zimbra">
<Code>...</Code>
[<a n="name">VALUE</a>]* // error information (arguments, e.g. ID that was bad, or whatever)
</Error>
</soap:Detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>
SOAP 1.1
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<soap:Fault>
<soap:faultcode>soap:Server</soap:faultcode>
<soap:faultstring>Server Error</soap:faultstring>
<soap:detail>
<Error xmlns="urn:zimbra">
<Code>...</Code>
[<a n="name">VALUE</a>]* // error information (arguments, e.g. ID that was bad, or whatever)
</Error>
</soap:detail>
</soap:Fault>
</soap:Body>
</soapEnvelope>
global soap/system errors used with zimbra:Error/Code:
service.FAILURE - generic system failure
service.INVALID_REQUEST - bad request (missing args, etc)
service.UNKNOWN_DOCUMENT - no handler for specified document
service.PARSE_ERROR - XML parsing error
service.PERM_DENIED - permission denied
service.AUTH_REQUIRED - an authtoken is required
service.AUTH_EXPIRED - authentication creds have expired
service.WRONG_HOST - operation is sent to a wrong host
service.PROXY_ERROR - unable to proxy operation
service.TOO_MANY_HOPS - operation was proxied too many times
service.INTERRUPTED - index operation was interrupted
service.NOT_IN_PROGRESS - attempt to stop index operation when it was not in progress
service.ALREADY_IN_PROGRESS - attempt to start index operation when it was already in progress
service.NO_SPELL_CHECK_URL - spellcheck is not available
service.RESOURCE_UNREACHABLE - unable to reach the remote resource
service.TEMPORARILY_UNAVAILABLE - resource is temporarily unavailable
service.NON_READONLY_OPERATION_DENIED -
-----------------------------
urn:zimbraAccount
account error/codes: (includes service.*):
account.AUTH_FAILED - bad account/password
account.CHANGE_PASSWORD - password must be changed
account.PASSWORD_LOCKED - password can't be changed
account.PASSWORD_CHANGE_TOO_SOON = password can't be changed yet
account.PASSWORD_RECENTLY_USED = can't use the same password again
account.INVALID_PASSWORD - new password does not meet the system's rules (length, content, etc.)
account.INVALID_ATTR_NAME - the specified attribute name is invalid
account.INVALID_ATTR_VALUE - the specified attribute value is invalid
account.MULTIPLE_ACCOUNTS_MATCHED - when auth by foreignPrincipal matches multiple accounts with the same foreignPrincipal
account.NO_SUCH_ACCOUNT
account.NO_SUCH_ALIAS
account.NO_SUCH_DOMAIN
account.NO_SUCH_COS
account.NO_SUCH_IDENTITY
account.NO_SUCH_SIGNATURE
account.NO_SUCH_DATA_SOURCE
account.NO_SUCH_SERVER
account.NO_SUCH_ZIMLET
account.NO_SUCH_DISTRIBUTION_LIST
account.NO_SUCH_CALENDAR_RESOURCE
account.NO_SUCH_MEMBER
account.MEMBER_EXISTS
account.ACCOUNT_EXISTS
account.DOMAIN_EXISTS
account.COS_EXISTS
account.SERVER_EXISTS
account.DISTRIBUTION_LIST_EXISTS
account.IDENTITY_EXISTS
account.SIGNATURE_EXISTS
account.DATA_SOURCE_EXISTS
account.DOMAIN_NOT_EMPTY
account.MAINTENANCE_MODE
account.ACCOUNT_INACTIVE
account.TOO_MANY_ACCOUNTS
account.TOO_MANY_IDENTITIES
account.TOO_MANY_SIGNATURES
account.TOO_MANY_DATA_SOURCES
account.TOO_MANY_SEARCH_RESULTS
<AuthRequest xmlns="urn:zimbraAccount">
[<account by="name|id|foreignPrincipal">...</account>]
[<password>...</password>]
[<preauth timestamp="{timestamp}" expires="{expires}">{computed-preauth-value}</preauth>]
[<authToken>...</authToken>]
[<virtualHost>{virtual-host}</virtualHost>]
[<prefs>[<pref name="..."/>...]</prefs>]
[<attrs>[<attr name="..."/>...]</attrs>]
[<requestedSkin>{skin}</requestedSkin>]
</AuthRequest>
<AuthResponse">
<authToken>...</authToken>
<lifetime>...</lifetime>
<session .../>
<refer>{mail-host}</refer>
[<prefs><pref name="{name}" modified="{modified-time}">{value}</pref>...</prefs>]
[<attrs><attr name="{name}">{value}</a>...</attrs>]
[<skin>{skin-name}</skin>]
</AuthResponse>
Note:
when specifiying an account, one of <password> or <preauth> must be specified. see preauth.txt for a discussion of preauth.
an authToken can be passed instead of account/password/preauth to validate an existing auth token.
{mail-host} = host additional SOAP requests should be directed to. Always returned, might be same as original host request was sent to.
{virtual-host} = if specified (in conjunction with by="name"), virtual-host is used to determine the domain of the account name, if it
does not include a domain component. For example, if the domain foo.com has a zimbraVirtualHostname of "mail.foo.com",
and an auth request comes in for "joe" with a virtualHost of "mail.foo.com", then the request will be equivalent to
logging in with "joe@foo.com".
only attrs that are allowed to be returned by GetInfo will be returned by this call
{requested-skin} = if specified the name of the skin requested by client
{skin-name} = if requested-skin specified, the name of the skin to use
---------
<ChangePasswordRequest>
<account by="name">...</account>
<oldPassword>...</oldPassword>
<password>...</password>
[<virtualHost>{virtual-host}</virtualHost>]
</ChangePasswordRequest>
<ChangePasswordResponse>
<authToken>...</authToken>
<lifetime>...</lifetime>
<ChangePasswordResponse/>
{virtual-host} = if specified virtual-host is used to determine the domain of the account name, if it
does not include a domain component. For example, if the domain foo.com has a zimbraVirtualHostname of "mail.foo.com",
and an auth request comes in for "joe" with a virtualHost of "mail.foo.com", then the request will be equivalent to
logging in with "joe@foo.com".
Returns new authToken, as old authToken will be invalidated on password change.
---------------------------
<EndSessionRequest xmlns="urn:zimbraAccount"/>
Ends the current session, removing it from all caches. Called when
the browser app (or other session-using app) shuts down. Has no
effect if called in a <nosession> context.
---------
<GetPrefsRequest>
<!-- get only the specified prefs -->
[<pref name="{name1}"/>
<pref name="{name2}"/>]
</GetPrefsRequest>
If no <pref> elements are provided, all known prefs are returned in the response.
If <pref> elements are provided, only those prefs are returned in the response.
<GetPrefsResponse>
<pref name="{name}">{value}</pref>
...
<pref name="{name}">{value}</pref>
</GetPrefsResponse>
----------------------------
<GetInfoRequest [sections="mbox,prefs,attrs,zimlets,props,idents,sigs,dsrcs,children"]>
</GetInfoRequest>
<-- by default, GetInfo returns all data; to limit the returned data, specify only the sections you want in the "sections" attr -->
<GetInfoResponse>
<version>{version}</version>
<id>{account-id}</id>
<name>{account-name}</name>
<lifetime>...</lifetime>
[<rest>{account-base-REST-url}</rest>
<used>{used}</used>
<prevSession>{previous-SOAP-session}</prevSession>
<accessed>{last-SOAP-access}</accessed>
<recent>{recent-messages}</recent>
]
<cos name="cos-name" id="cos-id"/>
<attrs>
<attr name="{name}">{value}</a>
...
<attr name="{name}">{value}</a>
</attrs>
<prefs>
<pref name="{name}">{value}</pref>
...
<pref name="{name}">{value}</pref>
</prefs>
<props>
<prop zimlet="{zimlet-name}" name="{name}">{value}</prop>
...
<prop zimlet="{zimlet-name}" name="{name}">{value}</prop>
</props>
<zimlets>
<zimlet>
<zimletContext baseUrl="..."/>
<zimlet>...</zimlet>
<zimletConfig>...</zimletConfig>
</zimlet>
...
</zimlets>
<mailURL>{mail-url}</mailURL>+
<publicURL>{account-base-public-url}</publicURL>
<identities>
<identity name={identity-name} id="...">
<a name="{name}">{value}</a>
...
<a name="{name}">{value}</a>
</identity>*
</identities>
<signatures>
<signature name={signature-name} id="...">
<a name="{name}">{value}</a>
...
<a name="{name}">{value}</a>
</signature>*
</signatures>
<dataSources>
{data-source}
...
</dataSources>*
<childAccounts>
<childAccount name="{child-account-name}" visible="0|1" id="{child-account-id}">
<attrs>
<attr name="{name}">{value}</a>*
</attrs>
</childAccount>*
</childAccounts>
[<license status="inGracePeriod|bad"/>]
</GetInfoResponse>
{version} = server version: <major>[.<minor>[.<maintenance>]][build] <release> <date>[ <type>]
{account-name} = email address (user@domain)
{life-time} = number of milliseconds until auth token expires
{account-base-REST-url} = base REST URL for the requested account
returned only if the command successfully executes on the target user's home mail server:
{used} = mailbox quota used in bytes
{last-SOAP-access} = time (in millis) of last write op from this session, or from *any* SOAP session if we don't have one
{previous-SOAP-session} = time (in millis) of last write op from any SOAP session before this session was initiated,
or same as {last-SOAP-access} if we don't have one
{recent-messages} = number of messages received since the previous soap session, or since the last SOAP write op if we don't have a session
prefs = user-settable preferences
attrs = account attrs that aren't user-settable, but the front-end needs.
Only attributes listed in zimbraAccountClientAttrs will be returned.
{mail-url} = URL to talk to for soap service for this account. i.e:
http://server:7070/service/soap/
Multiple URLs can be returned if both http and https (SSL) are enabled. If only one of the two is enabled,
the only one URL will be returned.
{account-base-public-url} = base public URL for the requested account
license attribute is pertinent to the Network edition only. this attribute is
present only when the installed license is NOT ok.
attrs under <childAccount>: including the following attrs of the child account:
- displayName
{data-source}: see GetDataSourcesRequest for details
----------------------------
<GetAccountInfoRequest>
<account by="id|name">...</account>
</GetAccountInfoRequest>
<GetAccountInfoResponse>
<name>{account-name}</name>
<attr name="{name}">{value}</a>+
<soapURL>{mail-url}</soapURL>+
<publicURL>{account-base-public-url}</publicURL>
</GetInfoResponse>
{account-name} = email address (user@domain)
{attrs} = account attrs. Currently only two attrs are returned:
zimbraId - the unique UUID of the zimbra account
zimbraMailHost - the server on which this user's mail resides
{mail-url} = URL to talk to for soap service for this account. i.e:
http://server:7070/service/soap/
Multiple URLs can be returned if both http and https (SSL) are enabled. If only one of the two is enabled,
the only one URL will be returned.
{account-base-public-url} = base public URL for the requested account
----------------------------
<GetAvailableSkinsRequest/>
<GetAvailableSkinsResponse>
<skin name="{skin-name}"/>+
</GetAvailableSkinsResponse>
Returns intersection of installed skins on the server and the list
specified in the zimbraAvailableSkin on an account (or its
CoS). If none is set in zimbraAvailableSkin, it returns the
entire list of installed skins. The installed skin list is obtained
by a directory scan of the designated location of skins on a server.
----------------------------
<GetAvailableCsvFormatsRequest/>
<GetAvailableCsvFormatsResponse>
<csv name="{format-name}"/>+
</GetAvailableCsvFormatsResponse>
Returns the known CSV formats that can be used for
import and export of addressbook.
----------------------------
<SearchGalRequest [type="{type}"] [limit="..."] [offset="..."] [sortBy="{sort-by}"] [groupBy="{group-by}"]>
[<cursor id="{prevId}" sortVal="{prevSortValue}" endSortVal="{endSortValue}"/> ]
<name>...</name>
</SearchGalRequest>
<SearchGalResponse more="{more}" sortBy="sort-by" offset="..." [tokenizeKey="{tokenize-key-op}"]>
<cn>...</cn>*
</SearchGalResponse>
{more-flag} = 1 if the results were truncated.
{tokenize-key-op} = and|or
- Not present if the search key was not tokenized.
- Some clients backtrack on GAL results assuming the results of a more
specific key is the subset of a more generic key, and it checks cached
results instead of issuing another SOAP request to the server.
If search key was tokenized and expanded with AND or OR, this cannot
be assumed.
{type} = type of addresses to search
"account" for regular user accounts, aliases and distribution lists
"resource" for calendar resources
"all" for combination of both types
if omitted, defaults to "all"
see SearchRequest for use of cursor.
----------------------------
<AutoCompleteGalRequest [type="{type}"] limit="limit-returned">
<name>...</name>
</AutoCompleteGalRequest>
<AutoCompleteGalResponse more="{more}" [tokenizeKey="{tokenize-key-op}"]>
<cn>...</cn>*
</AutoCompleteGalResponse>
{limit} = an integer specifying the maximum number of results to return
{type} = type of addresses to auto-complete on
"account" for regular user accounts, aliases and distribution lists
"resource" for calendar resources
"all" for combination of both types
if omitted, defaults to "accounts"
{more-flag} = 1 if the results were truncated.
{tokenize-key-op} = and|or
- Not present if the search key was not tokenized.
- Some clients backtrack on GAL results assuming the results of a more
specific key is the subset of a more generic key, and it checks cached
results instead of issuing another SOAP request to the server.
If search key was tokenized and expanded with AND or OR, this cannot
be assumed.
----------------------------
<AutoCompleteRequest folders="{folders}" includeGal="0|1" limit="...">
<name>...</name>
</AutoCompleteRequest>
<AutoCompleteResponse canBeCached="0|1">
<match ranking="..." l="..." type="gal|group|contact|unknown" email="..." [display="..."] [id="..."]/>*
</AutoCompleteResponse>
{folders} - comma separates list of folder IDs.
- email field contains comma separated email addresses in case of group
- display field contains string that should be displayed by the client
----------------------------
<SyncGalRequest [token="{previous-token}] [idOnly={true|false}]"/>
<SyncGalResponse token="{new-token}">
<cn>...</cn>*
<deleted id="{itemId}">*
</SyncGalResponse>
If the request has idOnly set to true, then the response will contain
id attribute without all the contact fields populated. The sync client
then should make batch request to the server to fetch the contact fields
with <GetContactsRequest/>.
----------------------------
<SearchCalendarResourcesRequest
[attrs="a1,a2,a3"] [sortBy="{sortBy}"] [sortAscending="{sortAscending}"] >
<searchFilter>
<conds [not="1|0"] [or="1|0"] >
[<cond> or <conds>]+
</conds> (exactly one instance of <conds>)
-- or --
<cond [not="1|0"] attr="{attr}" op="{op}" value="{value}" /> (exactly one instance of <cond>)
</searchFilter>
</SearchCalendarResourcesRequest>
<SearchCalendarResourcesResponse>
<calresource name="{name}" id="{id}">
<a n="...">...</a>+
</calresource>*
</SearchCalendarResourcesResponse>
Notes:
SearchCalendarResourcesRequest:
attrs - comma-seperated list of attrs to return ("displayName", "zimbraId", "zimbraCalResType")
sortBy - name of attribute to sort on. default is the calendar resource name.
sortAscending - whether to sort in ascending order (0/1), 1 is default
must have exactly one <conds> child or exactly one <cond> child and no other child element
conds: denotes a compound condition
must have 1 or more children
each child can be a <cond> or <conds>
not - if 1, negate the compound condition
or - if 1, child conditions are OR'd together; if 0 (default), they are AND'ed together
cond: denotes a simple condition of "attr operator value" form
not - if 1, negate the condition
attr - attribute name
op - operator; valid operators are:
"eq" - attr equals value (integer or string)
"has" - attr has value (substring search)
"ge" - attr greater than or equal to integer value
"le" - attr less than or equal to integer value
"gt" - attr greater than (but not equal to) integer value
"lt" - attr less than (but not equal to) integer value
"startswith" - attr starts with value (string)
"endswith" - attr ends with value (string)
value - value
----------------------------
<ModifyPrefsRequest>
[<pref name="{name}">{value}</pref>...]+
</ModifyPrefsRequest>
<ModifyPrefsResponse/>
Notes:
For multi-value prefs, just add the same attribute with 'n' different values:
<ModifyPrefsRequest>
<pref name="foo">value1</pref>
<pref name="foo">value2</pref>
.
.
.
</ModifyPrefsRequest>
---------
<CreateIdentityRequest>
<identity name="{identity-name}">
<a name="{name}">{value}</a>
...
<a name="{name}">{value}</a>
</identity>
</CreateIdentityRequest>
<CreateIdentityResponse>
<identity name="{identity-name}" id="{identity-id}">
....
</identity>
</CreateIdentityResponse>
Allowed attributes (see objectclass zimbraIdentity in zimbra.schema)
zimbraPrefBccAddress
zimbraPrefForwardIncludeOriginalText
zimbraPrefForwardReplyFormat
zimbraPrefForwardReplyPrefixChar
zimbraPrefFromAddress
zimbraPrefFromDisplay
zimbraPrefMailSignature
zimbraPrefMailSignatureEnabled
zimbraPrefMailSignatureStyle
zimbraPrefReplyIncludeOriginalText
zimbraPrefReplyToAddress
zimbraPrefReplyToDisplay
zimbraPrefReplyToEnabled
zimbraPrefSaveToSent
zimbraPrefSentMailFolder
zimbraPrefUseDefaultIdentitySettings
zimbraPrefWhenInFolderIds
zimbraPrefWhenInFoldersEnabled
zimbraPrefWhenSentToAddresses
zimbraPrefWhenSentToEnabled
---------
<GetIdentitiesRequest/>
<GetIdentitiesResponse>
<identity name="{identity-name}" id="{identity-id}">
<a name="{name}">{value}</a>
...
<a name="{name}">{value}</a>
</identity>+
</GetIdentitiesResponse>
---------
<ModifyIdentityRequest>
<identity [name="{identity-name}" | id="{identity-id}"]>
<a name="{name}">{value}</a>
...
<a name="{name}">{value}</a>
</identity>
</ModifyIdentityRequest>
<ModifyIdentityResponse/>
<-- must specify either 'name' or 'id' -->
---------
<DeleteIdentityRequest>
<identity [name="{identity-name}" | id="{identity-id}"]/>
</DeleteIdentityRequest>
<DeleteIdentityResponse/>
<-- must specify either 'name' or 'id' -->
---------
<CreateSignatureRequest>
<signature name="{signature-name}" [id="{id}"]/>
<content type="{text/plain | text/html}">{signature-value}</content>+
</signature>
</CreateSignatureRequest>
<CreateSignatureResponse>
<signature id="{id}" name="{signature-name}"/>
</CreateSignatureResponse>
- If an id is provided it will be honored as the id for the signature.
- CreateSignature will set account default signature to the signature being created
if there is currently no default signature for the account.
- There can be at most one text/plain signatue and one text/html signature.
---------
<GetSignaturesRequest/>
<GetSignaturesResponse>
<signature name="{signature-name}" id="{identity-id}"
<content type="{text/plain | text/html}">{signature-value}</content>+
</signature>+
</GetSignaturesResponse>
---------
<ModifySignatureRequest>
<signature id="{signature-id}" [name="{signature-name}"]>
<content type="{text/plain | text/html}">{signature-value}</content>+
</signature>
</ModifySignatureRequest>
<ModifySignatureResponse/>
- Changes attributes of the given signature. Only the attributes specified in the request
are modified.
- Server identify the signature by id, if the name attribute is present and is different
from the current name of the signature, the signature will be renamed.
---------
<DeleteSignatureRequest>
<signature [name="{signature-name}" | id="{signature-id}"]/>
</DeleteSignatureRequest>
<DeleteSignatureResponse/>
<-- must specify either 'name' or 'id' -->
---------
urn:zimbraMail
mail error/codes: (includes service.*)
Error code parameters:
- Error results have data parameters encoded in the
soap:detail for the error, in <a> elements:
[<a n="name">VALUE</a>]* // error information (arguments,
e.g. ID that was bad, or whatever)
- See SOAP 1.1 or SOAP 1.2 section above.
List of error codes:
mail.MAINTENANCE - in maintenance
mail.NO_SUCH_MBOX - no such mailbox
mail.NO_SUCH_ITEM - no such item
mail.NO_SUCH_CONV - no such converstation
mail.NO_SUCH_MSG - no such message
mail.NO_SUCH_PART - no such message part
mail.NO_SUCH_FOLDER - no such folder
mail.NO_SUCH_TAG - no such tag
mail.NO_SUCH_CONTACT - no such contact
mail.NO_SUCH_NOTE - no such note
mail.NO_SUCH_CALITEM - no such calendar item
mail.NO_SUCH_APPT - no such appointment
mail.NO_SUCH_TASK - no such task
mail.NO_SUCH_DOC - no such doc
mail.NO_SUCH_UPLOAD - no such upload
mail.NO_SUCH_WAITSET - no such waitset
mail.QUERY_PARSE_ERROR - couldn't parse search query (see below
for detailed error info)
mail.NO_SUCH_CONTACT - the specified contact id did not exist
mail.MODIFY_CONFLICT - if the modified date on a contact is different then one in the request
mail.ALREADY_EXISTS
mail.INVALID_ID
mail.INVALID_SYNC_TOKEN
mail.INVALID_NAME
mail.INVALID_TYPE
mail.INVALID_CONTENT_TYPE
mail.IS_NOT_CHILD
mail.CANNOT_CONTAIN
mail.CANNOT_COPY
mail.CANNT_TAG
mail.CANNOT_PARENT
mail.CANNOT_RENAME
mail.CANNOT_SUBSCRIBE
mail.IMMUTABLE_OBJECT
mail.WRONG_MAILBOX
mail.MODIFY_CONFLICT
mail.TRY_AGAIN
mail.SCAN_ERROR
mail.UPLOAD_REJECTED
mail.TOO_MANY_TAGS
mail.TOO_MANY_UPLOADS
mail.TOO_MANY_CONTACTS
mail.UNABLE_TO_IMPORT_CONTACTS
mail.UNABLE_TO_IMPORT_APPOINTMENTS
mail.QUOTA_EXCEEDED
mail.QUERY_PARSE_ERROR
mail.MESSAGE_PARSE_ERROR
mail.ADDRESS_PARSE_ERROR
mail.ICALENDAR_PARSE_ERROR
mail.MUST_BE_ORGANIZER
mail.CANNOT_CANCEL_INSTANCE_OF_EXCEPTION
mail.INVITE_OUT_OF_DATE
mail.SEND_ABORTED_ADDRESS_FAILURE
mail.SEND_PARTIAL_ADDRESS_FAILURE
mail.SEND_FAILURE
mail.TOO_MANY_QUERY_TERMS_EXPANDED
mail.INVALID_COMMIT_ID
------------------------------
mail.QUERY_PARSE_ERROR details
Arguments:
colNo - index into query string where the error occured
curTok - current token being parsed (not always set)
parserErr - localizable error code describing what happened. Current codes:
UNKNOWN_TEXT_AFTER_IS - user entered is:blah, blah unknown
MISSING_TEXT_AFTER_TOFROMCC - user entered from: without required text
LEXICAL_ERROR - Invalid character in search string or invalid operator name (e.g. "iis:foo")
PARSER_ERROR - Missing operand after operator ("in:") or other general parse error, look at curTok
INVALID_DATE - Couldn't parse argument to date: (before: after: etc) query. Check curTok.
------------------------------
<!--
defaults aren't normally included in the response, they may
be shown here in examples though
-->
Email addresses:
<e [t="{type}"] p="{personal-name}" a="{email-address}" d="{display-name}">{content}</e>
{type} = (f)rom, (t)o, (c)c, (b)cc, (r)eply-to, (s)ender, read-receipt (n)otification
Type is only sent when an individual message is returned. In the
list of conversations, all the email addresseses returned for a conversation are a subset
of the participants. In the list of messages in a converstation, the email addressses are
the senders.
{personal-name} = the comment/name part of an address
{email-address} = the user@domain part of an address
{display-name} = if we have personal, first word in "word1 word2" format, or last word in "word1, word2" format.
if no personal, take string before "@" in email-address.
{content} = the original email string as specified by the sender (since we can't reliably reconstruct it
out of the components)
MimeParts:
<mp part="{mime-part-name}" body="{is-body}" s="{size-in-bytes} mid="{message-id} cid="{conv-id}" [truncated="1"]
ct="{content-type}" name="{name}" cd="{content-disposition}" filename="{filename} ci="{content-id} cl="{content-location}">
[<content>{content}</content>]
<mp part="..." ...>
<mp part="..." ...>
</mp>
</mp>
</mp>
{mime-part-name} = MIME part, "" means top-level part, 1 first part, 1.1 first part of a multipart inside of 1.
truncated="1" = the caller requested a maximum length (max="...") for inlined <content>, and this part's content was truncated down to that length
{content-type} = MIME Content-Type. The mime type is the content of the element.
{name} = name attribute from the Content-Type param list
{cont-disp} = MIME Content-Disposition
{filename} = filename attribute from the Content-Disposition param list
{content-id} = MIME Content-ID (for display of embedded images)
{content-location} = MIME/Microsoft Content-Location (for display of embedded images)
{cont-desc} = MIME Content-Description. Note cont-desc is not currently used in the code.
{content} = the content of the part, if requested
{is-body} = set to 1, if this part is considered to be the "body" of the message for display
purposes.
{message-id} = item id of the enclosing message, only present if <mp> is not enclosed within a <m> element
Messages:
<m id="{message-id}" f="{flags}" s="{size}" d="{date}" cid="{conv-id}" l="{folder} origid="{original-id}">
<content>....</content>*
<e .../>*
<su>{subject}</su>
<fr>{fragment}</fr>
<mid>{Message-ID header}</mid>
[<inv>...</inv>]
[<mp>...</mp>]
[<content (url="{url}")>...</content>]
</m>
{content} = complete rfc822 message. only present during certain operations that deal with the raw content
of a message. There is at most 1 content element.
{conv-id} = converstation id. only present if <m> is not enclosed within a <c> element
{size} = size in bytes
{flags} = (u)nread, (f)lagged, has (a)ttachment, (r)eplied, (s)ent by me, for(w)arded, calendar in(v)ite,
(d)raft, IMAP-\Deleted (x), (n)otification sent, urgent (!), low-priority (?)
{date} = secs since epoch, from date header in message
{original-id} = message id of message being replied to/forwarded (outbound messages only)
{url} = content servlet relative url for retrieving message content
{subject} = subject of the message, only returned on an expanded message
{fragment} = first n-bytes of the message (probably between 40-100)
<e .../>* = zero or more addresses in the message, indentified by
type (t="f|t|c")
<inv ...>...</inv> = Parsed out iCal invite. See soap-calendar.txt
<mp ...>...</mp> = The root MIME part of the message. There is exactly 1 MIME part under
a message element. The "body" will be tagged with body="1", and the content
of the body will also be present
<content> = the raw content of the message. cannot have more than one of <mp>, <content> url, and <content> body.
Conversations:
<c id="{conv-id}" t="{tags}" n="{num-msgs}" [total="{all-msgs}"] d="{date}" f="{flags}" [elided="1"]>
<e ...>*
<su>{subject}</su>
<fr>{fragment}</fr>
<m>...</m>+
</c>
{date} = date (secs since epoch) of most recent message in converstation
{tags} = list of tag-ids on conv
{flags} = same flags as on <m> ("sarwfdxnu!?"), aggregated from all the conversation's messages
{subject} = subject of conversation
{fragment} = fragment of most recent msg in converstation
{num-msgs} = number of messages in conversation without IMAP \Deleted flag set
{all-msgs} = total number of messages in conversation
<e ...>* = zero or more participants in the converstations;
if elided="1", some participants are missing between the first and second returned <e> elements
<m>...</m>+ = one or more messages in the conversation. When doing search, the <m> elements returned
will only have the "id" attribute, and only messages that matched the search will be included.
Folders:
<folder id="{folder-id}" name="{folder-name}" l="{parent-id}" [f="{flags}"] [color="{color}"]
u="{unread}" n="{msg-count}" s="{total-size}" [view="{default-type}"]
[url="{remote-url}"] [perm="{effective-perms}"] [rest="{rest-url}"]>
[<acl> <grant perm="{rights}" gt="{grantee-type}" zid="{zimbra-id}" d="{grantee-name}" [pw="{password-for-guest}"] [key=="{access-key}"]/>* </acl>]
</folder>
{folder-name} = name of folder; max length 128; whitespace is trimmed by server;
cannot contain ':', '"', '/', or any character below 0x20
{parent-id} = id of parent folder (absent for root folder)
{flags} = checked in UI (#), exclude free/(b)usy info, IMAP subscribed (*), does not (i)nherit rights from parent, is a s(y)nc folder with external data source, sync is turned on(~), folder does n(o)t allow inferiors / children
{color} = numeric; range 0-127; defaults to 0 if not present; client can display only 0-7
{unread} = number of unread messages in folder
{msg-count} = number of non-subfolder items in folder
{total-size} = total size of all of non-subfolder items in folder
{default-type} = (optional) default type for the folder; used by web client to decide which view to use;
possible values are the same as <SearchRequest>'s {types}: conversation|message|contact|etc
{remote-url} = url (RSS, iCal, etc.) this folder syncs its contents to
{rest-url} = url to the folder on rest interface for rest-enabled apps (such as wiki and notebook)
{effective-perms} = for remote folders, the access rights the authenticated user has on the folder
- will contain the calculated (c)reate folder permission if the user has
both (i)nsert and (r)ead access on the folder
folders can have an optional ACL set on them for sharing. if they do (and the authenticated
user has (a)dminister rights on the folder), an <acl> element will be returned containing
1 or more <grant> elements, with the following attributes:
{rights} = some combination of (r)ead, (w)rite, (i)nsert, (d)elete, (a)dminister, workflow action (x), view (p)rivate, view (f)reebusy
{grantee-type} = the type of grantee: "usr", "grp", "dom" (domain), "cos",
"all" (all authenticated users), "pub" (public authenticated and unauthenticated access),
"guest" (non-Zimbra email address and password),
"key" (non-Zimbra email address and access key)
{grantee-name} = the display name (*not* the zimbra id) of the principal being granted rights;
optional if {grantee-type} is "all"
{pw} = optional argument. password when {grantee-type} is "guest"
{key} = optional argument. access key when {grantee-type} is "key"
Mountpoints:
<link id="{folder-id}" name="{folder-name}" l="{parent-id}" [f="{flags}"] owner="{owner's-display-name}" zid="{owner's-zimbra-id}" rid="{id-of-shared-item}" [color="{color}"] [view="{default-type}"]/>
{folder-name} = name of folder; max length 128; whitespace is trimmed by server;
cannot contain ':', '"', '/', or any character below 0x20
{parent-id} = id of parent folder (absent for root folder)
{flags} = checked in UI (#), exclude free/(b)usy info, IMAP subscribed (*)
{owner's-display-name} = primary email address of the owner of the linked-to resource
{owner's-zimbra-id} = Zimbra id (guid) of the owner of the linked-to resource
{id-of-shared-item} = item id of the linked-to resource in the remote mailbox
{color} = numeric; range 0-127; defaults to 0 if not present; client can display only 0-7
{default-type} = (optional) default type for the folder; used by web client to decide which view to use;
possible values are the same as <SearchRequest>'s {types}:
conversation|message|contact|appointment|note|task|etc
Tags:
<tag id="{tag-id}" name="{tag-name}" [color="{color}"] u="{unread}"/>
{tag-name} = name of tag; max length 128; whitespace is trimmed by server;
cannot contain ':', '"', '/', or any character below 0x20;
cannot begin with '\' (avoid collsions with IMAP)
{color} = numeric; range 0-127; defaults to 0 if not present; client can display only 0-7
{unread} = number of unread messages with this tag
----------
<SearchRequest [limit="..."] [offset="..."] [sortBy="{sort-by}"] [groupBy="{group-by}"]
[types="{types}"] [recip="*0|1"] [fetch="1|all|{item-id}"] [read="*0|1"]
[max="{max-inlined-length}"] [html="*0|1"] [neuter="0|*1"] [field={default_field}]
[calExpandInstStart=TIME_IN_MSEC] [calExpandInstEnd=TIME_IN_MSEC]
[allowableTaskStatus="need,inprogress,completed,canceled"]
>
*(<header n="{header-name}/>)
[<cursor id="prevId" sortVal="prevSortValue" endSortVal="endSortValue"/> ]
// sortVal should be set to the value of the 'sf' (SortField) attribute of the last
// hit on the previous 'page' of search results.
// endSortVal is NON-INCLUSIVE and optional (used for ranges)
[ // OPTIONAL: client timezone identification (necessary to time-correct a user-specified date/time query)
<tz id="timezonename"/> // References an existing server-known timezone by ID
OR
// This format is identical to the one defined in soap-calendar.txt, make sure the documents stay in sync
<tz
id="timezonename" // this name is ignored by the server, but it must be present
stdoff="<minutes>" // offset from UTC in standard time; local = UTC + offset
[dayoff="<minutes>"] // offset from UTC in daylight time; present only if DST is used
>
[ // If daylight savings time is not used, <standard> and <daylight> must be
// omitted. If DST is used, both <standard> and <daylight> must be present.
<standard // time/rule for transitioning from daylight time to standard time
// Either specify week/wkday combo, or mday.
[
week="<number>" // week number; 1=first, 2=second, 3=third, 4=fourth, -1=last
wkday="<number>" // day of week; 1=Sunday, 2=Monday, etc.
]
mon="<number>" // month; 1=January, 2=February, etc.
[mday="<number>"] // day of month (1..31)
hour="<number>" // transition hour (0..23)
min="<number>" // transition minute (0..59)
sec="<number>" // transition second; 0..59, usually 0
/>
<daylight // time/rule for transitioning from standard time to daylight time
[
week="<number>"
wkday="<number>"
]
mon="<number>"
[mday="<number>"]
hour="<number>"
min="<number>"
sec="<number>"
/>
] // optional STANDARD/DAYLIGHT definition
] // optional TIMEZONE specifier
[ // OPTIONAL: client locale identification
<locale>LOCALE-STRING</locale> // Where locale string is of the form LL-CC[-V+] where
// LL is two character language code
// CC is two character country code
// V+ is optional variant identifier string
//
// ISO Language Codes: http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt
// ISO Country Codes: http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html
//
//
]
<query>{query-string}</query>
</SearchRequest>
limit is an integer specifying the maximum number of results to return. if limt <= 0 or limit > 1000 then it defaults to 30.
offset is an integer specifying the 0-based offset into the results list to return as
the first result for this search operation.
For example, limit=10 offset=30 will return the 31st through 40th results inclusive.
For a response, the order of the returned results represents the sorted order. There
is not a separate index attribute or element.
if fetch="1" (or fetch="first") is specified, the first hit will be expanded inline (messages only at present)
if fetch="{item-id}", only the message with the given {item-id} is expanded inline
if fetch="all", all hits are expanded inline
+ if html="1" is also specified, inlined hits will return HTML parts if available
+ if read="1" is also specified, inlined hits will be marked as read
+ if neuter="0" is also specified, images in inlined HTML parts will not be "neutered"
+ if <header>s are requested, any matching headers are included in inlined message hits
+ if max="{max-inlined-length}" is specified, inlined body content in limited to the given length;
if the part is truncated, truncated="1" is specified on the <mp> in question
if recip="1" is specified
+ returned sent messages will contain the set of "To:" recipients instead of the sender
+ returned conversations whose first hit was sent by the user will contain
that hit's "To:" recipients instead of the conversation's sender list
{group-by} = DEPRECATED. Use TYPES instead.
{types} = comma-separated list. Legal values are:
conversation|message|contact|appointment|task|note|wiki|document
(default is "conversation")
**NOTE: only ONE of message, conversation may be set. If
both are set, the first is used.
{sort-by} = default is "dateDesc"
Valid choices:
dateDesc|dateAsc|subjDesc|subjAsc|nameDesc|nameAsc|none(*)
* - If sort-by is "none" then cursors MUST NOT be
used, and some searches are impossible
(searches that require intersection of complex
sub-ops). Server will throw an
IllegalArgumentException if the search is
invalid.
ADDITIONAL SORT MODES FOR TASKS: valid only if types="task" (and task alone):
taskDueAsc|taskDueDesc|taskStatusAsc|taskStatusDesc|taskPercCompletedAsc|taskPercCompletedDesc
{more-flag} = 1 if there are more search results remaining.
{content-matched} = 1 if the content of the message matched
<mp> elements will be set for the first response if fetch=1
<hp> elements may be present if any attachments matched
{field} = by default, text without an operator searches the CONTENT field. By setting the
{field} value, you can control the default operator. Specify any of the text operators that are
available in query.txt, e.g. 'content:' [the default] or 'subject:', etc. The date operators
(date, after, before) and the "item:" operator should not be specified as default fields
because of quirks in the search grammar.
calExpandInstStart and calExpandInstEnd:
If these are specified, and the search types include calendar item
types (e.g. appointment), then the search results include the
instances for calendar items within that range in the form
described below.
***IMPORTANT NOTE: Calendar Items that have no instances within
that range are COMPLETELY EXCLUDED from the results (e.g. not even
an <appt> element>. Calendar Items with no data (such as Tasks
with no date specified) are included, but with no instance
information***
For the optional <cursor> element:
-- The required parameters are (prevMailItemId, prevSortValue): these
correspond to the last hit on the current page (assuming you're
going forward -- if you're backing up then they should be the first
hit on the current page)....the server uses those parameters to
find the spot in the new results that corresponds to your old
position: even if some entries have been removed or added to the
search results (e.g. if you are searching is:unread and you read
some). The endSortVal paramater tells the cursor where to stop
returning values
-- Cursors are NOT legal if SortBy="none"
conversation result:
--------------------
<SearchResponse sortBy="sort-by" offset="..." more="{more-flag}">
[ <info>
[ <wildcard str="foo*" expanded="1|0"/> ]
</info> ]
<c id="{conv-id}" t="{tags}" n="{num-msgs}" [total="{all-msgs}"] d="{date}" f="{flags} [mbx="UID"] sf="SORT-FIELD-VALUE">
<e ...>*
<su>{subject}</su>
<fr>{fragment}</fr>
[<m id="MATCHED_MSG_ID">]+
</c>*
</SearchResponse>
Info block:
The <info> block is used to return general status
information about your search. The <wildcard> element tells
you about the status of wildcard expansions within your search
-- if expanded=1, then the wildcard was expanded and the
matches are included in the search. If expanded=0 then the
wildcard was not specific enough and therefore no wildcard
matches are included (exact-match *is* included in results).
message result:
---------------
<SearchResponse sortBy="sort-by" offset="..." more="{more-flag}">
[<info>...</info>]
<m id="{message-id}" t="{tags}" f="{flags}" s="{size}" d="{date}" cid="{conv-id}" l="{location}" score="..." [mbx="UID"] sf="SORT-FIELD-VALUE" [cm="1"]>
<e .../>* <!- from only -->
<su>{subject}</su>
<fr>{fragment}</fr>
*(<header n="{header-name}">header content</header>)
[<mp>...</mp>] // if fetch=1, the <mp>'s of the hit (first hit only)
<hp part="{mime-part-name}"/>+ // Hit Part -- indicator that the named part matched the search string
</m>
</SearchResponse>
contact result:
---------------
<SearchResponse offset="..." more="{more-flag}">
[<info>...</info>]
<cn id="id" t="tags" l="folder" sf="SORT-FIELD-VALUE" [email="Email_1 Addr"] [email2="Email_2_addr"]
email3="Email_3_addr" [type="contact|group"] rev="REVISION" fileAsStr="..." md="{metadata-change-date}"/>
type is assumed to be "contact" if not present. If it is present and set to "group", then the contact is a
personal distribution list.
note result:
------------
DOCUMENT ME
appointment result:
-------------------
<appt|task id="appointment_mail_item_id"
t="{tags}" f="{flags}" s="{size}" d="{date}" cid="{conv-id}" // standard hit data
l="{location}" score="..." [mbx="UID"] sf="SORT-FIELD-VALUE" // standard hit data
[fba="F|B|T|U"]
[transp="O|T"]
status="TENT|CONF|CANC"
ptst="NE|TE|AC|DE|DG"
[allDay="1"] // if set, this is an "all day" appointment
[otherAtt="1"] // if set, this appointment has other attendees
[alarm="1"] [recur="1"]
[name="NAME"] [loc="LOCATION"]
invId="default_invite_mail_item_id" compNum="default_invite_component_number"
isOrg="default_am_i_organizer_flag"
[priority="num"]
[percentComplete="num"] // only if a <task>
[dueDate="num"] // only if a <task>
[dur="duration"] // default duration
>
[<or d="friendly name" a="address">] // organizer, if available
[<fr>DEFAULT FRAGMENT</fr>]
Expanded instance data -- only if calExpandInstStart and
calExpandInstEnd are requested in the SearchRequest:
[ <inst
[s="START_SECS_GMT"]
[tzo="ms"] // offset from GMT in milliseconds for start time in the
// time zone of the instance; this is useful because the
// instance time zone may not be the same as the time zone
// of the requesting client; when rendering an all-day
// appointment, the client must shift the appointment by
// the difference between the instance time zone and its
// local time zone to determine the correct date to render
// the all-day block
[ex="1"]
[ridZ="YYYYMMDD[ThhmmssZ]"] // RECURRENCE-ID in "Z" (UTC) timezone, if this is an exception
[ANY CHANGED PARAMETERS]
>
[<f>FRAGMENT IF DIFFERENT FROM DEFAULT</f>]
[<dur DURATION>] // duration this instance if not same as default
[<isOrg>] // isOrg flag if not same as default
[<otherAtt>] // otherAtt flag if not same as default
</inst>
]+
Next alarm trigger time and related info:
[ <alarmData
nextAlarm="time in millis to show the alarm"
alarmInstStart="start time of the meeting instance the alarm is reminding about"
name="meeting subject"
loc="meeting location"
invId="invId" compNum="compNum" // these are used in GetMsg call
>
<alarm .../> // detail of the alarm (repeat policy, text to show, etc.)
// See <alarm> definition in soap-calendar.txt
</alarmData>
]
</appt|task>
-- fba: actual free-busy status: Free, Busy, busy-Tentative, busy-Unavailable (a.k.a. OutOfOffice)
While free-busy status is simply a property of an event that
is set during creation/update, "actual" free-busy status is the true
free-busy state that depends on appt/invite free-busy, event scheduling
status (confirmed vs. tentative vs. cancel), and more importantly, the
attendee's participation status. For example, actual free-busy is
busy-Tentative for an event with Busy free-busy value until the attendee
has acted on the invite.
-- transp: transparency: Opaque, Transparent
-- status: status of event: TENTative, CONFirmed or CANCelled
-- ptst: **your** participation status: NEeds-action, TEntative, ACcept, DEclined, DG (delegated)
-- get the summary of appointments for a specified time period...
-- otherAtt: 1 if there are other attendees to the meeting
-- alarm: 1 if there are some alarms
-- recur: 1 if this is a recurring appointment
-- id is mail_item id of APPOINTMENT object
-- invId is mail_item id of invite message with detailed information
-- comp is component number (invite # within the message)
-- parameters in the apptSum are "defaults" -- are same in instance unless specified
message-part result:
--------------------
<SearchResponse offset="..." more="{more-flag}">
[<info>...</info>]
<mp part="{mime-part-name}" s="{size-in-bytes} mid="{message-id}"
ct="{content-type}" name="{name}" filename="{filename}" score="..."/ sf="SORT-FIELD-VALUE">
</SearchResponse>
-----------
<SearchConvRequest cid="conversation-id" [limit="..."] [offset="..."] [sortBy="{sort-by}"] [types="{types}"] [nest="0|1"]
[fetch="1|hits|all|{item-id}"] [max="{max-inlined-length}"] [html="1"] [read="1"] [neuter="0"]>
*(<header n="{header-name}/>)
<query>{query-string}</query>
</SearchConvRequest>
{conversation-id} = the conversation to search within. REQUIRED.
if fetch="1" (or fetch="first"), the first matching message is expanded inline
if fetch="hits", all matching messages are expanded inline
if fetch="all", all messages are expanded inline
if fetch="{item-id}", only the message with the given {item-id} is expanded inline
SEE SearchRequest for more info
if nest="0" on the request, response looks like this:
<SearchConvResponse sortBy="sort-by" offset="..." more="{more-flag}">
[<info>...</info>]
<m id="{message-id}" [cm="1"] f="{flags}" s="{size}" d="{date}" cid="{conv-id}" score="..." sf="SORT-FIELD-VALUE">
<e .../> <!- from only -->
<su>{subject}</su>
<fr>{fragment}</fr>
*(<header n="{header-name}">header content</header>)
[<mp>...</mp>] // if fetch=1, the <mp>'s of the hit (first hit only)
<hp part="{mime-part-name}"/> // Hit Part -- indicator that the named part matched the search string
</m>*
</SearchConvResponse>
if nest="1" on the request, response looks like this:
<SearchConvResponse sortBy="sort-by" offset="..." more="{more-flag}">
[<info>...</info>]
<c id="{conv-id}" t="{tags}" n="{num-msgs}" [total="{all-msgs}"] f="{flags}">
<m id="{message-id}" [cm="1"] f="{flags}" s="{size}" d="{date}" cid="{conv-id}" score="..." sf="SORT-FIELD-VALUE">
<e .../> <!- from only -->
<su>{subject}</su>
<fr>{fragment}</fr>
[<mp>...</mp>] // if fetch=1, the <mp>'s of the hit (first hit only)
<hp part="{mime-part-name}"/> // Hit Part -- indicator that the named part matched the search string
</m>*
</c>
</SearchConvResponse>
{cm} = 1 if the message matched the specified query string
SEE SearchResponse for more info
------------
<BrowseRequest browseBy="{browse-by}" [regex="{regex-string}"] [maxToReturn="{max}"]/>
<BrowseResponse>
<bd freq="count">{browse-data}</bd>*
</BrowseResponse>
{browse-by} = domains|attachments|objects
{regex-string} = return only those results which match the specified regular expression
{max} = return only a maximum number of entries as requested. If more than {max}
results exist, the server will return the first {max}, sorted by frequency
{browse-data} =
for attachments: content type (application/msword)
for objects: object type (url, etc)
for domains: domains (stanford.edu, etc)
domain <bd> also contains the "h" attribute:
<bd h="{h-flags}">stanford.edu</bd>
which indicates whether or not the domain was from the "From", "To", or "Cc" header.
Valid flags are always one of: "f", "t", "ft", "c", "fc", "tc", "ftc"
----------
<GetItemRequest>
[<item [id="{item-id}"] [path="{path}"] [l="{folder-id}"]/>]
</GetItemRequest>
the caller must specify one of:
- an {item-id},
- a fully-qualified {path}, or
- both a {folder-id} and a relative {path}
<GetItemResponse>
<folder|m|c|cn|wiki|etc. ...>
</GetItemResponse>
a successful GetItemResponse will contain a single element appropriate for the type of the requested item
if there is no matching item, a fault containing the code mail.NO_SUCH_ITEM is returned
----------
<GetFolderRequest [visible="0|1"] [needGranteeName="0|1"]>
[<folder [l="{base-folder-id}"] [path="{fully-qualified-path}"]/>]
</GetFolderRequest>
- either a {base-folder-id} or a {fully-qualified-path} can optionally be specified;
if neither is present, the descent of the folder hierarchy begins at the mailbox's root folder (id 1).
- if "visible" is 1, we include all visible subfolders of the specified folder
when you have full rights on the mailbox, this is indistinguishable from the normal <GetFolderResponse>
when you don't: folders you can see appear normally,
folders you can't see (and can't see any subfolders) are omitted
folders you can't see (but *can* see >=1 subfolder) appear as <folder id="{id}" name="{name}"> hierarchy placeholders
- if *no* folders are visible and visible=1, the response looks like <GetFolderResponse/>
- if "needGranteeName" is 0, grantee names in in forlder grants (the d attribute in <grant>) are omitted.
default for needGranteeName is 1.
<GetFolderResponse>
<folder ...>
<folder .../>
<folder ...>
<folder .../>
</folder>
<folder .../>
</folder>
</GetFolderResponse>
GetFolderResponse always has exactly 1 folder element within it. Without a base
folder ID that folder element will represent the virtual root folder.
----------
<GetConvRequest>
<c id="{conv-id}" [fetch="1|all|{item-id}" max="{max-inlined-length}" html="0|1"]>
*(<header n="{header-name}/>)
</c>
</GetConvRequest>
GetConvRequest gets information about the 1 conversation named by id's value.
It will return exactly 1 conversation element.
if fetch="1|all" is included, the full expanded message structure is inlined
for the first (or for all) messages in the conversation
if fetch="{item-id}", only the message with the given {item-id} is expanded inline
if <header>s are requested, any matching headers are inlined into the response
(not available when raw="1")
<GetConvResponse>
<c id="{conv-id}" [t="{tags}"] n="{num-msgs}" [total="{all-msgs}"] [f="{flags}"]>
<su>{subject}</su>
<m id="{message-id}" [f="{flags}"] s="{size}" d="{date}" [t="{tags}"]>
<e .../>
<fr>{fragment}</fr>
</m>+
</c>
</GetConvResponse>
------------
<GetMsgRequest>
<m id="{msg-id}" [read="1"] [raw="1"] [max="{max-inlined-length}"] [html="1"] [neuter="0"] [part="{part}"]
[ridZ="YYYYMMDD[ThhmmssZ]"]
>
*(<header n="{header-name}/>)
</m>
</GetMsgRequest>
The {msg-id} can contain a subpart identifier (e.g. "775-778") to return
a message stored as a subpart of some other mail-item, specifically for
Messages stored as part of Appointments
read="1" to mark the message as read, "0" to leave the read status unchanged.
(default is 0.)
raw="1" to return the raw message content rather than a parsed mime structure;
(default is "0". if message too big or not ASCII, a content servlet URL is returned)
max="{max-inlined-length}" to limit the length of the text inlined into body <content> when raw="0"
(default is "0", meaning no limit.)
html="1" to return defanged HTML content by default.
(default is 0.)
neuter="1" to "neuter" <IMG> tags returned in HTML content; this involves switching
the "src" attribute to "dfsrc" so that images don't display by default
(default is 1.)
supply a "part" and the retrieved data will be on the specified message/rfc822 subpart.
if the part does not exist or is not a message/rfc822 part, mail.NO_SUCH_PART
ridZ="YYYYMMDD[ThhmmssZ]" is used only when making GetMsg call to open an instance of a recurring appointment.
the value specified is the date/time data of the RECURRENCE-ID of the instance being requested
if <header>s are requested, any matching headers are inlined into the response
(not available when raw="1")
<GetMsgResponse>
<m id="{message-id}" [origid="..." rt="r|w"] [part="{part}"] f="{flags}" t="{tags}" s="{size}" [d="{received-date}"] sd="{date-header}" l="{folder}" (cid="{conv}")
(cif="{X-Zimbra-Calendar-Intended-For header}")
>
<e .../>*
<su>{subject}</su>
<fr>{fragment}</fr>
[<irt>{Message-ID header for message being replied to}</irt>]
<mid>{Message-ID header}</mid>
*(<header n="{header-name}">header content</header>)
[<mp>...</mp>]
[<shr><content>{share-announcement-in-xml}</content</shr>]
[<content (url="...")>...</content>]
</m>
</GetMsgResponse>
origid/rt/irt are present only on drafts
cif is set when the message is a calendar invite that was forwarded by another user, whose calendar is being
managed by this user. The attribute is set to the email of the forwarding user, for whom the invite was
originally intended.
------------
<GetMsgMetadataRequest>
<m ids="{msg-id-list}"/>
</GetMsgMetadataRequest>
<GetMsgMetadataResponse>
(<m id="{message-id}" f="{flags}" t="{tags}" s="{size}" d="{received-date}" l="{folder}" [cid="{conv}"]
rev="{revision-number}" md="{date-metadata-changed}" ms="{change-sequence}"/>)*
</GetMsgMetadataResponse>
------------
<GetNoteRequest>
<note id="{note-id}"/>
</GetNoteRequest>
<GetNoteResponse>
<note id="{note-id}" [t="{tags}"] d="{date}" l="{folder}" [pos="{x,y,width,height}"] color="{color}">
<content>...</content>
</note>
</GetNoteResponse>
---------
<CreateFolderRequest>
<folder name="..." [l="{parent-folder}"] [fie="1"] [view="{default-type}"] [color="{color}"] [f="{flags}"] [url="{url}"] [sync="1"]>
[<acl> <grant perm="{rights}" gt="{grantee-type}" zid="{zimbra-id}" d="{grantee-name}" [pw="{password-for-guest}"] [key="{access-key}"]/>* </acl>]
</folder>
</CreateFolderRequest>
- if l is unset, name is the full path of the new folder; otherwise, name may not contain the folder separator '/'
- if fie="1" is set, the server will fetch the folder if it already exists rather than throwing mail.ALREADY_EXISTS
- if url is set and sync="1" (default), synchronize folder content on folder creation
<CreateFolderResponse>
<folder id="..." name="..." l="{parent-folder}" [u="{unread count}"] [n="{msg count}"]/>
</CreateFolderResponse>
- name and l are omitted on response for root folder
- u and/or n attributes are present on response iff count > 0
---------
<CreateNoteRequest>
<note l="{parent-folder}" (pos="{x,y,width,height}") (color="...")>
<content>...</content>
</note>
</CreateNoteRequest>
<CreateNoteResponse>
<note id="{note-id}" [t="{tags}"] d="{date}" l="{folder}" [pos="{x,y,width,height}"] color="{color}">
<content>...</content>
</note>
</CreateNoteResponse>
---------
<ItemActionRequest>
<!-- action can be preceeded by a "!" to negate it" -->
<action id="{list}" op="delete|read|flag|tag|move|trash|rename|update|color"
[tag="{id}"] [l="{folder}"] [name="{item-name}"] [color="{color}"] [rgb="{rgb-color}"]
[tcon="[-]{constraint}"] [f="{flags}"] [t="{id-list}"]/>
</ItemActionRequest>
<ItemActionResponse>
<action id="{list}" op="delete|read|flag|tag|move|trash|rename|update"/>
</ItemActionResponse>
{list} = on input, list of items to act on, on output, list of
items that were acted on
[-]{constraint} = list of characters; constrains the set of affected items in a conversation
t - include items in the Trash
j - include items in Spam/Junk
s - include items in the user's Sent folder (not necessarily "Sent")
o - include items in any other folder
a leading '-' means to negate the constraint (e.g. "-t" means all messages not in Trash)
For op="update", caller can specify any or all of: l="{folder}", name="{name}", color="{color}",
t="{tag-id-list}", f="{flags}". When modifying tags or flags, all specified tags and flags
are set, and all others are unset.
For op="tag" or op="!tag", caller must specify tag="{id}". This changes the state of
the specified tag without altering other tags.
<action op="color" id="{list}" color="{new-color} rgb="{new-color-in-rgb}"/>
- change the item's color to new color. only one of color or rgb attribute
needs to be present. if both are present rgb value takes precedence.
rgb is specified as CSS style #rrggbb
---------
<MsgActionRequest>
<!-- action can be preceeded by a "!" to negate it" -->
<action id="{list}" op="delete|read|flag|tag|move|update|spam|trash" [tag="{id}"] [l="{folder}"] [f="{flags}"] [t="{tag-id-list}"] [color="{color}"]/>
</MsgActionRequest>
<MsgActionResponse>
<action id="{list}" op="delete|read|flag|tag|move|update|spam|trash"/>
</MsgActionResponse>
{list} = on input, list of messages to act on, on output, list of
messages that were acted on
list may only have 1 element for action "spam"
For op="update", caller can specify any or all of: l="{folder}", name="{name}", color="{color}",
t="{tag-id-list}", f="{flags}".
for op="!spam", can optionally specify a destination folder
See <ItemActionRequest> for more details.
---------
<ConvActionRequest>
<!-- action can be preceeded by a "!" to negate it" -->
<action id="{list}" op="delete|read|flag|tag|move|spam|trash" [tag="{id}"] [l="{folder}"] [tcon="{constraint}"] [tcon="[-]{constraint}"]/>
</ConvActionRequest>
<ConvActionResponse>
<action id="{list}" op="delete|read|flag|tag|move|spam|trash"/>
</ConvActionResponse>
{list} = on input, list of conversations to act on, on output, list of
conversations that were acted on
list may only have 1 element for action "spam"
[-]{constraint} = list of characters; constrains the set of affected items in a conversation
t - include items in the Trash
j - include items in Spam/Junk
s - include items in the user's Sent folder (not necessarily "Sent")
o - include items in any other folder
a leading '-' means to negate the constraint (e.g. "-t" means all messages not in Trash)
for op="!spam", can optionally specify a destination folder
See <ItemActionRequest> for more details.
---------
<FolderActionRequest>
<action id="{list}" op="read|delete|rename|move|trash|empty|color|[!]grant|revokeorphangrants|url|import|sync|fb|[!]check|update|[!]syncon" [l="{target-folder}"]
[name="{new-name}"] [color="{new-color}"] [rgb="{rgb-color}"] [zid="{grantee-zimbra-id}"] [url="{target-url}"]
[excludeFreeBusy="{exclude-free-busy-boolean}">
[<grant perm="..." gt="..." d="..." [pw="..."] [key="..."]/>]
</action>
</FolderActionRequest>
<FolderActionResponse>
<action id="{list}" op="read|delete|empty|rename|move|trash|color|grant|url|import|sync|fb|[!]check|update" [zid="{grantee-zimbra-id}"]/>
</FolderActionResponse>
Actions:
<action op="read" id="{list}"/>
- mark all items in the folder as read
<action op="delete" id="{list}"/>
- hard-delete the folder, all items in the folder, and all the folder's subfolders
<action op="empty" id="{list}" [recusive="{delete-subfolders}"]/>
- hard-delete all items in the folder (and all the folder's subfolders if "recursive" is set)
<action op="rename" id="{list}" name="{new-name}" [l="{new-folder}"]/>
- change the folder's name (and optionally location);
if {new-name} begins with '/', the folder is moved to the new path and any missing path elements are created
<action op="move" id="{list}" l="{new-folder}"/>
- move the folder to be a child of {target-folder}
<action op="trash" id="{list}"/>
- move the folder to the Trash, marking all contents as read and
renaming the folder if a folder by that name is already present in the Trash
<action op="color" id="{list}" color="{new-color} rgb="{new-color-in-rgb}"/>
- see ItemActionRequest
<action op="grant" id="{list}">
<grant perm="..." gt="..." d="..." [pw="..."] [key="..."]/>
</action>
- add the <grant> object to the folder
<action op="!grant" id="{list}" zid="{grantee-zimbra-id}"/>
- revoke access from {grantee-zimbra-id}
(you can use "00000000-0000-0000-0000-000000000000" to revoke acces granted to "all"
or use "99999999-9999-9999-9999-999999999999" to revoke acces granted to "pub" )
<action op="revokeorphangrants" id="{folder-id}" zid="{grantee-zimbra-id}" gt="{grantee-type}"/>
- revoke orphan grants on the folder hierarchy granted to the grantee specified by zid and gt
"orphan grant" is a grant whose grantee object is deleted/non-existing. Server will throw
INVALID_REQUEST if zid points to an existing object,
Only supported if gt is usr|grp|cos|dom; otherwise server will throw INVALID_REQUEST.
<action op="url" id="{list}" url="{target-url}" [excludeFreeBusy="{exclude-free-busy-boolean}"]/>
- set the synchronization url on the folder to {target-url}, empty the folder, and\
synchronize the folder's contents to the remote feed, also sets {exclude-free-busy-boolean}
<action op="sync" id="{list}"/>
- synchronize the folder's contents to the remote feed specified by the folder's {url}
<action op="import" id="{list}" url="{target-url}"/>
- add the contents to the remote feed at {target-url} to the folder [1-time action]
<action op="fb" id="{list}" excludeFreeBusy="{exclude-free-busy-boolean}"/>
- set the excludeFreeBusy boolean for this folder (must specify {exclude-free-busy-boolean})
<action op="[!]check" id="{list}"/>
- set or unset the "checked" state of the folder in the UI
<action op="[!]syncon" id="{list}"/>
- set or unset the "sync" flag of the folder to sync a local folder with a remote source
<action op="update" id="{list}" [f="{new-flags}"] [name="{new-name}"] [l="{target-folder}"] [color="{new-color}"]>
[<acl><grant .../>*</acl>]
</action>
- do several operations at once:
name="{new-name}" to change the folder's name
l="{target-folder}" to change the folder's location
color="{new-color}" to set the folder's color
f="{new-flags}" to change the folder's exclude free/(b)usy, checked (#), and IMAP subscribed (*) state
<acl><grant ...>*</acl> to replace the folder's existing ACL with a new ACL
{list} = on input, list of folders to act on, on output, list of
folders that were acted on;
list may only have 1 element for action "rename" or "empty"
output of "grant" action includes the zimbra id the rights were granted on
note that "delete", "empty", "rename", "move", "color", "update" can be used on search folders as well as standard folders
---------
<NoteActionRequest>
<action id="{list}" op="delete|edit|move|trash|repos|flag|tag|color|update" [tag="{id}"] [l="{target-folder}"] [color="{color}"] [pos="{x,y,width,height}"]/>
</NoteActionRequest>
<NoteActionResponse>
<action id="{list}" op="delete|edit|move|trash|repos|flag|tag|color|update"/>
</NoteActionResponse>
{list} = on input, list of notes to act on, on output, list of
notes that were acted on;
list may only have 1 element for actions "edit", "repos", "color"
for op="update", caller can specify any or all of: l="{folder}", t="{tag-id-list}", f="{flags}", color="{color}", pos="{x,y,width,height}"
See <ItemActionRequest> for more details.
---------
<TagActionRequest>
<action op="read|rename|color|delete|update" id="..." [name="..."] [color="..."]/>
</TagActionRequest>
- if op="update", the caller can specify "name" and/or "color"
<TagActionResponse>
<action op="read|rename|color|delete|update" id="..."/> <!-- iff op was successful -->
</TagActionResponse>
--------------
<GetTagRequest/>
<GetTagResponse>
<tag id="..." name="..." color="..." [u="{unread_count}"]/>+
</GetTagResponse>
u attribute is present iff count > 0
---------
<CreateTagRequest>
<tag name="..." (color="...")/>
</CreateTagRequest>
<CreateTagResponse>
<tag (same as GetTagResponse)/>
</CreateTagResponse>
---------
<GetSearchFolderRequest>
<!-- get all by default -->
</GetSearchFolderRequest>
<GetSearchFolderResponse>
<search id="..." name="..." query="..." [types="..."] [sortBy="..."] l="{folder}"/>+
</GetSearchFolderResponse>
---------
<CreateSearchFolderRequest>
<search name="..." query="..." [types="..."] [sortBy="..."] l="{folder}" [f="{flags}"] [color="{color}"]/>
</CreateSearchFolderRequest>
<CreateSearchFolderResponse>
<search id="..." name="..." query="..." [types="...] [sortBy="..."] l="{folder}"/>
</CreateSearchFolderResponse>
---------
<ModifySearchFolderRequest>
<search id="..." query="..." [types="..."] [sortBy="..."]/>
</ModifySearchFolderRequest>
<ModifySearchFolderResponse>
<search id="..." name="..." query="..." [types="...] [sortBy="..."] l="{folder}"/> <!-- iff it was modified -->
</ModifySearchFolderResponse>
---------
<CreateMountpointRequest>
<link l="{folder}" name="{mountpoint-name}" [view="..."] [color="{color}"] [f="{flags}"] [fie="1"]
[zid="{owner's-zimbra-id}" | owner="{owner's-email-address}"] [rid="{id-of-shared-item}" | path="{path-to-shared-item}"]/>
</CreateMountpointRequest>
- caller must specify one of (zid | owner) and one of (rid | path)
<CreateMountpointResponse>
<link id="{created-link-item-id}" l="{folder}" name="..." [view="..."]/>
</CreateMountpointResponse>
---------
# origid will be present if this is a reply or forward
# TODO: indicate whether to save in SentMail (or some other folder)
+ add="1" on recipient email address means to add to caller's address book (no duplicate checking!)
+ supports (f)rom, (t)o, (c)c, (b)cc, (r)eply-to, (s)ender, read-receipt (n)otification "type" on <e> elements
+ only allowed one top-level <mp> but can nest <mp>s within if multipart/*
+ a leaf <mp> can have inlined content (<mp ct="{content-type}"><content>...</content></mp>)
+ a leaf <mp> can have referenced content (<mp><attach ...></mp>)
+ any <mp> can have a Content-ID header attached to it
+ on reply/forward, set origid on <m> element and set rt to "r" or "w", respectively
+ can optionally set identity-id to specify the identity being used to compose the message
+ if noSave="1", a copy will *not* be saved to sent regardless of account/identity settings
+ can set priority high (!) or low (?) on sent message by specifying "f" attr on <m>
<SendMsgRequest [suid="{send-uid}"] [needCalendarSentByFixup="0|1"] [noSave="0|1"]>
<m [f="!|?"] [origid="..." rt="r|w"] [idnt="{identity-id}"]>
<e t="{type}" a="{email-address}" p="{personal-name}" [add="1"]/>+
<su>{subject}</su>*
[<irt>{Message-ID header for message being replied to}</irt>]
<mp ct="{content-type}" [ci="{content-id}"]>
<content>...</content>
</mp>
<attach [aid="{attach-upload-id}[,{attach-upload-id}]"]>
[<m id="{message-id}" [optional="0|1"]/>]*
[<mp mid="{message-id}" part="{part-id}" [optional="0|1"]/>]*
[<cn id="{contact-id}" [optional="0|1"]/>]*
[<doc (id="{document-id}" | path="{document-path}") [optional="0|1"]/>]*
</attach>
</m>
</SendMsgRequest>
or, if you want to compose the message remotely, upload it via
FileUploadServlet, and submit it through our server:
<SendMsgRequest [suid="{send-uid}"] [needCalendarSentByFixup="0|1"]>
<m aid="{uploaded-MIME-body-ID}" [origid="..." rt="r|w"]/>
</SendMsgRequest>
# If the message is saved to the sent folder then the id of the message is returned.
# Otherwise, no id is returned -- just a <m></m> is returned.
<SendMsgResponse>
<m id="..." />
</SendMsgResponse>
needCalendarSentByFixup - Add SENT-BY parameter to ORGANIZER and/or ATTENDEE
properties in iCalendar part when sending message
on behalf of another user
default is 0
{send-uid} - an optional client-generated unique identifier string for the send
if the SendMsg request is re-sent but the message has not been modified, the client should use
the same {send-uid} and the server will try to check the status of the previous SendMsg attempt
----------------------------
# origid will be present if this is a reply or forward
# Can we have more than one From: address?
# TODO: indicate folder to save in (defaults to Drafts)
+ only allowed one top-level <mp> but can nest <mp>s within if multipart/*
+ on reply/forward, set origid on <m> element and set rt to "r" or "w", respectively
+ can optionally set identity-id to specify the identity being used to compose the message
+ if updating an existing draft, set "id" attr on <m> element
+ can refer to parts of existing draft in <attach> block
+ drafts default to the Drafts folder
+ setting folder/tags/flags/color occurs *after* the draft is created/updated, and if it fails the content *WILL STILL BE SAVED*
<SaveDraftRequest>
<m [id="{existing-draft-id}"] [origid="..." rt="r|w"] [idnt="{identity-id}"] [l="{folder}"] [f="{flags}"] [t="{tag-id-list}"] [color="{color}"]>
<e t="{type}" a="{email-address}" p="{personal-name}"/>+
<su>{subject}</su>*
[<irt>{Message-ID header for message being replied to}</irt>]
<mp ct="{content-type}">
<content>...</content>
</mp>
<attach [aid="{attach-upload-id}"]>
[<m id="{message-id}" [optional="0|1"]/>]*
[<mp mid="{message-id}" part="{part-id}" [optional="0|1"]/>]*
[<cn id="{contact-id}" [optional="0|1"]/>]*
[<doc (id="{document-id}" | path="{document-path}") [optional="0|1"]/>]*
</attach>
</m>
</SaveDraftRequest>
or, if you want to compose the message remotely, upload it via
FileUploadServlet, and submit it through our server:
<SaveDraftRequest>
<m aid="{uploaded-MIME-body-ID}" [id="{existing-draft-id}"] [origid="..." rt="r|w"] [l="{folder}"] [f="{flags}"] [t="{tag-id-list}"] [color="{color}"]/>
</SaveDraftRequest>
# The id of the saved draft is returned
<SaveDraftResponse>
<m id="{message-id}" f="{flags}" t="{tags}" s="{size}" [d="{received-date}"] sd="{date-header}" l="{folder}" (cid="{conv}")>
<e .../>*
<su>{subject}</su>
<irt>{Message-ID header for message being replied to}</irt>
<fr>{fragment}</fr>
<mid>{Message-ID header}</mid>
[<mp>...</mp>]
[<content (url="...")>...</content>]
</m>
</SaveDraftResponse>
----------------------------
<SendDeliveryReportRequest mid="{message-id}"/>
<SendDeliveryReportResponse/>
----------------------------
<AddMsgRequest>
<m l="{folder}" [f="{flags}"] [t="{tags}"] [d="{received-date}"] [aid="{uploaded-MIME-body-ID}"] [noICal="0|1"]>
<content>
...
</content>
[
<inv uid="UID">...</inv> # MUST have UID
]
...
</m>
</AddMsgRequest>
{flags} = (u)nread, (f)lagged, has (a)ttachment, (r)eplied, (s)ent by me, for(w)arded,
(d)raft, deleted (x), (n)otification sent
{tags} = comma-separated list of tag IDs
{folder} = folder pathname (starts with '/') or folder ID
{received-date} = (optional) time the message was originally received, in MILLISECONDS since the epoch
{uploaded-MIME-body-ID} = ID of message uploaded via FileUploadServlet
[noICal] = if TRUE, then don't process iCal attachments. Default is FALSE.
TODO: even if noICal is true, calendar should still link message to existing appointment
(by UID) if the appointment already exists.
Note that the <m> element should include the <content> element with the
entire message's content. (Omit <content> if you specify an "aid" attribute.)
No <mp> elements should be provided within <m>.
# Returns the Message's ID just created
<AddMsgResponse>
<m id="{message-id}" f="{flags}" t="{tags}" s="{size}" d="{received-date}" l="{folder}" [cid="{conv}"]
rev="{revision-number}" md="{date-metadata-changed}" ms="{change-sequence}"/>
</AddMsgResponse>
----------------------------
<RemoveAttachmentsRequest>
<m id="{message-id}" part="{list-of-part-ids-to-remove}">
</RemoveAttachmentsRequest>
{list-of-part-ids-to-remove} = comma-separated list of part IDs to strip from existing message body
# NOTE that this operation is effectively a create and a delete, and thus the message's item ID will change
<RemoveAttachmentsResponse>
<m id="{message-id}" f="{flags}" t="{tags}" s="{size}" d="{received-date}" l="{folder}" [cid="{conv}"]
rev="{revision-number}" md="{date-metadata-changed}" ms="{change-sequence}"/>
</RemoveAttachmentsResponse>
----------------------------
Contacts:
<cn id="{contact-id}" [t="{tags}"] [f="{flags}"] md="{modified-date}" [l="{folder}"] [fileAsStr="{file-as}"]>
<a n="{attr-name}">{attr-data}</a>+
<a n="{attr-name}" aid="{upload-id}"/>*
<a n="{attr-name}" id="{item-id}" [part="{subpart-name}"]/>*
<a n="{attr-name}" part="{part-id}"/>* <-- only valid when modifying an existing contact -->
</cn>
{contact-id} = unique contact id
{flags} = (f)lagged, has (a)ttachment
{modified-date} = secs since epoch, date contact was modified
{file-as} = current "file as" string for display/sorting purposes; *cannot* be used to *set* the file-as value
{attr-name} = name of the attribute (firstName, etc)
{folder-id} = id of folder to create contact in. Un-specified means use the default Contacts folder.
to add attachments, specify an {upload-id} instead of providing {attr-data} on the attr
alternatively, specify an {item-id} to attach, with an optional {subpart-name} for contacts and messages
when editing an existing contact, can omit the {item-id} and we'll assume it's the contact being edited
when contacts are returned, they look like:
<cn id="{contact-id}" t="{tags}" f="{flags}" md="{modified-date}" l="{folder}" fileAsStr="{file-as}">
<a n="{attr-name}">{attr-data}</a>+
<a n="{attr-name}" size="{attach-size}" ctype="{attach-content-type}" filename="{attach-filename}" part="{part-id}"/>*
</cn>
----------
<CreateContactRequest [verbose="0|1"]>
<cn [l="{folder-id}"] [t="{tags}"]>
<a>...</a>+
</cn>
</CreateContactRequest>
or, if you have an existing vCard to add, you can specify a <vcard> element with *one* of
-- inlined content
-- mid/part attributes specifying an existing message part
-- aid attribute specifying an uploaded text/calendar file
<CreateContactRequest [verbose="0|1"]>
<cn [l="{folder-id}"] [t="{tags}"]>
<vcard [mid="{message-id}" part="{part-identifier}] [aid={uploaded-attachment-id"}"]>
[BEGIN:VCARD
...
END:VCARD]
</vcard>
</cn>
</CreateContactRequest>
<CreateContactResponse>
(<cn> definition above)
</CreateContactResponse>
{folder-id} = id of folder to create contact in. Un-specified means use the default Contacts folder.
{tags} = list of tags to apply to the created contact
-- if "verbose='0'" (defaults to '1') was specified on the request, the returned <cn>
is just a placeholder containing the new contact ID (i.e. <cn id="{id}"/>)
----------
<ModifyContactRequest [replace="{replace-mode}"] [verbose="0|1"]>
<cn id="...">
<a>{attr-value}</a>+
</cn>
</ModifyContactRequest>
{attr-value} = new attribute value. If empty (<a/>), then the attribute will be removed.
{replace-mode} = 0|1 (0 is default)
if replace-mode is 1, all attrs in the specified contact are replaced with specified attrs, otherwise
the attrs are merged with the existing contact.
<ModifyContactResponse>
<cn ...>
<a n="...">...</a>
...
</cn>
</ModifyContactResponse>
NOTE: should we return modified attrs in response?
-- if verbose='0' (defaults to '1') was specified on the request, the returned <cn>
is just a placeholder containing the contact ID (i.e. <cn id="{id}"/>)
----------
<GetContactsRequest [sortBy="nameAsc|nameDesc"] [sync="1"] [l="{folder-id}"]>
<a n="..."/>*
<cn id="{contact-id}[,{contact-id}...]"/>*
</GetContactsRequest>
if sync="1" present, return modified date (md) on contacts.
if l="{folder-id}" is present, return only contacts in the specified folder.
if <a n="..."/> present, return only the specified attribute(s).
if <cn id="..."/> present, only get the specified contact(s).
<GetContactsResponse>
<cn [md="{metadata-change-date}"]>...</cn>*
</GetContactsResponse>
----------
<ContactActionRequest>
<!-- some actions can be preceeded by a "!" to negate them -->
<action id="{list}" op="move|delete|flag|trash|tag|update" tag="{id}" l="..."/>
</ContactActionRequest>
<ContactActionResponse>
<action id="{list}" op="move|delete|flag|trash|tag|update"/>
</ContactActionResponse>
{list} = on input, list of contacts to act on, on output, list of
contacts that were acted on
for op="update", caller can specify any or all of: l="{folder}", t="{tag-id-list}", f="{flags}", color="{color}", <a> attribute list:
<action id="{list}" op="update" [l="{folder}"] [t="{tag-id-list}"] [f="{flags}"] [color="{color}"]>
[<a n="fieldName">fieldValue</a>]*
</action>
See <ItemActionRequest> for more details.
----------
<ImportContactsRequest ct="{content-type}" [l="{folder-id}"] [csvfmt="{csv-format}"]>
<content [aid="{attach-upload-id}"]>...</content>
</ImportContactsRequest>
<ImportContactsResponse>
<cn ids="{list-of-created-ids} n="{num-imported}"/>
</ImportContactsResponse>
{content-type} = only currently supported content type is "csv"
{folder-id} = optional folder id to import contacts into
{attach-upload-id} = attachment id from upload server. If specified, then body of content is ignored.
{csv-format} = the format of csv being imported. when it's not defined Zimbra
format is assumed. the supported formats are defined in
$ZIMBRA_HOME/conf/zimbra-contact-fields.xml
TODO: should have an option on import that matches email addresses to existing contacts, and updates/ignores them.
----------
<ExportContactsRequest ct="{content-type}" [l="{folder-id}"] [csvfmt="{csv-format}"]/>
<ExportContactsResponse>
<content>...</content>
</ExportContactsResponse>
{content-type} = currently, the only supported content type is "csv" (comma-separated values)
{folder-id} = optional folder id to export contacts from
{csv-format} = optional csv format for exported contacts. the supported formats
are defined in $ZIMBRA_HOME/conf/zimbra-contact-fields.xml
----------
EXAMPLE:
<SearchRequest>
<query>is:unread</query>
</SearchRequest>
<SearchResponse hits="2" offset="...">
<c id="12344" n="2" d="10023420023" t="1,12" f="1">
<e p="Roland Schemers" a="schemers@example.zimbra.com" d="Roland"/>
<e p="Dan Karp" a="dan@example.zimbra.com" d="Dan"/>
<su>Speaking of animals</su>
<fr>I am still looking for my monkey!</fr>
</c>
<c id="456" n="2" d="10023420023" t="1,12" a="1">
<e p="Roland Schemers" a="schemers@example.zimbra.com" d="Roland"/>
<e p="Ross Dargahi" a="ross@example.zimbra.com" d="Ross"/>
<su>phone numbers</su>
<fr>(650) 123-4567</fr>
</c>
</SearchResponse>
EXAMPLE:
<GetConvRequest>
<c id="12345">
<m id=""9845"/>
</c>
</GetConvRequest>
<GetConvResponse>
<c id="12345" t="1,12" n="2">
<su>Speaking of animals</su>
<m id="123445" f="1" s="1234" d="10002323">
<e p="Dan Karp" a="dan@example.zimbra.com"/>
<fr>This is the fragment</fr>
</m>
<m id="9845" a="1" s="128981" d="10002323">
<e t="f" p="Roland Schemers" a="schemers@example.zimbra.com"/>
<e t="t" p="Dan Karp" a="dan@example.zimbra.com"/>
<fr>This is another frag</fr>
<mp part="" ct="multipart/mixed">
<mp part="1" ct="text/plain" body=1">
<content>This is another frag that is part of a bigger
message. blah blah blah</content>
</mp>
<mp part="2" ct="message/rfc822">
<mp part="2.1" ct="multipart/mixed">
<mp part="2.1.1" ct="text/plain" name="README.txt" cd="attachment" filename="README.txt"/>
<mp part="2.1.2" ct="image/jpeg" name="shot1.jpg" cd="inline" filename="shot1.jpg"/>
</mp>
</mp>
</mp>
</m>
</c>
</GetConvResponse>
EXAMPLE:
<GetMsgRequest>
<m id="9845"/>
</GetMsgRequest>
<GetMsgResponse>
<m id="9845" a="1" s="128981" d="10002323">
<e t="f" id="1" p="Roland Schemers" a="schemers@example.zimbra.com"/>
<e t="t" id="2" p="Dan Karp" a="dan@example.zimbra.com"/>
<su>Speaking of animals</su>
<fr>This is another frag</fr>
<mp part="" ct="multipart/mixed"/>
<mp part="1" ct="text/plain" body="1"/>
<content>This is another frag that is part of a bigger
message. blah blah blah</content>
</mp>
<mp part="2" ct="message/rfc822"/>
<mp part="2.1" ct="multipart/mixed"/>
<mp part="2.1.1" ct="text/plain"/>
<mp part="2.1.2" ct="text/plain" name="README.txt" cd="attachment" filename="README.txt"/>
<mp part="2.1.3" ct="image/jpeg" name="shot1.jpg" cd="inline" filename="shot1.jpg"/>
</mp>
</mp>
</mp>
</m>
</GetMsgResponse>
EXAMPLE:
<mail:BrowseRequest xmlns:mail="urn:zimbraMail">
<query>from:roland</query>
<browseBy>attachments</browseBy>
</mail:BrowseRequest>
<mail:BrowseResponse xmlns:mail="urn:zimbraMail">
<bd>application/pdf</bd>
<bd>application/msword</bd>
<bd>application/vnd.ms-powerpoint</bd>
<bd>image/jpeg</bd>
<bd>application/octet-stream</bd>
<bd>text/plain</bd>
<bd>image/gif</bd>
<bd>message/rfc822</bd>
</mail:BrowseResponse>
-----------------------
<NoOpRequest [wait='1' [delegate='0']] [limitToOneBlocked='1'] [timeout="msecs to wait"]/>
<NoOpResponse [waitDisallowed="1"]/>
A request that does nothing and always returns nothing. Used to keep a session alive, and return
any pending notifications.
If "wait" is set, and if the current session allows them, this request
will block until there are new notifications for the client. Note
that the soap envelope must reference an existing session that has
notifications enabled, and the notification sequencing number should
be specified.
If "wait" is set, the caller can specify whether notifications on
delegate sessions will cause the operation to return. If "delegate"
is 0, delegate mailbox notifications will be ignored. The default is 1.
Some clients (notably browsers) have a global-limit on the number of
outstanding sockets...in situations with two App Instances connected
to one Zimbra Server, the browser app my appear to 'hang' if two app
sessions attempt to do a blocking-NoOp simultaneously. Since the apps
are completely separate in the browser, it is impossible for the apps
to coordinate with each other -- therefore the 'limitToOneBlocked'
setting is exposed by the server. If specified, the server will only
allow a given user to have one single waiting-NoOp on the server at a
time, it will complete (with waitDisallowed='1') any existing
limited hanging NoOpRequests when a new request comes in.
The server may reply with a "waitDisallowed" attribute on response to
a request with wait="1". If "waitDisallowed" is true, then
blocking-NoOpRequests (ie requests with wait="1") are *not* allowed by
the server right now, and the client should stop attempting them.
The client may specifiy a custom timeout-length for their request if
they know something about the particular underlying network. The
server may or may not honor this request (depending on server
configured max/min values: see LocalConfig variables
zimbra_noop_default_timeout, zimbra_noop_min_timeout and
zimbra_noop_max_timeout)
-----------------------
<SetCustomMetadataRequest id="{item-id}">
<meta section="{metadata-section-key}">
(<a n="{key}"> {value} </a>)*
</meta>
</SetCustomMetadataRequest>
<SetCustomMetadataResponse id="{item-id}"/>
-- setting a custom metadata section but providing no key/value pairs
will remove the sction from the item
<GetCustomMetadataRequest id="{item-id}">
<meta section="{metadata-section-key}"/>
</GetCustomMetadataRequest>
<GetCustomMetadataResponse id="{item-id}">
[<meta section="{metadata-section-key}">
(<a n="{key}"> {value} </a>)*
</meta>]
</GetCustomMetadataResponse>
---------------------------
<SetMailboxMetadataRequest>
<meta section="{metadata-section-key}">
(<a n="{key}">{value}</a>)*
</meta>
</SetMailboxMetadataRequest>
<SetMailboxMetadataResponse/>
-- setting a mailbox metadata section but providing no key/value pairs
will remove the section from mailbox metadata
-- {metadata-section-key} must be no more than 36 characters long and must be
in the format of {namespace}:{section-name}. currently the only valid
namespace is "zwc".
<GetMailboxMetadataRequest>
<meta section="{metadata-section-key}"/>
</GetMailboxMetadataRequest>
<GetMailboxMetadataResponse>
<meta section="{metadata-section-key}">
(<a n="{key}">{value}</a>)*
</meta>
</GetMailboxMetadataResponse>
---------------------------
<GetRulesRequest>
<SaveRulesRequest>
These APIs have been replaced with <GetFilterRulesRequest> and <ModifyFilterRulesRequest>,
which offer improved ease of use and error handling. The old APIs will continue
to work in ZCS 6.0, and will be removed in the next major release.
---------------------------
<GetFilterRulesRequest/>
<GetFilterRulesResponse>
<filterRules>
<filterRule name="{rule-name}" [active="{0|1}"]>
<filterTests condition="{allof | anyof"}>
{test}
[test]
...
</filterTests>
<filterActions>
{action}
[action]
...
</filterActions>
</filterRule>
[filter rule]
...
</filterRules>
</GetFilterRulesResponse>
<ModifyFilterRulesRequest>
<filterRules> ... </filterRules>
</ModifyFilterRulesRequest>
<ModifyFilterRulesResponse/>
* Default value for "active" is 1.
Tests:
<headerTest header="{header-name}" stringComparison="{type}" value="{value}" />
<headerExistsTest header="{header-name}" />
<sizeTest numberComparison="{over|under}" s="{size}" />
<dateTest dateComparison="{before|after}" d="{date}" />
<bodyTest value="{value}" />
<attachmentTest />
<addressBookTest header="{header-name}" folderPath="{folder-path}" />
<inviteTest />
Each test has the following optional attributes:
* "negative": specifies a "not" condition for that test
* "index": specifies a guaranteed order for the test elements
Actions:
<actionKeep />
<actionDiscard />
<actionFileInto folderPath="{folder-path}" />
<actionTag tagName="{tag-name}" />
<actionFlag flagName="{flag}" />
<actionRedirect a="{email-address}" />
<actionStop />
Each action has an optional "index" attribute which specifies a guaranteed order
for the action elements.
stringComparison values: is, contains, matches
numberComparison values: over, under
dateComparison values: before, after
size values are in bytes (no suffix), kilobytes (50K), megabytes (50M) or gigabytes (2G)
flag values: flagged, read
date values are in seconds since epoch, and are truncated to the day. Hours, minutes,
and seconds are ignored.
index is an integer, used to maintain the order of filter tests and actions.
---------------------------
<ApplyFilterRulesRequest>
<filterRules>
<filterRule name="{name}"/>+
</filterRules>
[<m ids="{msg-id-list}"/>]
[<query>{query-string}</query>]
</ApplyFilterRulesRequest>
<ApplyFilterRulesResponse>
<m ids="{msg-id-list}"/>
</ApplyFilterRulesResponse>
Applies one or more filter rules to messages specified by a comma-
separated ID list, or returned by a search query. One or the other
can be specified, but not both. Returns the list of ids of
existing messages that were affected.
Note that redirect actions are ignored when applying filter rules
to existing messages.
--------------------------
Synchronization:
*** PLEASE SEE sync.txt FOR SYNC-RELATED DOCUMENTATION ***
---------------------------
<GetSpellDictionariesRequest>
<GetSpellDictionariesResponse>
<dictionary>en_US</dictionary>
...
</GetSpellDictionariesResponse>
Returns the list of dictionaries that can be used for spell
checking.
---------------------------
<CheckSpellingRequest [dictionary="{name}"]>
[text to spell check]
</CheckSpellingRequest>
<CheckSpellingResponse available="0|1">
<misspelled word="chickun" suggestions="chicken,chocking,chucking,Chicky,checking"/>
</CheckSpellingResponse>
Suggested words are listed in decreasing order of their match score.
The "available" attribute specifies whether the server-side spell checking
interface is available or not.
{name} : the optional name of the aspell dictionary that will be used to
check spelling. If not specified, the the dictionary will be either
zimbraPrefSpellDictionary or the account's locale, in that order.
---------------------------
<GetAllLocalesRequest/>
<GetAllLocalesResponse>
<locale id="en_US" name="English (United States)"/>
...
</GetAllLocalesResponse>
Returns all locales defined in the system. This is the same list returned by
java.util.Locale.getAvailableLocales(), sorted by display name (name attribute).
---------------------------
<GetAvailableLocalesRequest/>
<GetAvailableLocalesResponse>
<locale id="{locale-id}" name="{locale-name-in-preferred-locale}"/>
...
</GetAvailableLocalesResponse>
Returns intersection of all translated locales installed on the server and the list specified in zimbraAvailableLocale.
The locale list in the response is sorted by display name (name attribute).
{locale-id} : locale id. e.g. en_US
{locale-name-in-preferred-locale} : locale name in the preferred locale
For example, if the locale is fr_CA and the preferred locale is en_US, name will contain "French (Canada)";
if the locale is en_US and the preferred locale is fr_CA, name will contain "anglais (Etats-Unis)"
The preferred locale is determined with the following precedence:
(1) zimbraPrefLocale of the target account if it is present
(2) Otherwise the locale specified in the Accept-Language http header if it is present
(3) Otherwise the locale returned by Provisioning.getLocale, which uses a predefined fallback
chain to determine the preferable locale.
---------------------------
<TestDataSourceRequest>
<pop3 host="pop.myisp.com" port="110" connectionType="cleartext|ssl"
username="mylogin" password="mypassword" leaveOnServer="true|false"/>
or
<imap host="imap.myisp.com" port="143" connectionType="cleartext|ssl"
username="mylogin" password="mypassword"/>
</TestDataSourceRequest>
or
<TestDataSourceRequest>
<pop3 id="{id}" [host="pop.myisp.com"] [port="110"] [connectionType="cleartext|ssl"]
[username="mylogin"] [password="mypassword"]/>
or
<imap id="{id}" [host="imap.myisp.com"] [port="143"] [connectionType="cleartext|ssl"]
[username="mylogin"] [password="mypassword"]/>
</TestDataSourceRequest>
<TestDataSourceResponse>
<pop3 success="0|1" [error="Error message"]/>
or
<imap success="0|1" [error="Error message"]/>
</TestDataSourceResponse>
Tests the connection to the specified data source. Does not modify
the data source or import data. If the id is specified, uses an existing
data source. Any values specified in the request are used in the test
instead of the saved values.
---------------------------
===================
emailAddress="changed-phoebe@google.com"
useAddressForForwardReply="false"
defaultSignature="95915d7a-1809-4a73-a50f-c465214fae62"
fromDisplay="changed-from-display"
replyToAddress="changed-replay-to-addr@google.com"
replyToDisplay="changed-replyto-display"/>
==================
<CreateDataSourceRequest/>
<pop3 name="My POP3 Account" isEnabled="0|1" host="pop.myisp.com" port="110"
connectionType="cleartext|ssl" username="mylogin" password="mypassword" l="{folder-id}"
leaveOnServer="0|1" [pollingInterval="10m"]
[emailAddress="{email-address}"]
[useAddressForForwardReply="0|1"]
[defaultSignature="{default-signature-id}"]
[fromDisplay="{from-display}"]
[fromAddress="{from-address}"]
[replyToAddress="{replyto-address}"]
[replyToDisplay="{replyto-display}"]/>
or
<imap name="My IMAP Account" isEnabled="0|1" host="imap.myisp.com" port="143"
connectionType="cleartext|ssl" username="mylogin" password="mypassword" l="{folder-id}"
[pollingInterval="10m"]
[emailAddress="{email-address}"]
[useAddressForForwardReply="0|1"]
[defaultSignature="{default-signature-id}"]
[fromDisplay="{from-display}"]
[fromAddress="{from-address}"]
[replyToAddress="{replyto-address}"]
[replyToDisplay="{replyto-display}"]/>
</CreateDataSourceRequest>
<CreateDataSourceResponse>
<pop3 id="{id}"/>
</CreateDataSourceResponse>
Creates a data source that imports mail items into the specified folder via
the POP3 or IMAP protocol. Only one data source is allowed per request.
---------------------------
<GetDataSourcesRequest/>
<GetDataSourcesResponse>
*[<pop3 id="{id}" name="My POP3 Account" isEnabled="0|1" host="pop3.myisp.com" port="110"
username="mylogin" l="{folder-id}" leaveOnServer="0|1" [pollingInterval="10m"]
[emailAddress="{email-address}"]
[useAddressForForwardReply="0|1"]
[defaultSignature="{default-signature-id}"]
[fromDisplay="{from-display}"]
[fromAddress="{from-address}"]
[replyToAddress="{replyto-address}"]
[replyToDisplay="{replyto-display}"]
[failingSince="{timestamp}">]
[<lastError>{error message}</lastError>]
</pop3>]
*[<imap name="My IMAP Account" isEnabled="0|1" host="imap.myisp.com" port="143"
connectionType="cleartext|ssl" username="mylogin" l="{folder-id}" [pollingInterval="10m"]
[emailAddress="{email-address}"]
[useAddressForForwardReply="0|1"]
[defaultSignature="{default-signature-id}"]
[fromDisplay="{from-display}"]
[fromAddress="{from-address}"]
[replyToAddress="{replyto-address}"]
[replyToDisplay="{replyto-display}"]>
[failingSince="{timestamp}">]
[<lastError>{error message}</lastError>]
</imap>]
...
</GetDataSourcesResponse>
Returns all data sources defined for the given mailbox. For each data source,
every attribute value is returned except password.
lastError: the error message from the most recent sync for this data source.
This element is not returned if the last sync was successful.
failingSince: if the most recent sync(s) failed, this attribute specifies
the timestamp of the first failure. This attribute is not returned
if the last sync was successful.
---------------------------
<ModifyDataSourceRequest>
*[<pop3 id="{id}" [name="My POP3 Account"] [isEnabled="0|1"] [host="pop3.myisp.com"]
[port="110"] [connectionType="cleartext|ssl"] [username="mylogin"]
[password="mypassword"] [l="{folder-id}"] [leaveOnServer="0|1"]
[pollingInterval="10m"]
[emailAddress="{email-address}"]
[useAddressForForwardReply="0|1"]
[defaultSignature="{default-signature-id}"]
[fromDisplay="{from-display}"]
[fromAddress="{from-address}"]
[replyToAddress="{replyto-address}"]
[replyToDisplay="{replyto-display}"]/>
*[<imap name="My IMAP Account" isEnabled="0|1" host="imap.myisp.com" port="143"
connectionType="cleartext|ssl" username="mylogin" password="mypassword" l="{folder-id}"
[pollingInterval="10m"]
[emailAddress="{email-address}"]
[useAddressForForwardReply="0|1"]
[defaultSignature="{default-signature-id}"]
[fromDisplay="{from-display}"]
[fromAddress="{from-address}"]
[replyToAddress="{replyto-address}"]
[replyToDisplay="{replyto-display}"]/>
</ModifyDataSourceRequest>
<ModifyDataSourceResponse/>
Changes attributes of the given data source. Only the attributes specified in the request
are modified. If the username, host or leaveOnServer settings are modified, the server
wipes out saved state for this data source. As a result, any previously downloaded
messages that are still stored on the remote server will be downloaded again.
---------------------------
<DeleteDataSourceRequest>
*[<dsrc [id="{data-source-id}" | name="{data-source-name}"]/>]
*[<pop3 [id="{data-source-id}" | name="{data-source-name}"]/>]
*[<imap [id="{data-source-id}" | name="{data-source-name}"]/>]
...
</DeleteDataSourceRequest>
<DeleteDataSourceResponse/>
Deletes the given data sources. The name or id of each data source must
be specified.
---------------------------
<ImportDataRequest>
*[<dsrc id="{id}"/>]
*[<pop3 id="{id}"/>]
*[<imap id="{id}"/>]
...
</ImportDataRequest>
<ImportDataResponse/>
Triggers the specified data sources to kick off their import processes. Data import runs
asynchronously, so the response immediately returns. Status of an import can be queried
via the <GetImportStatusRequest> message. If the server receives an
<ImportDataRequest> while an import is already running for a given data source,
the second request is ignored.
---------------------------
<GetImportStatusRequest/>
<GetImportStatusResponse>
*[<pop3 id="{id}" isRunning="0|1" [success="0|1"] [error="Error message"]/>]
*[<imap id="{id}" isRunning="0|1" [success="0|1"] [error="Error message"]/>]
...
</GetImportStatusResponse>
Returns current status for all data sources. Status values for a data source are
reinitialized when either (a) another import process is started or (b) when the
server is restarted. If import has not run yet, the success and error attributes
are not specified.
isRunning: Whether data is currently being imported from this data source.
success: Whether the last import completed successfully.
error: If the last import failed, the error message that was returned.
---------------------------
WaitSet: scalable mechanism for listening for changes to one or more accounts
<CreateWaitSetRequest>
<CreateWaitSetResponse>
<WaitSetRequest>
<WaitSetResponse>
<DestroyWaitSet>
<DestroyWaitSetResponse>
***See soap-waitset.txt for WaitSet API documentation***
---------------------------
Get account level permissions.
<GetPermissionRequest>
<!-- get only the permissions for the specified rights -->
[<ace right="{right1}"/>
<ace right="{right2}"/>]
</GetPermissionRequest>
If no <ace> elements are provided, all ACEs are returned in the response.
If <ace> elements are provided, only those ACEs with specified rights are returned in the response.
<GetPermissionResponse>
<ace right="{right}" [deny="{deny}"] gt="{grantee-type}" zid="{zimbra-id}" [d="{grantee-name}"] [pw="{password}"] [key="{accesskey}"]/>*
</GetPermissionResponse>
{right} = viewFreeBusy | invite
{deny} = 1 | 0(default)
if a right is specifically denied
{grantee-type} = the type of grantee:
usr - Zimbra user
grp - Zimbra group(distribution list)
all - all authenticated users
gst - non-Zimbra email address and password (not yet supported)
key - external user with an accesskey
pub - public authenticated and unauthenticated access
{zimbra-id} = zimbraId of the grantee
{grantee-name} = display name of the grantee.
ot present if {grantee-type} is "all" or "pub"
{pw} = optional arguments. password when {grantee-type} is "gst" (not yet supported)
{key} = optional arguments. access key when {grantee-type} is "key"
---------------------------
Grant account level permissions.
<GrantPermissionRequest>
<ace right="{right}" [deny="{deny}"] gt="{grantee-type}" [zid="{zimbra-id}"] [d="{grantee-name}"] [pw="{password}"] [key="{accesskey}"]/>+
</GrantPermissionRequest>
If gt is:
usr - either zid or d is required.
grp - either zid or d is required.
all - zid, d, pw are ignored
gst - zid is ignored, d is required, pw is optional (not yet supported)
key - zid is ignored, d is required
pub - zid, d, pw are ignored
For usr and grp:
- if zid is provided, server will lookup the entry by zid and grantee type, and d is ignored.
- if zid is not provided and d is provided, server will lookup the grantee by name and grantee type.
if the lookup failed, NO_SUCH_ACCOUNT/NO_SUCH_DISTRIBUTION_LIST will be thrown.
If gt == key:
- if key is given, server will use that as the access key for this grant
- if key is not given, server will generate an access key
GrantPermissionResponse returns permissions that are successfully granted.
<GrantPermissionResponse>
<ace right="{right}" [deny="{deny}"] gt="{grantee-type}" zid="{zimbra-id}" [d="{grantee-name}"] [pw="{password}"] [key="{accesskey}"]/>*
</GrantPermissionRequest>
---------------------------
Revoke account level permissions.
<RevokePermissionRequest>
<ace right="{right}" [deny="{deny}"] gt="{grantee-type}" [zid="{zimbra-id}"] [d="{grantee-name}"]/>*
</RevokePermissionRequest>
Same notes as those for GrantPermissionRequest about identifying the grantee.
RevokePermissionResponse returns permissions that are successfully revoked.
<RevokePermissionResponse>
<ace right="{right}" [deny="{deny}"] gt="{grantee-type}" zid="{zimbra-id}" [d="{grantee-name}"] [pw="{password}"] [key="{accesskey}"]/>*
</RevokePermissionResponse>
---------------------------
<CheckPermissionRequest>
<target type="{target-type}" by="id|name">...</target>
<right>...</right>+
</CheckPermissionRequest>
{target-type} = account | calresource
Check if the authed user has the specified right(s) on a target.
If the specified target cannot be found:
- if by is "id", throw NO_SUCH_ACCOUNT/NO_SUCH_CALENDAR_RESOURCE
- if by is "name", return the default permission for the right.
e.g.
With user1's auth token, the following checks if user1 can invite user2 and
view user2's free/busy.
<CheckPermissionRequest>
<target type="account" by="name">user2@test.com</target>
<right>invite</right>
<right>viewFreeBusy</right>
</CheckPermissionRequest>
<CheckPermissionResponse allow="{1|0}">
<right allow="{1|0}">invite</right>
<right allow="{1|0}">viewFreeBusy</right>
</CheckPermissionResponse>
allow = 1 | 0
1: the authed user has the right on the target
0: the authed user does not have the right on the target
In CheckPermissionResponse, it is the AND result of each individual result
In each <right> element, it is the result for that right.
---------------------------
<GetVersionInfoRequest/>
<GetVersionInfoResponse>
<info version="{version-string}" release="{release-string}" buildDate="{YYYYMMDD-hhmm}" buildHost="{host-name}"/>
</GetVersionInfoResponse>
This request will return a SOAP fault if the zimbraSoapExposeVersion
server/globalconfig attribute is set to FALSE.
---------------------------
<GetWhiteBlackListRequest/>
<GetWhiteBlackListResponse>
<whiteList>
<addr>...</addr>+
</whiteList>
<blackList>
<addr>...</addr>+
</blackList>
</GetWhiteBlackListResponse>
----------------------------
<ModifyWhiteBlackListRequest>
[<whiteList>
<addr [op="{op}"]>...</addr>+
</whiteList>]
[<blackList>
<addr [op="{op}"]>...</addr>+
</blackList>]
</ModifyWhiteBlackListRequest>
Note:
If no <addr> is present in a list, it means to remove all addresses
in the list.
e.g. remove all addresses in the white list
<ModifyWhiteBlackListRequest>
<whiteList/>
</ModifyWhiteBlackListRequest>
{op} = + | -
+ : add, ignored if the value already exists
- : remove, ignored if the value does not exist
if not present, replace the entire list with provided values.
Note, can't mix +/- with non-present op)
e.g.
1. replace the entire white list with "foo", "bar".
<whiteList>
<addr>foo</addr>
<addr>bar</addr>
</whiteList>
2. add values "foo" and "bar" to white list
<whiteList>
<addr op="+">foo</addr>
<addr op="+">bar</addr>
</whiteList>
3. remove values "foo" and "bar" from white list
<whiteList>
<addr op="-">foo</addr>
<addr op="-">bar</addr>
</whiteList>
4. add "foo" and remove 'bar"
<whiteList>
<addr op="+">foo</addr>
<addr op="-">bar</addr>
</whiteList>
5. mix +/- and non-present op - now allowed, INVALID_REQUEST will be thrown
<whiteList>
<addr op="+">foo</addr>
<addr>bar</addr>
</whiteList>
<ModifyWhiteBlackListResponse/>
----------------------------
<GetShareInfoRequest>
[<grantee type="{grantee_type}" [id="{grantee-id}"] [name="{grantee-name}"]/>]
[<owner by="{owner-by}">...</owner>]
</GetShareInfoRequest>
{grantee_type} = if <owner> is not specified: grp
if <owner> is specified: usr | grp | pub | all | cos | dom | guest | key
Filters the result by the specified grantee type, only shares granted to
the grantee type will be returned. If omitted, server will return shares
granted to all grantee types.
{grantee-id} = if specified, filters the result by the specified grantee id.
{grantee-name} = if specified, filters the result by the specified grantee name.
Notes on {grantee_type}, {grantee-id}, {grantee-name}:
- it's recommended that only one of {grantee_type}, {grantee-id}, {grantee-name} is specified.
- if multiple are specified and they conflict, e.g. {grantee-type} is grp but
{grantee-id} contains an account id, obviously no result will be returned because
no grant will be matching that condition.
{owner-by} = name | id
Note: In order to defend against harvest attacks this SOAP call will
return "no shares" instead of error when an invalid user name/id is used.
Notes:
- if <owner> is *not* specified, server will retrieve previously published (can only be done
by admins) share info from entries the authed account can inherit shares from.
e.g. all direct and indirect distribution lists the account belongs. Currently share info
can only be published on distribution lists. Publishing of cos/domain/all/pub shares
are not supported. Therefore those shares cannot be discovered if we go this route.
- if <owner> *is* specified, server will iterate through the owner's mailbox to discover all
shares applicable to the authed user, instead of looking at any of the published share info.
All applicable shares will be returned, including any shares that are:
- shared with the account directly
- shared with any group(and parent groups) the account belongs. (*is* supported)
- shared with the cos assigned to the account. (*is* supported)
- shared with the domain this account is in. (*is* supported)
- shared with all authed users (i.e. all Zimbra users) (*is* supported)
- shared with the public (*is* supported)
e.g.
1. What folders are shared with any of the groups I belong to?
1a. folders of any user
<GetShareInfoRequest>
<grantee type="grp">
</GetShareInfoRequest>
1b. folders of a particular user
<GetShareInfoRequest>
<grantee type="grp">
<owner by="name">user1@example.com</owner>
</GetShareInfoRequest>
2. What folders does a particular user share with me?
2a. include all folders directly shared with me and shared
with an entry I can inherit shares from:
<GetShareInfoRequest>
<owner by="name">user1@example.com</owner>
</GetShareInfoRequest>
2b. include only folders directly shared with me.
<GetShareInfoRequest>
<grantee type="usr">
<owner by="name">user1@example.com</owner>
</GetShareInfoRequest>
3. Show me all folders shared directly with me by any one.
Not yet supported.
<GetShareInfoResponse>
[<share ownerId="{owner-id}" ownerEmail={owner-email} [ownerName="{owner-display-name}"]
folderId="{folder-id}" folderPath="{fully-qualified-path}"
view="{default-type}" [mid="{mountpoint-id}"] rights="{rights}"
granteeType="{grantee-type}" granteeId="{grantee-id}" granteeName="{grantee-name}" [granteeDisplayName="{grantee-display-name}">]]+
</GetShareInfoResponse>
mid="{mountpoint-id}" : returned if the share is already mounted.
contains the folder id of the mountpoint in the local mailbox.
----------------------------
<SendShareNotificationRequest>
<share [l="{folder-id}"] [path="{fully-qualified-path}"]
gt="{grantee-type}" [zid="{grantee-id}"] [d="{grantee-display-name}"]/>
[<notes>{notes}</notes>]
</SendShareNotificationRequest>
granteeType = usr | grp | guest
- either a l or a path must be specified
- if gt is usr or grp, either a zid or d must be specified.
if gt is guest, d must be specified, zid is ignored.
<SendShareNotificationResponse/>
----------------------------
<GetEffectivePermsRequest>
<folder l="{folder-id}"/>]
</GetEffectivePermsRequest>
returns the effective permissions of the specified folder
<GetEffectiveFolderPermsResponse>
<folder perm="{permissions}"/>
</GetEffectiveFolderPermsResponse>
@be1
Copy link

be1 commented Sep 2, 2010

This file helped me out a lot :-)
I am forking ti to add JSON examples.
Thanks a lot!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment