> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendpost.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting Up Custom SMTP Integration

> Configure your own SMTP server as a Third-Party Sending Provider in SendPost with connectivity validation and event reporting.

## 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

<Note>
  OAuth or token-based SMTP auth is not supported. Only PLAIN/LOGIN and unauthenticated connections are supported.
</Note>

### 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](https://app.sendpost.io)
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:

| Field                   | Description                                                    |
| ----------------------- | -------------------------------------------------------------- |
| **Name**                | A human-readable label (e.g., "Postfix Cluster US-East")       |
| **SMTP Host**           | Hostname or IP of your SMTP server (e.g., `smtp.customer.com`) |
| **SMTP Port**           | Default 587; options include 25, 465, 587, 2525                |
| **Connection Security** | None / STARTTLS / TLS                                          |
| **Authentication**      | None / PLAIN / LOGIN                                           |
| **Username**            | SMTP username (if auth is enabled)                             |
| **Password**            | SMTP password (if auth is enabled)                             |
| **Max Rate Per Hour**   | Global 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:

<Check>TCP dial → EHLO → STARTTLS (if configured) → AUTH (if configured) → MAIL FROM → RCPT TO → DATA (minimal test message) → QUIT</Check>

* **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.

<Warning>
  **Save the Event Ingestion API Key** when it is displayed. It is shown only once and is required to install the event reporting agent.
</Warning>

### 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:

```bash theme={null}
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](/guides/custom-smtp/event-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

* [Send emails via Custom SMTP](/guides/custom-smtp/sending-emails) using the SendPost API
* [Configure the event agent](/guides/custom-smtp/event-agent) for delivered/bounced/deferred events
* [View event types](/guides/custom-smtp/event-types) and [analytics](/guides/custom-smtp/analytics)