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

# SMTP Credentials

> Learn how to create and manage SMTP credentials for sending emails through AhaSend's SMTP relay

SMTP credentials allow you to authenticate with AhaSend's SMTP servers to send emails using the Simple Mail Transfer Protocol. This guide will walk you through creating, configuring, and managing your SMTP credentials.

<Info>
  **New to SMTP?** SMTP (Simple Mail Transfer Protocol) is the standard protocol for sending emails over the internet. It's supported by virtually all programming languages and email libraries, making it the most compatible way to send emails.
</Info>

## What are SMTP Credentials?

SMTP credentials consist of a **username** and **password** that authenticate your application with AhaSend's SMTP servers. Unlike API keys, SMTP credentials work with any SMTP-compatible email library or application, making them perfect for:

* **Legacy applications** that already use SMTP
* **Email libraries** that don't support HTTP APIs
* **Third-party applications** that need SMTP configuration
* **Cross-platform compatibility** across all programming languages

## Creating SMTP Credentials

<Info>
  Please note that it might take up to 2 minutes for newly created SMTP credentials to propagate through our systems and become available on all SMTP servers.
</Info>

<Steps>
  <Step title="Access Credentials Dashboard" icon="user">
    1. **Log in** to your [AhaSend Dashboard](https://dash.ahasend.com)
    2. **Navigate** to the **Credentials** section from the main menu
    3. **Click** the **"Create Credential"** button
  </Step>

  <Step title="Configure Credential Settings" icon="gear">
    **Select Credential Type:**

    * Choose **"SMTP"** as the credential type

    **Choose a Descriptive Name:**

    * Use a name that helps you identify this credential later
    * Examples: "Production SMTP", "example.com SMTP", "Staging Environment"

    <Tip>
      **Naming Tip:** If you have multiple domains, include the domain name in your credential name (e.g., "example.com Production SMTP") to make management easier.
    </Tip>
  </Step>

  <Step title="Set Credential Mode" icon="vial">
    Choose the appropriate mode for your use case:

    **Production Mode:**

    * Sends emails to real recipients
    * Use for live applications and real email delivery
    * Emails are delivered normally

    **Sandbox Mode:**

    * Simulates email sending without actual delivery to recipients
    * Perfect for testing and development environments
    * Completely free - doesn't count toward your email credits
    * Still triggers webhooks for testing your integrations

    <Info>
      **Sandbox Benefits:** Sandbox mode processes emails just like production (including webhook events) but stops short of actual delivery. This makes it perfect for testing your integration safely. [Learn more about sandbox mode →](/smtp/sandbox)
    </Info>
  </Step>

  <Step title="Configure Credential Scope" icon="shield">
    **Global Scope (Recommended):**

    * Works with all domains in your account
    * Simplest option for most users
    * Can be changed later if needed

    **Domain-Specific Scope:**

    * Restricts credential to specific domains
    * Better security for multi-domain setups
    * Requires separate credentials per domain

    <Info>
      **Getting Started:** Choose "Global" scope initially. You can always create more specific credentials later as your needs grow.
    </Info>
  </Step>

  <Step title="Generate and Save Credentials" icon="key">
    1. **Click** "Create Credential" to generate your SMTP credentials
    2. **Copy and securely store** both the username and password
    3. **Save them** in your password manager or secure storage
  </Step>
</Steps>

## Managing SMTP Credentials

### Viewing Your Credentials

Once created, you can view and manage your SMTP credentials in the dashboard:

* **Name/Label:** The descriptive name you gave the credential
* **Username:** Always visible in the credentials list
* **Password:** Visible in the dashboard for easy copying
* **Mode:** Can be changed between Production and Sandbox
* **Scope:** Can be modified to adjust domain restrictions

### Security Best Practices

<AccordionGroup>
  <Accordion title="Secure Storage" icon="shield">
    * **Never** commit credentials to version control (Git repositories)
    * **Use environment variables** to store credentials in your applications
    * **Rotate credentials** periodically for enhanced security
    * **Use different credentials** for different environments (dev, staging, production)
  </Accordion>

  <Accordion title="Access Control" icon="lock">
    * **Limit access** to credentials within your team
    * **Use scoped credentials** to restrict domain access when possible
    * **Monitor usage** through the dashboard's activity logs
    * **Disable unused credentials** to reduce security surface
  </Accordion>

  <Accordion title="Network Security" icon="network-wired">
    * **Always use STARTTLS** encryption when connecting
    * **Prefer port 587** for most applications
    * **Use port 2525** if 587 is blocked by your network
    * **Avoid port 25** unless specifically required
  </Accordion>
</AccordionGroup>

## Using SMTP Credentials

### Connection Settings

Configure your email library or application with these settings:

```
Host: send.ahasend.com
Port: 587 (recommended) or 25, 2525
Security: STARTTLS (required)
Username: [Your SMTP username from dashboard]
Password: [Your SMTP password from dashboard]
```

### Integration Examples

<CardGroup cols={3}>
  <Card title="Node.js" icon="node-js" href="/smtp/nodejs">
    Nodemailer and other Node.js email libraries
  </Card>

  <Card title="Python" icon="python" href="/smtp/python">
    Django, Flask, and smtplib examples
  </Card>

  <Card title="PHP" icon="php" href="/smtp/php">
    PHPMailer, Laravel, and native PHP
  </Card>

  <Card title="Go" icon="golang" href="/smtp/golang">
    Standard library and gomail examples
  </Card>

  <Card title="Ruby" icon="gem" href="/smtp/ruby">
    Action Mailer and Net::SMTP
  </Card>

  <Card title="Command Line" icon="terminal" href="/smtp/cli">
    Send emails directly from terminal
  </Card>
</CardGroup>

## API Management

For programmatic management of SMTP credentials, use our REST API:

<CardGroup cols={2}>
  <Card title="Create SMTP Credential" icon="plus" href="/api-reference/smtp-credentials/create-smtp-credential">
    Create new SMTP credentials via API
  </Card>

  <Card title="List SMTP Credentials" icon="list" href="/api-reference/smtp-credentials/get-smtp-credentials">
    Retrieve all your SMTP credentials
  </Card>

  <Card title="Get SMTP Credential" icon="eye" href="/api-reference/smtp-credentials/get-smtp-credential">
    Get details of a specific credential
  </Card>

  <Card title="Delete SMTP Credential" icon="trash" href="/api-reference/smtp-credentials/delete-smtp-credential">
    Remove SMTP credentials you no longer need
  </Card>
</CardGroup>

<Info>
  **API vs Dashboard:** The API is perfect for automation, infrastructure-as-code, or when you need to manage credentials programmatically. For manual setup, the dashboard provides a more user-friendly experience.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication Failed" icon="triangle-exclamation">
    **Common causes:**

    * Incorrect username or password
    * Using your dashboard login instead of SMTP credentials
    * Credentials not created or expired

    **Solutions:**

    * Verify credentials in your dashboard
    * Create new SMTP credentials if needed
    * Check for typos in configuration
  </Accordion>

  <Accordion title="Connection Timeout" icon="clock">
    **Common causes:**

    * Network firewall blocking SMTP ports
    * Incorrect host or port configuration
    * ISP blocking outbound SMTP

    **Solutions:**

    * Try port 2525 if 587 is blocked
    * Check firewall settings
    * Contact your ISP about SMTP restrictions
  </Accordion>

  <Accordion title="TLS/SSL Errors" icon="shield-xmark">
    **Common causes:**

    * Outdated TLS libraries
    * Incorrect security settings
    * Self-signed certificate issues

    **Solutions:**

    * Enable STARTTLS (not SSL/TLS)
    * Update your email library
    * Verify TLS version support
  </Accordion>

  <Accordion title="Rate Limiting" icon="gauge">
    **Symptoms:**

    * Emails being deferred or rejected
    * Temporary errors during high-volume sending

    **Solutions:**

    * Check your plan's rate limits
    * Implement exponential backoff
    * Contact support for higher limits
  </Accordion>
</AccordionGroup>

## Advanced Configuration

### Multiple Credentials

You can create multiple SMTP credentials for different purposes:

* **Environment separation:** Different credentials for dev, staging, and production
* **Domain isolation:** Separate credentials for each domain you send from
* **Team access:** Individual credentials for different team members or applications

### Credential Scoping

<AccordionGroup>
  <Accordion title="Global Scope" icon="globe">
    * Works with all domains in your account
    * Simplest setup for single-domain users
    * Good for getting started quickly
  </Accordion>

  <Accordion title="Domain-Specific Scope" icon="filter">
    * Restricts sending to specific domains
    * Better security for multi-domain setups
    * Prevents accidental cross-domain sending
  </Accordion>
</AccordionGroup>

## Next Steps

Now that you have SMTP credentials set up:

<CardGroup cols={2}>
  <Card title="Configure Sandbox Mode" icon="flask" href="/smtp/sandbox">
    Set up a safe testing environment for development
  </Card>

  <Card title="Learn About Special Headers" icon="header" href="/smtp/special-headers">
    Use custom headers for tracking and metadata
  </Card>
</CardGroup>

<Tip>
  **Pro Tip:** Start with sandbox mode credentials for testing, then create production credentials when you're ready to send real emails. This prevents accidental emails during development.
</Tip>