---
title: "Connect an SMTP/IMAP email account"
method: POST
path: "/v1/email-accounts/smtp-imap/connect"
tags: ["email-accounts"]
---

# Connect an SMTP/IMAP email account

`POST /v1/email-accounts/smtp-imap/connect`

## Request

- Base URL: `https://developer.saleshandy.com` (the document declares no server; this is the origin it was published from)
- URL: `https://developer.saleshandy.com/v1/email-accounts/smtp-imap/connect`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/saleshandy/apis/develop-with-saleshandy/docs/v1/email-accounts/smtp-imap/connect/post.ts> (a function with typed inputs; its response is checked against the schema)

Connects a new SMTP/IMAP email account for use as a sending mailbox in sequences.

The account is **always saved** to the database, even if the connection test fails — inspect the `smtpConnection` and `imapConnection` fields in the response.

*   `status: 0` — created but connection unverified (check `smtpConnection.error`/`imapConnection.error`).
*   `status: 1` — connected and verified.

`emailServiceProvider` must be **lowercase** (e.g. `"zoho"`). Valid values: `zoho`, `gmail`, `yahoo`, `sendgrid`, `mailgun`, `ses`, `outlook`.

`fromName` is the full display name shown in the From header; it is independent of `fromFirstName`/`fromLastName` — all three must be supplied.

## Request body

- ConnectEmailAccountDto
  - `emailServiceProvider` 'gmail' | 'microsoft' | 'gsuite' | 'o365' | 'yahoo' | 'zoho' | 'godaddy' | 'yandex' | 'sendgrid' | 'other', required: Email service provider identifier. Accepted values: gmail, microsoft, gsuite, o365, yahoo, zoho, godaddy, yandex, sendgrid, other.
  - `fromName` string, required: Full display name shown as the sender.
  - `fromFirstName` string, required: Sender's first name.
  - `fromLastName` string, required: Sender's last name.
  - `payload` ConnectEmailAccountPayloadDto, required
    - `smtp` SmtpConnectionDto, required
      - `emailAddress` string, required: Email address used for SMTP authentication.
      - `password` string, required: SMTP password or app-specific password.
      - `host` string, required: SMTP hostname.
      - `port` number, required: SMTP port (1–65535).
      - `encryption` 'TLS' | 'SSL', required: SMTP connection encryption.
      - `userName` string, required: SMTP username — usually the same as the email address.
    - `imap` ImapConnectionDto, required
      - `emailAddress` string, required: Email address used for IMAP authentication.
      - `password` string, required: IMAP password or app-specific password.
      - `host` string, required: IMAP hostname.
      - `port` number, required: IMAP port (1–65535).
      - `encryption` 'TLS' | 'SSL', required: IMAP connection encryption.

## Response `200`

Email account connected successfully

## Other responses

- `400`: 4000: Failed to connect email account<br><br>
- `409`: 1001: Email account already exists<br><br>
- `500`: 5001: Internal server error, please try again later<br><br>

---

[API](https://skmtc.dev/saleshandy/apis/develop-with-saleshandy.md) - [All operations](https://skmtc.dev/saleshandy/apis/develop-with-saleshandy/llms.txt) - [OpenAPI document](https://skmtc.dev/saleshandy/apis/develop-with-saleshandy/revisions/e7a29c931aa7?raw)