> ## Documentation Index
> Fetch the complete documentation index at: https://api.smartlead.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add SMTP Email Account

> Add new SMTP/IMAP email account with connection validation and optional warmup configuration

<Note>
  Creates a new email account with SMTP and IMAP configuration. SmartLead will validate the connection and optionally enable email warmup. Supports both standard SMTP accounts and OAuth providers (Gmail, Outlook).
</Note>

## Query Parameters

<ParamField query="api_key" type="string" required>
  Your SmartLead API key
</ParamField>

## Request Body

<ParamField body="from_name" type="string" required>
  Display name for outgoing emails (e.g., "John Doe")
</ParamField>

<ParamField body="from_email" type="string" required>
  Email address (must be valid email format)
</ParamField>

<ParamField body="user_name" type="string" required>
  SMTP username (usually the email address)
</ParamField>

<ParamField body="password" type="string" required>
  SMTP password or app-specific password
</ParamField>

<ParamField body="smtp_host" type="string" required>
  SMTP server hostname (e.g., "smtp.gmail.com")
</ParamField>

<ParamField body="smtp_port" type="number" required>
  SMTP server port (common ports: 587 for TLS, 465 for SSL, 25 for plain)
</ParamField>

<ParamField body="imap_host" type="string" required>
  IMAP server hostname (e.g., "imap.gmail.com")
</ParamField>

<ParamField body="imap_port" type="number" required>
  IMAP server port (common ports: 993 for SSL, 143 for plain)
</ParamField>

<ParamField body="warmup_enabled" type="boolean" required>
  Whether to enable email warmup for this account
</ParamField>

<ParamField body="id" type="number">
  Email account ID (only for updates, null for new accounts)
</ParamField>

<ParamField body="type" type="string">
  Email provider type. Valid values: `GMAIL`, `OUTLOOK`, `SMTP`
</ParamField>

<ParamField body="token" type="object">
  OAuth token object (for Gmail/Outlook OAuth accounts)

  <Expandable title="Token properties">
    <ParamField body="scope" type="string" required>
      OAuth scope granted
    </ParamField>

    <ParamField body="access_token" type="string">
      OAuth access token
    </ParamField>

    <ParamField body="refresh_token" type="string">
      OAuth refresh token
    </ParamField>

    <ParamField body="id_token" type="string">
      OAuth ID token
    </ParamField>

    <ParamField body="expiry_date" type="number" required>
      Token expiry timestamp
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="different_reply_to_address" type="string">
  Custom reply-to email address (if different from from\_email)
</ParamField>

<ParamField body="imap_user_name" type="string">
  IMAP username (if different from SMTP username)
</ParamField>

<ParamField body="imap_password" type="string">
  IMAP password (if different from SMTP password)
</ParamField>

<ParamField body="max_email_per_day" type="number">
  Maximum emails allowed per day (including warmup and campaign emails)
</ParamField>

<ParamField body="custom_tracking_url" type="string">
  Custom domain for tracking links
</ParamField>

<ParamField body="bcc" type="string">
  BCC email address for all outgoing emails
</ParamField>

<ParamField body="time_to_wait_in_mins" type="number">
  Minimum time to wait between emails in minutes
</ParamField>

<ParamField body="signature" type="string">
  Email signature HTML
</ParamField>

<ParamField body="total_warmup_per_day" type="number">
  Number of warmup emails to send per day (if warmup\_enabled is true)
</ParamField>

<ParamField body="daily_rampup" type="number">
  Daily increase in warmup email count
</ParamField>

<ParamField body="reply_rate_percentage" type="number">
  Target reply rate percentage for warmup emails
</ParamField>

<ParamField body="client_id" type="number">
  Client ID for multi-tenant accounts
</ParamField>

<ParamField body="is_suspended" type="boolean">
  Whether the account should be suspended upon creation
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://server.smartlead.ai/api/v1/email-accounts/save?api_key=YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "from_name": "John Doe",
      "from_email": "john@example.com",
      "user_name": "john@example.com",
      "password": "your_app_password",
      "smtp_host": "smtp.gmail.com",
      "smtp_port": 587,
      "imap_host": "imap.gmail.com",
      "imap_port": 993,
      "warmup_enabled": true,
      "total_warmup_per_day": 20,
      "daily_rampup": 2,
      "max_email_per_day": 50,
      "time_to_wait_in_mins": 5,
      "type": "GMAIL"
    }'
  ```

  ```python Python theme={null}
  import requests

  API_KEY = "YOUR_API_KEY"

  payload = {
      "from_name": "John Doe",
      "from_email": "john@example.com",
      "user_name": "john@example.com",
      "password": "your_app_password",
      "smtp_host": "smtp.gmail.com",
      "smtp_port": 587,
      "imap_host": "imap.gmail.com",
      "imap_port": 993,
      "warmup_enabled": True,
      "total_warmup_per_day": 20,
      "daily_rampup": 2,
      "max_email_per_day": 50,
      "time_to_wait_in_mins": 5,
      "type": "GMAIL",
      "signature": "<p>Best regards,<br>John</p>"
  }

  response = requests.post(
      "https://server.smartlead.ai/api/v1/email-accounts/save",
      params={"api_key": API_KEY},
      json=payload
  )

  result = response.json()
  if result.get('ok'):
      print(f"Email account added successfully. ID: {result['data']['id']}")
  else:
      print(f"Error: {result.get('message')}")
  ```

  ```javascript JavaScript theme={null}
  const API_KEY = 'YOUR_API_KEY';

  const payload = {
    from_name: 'John Doe',
    from_email: 'john@example.com',
    user_name: 'john@example.com',
    password: 'your_app_password',
    smtp_host: 'smtp.gmail.com',
    smtp_port: 587,
    imap_host: 'imap.gmail.com',
    imap_port: 993,
    warmup_enabled: true,
    total_warmup_per_day: 20,
    daily_rampup: 2,
    max_email_per_day: 50,
    time_to_wait_in_mins: 5,
    type: 'GMAIL',
    signature: '<p>Best regards,<br>John</p>'
  };

  const response = await fetch(
    `https://server.smartlead.ai/api/v1/email-accounts/save?api_key=${API_KEY}`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload)
    }
  );

  const result = await response.json();
  if (result.ok) {
    console.log(`Email account added successfully. ID: ${result.data.id}`);
  } else {
    console.log(`Error: ${result.message}`);
  }
  ```
</RequestExample>

## Response Codes

<ResponseField name="200" type="Success">
  Email account added successfully with connection validation
</ResponseField>

<ResponseField name="400" type="Bad Request">
  SMTP or IMAP connection failed - check credentials and server settings
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Invalid or missing API key
</ResponseField>

<ResponseField name="422" type="Validation Error">
  Missing required fields or invalid field values
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Server error occurred
</ResponseField>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "ok": true,
    "message": "Email account added successfully",
    "data": {
      "id": 123,
      "from_email": "john@example.com",
      "is_smtp_success": true,
      "is_imap_success": true,
      "warmup_details": {
        "status": "ACTIVE",
        "total_warmup_per_day": 20
      }
    }
  }
  ```

  ```json 400 - Connection Failed theme={null}
  {
    "ok": false,
    "message": "SMTP connection failed",
    "error": "Invalid credentials"
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Invalid API Key"
  }
  ```

  ```json 422 - Validation Error theme={null}
  {
    "error": "from_name is required"
  }
  ```
</ResponseExample>

## Configuration Examples

<AccordionGroup>
  <Accordion title="Gmail Configuration">
    ```json theme={null}
    {
      "from_name": "Your Name",
      "from_email": "your.email@gmail.com",
      "user_name": "your.email@gmail.com",
      "password": "your_app_specific_password",
      "smtp_host": "smtp.gmail.com",
      "smtp_port": 587,
      "imap_host": "imap.gmail.com",
      "imap_port": 993,
      "type": "GMAIL",
      "warmup_enabled": true
    }
    ```
  </Accordion>

  <Accordion title="Outlook/Office 365 Configuration">
    ```json theme={null}
    {
      "from_name": "Your Name",
      "from_email": "your.email@outlook.com",
      "user_name": "your.email@outlook.com",
      "password": "your_password",
      "smtp_host": "smtp.office365.com",
      "smtp_port": 587,
      "imap_host": "outlook.office365.com",
      "imap_port": 993,
      "type": "OUTLOOK",
      "warmup_enabled": true
    }
    ```
  </Accordion>

  <Accordion title="Custom SMTP Configuration">
    ```json theme={null}
    {
      "from_name": "Your Name",
      "from_email": "you@yourdomain.com",
      "user_name": "you@yourdomain.com",
      "password": "your_password",
      "smtp_host": "smtp.yourdomain.com",
      "smtp_port": 587,
      "imap_host": "imap.yourdomain.com",
      "imap_port": 993,
      "type": "SMTP",
      "warmup_enabled": false
    }
    ```
  </Accordion>
</AccordionGroup>

## Usage Notes

<Warning>
  For Gmail accounts, you must use an [App Password](https://support.google.com/accounts/answer/185833) rather than your regular Gmail password. Enable 2-factor authentication first, then generate an app password.
</Warning>

<Info>
  SmartLead automatically validates SMTP and IMAP connections upon adding an account. If validation fails, the account is still created but marked with connection errors that you can fix later.
</Info>

<Tip>
  Enable warmup for new email accounts to gradually build sender reputation. Set `total_warmup_per_day` to start with 10-20 emails and use `daily_rampup` of 2-5 to increase daily volume gradually.
</Tip>

## Related Endpoints

* [Add OAuth Email Account](/api-reference/email-accounts/add-oauth) - For OAuth-based Gmail/Outlook
* [Get All Email Accounts](/api-reference/email-accounts/get-all)
* [Update Warmup Settings](/api-reference/email-accounts/warmup-settings)