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

# Troubleshooting & FAQs

> Common issues, solutions, and frequently asked questions for Custom SMTP integration with SendPost.

## Common Issues

<AccordionGroup>
  <Accordion title="TPSP Creation Fails (SMTP Connectivity Test)" icon="envelope">
    **Symptoms**: "Connection refused", "TLS handshake failed", "Auth rejected", "MAIL FROM/RCPT TO/DATA failure", or "Timeout" when creating the Custom SMTP provider.

    **Checklist**:

    * Ensure the SMTP host and port are reachable from SendPost (firewall, security groups)
    * For STARTTLS/TLS: verify certificate and that the server supports the chosen security
    * For auth: confirm username/password are correct and the server accepts PLAIN or LOGIN
    * Try connecting manually: `telnet smtp.yourhost.com 587` or `openssl s_client -connect smtp.yourhost.com:587 -starttls smtp`

    **Note**: At creation, SendPost runs a **full SMTP transaction** (EHLO, STARTTLS if configured, AUTH if configured, MAIL FROM, RCPT TO, DATA with minimal test message, QUIT). Any step can cause rejection. You can test without creating: `POST /api/v1/tpsp/test/custom-smtp` with the same SMTP config in the body.
  </Accordion>

  <Accordion title="Emails Not Sending / CSDropped" icon="circle-xmark">
    **Symptoms**: Messages show CSDropped or never reach your MTA.

    **Checklist**:

    * **No return path domain**: If CSDropped shows "No verified return path domain configured for sender domain", the sender domain has no verified return path; this is non-retryable.
    * Confirm the IP Pool used in the request routes to your Custom SMTP TPSP
    * Check that your SMTP server is up and accepting connections on the configured port
    * Review CSDropped event details: SMTP code and description indicate relay failure (e.g., 5xx, connection timeout)
    * Ensure rate limits (global and per-provider) are not exceeded
    * Verify no suppression or validation rules are dropping the message before relay

    **Retry behavior**: SendPost retries up to 5 times with linear backoff (1h, 2h, 3h, 4h, 5h). CSDropped is emitted after all retries fail, or immediately for non-retryable failures (e.g. missing return path domain).
  </Accordion>

  <Accordion title="Events Not Appearing (Agent)" icon="bell-slash">
    **Symptoms**: CSSent and opens/clicks appear, but CSDelivered / CSHardBounced / CSSoftBounced from the MTA do not.

    **Checklist**:

    * Confirm the event reporting agent is installed and running on the MTA server
    * Verify the agent uses the correct Event Ingestion API Key (header `X-SP-Event-ApiKey`)
    * Ensure each event has valid `message_id` (SendPost UUID) and `event_type` in `delivered`, `bounced`, `deferred`, `soft_bounced`
    * Check agent config: correct log path (e.g. `/var/log/mail.log`), endpoint URL
    * Ensure Postfix preserves headers (e.g. `X-Sendpost-Message-UUID`) so the agent can correlate queue ID → message UUID
    * Check agent health: `http://localhost:9113/health` and logs for parse/connect errors
    * In SendPost dashboard: "Agent status" should show ✓ when agent has reported recently

    **Note**: Deferred events are accepted by the API but **not stored** (by design); they will not appear in the UI.
  </Accordion>

  <Accordion title="Bounces Not Reflected" icon="rotate-left">
    **Symptoms**: Recipient bounces not showing as CSHardBounced / CSSoftBounced.

    **Checklist**:

    * **Agent**: The agent sends `bounced` or `soft_bounced`; SendPost classifies to CSHardBounced vs CSSoftBounced using the SMTP description (keyword-based). Ensure the agent is running and includes `smtp_description` when available.
    * **Bounce processor**: Async DSNs must go to your bounce address. Return-Path is `bounces+{uuid}+{said}@sp-bounce.{domain}`; ensure `sp-bounce.{domain}` CNAMEs to `sp.sendpost.info` and that your MTA sends bounces to that address.
    * In Events, filter by CSHardBounced (63) and CSSoftBounced (64).
  </Accordion>

  <Accordion title="Deferred not visible in UI" icon="circle-info">
    By design, deferred events are **accepted by the event ingestion API but not stored**. They do not appear in the Events page or analytics. Only delivered, hard bounce, and soft bounce from the agent are stored.
  </Accordion>

  <Accordion title="Agent Correlation Warnings" icon="code">
    **Symptoms**: Agent logs "unknown queue ID" or delivery entries not matching any message.

    **Causes**: Postfix queue ID rewritten (e.g. content\_filter), or custom headers stripped so message-id/UUID is lost.

    **Mitigation**: Preserve `X-Sendpost-Message-UUID` (or the header used for correlation) through your Postfix pipeline. Document required Postfix config in your runbook.
  </Accordion>
</AccordionGroup>

***

## Getting Help

If issues persist:

1. **Events**: Use the SendPost Events page with filters (provider, event type, date) and note message IDs and timestamps.
2. **Support**: Contact SendPost support with:
   * Account ID and Custom SMTP TPSP ID
   * Message ID(s) and example timestamps
   * Error messages or SMTP codes from CSDropped/agent logs
   * Whether the agent is installed and agent\_last\_seen\_at recent

***

## FAQs

<AccordionGroup>
  <Accordion title="Can I use multiple Custom SMTP servers?">
    Yes. Create a separate Custom SMTP TPSP for each server. Each has its own Event Ingestion API Key and agent config. One TPSP maps to one SMTP server; for HA, put a load balancer in front of your MTAs.
  </Accordion>

  <Accordion title="Is the Event Ingestion API Key the same as my SendPost API key?">
    No. The Event Ingestion API Key is scoped only to that Custom SMTP TPSP and is used only to authenticate event submissions from the agent. It cannot send email or access other SendPost APIs.
  </Accordion>

  <Accordion title="Does SendPost sign DKIM for Custom SMTP?">
    SendPost prepares the message including DKIM signing (using your verified domain keys) before relaying to your SMTP server. Your MTA receives a fully-formed message. (Whether SendPost signs for Custom SMTP in all cases is product-specific; see PRD for current scope.)
  </Accordion>

  <Accordion title="What if my SMTP server goes down?">
    Messages stay in the queue and are retried (up to 5 times with backoff). If all retries fail, SendPost emits CSDropped. You are responsible for your MTA availability.
  </Accordion>

  <Accordion title="Can I route some traffic to Custom SMTP and some to SendPost IPs?">
    Yes. Use IP Pools: create a pool that routes a percentage to your Custom SMTP TPSP and the rest to SendPost IPs (or other TPSPs). Use the `ippool` parameter in the send API.
  </Accordion>

  <Accordion title="Is the agent open source?">
    The agent can be distributed as a binary; see product documentation for source availability. It is a single binary, runs as an unprivileged user, and only reads MTA logs (no write access to Postfix).
  </Accordion>

  <Accordion title="How do I update the agent?">
    Manual updates only. Re-run the install script or replace the binary and restart the service.
  </Accordion>

  <Accordion title="Are duplicate events possible?">
    SendPost may deduplicate terminal bounce events (e.g. agent and bounce processor both reporting). Non-terminal events (e.g. CSSent and CSDelivered) are distinct and both are stored.
  </Accordion>
</AccordionGroup>