Skip to main content

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.

​
Common Issues

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

​
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

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.
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.
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.)
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.
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.
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).
Manual updates only. Re-run the install script or replace the binary and restart the service.
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.