Connect your inbox

Smailor can exchange mail with the inbox you already use — Gmail, Outlook,
Apple Mail, Thunderbird — or with code you write yourself. There are five ways
to do it, and they are not interchangeable. Pick one from the table below before
reading further — most of the time lost on this topic is lost configuring the
wrong one.

Which one do you want

If you only need to see your Smailor mail somewhere else, you want A. If you
need to reply from somewhere else and have the reply look like it came from
your Smailor address, you want B. If you want the mail inside a desktop or phone
mail client rather than inside another mailbox, you want B and C together: C
fills the incoming half of the client's dialog, B the outgoing half.

A — Forwarding (available)

Settings → Forwarding. Every mail a Smailor mailbox receives is copied to an
external address. Rules can be scoped to one mailbox, to one group, and can
exclude groups.

The destination has to agree

Creating a rule, or repointing an existing one, sends a confirmation email to
the destination. Nothing is forwarded until someone opens the link in that
email. The link is single use and expires after 24 hours; Settings →
Forwarding shows unconfirmed rules as Awaiting confirmation and offers a
Resend.

This exists because a forwarding rule is, mechanically, a content export: it
copies a mailbox to an address that until now nobody had checked. The
confirmation is what turns a typed address into a destination that has agreed.

What you cannot forward to

An address on a domain Smailor serves — including your own Smailor addresses.
Mail forwarded there re-enters Smailor as new inbound mail, matches the same
rule, and forwards again, indefinitely. This is refused when the rule is created
and re-checked on every forward, because a destination domain that is external
today can be added to Smailor tomorrow.

To move mail between two of your own Smailor mailboxes, use a routing rule
instead.

Deliverability

A forward breaks SPF: the mail leaves from Smailor's IPs, which the original
sender's domain does not authorise. DKIM on the original message is preserved,
so DMARC can still pass on the DKIM side, but a forwarded message is inherently
more likely to be filtered than a direct one. Sender Rewriting Scheme (SRS) is
not implemented — see the open questions in the internal plan.

Limits

One rule on Free, three on Solo/Starter, twenty on Pro, unlimited on Business.
The limit applies when a rule is created; an account already over its plan's
number keeps the rules it has.

B — SMTP submission (available)

Settings → Mail client access (/settings/smtp). Issue a password that a
mail client authenticates with to send as one of your Smailor addresses. The same
page carries the reading half, mode C, because a mail client asks for an incoming
and an outgoing server in one dialog.

Only an address on a verified custom domain can be attached to a mail client.
Addresses on Smailor's own domains receive mail but cannot send, so the page
refuses to issue a password for one instead of letting the first reply bounce.

If a server is not answering, the page says so — it names the host and
port, and still lets you prepare a password, rather than handing you settings
that fail silently in your mail client.

Server settings:

Encryption is genuinely not a choice you have to get right. 587 normally starts
in the clear and upgrades with STARTTLS, but it also accepts a client that
opens with a TLS handshake directly, which is what iOS Mail does the moment
"Use SSL" is switched on. 465 is implicit TLS only. Whichever combination a
client offers, the session is encrypted before authentication: unencrypted
AUTH is refused on every port, so there is no setting here that quietly sends
a password in the clear.

What is true of a credential:

• It is bound to one mailbox and may send as that address only — not as a
  colleague on the same domain, not as another account.
• It is shown once. Only a hash is stored, so it cannot be recovered; rotate by
  issuing a new one and revoking the old.
• The username is the full mailbox address ([email protected]), which is what
  Gmail and desktop clients expect.
• Revoking is immediate. Deleting the mailbox revokes every credential bound to
  it.
• It is not an API key and can never become one: smtp:send is deliberately
  outside the HTTP scope vocabulary, so it cannot be granted to a REST key.
• Free accounts get none. One on Solo/Starter, ten on Pro, twenty on Business.

Mail sent this way goes through the same outbound queue, sender-node routing,
quota and spam checks as everything else, and counts against the same monthly
send allowance. There is no separate SMTP quota, by design — a separate one
would be a trivial way around the plan.

Things worth knowing before you set this up

• Your From is always your Smailor address. The pipeline rebuilds the
  message rather than relaying it byte for byte, so a client cannot send as
  anything else. A client configured with a mismatched identity is refused
  outright rather than silently corrected.
• Attachments are carried through. Inline images that are part of the HTML
  body are not attached a second time.
• Up to 10 recipients per message, each becoming its own queued message.
• A temporary failure means retry. If the client reports a 451, the
  message is still in its outbox and will be retried; a 550 is permanent and
  will not be.
• "Last used" in Settings → Mail client access shows when and from which address a
  credential was last used. That address will belong to Google or Microsoft when
  sending from their webmail, not to you.

What your provider actually allows

• Gmail supports adding an external SMTP server under Send mail as. This
  is the case the feature is built for.
• Outlook.com and iCloud.com do not let you add a custom outgoing server
  from the web interface. There is no way to make this work from those webmails.
• Desktop clients — Outlook desktop, Apple Mail, Thunderbird — do support a
  custom outgoing server and will work.

C — POP3 (available on Pro and Business)

Settings → Mail client access (/settings/smtp), reading half. Issue a
password that a mail client authenticates with to download a Smailor mailbox.

Port 110 with STLS is not offered, and will not be: a plaintext port that
upgrades is a port where one client misconfiguration sends the password in the
clear. 995 is implicit TLS, so there is no pre-encryption state to get wrong.

One password per device

POP3 was designed for a single device draining its own spool, so a laptop and a
phone are two credentials rather than one secret copied between them. Ten
credentials on Pro, twenty on Business. Free, Solo and Starter get none — a
mailbox readable by a long-lived password typed into desktop software is a larger
commitment than a dashboard session.

What the client sees

• The 250 most recent messages. POP3 has no notion of a window: LIST is the
  whole mailbox and a client re-reads it on every poll. The full history stays in
  Smailor.
• Messages over 30 MB are listed but not downloadable. RETR declines with a
  line pointing at the web view, rather than omitting the message and looking
  like lost mail.
• Rebuilt messages, not the original bytes. Smailor stores parsed mail, so
  each message is reconstructed. The original sender's DKIM signature is not
  carried over and a client that checks DKIM locally will report the message
  unsigned — Smailor verified it on arrival. Headers Smailor does not store are
  absent rather than invented: no Received chain, no List-Unsubscribe. Every
  rebuilt message carries X-Smailor-Reconstructed: 1.

Deleting in the mail client does not delete in Smailor

Mail clients issue DELE after downloading unless "leave a copy on the server"
is ticked, and several tick it off by default. Here DELE records a tombstone
against that one credential: the message stops appearing in that client's
listing and is untouched in Smailor. Someone who empties their Apple Mail inbox
still has everything in the dashboard.

Optionally, let one device report back

A shared support inbox and a POP3 spool disagree about everything: mail read on a
phone stays bold in the dashboard. A single credential — the laptop someone works
from all day, not a phone polling in the background — can opt in to mirroring its
state:

• Downloading a message marks the conversation read in Smailor, if it was not
  already. The timestamp records when the mailbox first saw the message and is
  never moved afterwards.
• Deleting archives the conversation, on top of the tombstone. That is where the
  dashboard's own archive button puts it, and it is reversible from there.

Off by default, including on credentials created before the option existed.
The reason is the first poll: a client downloads everything it has not seen, so
enabling this against an established mailbox marks a large part of it read in one
pass.

Limits worth knowing

• 120 sessions per credential per hour. Clients reconnect on every poll, so
  this is a real ceiling and it is what stops a client polling every second from
  rebuilding the mailbox on every pass.
• 20 failed authentications per username per 5 minutes. Successes do not
  count: every POP3 operation re-sends the password, so counting them would cap
  how much mail a mailbox may sync instead of how fast a secret may be guessed.
• A reading credential carries pop3:read and nothing else. It cannot send, and
  it is not an API key.

D — REST API and webhooks (available)

For reading and sending programmatically. See REST-API.md.

Use this rather than B or C when the consumer is your own code: it is the only
one of the five with per-resource scopes, so a key can be granted read-only
access to mailboxes without also being able to send.

Inbound webhooks are signed with HMAC — the same signing scheme as Focus
webhooks, not a second one.

E — IMAP (not built)

There is no IMAP server. Connecting a client to Smailor over IMAP is not
possible, and no date is committed. An IMAP server is a stateful process
terminating untrusted connections from the public internet, which is a very
different thing to operate than an HTTP app, and the build-versus-adopt decision
has not been made.

The permission vocabulary already keeps the two apart: imap:read is a separate
scope from pop3:read, so a password handed to a script for POP3 will not start
opening IMAP sessions the day an IMAP listener ships. Whether a deployment serves
IMAP is an ops switch, not a code change.

If you need mail in a generic client today, use C — accepting that it shows
recent mail rather than the whole archive — or A.

Security notes that apply to all five

• Your account password is never usable for SMTP or POP3. Protocol credentials
  are always separate, individually revocable, and stored hashed. The three
  kinds cannot be substituted for one another either: an API key, a sending
  password (smtp_…) and a reading password (mail_…) carry disjoint scopes,
  so one pasted into the wrong dialog fails rather than working with more
  power than intended. Reused
  passwords on legacy mail protocols are the single largest cause of consumer
  mailbox compromise, and the separation is not a later hardening step.
• A domain must be verified before anything can send from it. This applies on
  every plan.
• Every outbound path — dashboard, API, forwarding and SMTP submission — goes
  through the same spam scoring and IP reputation checks. Nothing routes around
  them.

Related

• REST API reference — mode D, and the scopes an API key carries
• Add a new domain — required before B or C
• Email setup and deliverability — SPF, DKIM, DMARC