# Inbox connectors

![](/assets/inbox-connectors.png)

Inbox connectors allow you to connect external mailboxes with MailSlurp inboxes. This means you can send and receive
emails using MailSlurp APIs and dashboards by syncing with existing mail accounts over IMAP and SMTP. This feature
supports popular providers like Google/Gmail, Outlook/Exchange, as well as custom IMAP and SMTP servers.

![](/mermaid-gen/connectors-about.mmd.svg)

## Terminology

Connectors are a way to link external email accounts with MailSlurp inboxes. They are comprised of several components:

| Feature          | Description                                       |
|------------------|---------------------------------------------------|
| Connector        | Main component with ID and email address          |
| Connector inbox  | The MailSlurp inbox for storing synced emails     |
| External mailbox | External email account hosted by your provider    |
| IMAP settings    | Settings for reading emails from external mailbox |
| SMTP settings    | Settings for sending emails via external mailbox  |
| Sync settings    | Settings for background automatic syncing         |
| Connector events | Event and logs saved for each sync and send       |

## Creating a connector

You can create inbox connectors in the dashboard or using the API. In the dashboard you can choose between common
providers like Google and Microsoft or use custom settings:

![](/examples-screenshots/ms2-app/connectors/connector-connections-missing.jpeg)

Using the [Javascript SDK](/docs/js/), here is an example:

```typescript
const connector = await connectorController.createConnectorWithOptions({
  createConnectorWithOptions: {
    // configure email and name
    createConnectorOptions: {
      emailAddress: externalInbox.emailAddress,
      name: 'example-connector',
      enabled: true
    },
    // configure imap settings
    createConnectorImapConnectionOptions: {
      enabled: true,
      imapHost: externalMailServer.imapServerHost,
      imapPort: externalMailServer.imapServerPort,
      imapPassword: externalMailServer.imapPassword,
      imapUsername: externalMailServer.imapUsername,
      imapSsl: false,
      startTls: false
    },
    // configure smtp settings
    createConnectorSmtpConnectionOptions: {
      enabled: true,
      smtpHost: externalMailServer.smtpServerHost,
      smtpPort: externalMailServer.smtpServerPort,
      smtpPassword: externalMailServer.smtpPassword,
      smtpUsername: externalMailServer.smtpUsername,
      smtpSsl: false,
      startTls: false
    },
    // no automatic sync set
    createConnectorSyncSettingsOptions: undefined
  }
});
```

See the [API reference](/docs/api/) for more connector options.

### Connecting Google Accounts

To connect Gmail/Google workspace accounts you need to first create
an [app password](https://knowledge.workspace.google.com/kb/how-to-create-app-passwords-000009237) for your google
account.

1. Go to your [Google account settings](https://myaccount.google.com/)
2. Search for "app password" in the search bar
3. Create a new app password for MailSlurp
4. Copy the password into the MailSlurp connector SMTP and IMAP password settings
5. Use your email account as the username for each setting.

Next, ensure you have enabled IMAP in Gmail settings.

1. In Gmail, click `Settings` gear icon, then click `All settings`
2. Click the `Forwarding and POP/IMAP` tab
3. In the IMAP section, select `Enable IMAP`, then save changes.

Then configure the connector connection settings to use
the [Gmail mail servers](https://support.google.com/a/answer/9003945):

<!-- docs-native-component:start:connector-provider-settings:google -->
<section data-component="ConnectorProviderSettingsTable">
<table>
<thead><tr><th>Setting</th><th>Value</th></tr></thead>
<tbody>
<tr><th>Provider</th><td>GOOGLE</td></tr>
<tr><th>IMAP username</th><td>Your email</td></tr>
<tr><th>IMAP password</th><td>Your <a href="https://knowledge.workspace.google.com/kb/how-to-create-app-passwords-000009237">app password</a></td></tr>
<tr><th>IMAP server</th><td><code>imap.gmail.com</code></td></tr>
<tr><th>IMAP port</th><td><code>993</code></td></tr>
<tr><th>IMAP SSL</th><td><code>true</code></td></tr>
<tr><th>IMAP StartTLS</th><td><code>false</code></td></tr>
<tr><th>SMTP username</th><td>Your email</td></tr>
<tr><th>SMTP password</th><td>Your <a href="https://knowledge.workspace.google.com/kb/how-to-create-app-passwords-000009237">app password</a></td></tr>
<tr><th>SMTP server</th><td><code>smtp.gmail.com</code></td></tr>
<tr><th>SMTP port</th><td><code>465</code></td></tr>
<tr><th>SMTP SSL</th><td><code>true</code></td></tr>
<tr><th>SMTP StartTLS</th><td><code>true</code></td></tr>
</tbody>
</table>
</section>
<!-- docs-native-component:end:connector-provider-settings -->

### Connecting Microsoft Accounts

<!-- docs-native-component:start:connector-provider-settings:microsoft -->
<section data-component="ConnectorProviderSettingsTable">
<table>
<thead><tr><th>Setting</th><th>Value</th></tr></thead>
<tbody>
<tr><th>Provider</th><td>MICROSOFT</td></tr>
<tr><th>IMAP username</th><td>Your email</td></tr>
<tr><th>IMAP password</th><td>Your external password or app password</td></tr>
<tr><th>IMAP server</th><td><code>outlook.office365.com</code></td></tr>
<tr><th>IMAP port</th><td><code>993</code></td></tr>
<tr><th>IMAP SSL</th><td><code>true</code></td></tr>
<tr><th>IMAP StartTLS</th><td><code>false</code></td></tr>
<tr><th>SMTP username</th><td>Your email</td></tr>
<tr><th>SMTP password</th><td>Your external password or app password</td></tr>
<tr><th>SMTP server</th><td><code>smtp-mail.outlook.com</code></td></tr>
<tr><th>SMTP port</th><td><code>587</code></td></tr>
<tr><th>SMTP SSL</th><td><code>false</code></td></tr>
<tr><th>SMTP StartTLS</th><td><code>true</code></td></tr>
</tbody>
</table>
</section>
<!-- docs-native-component:end:connector-provider-settings -->

## Testing connections

Once you add IMAP and SMTP connections you can see the status in the dashboard:

![](/examples-screenshots/ms2-app/connectors/connector-connections-present.jpeg)

You can test connections against the servers using the test connection endpoints:

```typescript
const testResult = await connectorController.testConnectorImapConnection({
  id: connector.id
})
expect(testResult.success).toBeTruthy();
```

You can also see the status and logs of the connection in the dashboard:

![](/examples-screenshots/ms2-app/connectors/connector-imap-test.jpeg)

## Syncing emails

Syncing is the process of fetching emails from an external mailbox and storing them in a MailSlurp inbox. Synchronizing
emails between an external inbox and a MailSlurp connector is done via several mechanisms:

- Direct [sync requests](/docs/api/)
- Scheduled background sync using sync settings
- Sync during [waitFor](/docs/wait-for/) commands
- Sync during [email fetch](/docs/emails/) commands

### Direct sync example

```typescript
const result: ConnectorSyncRequestResult = await connectorController.syncConnector({
  id: connector.id,
  // enable logging to debug
  logging: true
});
expect(result.syncResult?.emailIds?.length).toBeGreaterThan(0);
expect(result.syncResult?.emailSyncCount).toEqual(1);
// can view IMAP logs
expect(result.syncResult?.logs?.some(line => line.includes('CAPABILITY IMAP4rev1'))).toBeTruthy();
```

## Sending emails

To send emails from a 3rd party account using MailSlurp inboxes and APIs either:

- use the existing send email methods with the connectors `inboxId`.
- use the connector `sendEmailFromConnector` method.