emailexchangews
Interface BAAEmailExchange

public interface BAAEmailExchange

Email web service that contains APIs for the Microsoft Exchange mail platform.

Method Summary

AddMailStoreUserFromCompanyDirectoryResult	addMailStoreUserFromCompanyDirectory(java.lang.String smtpAddress) adds a given SMTP address to the mail store database from the company directory
ClearEmailUserStatsResult	clearEmailUserStats(int userId) Clears email statistics for a user
EnableUserMailRedirectionResult	enableUserMailRedirection(int userId, boolean enableMailRedirection) Enables or disables the mail redirection for a specific user.
EnableUsersMailRedirectionResult	enableUsersMailRedirection(java.util.List<java.lang.Integer> userIds, boolean enableMailRedirection) Enables or disables the mail redirection for a specific list of users.
FindMailStoreUsersResult	findMailStoreUsers(MailStoreUserSearchCriteria searchCriteria, MailStoreUserSearchResultSortByEnum sortByCriteria, boolean sortByAscendingOrder, java.lang.String criteriaAndResultSetLocale, MailStoreUserSearchResult pageCriteria, int pageSize) Finds users from a mailstore.
FindPersonalRedirectionFolderInformationResult	findPersonalRedirectionFolderInformation(int userId) Returns the user's folder redirection settings.
GatherEnableBlackBerryUserAttributesResult	gatherEnableBlackBerryUserAttributes(MailStoreUserSearchResult result, java.lang.String locale) Returns EnableBlackBerryUserAttributesType from a MailStoreUserSearchResult.
SetPersonalRedirectionFolderInformationResult	setPersonalRedirectionFolderInformation(int userId, PersonalRedirectionFolderInformation newPersonalRedirectionFolderInformation) Sets the user's folder redirection settings.
SynchronizeCalendarResult	synchronizeCalendar(int deviceId) Force synchronizes the calendar for a device
java.lang.String	test(java.lang.String input)

Method Detail

findMailStoreUsers

FindMailStoreUsersResult findMailStoreUsers(MailStoreUserSearchCriteria searchCriteria,
                                            MailStoreUserSearchResultSortByEnum sortByCriteria,
                                            boolean sortByAscendingOrder,
                                            java.lang.String criteriaAndResultSetLocale,
                                            MailStoreUserSearchResult pageCriteria,
                                            int pageSize)

Finds users from a mailstore. The users returned by this api are used to create BlackBerry enabled users.

Parameters:

searchCriteria - the search criteria used to find mailstore users

sortByCriteria - results are sorted by this criteria

sortByAscendingOrder - results are sorted in ascending order if true, descending otherwise

criteriaAndResultSetLocale - locale of the specified searchCriteria, the search result will also be in this locale

pageCriteria - the last element of the previous page. Use this to retrieve next page. Set to null if retrieving first page

pageSize - number of results to return on a single page

Returns:

mailstore users matching the specified search criteria

Since:

5.0.0

Sample:

Java CXF

//create search criteria
MailStoreUserSearchCriteria criteria=new MailStoreUserSearchCriteria();
 
//search by DisplayName
criteria.setDisplayName("user1");
 
//search for users not on a BES already
criteria.setIsNewUserOnly(true);
 
//The type refers to MS Addresses table type column value.
//0 - All mailstore entries.
//6 - User is mail-enabled.
//7 - User is non-mail-enabled (e.g. contact).
//8 - Distribution list.
//Use type 6 here
criteria.setType(6);
 
//create sort by enum
MailStoreUserSearchResultSortByEnum sortByEnum=new MailStoreUserSearchResultSortByEnum();
sortByEnum.setEnum(MailStoreUserSearchResultSortByEnumType.DISPLAY_NAME);
 
int iPageSize=100;
String locale="en_US";
 
FindMailStoreUsersResult result=emailExchangeWebService.findMailStoreUsers(criteria, sortByEnum, true, locale, null, iPageSize);
 
//loop through pages
while (result.getFindMailStoreUsersReturnStatus().getCode() == FindMailStoreUsersReturnStatusEnumType.SUCCESS && result.getMailStoreUserSearchResult()!=null && result.getMailStoreUserSearchResult().size()>0) {
    for (MailStoreUserSearchResult itr: result.getMailStoreUserSearchResult()) {
       System.out.println(itr.getEmailAddress());
    }
    result=emailExchangeWebService.findMailStoreUsers(criteria, sortByEnum, true, locale, result.getMailStoreUserSearchResult().get(result.getMailStoreUserSearchResult().size()-1), iPageSize);
}
 
if (result.getFindMailStoreUsersReturnStatus().getCode() != FindMailStoreUsersReturnStatusEnumType.SUCCESS) {
   System.out.println("Error occured: " + result.getFindMailStoreUsersReturnStatus().getMessage());
}

                   

setPersonalRedirectionFolderInformation

SetPersonalRedirectionFolderInformationResult setPersonalRedirectionFolderInformation(int userId,
                                                                                      PersonalRedirectionFolderInformation newPersonalRedirectionFolderInformation)

Sets the user's folder redirection settings.

Parameters:

userId - the id of the user to retrieve the settings for

newPersonalRedirectionFolderInformation - the new folder redirection settings

Returns:

the status of the API call

Since:

5.0.0

Sample:

Java CXF

FindPersonalRedirectionFolderInformationResult result =
        emailExchangeWSStub.findPersonalRedirectionFolderInformation( userId );
if( result.getFindPersonalRedirectionFolderInformationReturnStatus().getCode() 
                          != FindPersonalRedirectionFolderInformationStatusEnumType.SUCCESS ) {
    System.out.println( "Error occured: " 
                                  + result.getFindPersonalRedirectionFolderInformationReturnStatus().getMessage() );
}

//change the redirection type
PersonalRedirectionFolderInformation redirectionInformation = result.getPersonalRedirectionFolderInformation();
redirectionInformation.setRedirectionType(
            PersonalRedirectionFolderInformationTypeEnumType.INBOX_AND_SENT_ITEMS_ONLY );

//save the changes
SetPersonalRedirectionFolderInformationResult result =
            emailExchangeWSStub.setPersonalRedirectionFolderInformation( userId, redirectionInformation );
if( result.getSetPersonalRedirectionFolderInformationReturnStatus().getCode() 
           != SetPersonalRedirectionFolderInformationStatusEnumType.SUCCESS ) {
    System.out.println( "Error occured: " 
           + result.getSetPersonalRedirectionFolderInformationReturnStatus().getMessage() );
       }
                   

Permissions Required:

Current user OR User and device -> Edit a user

gatherEnableBlackBerryUserAttributes

GatherEnableBlackBerryUserAttributesResult gatherEnableBlackBerryUserAttributes(MailStoreUserSearchResult result,
                                                                                java.lang.String locale)

Returns EnableBlackBerryUserAttributesType from a MailStoreUserSearchResult. This is an useful API to use for the client to construct EnableBlackBerryUserAttributes, which is needed to create BlackBerry enabled users.

Parameters:

result - this is the MailStoreUserSearchResult object from the findMailStoreUsers API call.

locale - the locale of the data

Returns:

the user id of the newly created user

Since:

5.0.0

Sample:

Java CXF

String locale="en_US";
GatherEnableBlackBerryUserAttributesResult attributes=emailExchangeWebService.gatherEnableBlackBerryUserAttributes(mailStoreUserSearchResult, locale);
                   

Permissions Required:

Current user OR User and device -> View a user

enableUserMailRedirection

EnableUserMailRedirectionResult enableUserMailRedirection(int userId,
                                                          boolean enableMailRedirection)

Enables or disables the mail redirection for a specific user.

Parameters:

userId - the user id of the user to enable or disable the mail redirection for

enableMailRedirection - true to enable mail redirection, or false to disable it

Returns:

the status of the API call

Since:

5.0.0

Sample:

Java CXF

//call enableUserMailRedirection
EnableUserMailRedirectionResult result =
             emailExchangeWSStub.enableUserMailRedirection( userId, false );
if( result.getEnableUserMailRedirectionReturnStatus().getCode() 
            != EnableUserMailRedirectionReturnStatusEnumType.SUCCESS ) {
    System.out.println( "Error occured: " 
            + result.getEnableUserMailRedirectionReturnStatus().getMessage() );
    return;
}

System.out.println( "Mail redirection for user id " + userId +
        " had been disabled." );

                   

Permissions Required:

Current user OR User and device -> Turn on redirection AND User and device -> Turn off redirection

clearEmailUserStats

ClearEmailUserStatsResult clearEmailUserStats(int userId)

Clears email statistics for a user

Parameters:

userId - the id of the user to clear email stats for

Since:

5.0.1

Sample:

Java CXF

ClearEmailUserStatsResult clearEmailUserStatsResult = emailExchangeWebService.clearEmailUserStats(userId);
if( clearEmailUserStatsResult.getClearEmailUserStatsReturnStatus().getCode() != ClearEmailUserStatsReturnStatusEnumType.SUCCESS ) {
       System.out.println( "Error occured while clearing email stats for user: " + clearEmailUserStatsResult.getClearEmailUserStatsReturnStatus().getMessage() );
}
else {
       System.out.println( "User email stats cleared: id=" + userId );
}

                   

Permissions Required:

Current user OR User and device -> Clear user statistics

addMailStoreUserFromCompanyDirectory

AddMailStoreUserFromCompanyDirectoryResult addMailStoreUserFromCompanyDirectory(java.lang.String smtpAddress)

adds a given SMTP address to the mail store database from the company directory

Parameters:

smtpAddress - the SMTP address

Returns:

the status of the method call

Since:

5.0.2

Sample:

Java CXF

String SMTPAddress="clyde.warren@test.rim.net";
AddMailStoreUserFromCompanyDirectoryResult result= emailExchangeWebService.addMailStoreUserFromCompanyDirectory(SMTPAddress);
 
if (result.getAddMailStoreUserFromCompanyDirectoryReturnStatus().getCode() != AddMailStoreUserFromCompanyDirectoryReturnStatusEnumType.SUCCESS) {
       System.out.println("Error occured: " + result.getAddMailStoreUserFromCompanyDirectoryReturnStatus().getMessage());
}

                   

Permissions Required:

User and device -> Refresh available user list from company directory

enableUsersMailRedirection

EnableUsersMailRedirectionResult enableUsersMailRedirection(java.util.List<java.lang.Integer> userIds,
                                                            boolean enableMailRedirection)

Enables or disables the mail redirection for a specific list of users.

Parameters:

userIds - the user ids of the users to enable or disable the mail redirection for

enableMailRedirection - true to enable mail redirection, or false to disable it

Returns:

the status of the API call

Since:

5.0.0

Sample:

Java CXF

//call enableUsersMailRedirection
EnableUsersMailRedirectionResult result =
             emailExchangeWSStub.enableUsersMailRedirection( userIds, false );
if( result.getEnableUserMailRedirectionReturnStatus().getCode() 
            != EnableUserMailRedirectionReturnStatusEnumType.SUCCESS ) {
    System.out.println( "Error occured: " 
            + result.getEnableUserMailRedirectionReturnStatus().getMessage() );
    int numberOfUserIds = userIds.size();
    List<EnableUsersMailRedirectionReturnResult> resultList = result.getEnableUsersMailRedirectionReturnResult();
    if( resultList.size() < numberOfUserIds ) {
        System.out.println( "The number of results returned does not match the number of user ids given.");
        return;
    }
    EnableUsersMailRedirectionReturnResult itr;
    for( int count = 0; count < numberOfUserIds; count++ ) {
        itr = resultList.get( count );
        if( itr.getEnableUserMailRedirectionReturnStatus().getCode()
                != EnableUserMailRedirectionReturnStatusEnumType.SUCCESS ) {
            System.out.println( "Error occured for user id "
                    + userIds.get( count )
                    + ": " + itr.getEnableUserMailRedirectionReturnStatus().getMessage() );
        }
    }
    return;
}
System.out.println( "Mail redirections for user ids " + userIds.toString() +
        " have been disabled." );

                   

Permissions Required:

Current user OR User and device -> Turn on redirection AND User and device -> Turn off redirection

synchronizeCalendar

SynchronizeCalendarResult synchronizeCalendar(int deviceId)

Force synchronizes the calendar for a device

Parameters:

deviceId - the device id to synchronize the calendar for

Since:

5.0.2

Sample:

Java CXF

SynchronizeCalendarResult synchronizeCalendarResult = emailDominoWebService.synchronizeCalendar(deviceId);;
if( synchronizeCalendarResult.getSynchronizeCalendarReturnStatus().getCode() != SynchronizeCalendarReturnStatusEnumType.SUCCESS ) {
       System.out.println( "Error occured while synchronizing calendar for deviceId " + deviceId + ": " + synchronizeCalendarResult.getSynchronizeCalendarReturnStatus().getMessage() );
}
else {
       System.out.println( "A calendar synchronization has been queued: deviceId=" + deviceId );
}

                   

Permissions Required:

Device owner OR Organizations -> Edit a device across organizations OR User and device -> Edit a device

test

java.lang.String test(java.lang.String input)

findPersonalRedirectionFolderInformation

FindPersonalRedirectionFolderInformationResult findPersonalRedirectionFolderInformation(int userId)

Returns the user's folder redirection settings.

Parameters:

userId - the id of the user to retrieve the settings for

Returns:

the folder redirection settings for the specified user

Since:

5.0.0

Sample:

Java CXF

FindPersonalRedirectionFolderInformationResult result =
        emailExchangeWSStub.findPersonalRedirectionFolderInformation( userId );
if( result.getFindPersonalRedirectionFolderInformationReturnStatus().getCode() 
                          != FindPersonalRedirectionFolderInformationStatusEnumType.SUCCESS ) {
    System.out.println( "Error occured: " 
                                  + result.getFindPersonalRedirectionFolderInformationReturnStatus().getMessage() );
}

System.out.println( "Redirection type for user id " + userId + " is: " +
        result.getPersonalRedirectionFolderInformation().getRedirectionType().name() );

                   

Permissions Required:

Current user OR User and device -> View a user