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

# Send Emails with SMTP

> Learn how to send emails using Nuntly's SMTP server with your favorite email clients and libraries.

## Overview

Nuntly provides an SMTP server that allows you to send emails using standard SMTP clients and libraries. This is perfect if you want to integrate email sending into existing applications or use tools that support SMTP.

## SMTP Configuration

Use these settings to configure your SMTP client:

| Setting      | Value                                     |
| ------------ | ----------------------------------------- |
| **Host**     | `smtp.nuntly.com`                         |
| **Port**     | `587`                                     |
| **Username** | `nuntly`                                  |
| **Password** | Your Nuntly API Key (starts with `ntly_`) |

<Note>
  You need a valid API key to authenticate with the SMTP server. You can create one in the [API Keys](https://nuntly.com/api-keys) section of your
  dashboard. The `from` address must belong to a [verified domain](https://nuntly.com/domains) in your account.
</Note>

### Understanding SMTP Ports

Nuntly SMTP server uses **port 587** with STARTTLS encryption. Here's what you need to know about SMTP ports:

| Port     | Security | Description                                            | Nuntly Support    |
| -------- | -------- | ------------------------------------------------------ | ----------------- |
| **25**   | None     | Standard SMTP port, often blocked by ISPs              | ❌ Not supported   |
| **465**  | SSL/TLS  | SMTP over implicit SSL                                 | ❌ Not supported   |
| **587**  | STARTTLS | Modern SMTP submission with opportunistic encryption   | ✅ **Recommended** |
| **2525** | STARTTLS | Alternative submission port (for restrictive networks) | ❌ Not supported   |

<Warning>
  **Why port 587?** <br />
  Port 587 is the standard port for email submission (RFC 6409) and uses STARTTLS to upgrade the connection to encrypted. This provides better
  compatibility and security than older approaches.
</Warning>

## Code Examples

Each example below configures an SMTP client with your Nuntly credentials, composes a message with both plain text and HTML parts, and sends it through the Nuntly SMTP server. Simply replace `ntly_your_api_key_here` with your actual API key.

<CodeGroup>
  ```javascript Node.js theme={null}
  const nodemailer = require('nodemailer');

  const transporter = nodemailer.createTransport({
  host: 'smtp.nuntly.com',
  port: 587,
  secure: false, // Use STARTTLS
  auth: {
  user: 'nuntly',
  pass: 'ntly_your_api_key_here',
  },
  });

  const mailOptions = {
  from: 'ray@info.tomlinson.ai',
  to: 'maiya5@gmail.com',
  subject: 'Hello from Nuntly SMTP',
  text: 'This is a test email sent via SMTP',
  html: '<h1>Hello!</h1><p>This is a test email sent via SMTP</p>',
  };

  transporter.sendMail(mailOptions, (error, info) => {
  if (error) {
  console.error('Error:', error);
  } else {
  console.log('Email sent:', info.messageId);
  }
  });

  ```

  ```python Python theme={null}
  import smtplib
  from email.mime.text import MIMEText
  from email.mime.multipart import MIMEMultipart

  # Create message
  msg = MIMEMultipart('alternative')
  msg['Subject'] = 'Hello from Nuntly SMTP'
  msg['From'] = 'ray@info.tomlinson.ai'
  msg['To'] = 'maiya5@gmail.com'

  # Add text and HTML parts
  text_part = MIMEText('This is a test email sent via SMTP', 'plain')
  html_part = MIMEText('<h1>Hello!</h1><p>This is a test email sent via SMTP</p>', 'html')

  msg.attach(text_part)
  msg.attach(html_part)

  # Send email
  with smtplib.SMTP('smtp.nuntly.com', 587) as server:
      server.starttls()
      server.login('nuntly', 'ntly_your_api_key_here')
      server.send_message(msg)
      print('Email sent successfully!')
  ```

  ```php PHP theme={null}
  <?php
  use PHPMailer\PHPMailer\PHPMailer;
  use PHPMailer\PHPMailer\Exception;

  require 'vendor/autoload.php';

  $mail = new PHPMailer(true);

  try {
      // Server settings
      $mail->isSMTP();
      $mail->Host       = 'smtp.nuntly.com';
      $mail->SMTPAuth   = true;
      $mail->Username   = 'nuntly';
      $mail->Password   = 'ntly_your_api_key_here';
      $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
      $mail->Port       = 587;

      // Recipients
      $mail->setFrom('ray@info.tomlinson.ai', 'Sender Name');
      $mail->addAddress('maiya5@gmail.com', 'Recipient Name');

      // Content
      $mail->isHTML(true);
      $mail->Subject = 'Hello from Nuntly SMTP';
      $mail->Body    = '<h1>Hello!</h1><p>This is a test email sent via SMTP</p>';
      $mail->AltBody = 'This is a test email sent via SMTP';

      $mail->send();
      echo 'Email sent successfully!';
  } catch (Exception $e) {
      echo "Error: {$mail->ErrorInfo}";
  }
  ?>
  ```

  ```ruby Ruby theme={null}
  require 'mail'

  Mail.defaults do
    delivery_method :smtp, {
      address:              'smtp.nuntly.com',
      port:                 587,
      user_name:            'nuntly',
      password:             'ntly_your_api_key_here',
      authentication:       'plain',
      enable_starttls_auto: true
    }
  end

  mail = Mail.new do
    from     'ray@info.tomlinson.ai'
    to       'maiya5@gmail.com'
    subject  'Hello from Nuntly SMTP'
    text_part do
      body 'This is a test email sent via SMTP'
    end
    html_part do
      content_type 'text/html; charset=UTF-8'
      body '<h1>Hello!</h1><p>This is a test email sent via SMTP</p>'
    end
  end

  mail.deliver!
  puts 'Email sent successfully!'
  ```
</CodeGroup>

### Shell (Swaks)

[Swaks](https://jetmore.org/john/code/swaks/) (Swiss Army Knife for SMTP) is a powerful command-line tool for testing SMTP servers.

The examples below cover sending a plain text email, an HTML email, and a verbose connection test, all from the terminal.

**Install Swaks**

<CodeGroup>
  ```bash macOS theme={null}
  brew install swaks
  ```

  ```bash Ubuntu/Debian theme={null}
  sudo apt-get install swaks
  ```

  ```bash CentOS/RHEL theme={null}
  sudo yum install swaks
  ```

  ```powershell Windows theme={null}
  choco install swaks
  ```
</CodeGroup>

**Send a simple email**

```bash theme={null}
swaks --to maiya5@gmail.com \
      --from ray@info.tomlinson.ai \
      --server smtp.nuntly.com:587 \
      --auth LOGIN \
      --auth-user nuntly \
      --auth-password ntly_your_api_key_here \
      --tls \
      --header "Subject: Hello from Swaks" \
      --body "This is a test email sent via Swaks"
```

**Send an HTML email:**

```bash theme={null}
swaks --to maiya5@gmail.com \
      --from ray@info.tomlinson.ai \
      --server smtp.nuntly.com:587 \
      --auth LOGIN \
      --auth-user nuntly \
      --auth-password ntly_your_api_key_here \
      --tls \
      --header "Subject: Hello from Swaks" \
      --header "Content-Type: text/html" \
      --body '<h1>Hello!</h1><p>This is a test email sent via Swaks</p>'
```

**Test SMTP connection (with verbose output):**

```bash theme={null}
swaks --to maiya5@gmail.com \
      --from ray@info.tomlinson.ai \
      --server smtp.nuntly.com:587 \
      --auth LOGIN \
      --auth-user nuntly \
      --auth-password ntly_your_api_key_here \
      --tls \
      --header "Subject: SMTP Connection Test" \
      --body "Testing SMTP connectivity" \
      --show-password
```

<Tip>
  Use the `--show-password` flag to display the full SMTP conversation, including authentication. This is useful for debugging connection issues.
</Tip>

## Troubleshooting

### Authentication Failed

Make sure you're using:

* Username: exactly `nuntly` (lowercase)
* Password: Your valid API key (starts with `ntly_`)

### Connection Timeout

Verify that:

* Port 587 is not blocked by your firewall
* You're using STARTTLS (not SSL/TLS)
* The SMTP server hostname is correct: `smtp.nuntly.com`

### Email Size Exceeded

If you receive a "552 Email size exceeds limit" error:

* Reduce your email size or attachment count
* Upload large files to a blob storage (e.g. AWS S3, Google Cloud Storage, Azure Blob) and include a download link in the email body instead of attaching them
* See [Limits](/docs/api-reference/limits) for detailed size constraints

## Learn more

<CardGroup cols={2}>
  <Card title="Handle webhook events" icon="webhook" href="/docs/guides/integrate-webhooks">
    Receive and process delivery, bounce, and open events in your app
  </Card>

  <Card title="API Reference" icon="code" href="/docs/api-reference/introduction">
    Explore the REST API for advanced features
  </Card>
</CardGroup>