> ## Documentation Index > Fetch the complete documentation index at: https://docs.maildiver.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Overview > Send emails with SMTP Learn how to integrate MailDiver via SMTP for seamless email delivery. SMTP is only available for Managed (Cloud) customers. Self-hosted users should use the [API](/api-reference/introduction) instead. ## Prerequisites Before using SMTP, you must: 1. [Create an API key](https://app.maildiver.com/api-keys) from your dashboard 2. [Verify your domain](https://app.maildiver.com/domains) to send emails Need help with DNS records? Check out our [step-by-step DNS setup guide](/knowledge/guides/add-dns-records). ## SMTP Credentials Configure your SMTP client with these settings: | Setting | Value | | -------- | ------------------------------------ | | Host | `smtp.maildiver.com` | | Username | `maildiver` | | Password | `MAILDIVER_API_KEY` | | Ports | 587 (STARTTLS) or 465 (Implicit TLS) | ### Port Types **Recommended**: Use port **587 (STARTTLS)** - it's the industry standard for email submission and has the best compatibility. | Port | Type | Security | | ---- | -------- | ---------------------------------------------------------------------- | | 587 | STARTTLS | Explicit SSL/TLS (starts plain, upgrades to SSL/TLS) - **Recommended** | | 465 | Implicit | Implicit SSL/TLS (immediately connects via SSL/TLS) - Legacy support | ## Quick Start Any SMTP client can connect to MailDiver using these credentials: ``` Host: smtp.maildiver.com Port: 587 (STARTTLS) Username: maildiver Password: MAILDIVER_API_KEY ``` ## Validation Rules MailDiver validates all emails before sending: | Field | Requirement | Max Length/Size | | ----------- | ------------------------------ | --------------- | | From | Required, valid email | 100 characters | | To | Required, at least 1 recipient | 50 recipients | | CC | Optional | 50 recipients | | BCC | Optional | 50 recipients | | Reply-To | Optional | 50 recipients | | Subject | Required | 100 characters | | HTML | At least HTML or text required | 40MB | | Text | At least HTML or text required | 10MB | | Attachments | Optional | 10 files, 40MB | **SMTP Message Size Limit**: The entire SMTP message (including headers, content, and attachments combined) has a maximum size of **10MB**. While individual HTML can be up to 40MB and text up to 10MB when using the API, SMTP transmissions are limited to 10MB total. ### Common Validation Errors **Subject too long:** ``` 554 Email validation failed: subject is too long: 150 characters. Max length is 100 ``` **Domain not verified:** ``` 550 Domain example.com not verified for workspace abc123 ``` **Missing content:** ``` 554 Email validation failed: Email must have either html, text, or a template ID ``` **Rate limit exceeded:** ``` 421 4.7.1 Rate limit exceeded. Maximum 300 emails per minute. ``` ## Advanced Features ### Template Variables (Inline) Use inline template variables for dynamic content: ```javascript theme={null} await transporter.sendMail({ from: 'hello@yourdomain.com', to: 'customer@example.com', subject: 'Special Offer', html: '

Hello {{name}}!

Get {{discount}}% off with code: {{code}}

', headers: { 'X-Template-Variables': JSON.stringify({ name: 'John', discount: 20, code: 'SAVE20', }), }, }); ``` The variables in your HTML will be automatically replaced with the provided values. **Limits:** * Maximum 100 template variables per email * Variables must be valid JSON ### Using Saved Templates Reference a saved template from your [dashboard](https://app.maildiver.com/templates): ```javascript theme={null} await transporter.sendMail({ from: 'hello@yourdomain.com', to: 'customer@example.com', subject: 'Welcome Email', html: '

Fallback content if template not found

', headers: { 'X-Template-Id': '01936d9f-1d6a-7b3c-9f2e-4a5c6d7e8f9a', 'X-Template-Variables': JSON.stringify({ userName: 'John', activationLink: 'https://app.example.com/activate/abc123', }), }, }); ``` ### Rate Limiting **Rate Limit:** 300 emails per minute (5 emails/second average) Exceeding the rate limit will result in `421 4.7.1` error responses. Your client should implement retry logic with exponential backoff. Need higher limits? [Contact us](https://maildiver.com/support) to discuss your requirements. ## Testing Your Connection Use the `swaks` command-line tool to quickly test your SMTP connection: ```bash theme={null} # Install swaks brew install swaks # macOS apt install swaks # Ubuntu # Test SMTP connection swaks \ --to test@example.com \ --from hello@yourdomain.com \ --server smtp.maildiver.com:587 \ --tls \ --auth-user maildiver \ --auth-password MAILDIVER_API_KEY \ --header "Subject: Test Email" \ --body "This is a test email" ``` ## FAQ ### Where can I see emails sent via SMTP? All emails sent via SMTP appear in your MailDiver dashboard under the "Emails" section, just like emails sent via the API. ### Does rate limiting apply to SMTP? Yes, the 300 emails per minute rate limit applies to all email sending methods (API and SMTP combined). ### Can I use SMTP for transactional and marketing emails? Yes, SMTP works for all email types. However, for marketing emails and newsletters, consider using the [Broadcast Emails](/knowledge/guides/broadcast-emails) feature for better campaign management. ### What happens if my API key is invalid? You'll receive a `535 Authentication Failed` error. Make sure your API key is active and hasn't been revoked. ### Can I use a different username? No, the username must always be `maildiver`. Your API key serves as the password for authentication. ### How do I monitor SMTP sending? All SMTP activity is logged in your dashboard. You can view: * Delivery status * Bounce and complaint rates * Open and click tracking (if enabled) * Error logs for failed sends ## Troubleshooting ### Connection Refused **Possible causes:** * Incorrect host or port * Firewall blocking SMTP ports * Network connectivity issues **Solution:** * Verify host is `smtp.maildiver.com` * Check ports 587 or 465 are not blocked * Test with: `telnet smtp.maildiver.com 587` ### Authentication Failed (535) **Possible causes:** * Invalid or expired API key * Wrong username (must be `maildiver`) * API key for different workspace **Solution:** * Create a new API key from your dashboard * Verify username is exactly `maildiver` * Ensure API key matches your verified domain ### SSL/TLS Errors **Possible causes:** * Using wrong security settings for port * Outdated SSL/TLS libraries * Certificate validation issues **Solution:** * Port 587: Use STARTTLS (`secure: false`) * Port 465: Use implicit TLS (`secure: true`) * Update your SMTP client library ## Next Steps Learn how to send emails with Nodemailer, including connection pooling and attachments ## Support Need help with SMTP integration? * Email: [support@maildiver.com](mailto:support@maildiver.com) * Documentation: [docs.maildiver.com](https://maildiver.com/docs) * Dashboard: [maildiver.com](https://maildiver.com)