Super-ExMerge On-line Documentation

⌘K
  2. Home
  4. Docs
  6. Super-ExMerge On-line Doc...
  8. PowerShell Cmdlet Referen...
  10. Test-MapiConnection

Test-MapiConnection

Use this cmdlet to test the mapi connection to an Exchange or Office 365 mailbox, archive mailbox, or public folder system. This can be useful to ensure that connection info to be used with New-ConnectionInfo is valid before creating a new sync task.

Test-MapiConnection

  • -ConnectionType
  • -SMTP
  • -AutoDiscoverServer
  • -Creds
  • [-TimeOutAfterSeconds]

Description

Jump To:

Use the Test-MapiConnection to validate that the connection info provided will succeed. This test ensures that connection info to be used with a new sync task is working now, versus adding to the new task and having to check log files later for success.

The cmdlet operates by launching a background process (MapiConnectionTester32.exe or MapiConnectionTester64.exe) that will perform the connection test. The testing application will attempt to create a MAPI profile, if needed, logon to the specified store, and attempt to open the root folder of the store.

Note that much like the Super-ExMerge service, the test program will attempt to authenticate using the credentials provided. Those credentials need to have appropriate permissions to open the store.

Examples

Jump To:
Example 1
  Test-MapiConnection -ConnectionType Mailbox -SMTP joe@source.com -AutoDiscoverServer autodiscover.source.com -Creds 'joe@source.com:HostKey#28v8b7nkuhb87vkbhbiuhf09==
Waiting for the test app to start...
Test app has started...waiting for results...
Starting AutoDiscover lookup for joe@source.com on server autodiscover.source.com
AutoDiscoverXML returned and is 7,295 bytes.
MailServer (EXHTTP): exch01.source.com
    MapiHTTP: False
    Email Addr: joe@source.com
    DeploymentID: 28a9f37b-f3a1-4dac-b895-6c0098e1ffa9
Checking for existing profile with name: MapiConnectionTester32-joe@source.com-DC11FE76
Attempting to add the mailbox to the profile...
Profile created/selected with name: MapiConnectionTester32-joe@source.com-DC11FE76
Logon to mapi session successful.
Open of mapi store completed succesfully.
Open of root folder of mapi store completed successfully.
Connection test successful

This example connects to the mailbox identified by joe@source.com using credentials that provide owner access to the mailbox.


Parameters

Jump To:

-ConnectionType

The ConnectionType parameter specifies the type of Exchange store for which the testing program should attempt to connect.
The following types are currently available for testing:

Mailbox:
Connect to the mailbox store identified by the -SMTP parameter.

ArchiveMailbox:
Connect to the Exchange online archive for the mailbox identified by the -SMTP parameter, if one exists. If there is no archive mailbox an error is thrown stating such.

PublicFolders:
Connect to the Exchange Public Folders associated with the mailbox identified by the -SMTP parameter, if they exist. If there are no public folders, an error is thrown stating such. Note that the availability of public folders is based on information returned by AutoDiscover. See the scenario documentation about PublicFolders-to-PST for more information about public folder connections.

Required:
Yes
Type:
ConnectionTypes [Enum]
Aliases:
Type, CT
Position:
0
Default Value:
Mailbox

-SMTP

The SMTP parameter specifies the identity of the Exchange mailbox to which to connect. Note that for all supported connection types, mailbox/archive/public folders, the initial connection is made to the mailbox provided. This is simply the way that MAPI works with regards to accessing Exchange. Once the mailbox logon succeeds, the open of the appropriate store type is then made.

Required:
Yes
Type:
String
Aliases:
None
Position:
1
Default Value:
None

-AutoDiscoverServer

The AutoDiscoverServer parameter specifies the autodiscover host at which the test program should send the autodiscover request.

Note that for Office 365 the value can be either autodiscover-s.outlook.com or outlook.office365.com. If the environment is using Hybrid Modern Authentication, this value might need to point to an on-premises server instead of Office 365. According to Microsoft documentation, Hybrid Modern Authentication requires that the authentication occur within the local environment first. See this article for detail and search the page for “What doesn’t change?“: Hybrid Modern Authentication overview…

Additionally, unlike Outlook, Super-ExMerge does not try to “auto determine” the autodiscover hostname. Super-ExMerge will send the request directly to the server name provided to this parameter. This avoids challenges with shared namespaces and migration scenarios.

Required:
Yes
Type:
String
Aliases:
Server, svr, ADS
Position:
2
Default Value:
None

-FormattedCreds

The FormattedCreds parameter specifies the credentials that should be used to authenticate to the mailbox referenced by the -SMTP parameter.

Note that the credential provided is not necessarily required to be the same as the mailbox. If the credential has either FullAccess privileges, or system privileges, access to the mailbox is allowed even if not the owner of it. Review the Authentication documentation in the Vocabulary and Glossary section for more detail.

Required:
Yes
Type:
String or FormattedCredential
Aliases:
Creds, FC
Position:
3
Default Value:
None

-TimeOutAfterSeconds

The TimeOutAfterSeconds parameter sets the duration of time that the cmdlet will wait for the testing application to respond to the cmdlet. For connections to mail servers over a very long distance or with a very high latency, the responsiveness of the testing program can be slowed as a result. It may be necessary to increase the timeout in such cases.

The default timeout is 300 seconds (5 minutes).

Required:
No
Type:
Int32
Aliases:
None
Position:
Not a positioned parameter. Use by name only.
Default Value:
300

Output

Jump To:

This cmdlet will text messages on the pipeline as responses from the testing program that show the results of the various testing element performed.

How can we help?