Sendpit Integration Guide

Introduction

Sendpit is an email testing platform that captures outgoing emails from your application during development and QA. It provides isolated SMTP mailboxes so you can test email functionality without sending messages to real recipients.

SMTP integration uses standard configuration with no special SDK. The REST API is optional for programmatic message submission and inspection.

SMTP Credentials

Each Sendpit mailbox provides unique SMTP credentials:

Prefer port 587. Port 2525 is a non-standard compatibility fallback for networks that block standard submission ports. It requires explicit client configuration and STARTTLS; IANA assigns TCP/2525 to ms-v-worlds, not SMTP.

Environment Variable Convention

SMTP_HOST=smtp.sendpit.com
SMTP_PORT=587
SMTP_USERNAME=mb_your_mailbox_username
SMTP_PASSWORD=your_mailbox_smtp_password

Credentials are available in your Sendpit dashboard under Mailbox → Settings → SMTP Credentials.

Quick Start (Generic SMTP)

Configure any application or library that supports SMTP with these settings:

Host:       smtp.sendpit.com
Port:       587 or 2525 (STARTTLS), or 465 (implicit TLS)
Username:   <your mailbox username>
Password:   <your mailbox password>
Encryption: STARTTLS on 587/2525, implicit TLS on 465
Auth:       PLAIN or LOGIN (after TLS)

Send a test email using your application's normal email functionality. The message appears in your Sendpit mailbox within seconds.

Language-Specific Integration

Looking for a deep-dive guide? We have comprehensive setup guides for Laravel, Django & Python, Node.js, Ruby on Rails, and Docker.

PHP (Laravel)

.env

MAIL_MAILER=smtp
MAIL_HOST=smtp.sendpit.com
MAIL_PORT=587
MAIL_USERNAME=mb_your_mailbox_username
MAIL_PASSWORD=your_mailbox_smtp_password
MAIL_SCHEME=smtp
MAIL_REQUIRE_TLS=true
MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME="${APP_NAME}"

Laravel 12's SMTP mailer must include 'require_tls' => env('MAIL_REQUIRE_TLS', true) in config/mail.php; see the full Laravel guide for the complete config, Mailables, and testing examples.

Node.js (Nodemailer)

Install

npm install nodemailer

.env

SMTP_HOST=smtp.sendpit.com
SMTP_PORT=587
SMTP_USERNAME=mb_your_mailbox_username
SMTP_PASSWORD=your_mailbox_smtp_password

Transporter config

const nodemailer = require('nodemailer');

const transporter = nodemailer.createTransport({
  host: process.env.SMTP_HOST,
  port: parseInt(process.env.SMTP_PORT, 10),
  secure: false, // Use STARTTLS
  requireTLS: true, // Require STARTTLS upgrade
  auth: {
    user: process.env.SMTP_USERNAME,
    pass: process.env.SMTP_PASSWORD,
  },
});

For sending examples plus Express, NestJS, and Next.js setups, see the full Node.js guide.

Python (smtplib)

.env

SMTP_HOST=smtp.sendpit.com
SMTP_PORT=587
SMTP_USERNAME=mb_your_mailbox_username
SMTP_PASSWORD=your_mailbox_smtp_password

send_email.py

import os
import ssl
import smtplib
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart

smtp_host = os.environ['SMTP_HOST']
smtp_port = int(os.environ['SMTP_PORT'])
smtp_user = os.environ['SMTP_USERNAME']
smtp_pass = os.environ['SMTP_PASSWORD']
tls_context = ssl.create_default_context()

msg = MIMEMultipart('alternative')
msg['Subject'] = 'Test from Sendpit'
msg['From'] = 'noreply@example.com'
msg['To'] = 'recipient@example.com'

text = 'This is a test email.'
html = '<p>This is a test email.</p>'

msg.attach(MIMEText(text, 'plain'))
msg.attach(MIMEText(html, 'html'))

with smtplib.SMTP(smtp_host, smtp_port) as server:
    server.starttls(context=tls_context)
    server.login(smtp_user, smtp_pass)
    server.sendmail(msg['From'], msg['To'], msg.as_string())

print('Email sent successfully')

Using Django or Flask? See the full Django & Python guide.

Ruby (Action Mailer / Rails)

config/environments/development.rb

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: ENV['SMTP_HOST'],
  port: ENV['SMTP_PORT'].to_i,
  user_name: ENV['SMTP_USERNAME'],
  password: ENV['SMTP_PASSWORD'],
  authentication: :plain,
  enable_starttls: true
}

.env

SMTP_HOST=smtp.sendpit.com
SMTP_PORT=587
SMTP_USERNAME=mb_your_mailbox_username
SMTP_PASSWORD=your_mailbox_smtp_password

For mailer classes, encrypted Rails credentials, per-environment configs, Sinatra, and RSpec/Minitest testing, see the full Ruby on Rails guide.

Ruby (Net::SMTP standalone)

require 'net/smtp'

smtp_host = ENV['SMTP_HOST']
smtp_port = ENV['SMTP_PORT'].to_i
smtp_user = ENV['SMTP_USERNAME']
smtp_pass = ENV['SMTP_PASSWORD']

message = <<~MESSAGE
From: noreply@example.com
To: recipient@example.com
Subject: Test from Sendpit

This is a test email.
MESSAGE

smtp = Net::SMTP.new(smtp_host, smtp_port)
smtp.enable_starttls  # Enable STARTTLS
smtp.start('localhost', smtp_user, smtp_pass, :plain) do |server|
  server.send_message(message, 'noreply@example.com', 'recipient@example.com')
end

puts 'Email sent successfully'

Java (Jakarta Mail)

pom.xml

<dependency>
    <groupId>com.sun.mail</groupId>
    <artifactId>jakarta.mail</artifactId>
    <version>2.0.1</version>
</dependency>

SendEmail.java

import jakarta.mail.*;
import jakarta.mail.internet.*;
import java.util.Properties;

public class SendEmail {
    public static void main(String[] args) {
        String host = System.getenv("SMTP_HOST");
        String port = System.getenv("SMTP_PORT");
        String username = System.getenv("SMTP_USERNAME");
        String password = System.getenv("SMTP_PASSWORD");

        Properties props = new Properties();
        props.put("mail.smtp.host", host);
        props.put("mail.smtp.port", port);
        props.put("mail.smtp.auth", "true");
        props.put("mail.smtp.starttls.enable", "true");
        props.put("mail.smtp.starttls.required", "true");

        Session session = Session.getInstance(props, new Authenticator() {
            @Override
            protected PasswordAuthentication getPasswordAuthentication() {
                return new PasswordAuthentication(username, password);
            }
        });

        try {
            Message message = new MimeMessage(session);
            message.setFrom(new InternetAddress("noreply@example.com"));
            message.setRecipients(Message.RecipientType.TO,
                InternetAddress.parse("recipient@example.com"));
            message.setSubject("Test from Sendpit");
            message.setText("This is a test email.");

            Transport.send(message);
            System.out.println("Email sent successfully");

        } catch (MessagingException e) {
            throw new RuntimeException(e);
        }
    }
}

Go (net/smtp)

main.go

package main

import (
	"crypto/tls"
	"fmt"
	"net"
	"net/smtp"
	"os"
)

func main() {
	host := os.Getenv("SMTP_HOST")
	port := os.Getenv("SMTP_PORT")
	username := os.Getenv("SMTP_USERNAME")
	password := os.Getenv("SMTP_PASSWORD")

	from := "noreply@example.com"
	to := "recipient@example.com"

	msg := []byte("To: recipient@example.com\r\n" +
		"Subject: Test from Sendpit\r\n" +
		"\r\n" +
		"This is a test email.\r\n")

	// Connect to server
	conn, err := net.Dial("tcp", host+":"+port)
	if err != nil {
		fmt.Printf("Connection error: %v\n", err)
		return
	}

	client, err := smtp.NewClient(conn, host)
	if err != nil {
		fmt.Printf("Client error: %v\n", err)
		return
	}
	defer client.Close()

	// Upgrade to TLS (STARTTLS)
	tlsConfig := &tls.Config{ServerName: host}
	if err = client.StartTLS(tlsConfig); err != nil {
		fmt.Printf("STARTTLS error: %v\n", err)
		return
	}

	// Authenticate
	auth := smtp.PlainAuth("", username, password, host)
	if err = client.Auth(auth); err != nil {
		fmt.Printf("Auth error: %v\n", err)
		return
	}

	// Send email
	if err = client.Mail(from); err != nil {
		fmt.Printf("Mail error: %v\n", err)
		return
	}
	if err = client.Rcpt(to); err != nil {
		fmt.Printf("Rcpt error: %v\n", err)
		return
	}

	w, err := client.Data()
	if err != nil {
		fmt.Printf("Data error: %v\n", err)
		return
	}
	_, err = w.Write(msg)
	if err != nil {
		fmt.Printf("Write error: %v\n", err)
		return
	}
	err = w.Close()
	if err != nil {
		fmt.Printf("Close error: %v\n", err)
		return
	}

	client.Quit()
	fmt.Println("Email sent successfully")
}

.env (load with godotenv or export manually)

SMTP_HOST=smtp.sendpit.com
SMTP_PORT=587
SMTP_USERNAME=mb_your_mailbox_username
SMTP_PASSWORD=your_mailbox_smtp_password

Common SMTP Errors & Troubleshooting

Authentication Failed

535 5.7.8 Authentication credentials invalid

Causes:

• Incorrect username or password
• Credentials copied with trailing whitespace
• Mailbox deleted or credentials regenerated

Fix:

• Re-copy credentials from the Sendpit dashboard
• Verify no extra spaces in .env file
• Check that the mailbox still exists

Connection Refused

Connection refused (port 587)

Causes:

• Firewall blocking outbound port 587
• Corporate network restrictions
• Incorrect host or port

Fix:

• Verify smtp.sendpit.com:587 is reachable: telnet smtp.sendpit.com 587
• If port 587 is blocked, explicitly try the non-standard 2525 compatibility fallback with STARTTLS
• Contact your network administrator if both STARTTLS ports are blocked
• Some corporate networks require VPN or allowlisting

TLS/SSL Errors

SSL routines:ssl3_get_record:wrong version number

Causes:

• Encryption mode does not match the port (implicit TLS against STARTTLS port 587/2525, or STARTTLS against implicit-TLS port 465)
• TLS configuration mismatch

Fix:

• Match the encryption to the port: STARTTLS on 587/2525, implicit TLS (SSL) on 465
• Use port 587 or 2525 (STARTTLS), or 465 (implicit TLS)
• Ensure secure: false with requireTLS: true in Node.js (Nodemailer)
• Sendpit requires TLS; SMTP authentication happens only after the STARTTLS upgrade

Connection Timeout

Connection timed out after 30 seconds

Causes:

• Network latency or routing issues
• DNS resolution problems
• Firewall silently dropping packets

Fix:

• Test connectivity: nc -zv smtp.sendpit.com 587
• Try from a different network
• Check DNS resolution: nslookup smtp.sendpit.com

Rate Limiting

Sendpit enforces connection concurrency and rolling connection windows, with additional controls around repeated authentication failures. A busy source can receive a temporary 421 response; an unavailable authentication dependency or temporary credential check can return 454.

Best practice: Treat 421 and 454 as transient failures, retry with bounded exponential backoff and jitter, and avoid reconnecting for every message in a bulk test.

Security & Best Practices

Keep Credentials in Environment Variables

Never hardcode SMTP credentials in source code.

// Bad
$password = 'your_mailbox_smtp_password';

// Good
$password = env('MAIL_PASSWORD');

Use .env Files (Not Committed to Git)

# .gitignore
.env
.env.local
.env.*.local

Rotate Credentials Periodically

Regenerate SMTP credentials in the Sendpit dashboard if:

• A team member leaves
• Credentials may have been exposed
• As part of regular security hygiene

Regenerating credentials immediately invalidates the old password.

Use Separate Mailboxes per Environment

This prevents test data from mixing and simplifies debugging.

Avoid Logging Credentials

Keep SMTP settings out of exception context and structured log fields, and use your framework's supported redaction or log-processor mechanism. Never emit the SMTP DSN, password, authentication exchange, or complete environment.

API Access and Limitations

Sendpit captures emails via SMTP and provides a REST API for programmatic retrieval (Basic plan and above). The following summarizes what is and is not available:

For REST API documentation, see the Developer Docs. For SMTP setup, continue below.

Next Steps: Webhook Automation

Once SMTP integration is working, you can automate workflows using webhooks (Pro plans and above).

Webhooks notify your application in real-time when emails arrive-useful for:

• CI/CD pipelines that verify email delivery
• Automated QA workflows
• Custom integrations and alerting

Learn more: Developer Documentation → Webhooks

Quick Connectivity Test

Before troubleshooting application issues, verify basic connectivity:

# Test TCP connection
nc -zv smtp.sendpit.com 587

# Test with telnet (interactive)
telnet smtp.sendpit.com 587

# Test DNS resolution
nslookup smtp.sendpit.com

# Test with OpenSSL (if TLS issues suspected)
openssl s_client -connect smtp.sendpit.com:587 -starttls smtp

If these commands fail, the issue is network-level (firewall, DNS, routing), not application configuration.

Last updated: December 2025