SMTP API

Overview

The MXroute SMTP API provides a simple HTTP-based interface for sending emails through MXroute's SMTP servers. Instead of configuring SMTP directly in your application, you can send emails via HTTP POST requests to our hosted API endpoint at smtpapi.mxroute.com.

This API is particularly useful for:

• Applications that have difficulty with SMTP configuration
• Serverless environments where persistent SMTP connections aren't ideal
• Quick integrations without dealing with SMTP libraries
• Scenarios where firewall rules block SMTP ports

API Endpoint

URL: https://smtpapi.mxroute.com/
Method: POST
Content-Type: application/json

Authentication

The API uses your existing MXroute email credentials. Each request must include:

• Your MXroute server hostname
• Your email account username (typically your full email address)
• Your email account password

Request Format

Required Fields

Field	Type	Description
server	string	Your MXroute server hostname (e.g., tuesday.mxrouting.net, heracles.mxrouting.net)
username	string	Your SMTP username (usually your full email address)
password	string	Your SMTP password
from	string	The sender's email address (must be an address you control)
to	string	The recipient's email address
subject	string	Email subject line
body	string	Email body content (HTML supported)

Example Request

curl -X POST https://smtpapi.mxroute.com/ \
  -H "Content-Type: application/json" \
  -d '{
    "server": "tuesday.mxrouting.net",
    "username": "noreply@yourdomain.com",
    "password": "your_password",
    "from": "noreply@yourdomain.com",
    "to": "customer@example.com",
    "subject": "Order Confirmation",
    "body": "<h2>Thank you for your order!</h2><p>Your order has been confirmed and will be processed shortly.</p>"
  }'

Response Format

The API returns JSON responses indicating success or failure.

Success Response

{
  "success": true,
  "message": "Email sent successfully."
}

Error Response

{
  "success": false,
  "message": "Invalid server specified."
}

Common error messages include:

• "Invalid server specified" - The server hostname is not recognized
• "Missing required field: [field]" - A required field is missing from the request
• "Invalid JSON format" - The request body is not valid JSON
• "Authentication failed" - Username/password combination is incorrect

Code Examples

PHP

<?php
$data = [
    'server' => 'tuesday.mxrouting.net',
    'username' => 'noreply@yourdomain.com',
    'password' => 'your_password',
    'from' => 'noreply@yourdomain.com',
    'to' => 'customer@example.com',
    'subject' => 'Welcome!',
    'body' => '<p>Welcome to our service!</p>'
];

$ch = curl_init('https://smtpapi.mxroute.com/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['success']) {
    echo "Email sent successfully!";
} else {
    echo "Error: " . $result['message'];
}
?>

Python

import requests
import json

data = {
    'server': 'tuesday.mxrouting.net',
    'username': 'noreply@yourdomain.com',
    'password': 'your_password',
    'from': 'noreply@yourdomain.com',
    'to': 'customer@example.com',
    'subject': 'Welcome!',
    'body': '<p>Welcome to our service!</p>'
}

response = requests.post(
    'https://smtpapi.mxroute.com/',
    json=data,
    headers={'Content-Type': 'application/json'}
)

result = response.json()
if result['success']:
    print("Email sent successfully!")
else:
    print(f"Error: {result['message']}")

Node.js

const fetch = require('node-fetch');

const data = {
    server: 'tuesday.mxrouting.net',
    username: 'noreply@yourdomain.com',
    password: 'your_password',
    from: 'noreply@yourdomain.com',
    to: 'customer@example.com',
    subject: 'Welcome!',
    body: '<p>Welcome to our service!</p>'
};

fetch('https://smtpapi.mxroute.com/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => {
    if (result.success) {
        console.log('Email sent successfully!');
    } else {
        console.error('Error:', result.message);
    }
});

Security Considerations

HTTPS Required

All requests must be made over HTTPS. The API will reject non-secure connections to protect your credentials.

Credential Storage

• Never hardcode credentials in your source code
• Use environment variables or secure configuration files
• Consider using application-specific passwords if available
• Rotate passwords regularly

Rate Limiting

The API implements rate limiting to prevent abuse. If you need to send high volumes of email, consider:

• Implementing retry logic with exponential backoff
• Spreading sends over time
• Using SMTP directly for bulk operations

Input Validation

• The API validates all input fields
• Email addresses are checked for proper format
• Server hostnames must be valid MXroute servers
• HTML content is allowed but should be properly formatted

Limitations

• Single recipient only: Each API call sends to one recipient. For multiple recipients, make separate API calls.
• No attachments: The current version does not support file attachments. Use SMTP directly if you need to send attachments.
• Message size: Email body content is limited to reasonable sizes (typically under 10MB including HTML).
• HTML only in body: The API supports HTML in the body field but not in other fields like subject.

Best Practices

1. Error Handling: Always check the success field in the response and handle errors appropriately.

2. Logging: Log API responses for debugging, but ensure you don't log sensitive information like passwords.

3. Retry Logic: Implement retry logic for transient failures, but respect rate limits.

4. Testing: Use a test email address as the recipient during development to avoid sending emails to real users.

5. From Address: Always use a from address that you own and have configured in your MXroute account.

Troubleshooting

Authentication Failed

• Verify your username is the full email address
• Check that your password is correct
• Ensure you're using the correct server hostname

Invalid Server

• Double-check your server hostname (found in your MXroute welcome email)
• Common servers include: tuesday.mxrouting.net, heracles.mxrouting.net, echo.mxrouting.net

Email Not Delivered

• Check spam folders at the recipient
• Verify SPF, DKIM, and DMARC records are properly configured
• Ensure the from address is a valid address on your account

Rate Limit Exceeded

• Implement exponential backoff
• Reduce sending frequency
• Contact support if you need higher limits

Alternative Methods

If the SMTP API doesn't meet your needs, consider these alternatives:

• Direct SMTP: Configure your application to use SMTP directly (see Email Server Settings)
• Email Clients: Use email client integrations for manual sending
• SMTP Libraries: Most programming languages have robust SMTP libraries (PHPMailer, Nodemailer, smtplib, etc.)

Support

For issues specific to the SMTP API, include the following in your support ticket:

• The exact error message received
• Server hostname you're trying to use
• Timestamp of the failed attempt
• Sanitized example of your API request (remove passwords)