Skip to main content

​
Prerequisites

Before setting up the Custom SMTP integration, ensure you have:

​
1. SMTP Server

  • A running SMTP server (Postfix or any standards-compliant MTA)
  • Hostname or IP and port (e.g., 25, 465, 587, 2525)
  • Connection security: None, STARTTLS, or TLS
  • Authentication (if required): PLAIN or LOGIN; username and password
OAuth or token-based SMTP auth is not supported. Only PLAIN/LOGIN and unauthenticated connections are supported.

​
2. SendPost Account

  • A SendPost account with admin access
  • At least one sub-account created
  • Your sending domain verified in SendPost (same domain your MTA uses)

​
3. Bounce Domain (Already Configured)

Your verified domain should already have bounce handling: sp-bounce.{domain} CNAME’d to sp.sendpost.info. Custom SMTP reuses this; no additional DNS changes are required.

​
Setting Up Custom SMTP Integration

​
Step 1: Create Custom SMTP TPSP

  1. Log in to your SendPost Dashboard
  2. Go to Settings → Providers
  3. Click NEW and select Custom SMTP as the provider type

​
Step 2: Configure SMTP Settings

Fill in the form:
FieldDescription
NameA human-readable label (e.g., “Postfix Cluster US-East”)
SMTP HostHostname or IP of your SMTP server (e.g., smtp.customer.com)
SMTP PortDefault 587; options include 25, 465, 587, 2525
Connection SecurityNone / STARTTLS / TLS
AuthenticationNone / PLAIN / LOGIN
UsernameSMTP username (if auth is enabled)
PasswordSMTP password (if auth is enabled)
Max Rate Per HourGlobal rate limit for this TPSP (default 60)

​
Step 3: Test Connection (Required)

Before you can create the TPSP, you must click Test Connection. This runs a full SMTP connectivity test using the details you entered:
TCP dial → EHLO → STARTTLS (if configured) → AUTH (if configured) → MAIL FROM → RCPT TO → DATA (minimal test message) → QUIT
  • If the test passes: The Submit button is enabled. Click Submit to create the Custom SMTP TPSP. SendPost then creates the record, initializes per-provider hubs and consumers, and generates the Event Ingestion API Key.
  • If the test fails: A descriptive error is shown (e.g., connection refused, TLS handshake failed, auth rejected, MAIL FROM/RCPT TO/DATA failure, timeout). Fix your server or firewall, then run Test Connection again. Submit remains disabled until the test passes.
Save the Event Ingestion API Key when it is displayed. It is shown only once and is required to install the event reporting agent.

​
Step 4: Install Event Reporting Agent

To get delivered, bounced, and deferred events from your MTA (in addition to synchronous sent and SendPost tracking), install the event reporting agent on the server where your MTA runs. The UI shows a one-liner install command. For Postfix: 
curl -sSL https://sendpost-agent.s3.us-east-1.amazonaws.com/agent | sudo bash -s -- \
  --api-key <EVENT_INGESTION_KEY> \
  --mta postfix \
  --endpoint https://events.sendpost.io/api/v1/tpsp/custom-smtp/events
Replace <EVENT_INGESTION_KEY> with the key from Step 3. The agent tails the Postfix mail log, parses delivery/bounce/defer entries, and batches them to SendPost’s event ingestion endpoint. See Event Reporting Agent for configuration, log path, and health checks.

​
Step 5: Configure IP Pool for Custom SMTP Routing

  1. Go to Settings → IP Pools
  2. Create a new IP Pool or edit an existing one
  3. Configure routing so that traffic is sent to your Custom SMTP TPSP (e.g., set a percentage or use it as primary/failover)
  4. Save. Use the pool name in API calls via the ippool parameter.

​
Step 6: Send Test Email

Use the Send Test button in the provider setup (or send via API with the correct ippool). Confirm:
  • CSProcessed – message queued
  • CSSent – your MTA returned 2xx (accepted for delivery)
  • CSOpen / CSClick – if tracking is enabled
  • CSDelivered – after the agent reports from your MTA logs (if agent is installed)

​
Setup Checklist in UI

After creation, the dashboard shows:
  • SMTP connectivity: ✓ (verified at creation)
  • Agent status: ✓ when agent_last_seen_at is recent, or ⚠️ if the agent has not reported yet or is stale

​
Next Steps