BYOSMTP in NimbusOS means you run the sending infrastructure and NimbusOS runs the platform on top. You connect any mailbox that speaks SMTP and IMAP with your own credentials, and the platform handles everything else: rotation, scoring, reply sync, bounce classification, deliverability alerts. This article covers the connection flow, the validation checks, the credential security model, and the operational tradeoffs of going custom versus hosted.
Why BYOSMTP
Three reasons usually drive the decision.
Full control over infrastructure. Your IP, your DNS, your reputation, your choice of ESP or self-hosted relay. If you already operate an Amazon SES, Postmark, Sparkpost, or self-hosted Postfix setup, BYOSMTP lets NimbusOS use it directly.
Regulatory or procurement constraints. Some organizations cannot send through a third-party relay. BYOSMTP keeps the send path inside your controlled infrastructure.
Cost at very large scale. At volumes above 200,000 sends per day, owning the send path often costs less than paying per-send to a managed relay.
The tradeoff: you own the deliverability outcomes. The platform will monitor and alert, but it cannot fix a poisoned IP or a misconfigured DKIM record that lives outside its reach.
Supported Connection Modes
NimbusOS BYOSMTP supports three SMTP modes and one IMAP mode.
SMTP with SSL on port 465. Most common for modern providers. Full TLS from connection open.
SMTP with STARTTLS on port 587. Plain connection that upgrades to TLS after the EHLO exchange. Supported by nearly every ESP.
SMTP on port 25 with no TLS. Supported but strongly discouraged. Most ISPs will reject or quarantine mail that arrived over cleartext. Only use this for internal relay setups where the mail is re-encrypted before leaving your network.
IMAP on port 993 with SSL. For reply sync. Used to pull inbound messages into the unified inbox and for reply classification.
The Connection Flow
Open /email-accounts and click Connect Account. Choose Custom SMTP. You enter seven fields.
- SMTP host
- SMTP port
- SMTP mode (SSL, STARTTLS, none)
- Username (usually the email address)
- Password or API key
- IMAP host
- IMAP port
On submit, the platform runs three validation checks in sequence.
Check 1: DNS validation
Before any connection attempt, the platform resolves the SMTP host's MX record, the sending domain's SPF record, the DKIM selector's TXT record, and the DMARC policy. If any of those is missing or misaligned, the connection is rejected with a specific error indicating which record is wrong.
This is important. A badly configured DNS setup will pass a simple SMTP login test but fail on every outbound send because the receiving ISP cannot authenticate the message. The platform blocks the connection before you start burning reputation.
Check 2: Authentication and connection test
The platform opens an SMTP connection using the provided credentials, issues a test send to an internal NimbusOS address, and confirms the SMTP server accepts the message with a 250 OK. Parallel to that, it opens an IMAP connection, lists folders, and reads the INBOX message count.
Both legs must succeed. Common failures at this step:
- 535 auth failure (wrong password, or 2FA without an app password)
- 530 must issue STARTTLS first (wrong SMTP mode)
- TLS handshake failure (unsupported cipher, usually on older relays)
- 550 Relay access denied (IP not whitelisted for the relay)
Check 3: Roundtrip reply test
The test message the platform sent is picked up from the IMAP side. The platform confirms it can read the message it just sent. This proves the IMAP credentials resolve to the same mailbox the SMTP credentials authorize against. Mismatched SMTP and IMAP credentials is a surprisingly common cause of reply sync that silently drops inbound messages.
If all three checks pass, the EmailAccountHealth row is created with a starting overall_score of 50 (a neutral starting point for a BYOSMTP account). The inbox enters stage 0 and warmup enrollment begins.
Credential Security Model
Every stored credential is encrypted with Fernet, a symmetric authenticated encryption scheme built on AES-128-CBC and HMAC-SHA256. The encryption key is workspace scoped and rotated on a schedule.
Three properties of the security model are worth understanding.
Database dump is not enough. A raw database backup contains the ciphertext but not the key. The key lives in the application secrets store, not in the database.
Access is gated at the ORM layer. The EncryptedCharField custom field type handles encrypt on save and decrypt on read. The plaintext is never written to the database and only exists in memory during a send operation.
Audit trail on every decrypt. A decrypt operation writes an AuditLog row with the user (or system process), the workspace, and the purpose. The log makes credential access observable.
The practical implication: credentials you paste into NimbusOS are as protected as your workspace secrets, not more and not less. If you consider your workspace access sensitive, the credentials are held with that same posture.
Rate Limits and SMTP Throttling
Custom SMTP servers usually have their own rate limits. NimbusOS respects them through the daily_send_limit field on the account, which you configure at connection time.
If you do not know the limit of your SMTP provider, start at 100 per day and watch the provider's admin console during the first week. If the provider has API visibility, you can also configure the platform to pull the provider's limit directly by adding the provider's API key in Integrations. The most common providers (SES, Postmark, Sparkpost, Sendgrid) expose their daily limit via API and NimbusOS will read it.
The SMTP connection itself has a per-connection rate limit. The platform reuses SMTP connections across sends to avoid reconnection overhead, but it also throttles sends within a single connection. The default throttle is 5 sends per second per connection, which matches the ReachInbox client rate limit and is tolerable for nearly every SMTP relay.
Reply Sync Interval
IMAP reply sync pulls new messages every 2 minutes by default. You can lower this to 30 seconds for urgent reply workflows or raise it to 10 minutes for quieter campaigns.
Sync runs the UIDNEXT IMAP command to identify new messages since last poll, then fetches only the new message bodies. A busy mailbox with 1000 inbound messages per day costs negligible bandwidth even at 30 second polling.
Warmup on BYOSMTP Inboxes
Warmup works on BYOSMTP but uses the platform's native warmup engine rather than the ReachInbox partner network. This has two implications.
The warmup partner pool is smaller, so stage progression is 40 to 50 percent slower compared to a ReachInbox hosted inbox. Plan for 4 weeks to stage 3 rather than 2 weeks.
The IP you send from is your responsibility. The platform cannot fix a poisoned IP or a shared IP neighborhood problem. If warmup stalls and all other signals look clean, the IP itself may be the issue. Ask the SMTP provider to confirm the IP reputation.
DNS Records You Must Have
BYOSMTP requires four DNS records correctly configured on the sending domain.
MX record pointing to a mail server that can receive for the domain. Required for DMARC alignment and for reply capture.
SPF record authorizing the SMTP server to send on behalf of the domain. Example: v=spf1 include:_spf.your-provider.com -all.
DKIM record with the selector your SMTP provider uses. A common mistake is publishing the key with the wrong selector name; match the provider's documented value exactly.
DMARC record with a policy. Start at p=none during warmup, then move to p=quarantine and eventually p=reject as the fleet matures.
The DNS validation check at connection time confirms all four. The platform's DomainHealth model stores the check result and re-runs nightly.
Monitoring
The inbox detail page for a BYOSMTP account shows:
- Live
overall_scoreand its components - SMTP connection success rate
- Send attempt count and success rate
- IMAP sync lag in minutes
- DNS health by record type
- Blacklist status (aggregated across major DNSBLs)
A drop in any of these is a precursor to a deliverability problem. The platform alerts on thresholds the user configures; defaults are sane for most fleets.
Troubleshooting
"Connection test passes but sends are not arriving"
DMARC is not aligned. The From header domain must match the DKIM signing domain and be authorized by SPF. An Amazon SES send from no-reply@acme.com must have SPF that authorizes SES and DKIM signed by an acme.com key. If DKIM is signed by amazonses.com and DMARC is strict, messages will be rejected silently. Fix the DKIM configuration.
"Sends arrive but open tracking never fires"
Tracking pixels are being stripped by a downstream filter, or the tracking domain is blacklisted. Check the tracking domain configuration in /link-tracking. Running tracking through a custom domain instead of the default shared domain fixes this most of the time.
"IMAP sync shows no new messages even when I received replies"
Folder path mismatch. Outlook shows the inbox as "Inbox" in English locale but "Posteingang" in German, "Boîte de réception" in French, and so on. Configure the exact folder name in the account detail.
Frequently Asked Questions
Can I rotate SMTP credentials without disrupting campaigns?
Yes. Edit the account, paste the new credentials, click Test. On success, new sends use the new credentials. In flight sends already submitted to SMTP continue to the old relay.
Does BYOSMTP support multiple sending addresses on the same account?
No. Each EmailAccountHealth row maps to one sending address. If you have three aliases on one mailbox, create three separate accounts with the same SMTP credentials but different display addresses.
What if my SMTP provider requires IP whitelisting?
Contact support for the current NimbusOS egress IP range. The platform runs from a stable range and the range is published to customers on request.
Can I mix BYOSMTP and ReachInbox accounts in the same campaign?
Yes. The rotation engine treats every EmailAccountHealth row equally. Mixing is useful for hybrid fleets where part of the volume runs on owned infrastructure and part runs through ReachInbox.
What to Read Next
After BYOSMTP is configured, the most useful next pages are Email Warmup for the stage engine, SPF, DKIM and DMARC for the DNS deep dive, and Connecting Email Accounts for other connection modes you might blend with custom SMTP.