---
title: Elastic Exchange Server connector reference
description: The Elastic Exchange Server connector is built with the Elastic connector framework and is available as a self-managed connector. It syncs mail, contacts,...
url: https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/search-connectors/es-connectors-exchange-server
products:
  - Elasticsearch
applies_to:
  - Elastic Stack: Planned
---

# Elastic Exchange Server connector reference
The Elastic Exchange Server connector is built with the Elastic connector framework and is available as a [self-managed connector](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/search-connectors/self-managed-connectors). It syncs mail, contacts, calendar events, tasks, and attachments from on-premises Microsoft Exchange Server.
<note>
  This connector is the on-premises (server) mode of the [Outlook connector](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/search-connectors/es-connectors-outlook), available as its own connector. The `outlook_server` data source of the Outlook connector is deprecated. Use the Exchange Server connector for on-premises Exchange.
</note>


## **Self-managed connector reference**


### Availability and prerequisites

This connector is available as a self-managed connector. To use this connector, satisfy all [self-managed connector prerequisites](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/search-connectors/self-managed-connectors).

### Create an Exchange Server connector


#### Use the UI

To create a new Exchange Server connector:
1. In the Kibana UI, search for "connectors" using the [global search field](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/query-filter/filtering#_finding_your_apps_and_objects) and choose the "Elasticsearch" connectors.
2. Follow the instructions to create a new  **Exchange Server** self-managed connector.


#### Use the API

You can use the Elasticsearch [Create connector API](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-connector) to create a new self-managed Exchange Server connector.
For example:
```json

{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Exchange Server",
  "service_type": "exchange_server"
}
```

<dropdown title="You’ll also need to create an API key for the connector to use.">
  <note>
    The user needs the cluster privileges `manage_api_key`, `manage_connector` and `write_connector_secrets` to generate API keys programmatically.
  </note>
  To create an API key for the connector:
  1. Run the following command, replacing values where indicated. Note the `encoded` return values from the response:
     ```json

     {
       "name": "connector_name-connector-api-key",
       "role_descriptors": {
         "connector_name-connector-role": {
           "cluster": [
             "monitor",
             "manage_connector"
           ],
           "indices": [
             {
               "names": [
                 "index_name",
                 ".search-acl-filter-index_name",
                 ".elastic-connectors*"
               ],
               "privileges": [
                 "all"
               ],
               "allow_restricted_indices": false
             }
           ]
         }
       }
     }
     ```
  2. Update your `config.yml` file with the API key `encoded` value.
</dropdown>

Refer to the [Elasticsearch API documentation](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-connector) for details of all available Connector APIs.

### Usage

To use this connector as a **self-managed connector**, use the **Exchange Server** tile from the connectors list OR **Customized connector** workflow.
For additional operations, see [*Connectors UI in Kibana*](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/search-connectors/connectors-ui-in-kibana).

### Connecting to Exchange Server

To connect to Exchange Server, the connector fetches Active Directory users with the help of the `ldap3` Python library, then reads each mailbox through Exchange Web Services (EWS).
The account you configure in `username` and `password` needs:
- Permission to read user objects from Active Directory.
- The Exchange `ApplicationImpersonation` role for the mailboxes you want to sync. The connector opens each mailbox with impersonation, so valid credentials alone are not enough.


### Configuration

<definitions>
  <definition term="exchange_server">
    (required) IP address to connect with Exchange Server. Example: `127.0.0.1`
  </definition>
  <definition term="active_directory_server">
    (required) IP address of the Active Directory server used to fetch users. Example: `127.0.0.1`
  </definition>
  <definition term="username">
    (required) Username to authenticate with Exchange Server.
  </definition>
  <definition term="password">
    (required) Password to authenticate with Exchange Server.
  </definition>
  <definition term="domain">
    (required) Active Directory domain name, used to look up users. Example: `corp.example.com`
  </definition>
  <definition term="ssl_enabled">
    Whether SSL verification will be enabled. Default value is `False`.
  </definition>
  <definition term="ssl_ca">
    (required if SSL is enabled) Content of SSL certificate. Example certificate:
    ```txt
    -----BEGIN CERTIFICATE-----
    MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
    ...
    7RhLQyWn2u00L7/9Omw=
    -----END CERTIFICATE-----
    ```
  </definition>
  <definition term="sync_all_mail_folders">
    Indexes mail from the user mail folders in each mailbox, not only Inbox, Sent, Junk, and Archive. Other folders are stored as `Mail` with a `folder_name` field. The four default folders keep their existing types. System folders such as Deleted Items, Drafts, Outbox, and search folders are never indexed. Enabling this setting increases sync time, load on Exchange, and index size. Default value is `False`.
  </definition>
  <definition term="use_text_extraction_service">
    Use [self-hosted content extraction service](/elastic/elasticsearch/tree/main/reference/search-connectors/es-connectors-content-extraction#es-connectors-content-extraction-data-extraction-service). Default value is `False`.
  </definition>
  <definition term="Index full raw email (including headers)">
    Toggle to index the full raw MIME message. Default value is `False`. When off, only the email body (preferring `text/plain` over `text/html`) and a minimal set of headers (`Subject`, `From`, `Reply-To`, `To`, `Cc`, `Bcc`, `Date`, `Message-ID`) are indexed. Routing/authentication headers and binary attachments are dropped. Enable this toggle to restore the passthrough behavior when body extraction misses content.
  </definition>
  <definition term="use_document_level_security">
    Toggle to enable [Document level security (DLS)](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/search-connectors/document-level-security). When enabled:
    - Full syncs will fetch access control lists for each document and store them in the `_allow_access_control` field.
    - Access control syncs fetch users' access control lists and store them in a separate index.
  </definition>
</definitions>


### Deployment using Docker

You can deploy the Exchange Server connector as a self-managed connector using Docker. Follow these instructions.
<dropdown title="Step 1: Download sample configuration file">
  Download the sample configuration file. You can either download it manually or run the following command:
  ```sh
  curl https://raw.githubusercontent.com/elastic/connectors/main/app/connectors_service/config.yml.example --output ~/connectors-config/config.yml
  ```
  Remember to update the `--output` argument value if your directory name is different, or you want to use a different config file name.
</dropdown>

<dropdown title="Step 2: Update the configuration file for your self-managed connector">
  Update the configuration file with the following settings to match your environment:
  - `elasticsearch.host`
  - `elasticsearch.api_key`
  - `connectors`
  If you’re running the connector service against a Dockerized version of Elasticsearch and Kibana, your config file will look like this:
  ```yaml
  # When connecting to your cloud deployment you should edit the host value
  elasticsearch.host: http://host.docker.internal:9200
  elasticsearch.api_key: <ELASTICSEARCH_API_KEY>

  connectors:
    -
      connector_id: <CONNECTOR_ID_FROM_KIBANA>
      service_type: exchange_server
      api_key: <CONNECTOR_API_KEY_FROM_KIBANA>
  ```
  Using the `elasticsearch.api_key` is the recommended authentication method. However, you can also use `elasticsearch.username` and `elasticsearch.password` to authenticate with your Elasticsearch instance.Note: You can change other default configurations by uncommenting specific settings in the configuration file and modifying their values.
</dropdown>

<dropdown title="Step 3: Run the Docker image">
  Run the Docker image with the Connector Service using the following command:
  ```sh
  docker run \
  -v ~/connectors-config:/config \
  --network "elastic" \
  --tty \
  --rm \
  docker.elastic.co/integrations/elastic-connectors:9.5.5 \
  /app/bin/elastic-ingest \
  -c /config/config.yml
  ```
</dropdown>

Refer to [`DOCKER.md`](https://github.com/elastic/connectors/tree/main/docs/DOCKER.md) in the `elastic/connectors` repo for more details.
Find all available Docker images in the [official registry](https://www.docker.elastic.co/r/integrations/elastic-connectors).
<tip>
  We also have a quickstart self-managed option using Docker Compose, so you can spin up all required services at once: Elasticsearch, Kibana, and the connectors service. Refer to this [README](https://github.com/elastic/connectors/tree/main/scripts/stack#readme) in the `elastic/connectors` repo for more information.
</tip>


### Content Extraction

Refer to [Content extraction](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/search-connectors/es-connectors-content-extraction).

### Documents and syncs

The connector syncs the following objects and entities:
- **Mails**
  - **Inbox Mails**
- **Sent Mails**
- **Archive Mails**
- **Junk Mails**
- **Mail** — other user mail folders, when `sync_all_mail_folders` is enabled. Includes a `folder_name` field.
- **Contacts**
- **Calendar Events**
- **Tasks**
- **Attachments**
  - **Mail Attachments**
- **Task Attachments**
- **Calendar Attachments**

<note>
  - Content from files bigger than 10 MB won’t be extracted by default. You can use the [self-managed local extraction service](/elastic/elasticsearch/tree/main/reference/search-connectors/es-connectors-content-extraction#es-connectors-content-extraction-local) to handle larger binary files.
  - Permissions are not synced unless document level security is enabled. When it is not enabled, **all documents** indexed to an Elastic deployment will be visible to **all users with access** to that Elastic Deployment.
  - Mailbox discovery uses **Active Directory** (LDAP), not Microsoft Graph. The connector considers AD `user` objects that match its LDAP search filters and have a valid **`mail`** attribute, then opens each mailbox through **Exchange Web Services (EWS)**. AD accounts without `mail`, and SMTP addresses with **no mailbox** on Exchange (including many **service accounts**), are **skipped** during sync. **Shared mailboxes** are synced only when their AD user is discovered and Exchange exposes a mailbox for that address.
</note>


#### Sync types

[Full syncs](/elastic/elasticsearch/tree/main/reference/search-connectors/content-syncs#es-connectors-sync-types-full) are supported by default for all connectors.
This connector also supports [incremental syncs](/elastic/elasticsearch/tree/main/reference/search-connectors/content-syncs#es-connectors-sync-types-incremental).

### Document level security

Document level security (DLS) enables you to restrict access to documents based on a user’s permissions. Refer to [configuration](#es-connectors-exchange-server-client-configuration) on this page for how to enable DLS for this connector.
<note>
  Refer to [DLS in Search Applications](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/search-connectors/es-dls-e2e-guide) to learn how to ingest data from a connector with DLS enabled, when building a search application. The example uses SharePoint Online as the data source, but the same steps apply to every connector.
</note>


### Sync rules

[Basic sync rules](/elastic/elasticsearch/tree/main/reference/search-connectors/es-sync-rules#es-sync-rules-basic) are identical for all connectors and are available by default.

### Advanced Sync Rules

Advanced sync rules are not available for this connector in the present version.

### Connector Client operations


#### End-to-end Testing

**Note:** End-to-end testing is not available in the current version of the connector.

#### Known issues

Refer to [Known issues](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/search-connectors/es-connectors-known-issues) for a list of known issues for all connectors. Known issues listed for the Outlook connector that relate to Exchange Server (on-premises) can also affect this connector.

### Troubleshooting

See [Troubleshooting](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/search-connectors/es-connectors-troubleshooting).

### Security

See [Security](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/search-connectors/es-connectors-security).

### Framework and source

This connector is included in the [Elastic connector framework](https://github.com/elastic/connectors/tree/main).
View the [source code for this connector](https://github.com/elastic/connectors/tree/main/app/connectors_service/connectors/sources/exchange_server) (branch *main*, compatible with Elastic *9.6*).