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.
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
Access Credentials Dashboard
- Log in to your AhaSend Dashboard
- Navigate to the Credentials section from the main menu
- Click the “Create Credential” button
Configure Credential Settings
Select Credential Type:
- Choose “SMTP” as the credential type
- Use a name that helps you identify this credential later
- Examples: “Production SMTP”, “example.com SMTP”, “Staging Environment”
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.
Set Credential Mode
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
- 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
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 →
Configure Credential Scope
Global Scope (Recommended):
- Works with all domains in your account
- Simplest option for most users
- Can be changed later if needed
- Restricts credential to specific domains
- Better security for multi-domain setups
- Requires separate credentials per domain
Getting Started: Choose “Global” scope initially. You can always create more specific credentials later as your needs grow.
Generate and Save Credentials
- Click “Create Credential” to generate your SMTP credentials
- Copy and securely store both the username and password
- Save them in your password manager or secure storage
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
Secure Storage
Secure Storage
- 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)
Access Control
Access Control
- 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
Network Security
Network Security
- 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
Using SMTP Credentials
Connection Settings
Configure your email library or application with these settings:Integration Examples
Node.js
Nodemailer and other Node.js email libraries
Python
Django, Flask, and smtplib examples
PHP
PHPMailer, Laravel, and native PHP
Go
Standard library and gomail examples
Ruby
Action Mailer and Net::SMTP
Command Line
Send emails directly from terminal
API Management
For programmatic management of SMTP credentials, use our REST API:Create SMTP Credential
Create new SMTP credentials via API
List SMTP Credentials
Retrieve all your SMTP credentials
Get SMTP Credential
Get details of a specific credential
Delete SMTP Credential
Remove SMTP credentials you no longer need
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.
Troubleshooting
Authentication Failed
Authentication Failed
Common causes:
- Incorrect username or password
- Using your dashboard login instead of SMTP credentials
- Credentials not created or expired
- Verify credentials in your dashboard
- Create new SMTP credentials if needed
- Check for typos in configuration
Connection Timeout
Connection Timeout
Common causes:
- Network firewall blocking SMTP ports
- Incorrect host or port configuration
- ISP blocking outbound SMTP
- Try port 2525 if 587 is blocked
- Check firewall settings
- Contact your ISP about SMTP restrictions
TLS/SSL Errors
TLS/SSL Errors
Common causes:
- Outdated TLS libraries
- Incorrect security settings
- Self-signed certificate issues
- Enable STARTTLS (not SSL/TLS)
- Update your email library
- Verify TLS version support
Rate Limiting
Rate Limiting
Symptoms:
- Emails being deferred or rejected
- Temporary errors during high-volume sending
- Check your plan’s rate limits
- Implement exponential backoff
- Contact support for higher limits
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
Global Scope
Global Scope
- Works with all domains in your account
- Simplest setup for single-domain users
- Good for getting started quickly
Domain-Specific Scope
Domain-Specific Scope
- Restricts sending to specific domains
- Better security for multi-domain setups
- Prevents accidental cross-domain sending
Next Steps
Now that you have SMTP credentials set up:Configure Sandbox Mode
Set up a safe testing environment for development
Learn About Special Headers
Use custom headers for tracking and metadata
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.