Skip to main content
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 instead.

​
Prerequisites

Before using SMTP, you must:
  1. Create an API key from your dashboard
  2. Verify your domain to send emails
Need help with DNS records? Check out our step-by-step DNS setup guide.

​
SMTP Credentials

Configure your SMTP client with these settings:
SettingValue
Hostsmtp.maildiver.com
Usernamemaildiver
PasswordMAILDIVER_API_KEY
Ports587 (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.
PortTypeSecurity
587STARTTLSExplicit SSL/TLS (starts plain, upgrades to SSL/TLS) - Recommended
465ImplicitImplicit 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:
FieldRequirementMax Length/Size
FromRequired, valid email100 characters
ToRequired, at least 1 recipient50 recipients
CCOptional50 recipients
BCCOptional50 recipients
Reply-ToOptional50 recipients
SubjectRequired100 characters
HTMLAt least HTML or text required40MB
TextAt least HTML or text required10MB
AttachmentsOptional10 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: 
await transporter.sendMail({
  from: 'hello@yourdomain.com',
  to: 'customer@example.com',
  subject: 'Special Offer',
  html: '<h1>Hello {{name}}!</h1><p>Get {{discount}}% off with code: {{code}}</p>',
  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: 
await transporter.sendMail({
  from: 'hello@yourdomain.com',
  to: 'customer@example.com',
  subject: 'Welcome Email',
  html: '<p>Fallback content if template not found</p>',
  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 to discuss your requirements.

​
Testing Your Connection

Use the swaks command-line tool to quickly test your SMTP connection: 
# 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 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

Nodemailer Guide

Learn how to send emails with Nodemailer, including connection pooling and attachments

​
Support

Need help with SMTP integration?