SMTP and IMAP

Your app talks to simmail exactly as it would to a real provider: SMTP to send, IMAP to read.

Addresses and ports

Your account page shows each universe’s host and ports. On simmail they look like this:

Service	Address	Security
SMTP submission	c1.simmail.dev:2525	STARTTLS
SMTP over TLS	c1.simmail.dev:4650	TLS from the first byte
IMAP	c1.simmail.dev:1143	STARTTLS
IMAP over TLS	c1.simmail.dev:9930	TLS from the first byte

Use the host your account page shows; your organization may be on another server.

Sign in with PLAIN or LOGIN. Always use STARTTLS or TLS: a server may refuse passwords sent over an unencrypted connection.

GET /api/connection returns the same details for the universe, including whether the certificate is self-signed and its SHA-256 fingerprint. GET /api/connection/cert downloads the certificate, so you can trust it instead of switching verification off.

Logins

A login is an address and a password your app uses. Logins belong to a universe and are made under Settings → Mail logins in its dashboard, or with the API (admin role):

curl -s -X POST https://c1.simmail.dev/api/accounts \
  -H "Authorization: Bearer smk_your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"address": "app@yourcompany.test", "password": "a-long-password", "display_name": "Acme App"}'

Field	Meaning
address	The mailbox it signs in to.
password	Its password.
display_name	Optional.
username	Optional: a login name other than the address, for example apikey.
allow_smtp, allow_imap	Which protocols it may use. Both true for a new login.
disabled	true switches it off without deleting it.
note	Your note.

Your plan sets how many logins your organization can have.

Caution

A login name can be used once in your organization, across its universes; that is how simmail knows which universe an SMTP or IMAP session belongs to. If you get “login name already in use”, another of your universes already has it. Another organization may use the same name: simmail tells the two apart by the password, and refuses a password that would make them ambiguous (“choose a different password”).

Testing a login

POST /api/accounts/{address}/test runs the same check SMTP and IMAP use (admin role):

curl -s -X POST https://c1.simmail.dev/api/accounts/app@yourcompany.test/test \
  -H "Authorization: Bearer smk_your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"password": "a-long-password"}'

{
  "imap": { "address": "app@yourcompany.test", "ok": true },
  "smtp": { "address": "app@yourcompany.test", "ok": true }
}

Every attempt also appears as an auth.ok or auth.failed event, with the reason for a failure (“wrong password”, “SMTP not allowed for this account”, “account disabled” …).

Repeated failures

After five failed logins from one IP address, further tries from it are slowed down, waiting longer each time up to 15 minutes. Apps on the server’s own machine are never slowed.

Sending

• Sign in, then send from any address. The message lands in the recipients’ INBOX and a copy goes to the sender’s Sent folder.
• Recipients never see the Bcc header.
• simmail adds a Received header, and a Message-ID and Date if your message lacks them.
• Addresses simmail has never seen get a mailbox automatically, unless the universe’s recipient rules say otherwise (bounce, refuse, or a share of dead addresses).
• Your plan sets how many messages a month are accepted. Past it, SMTP answers 452 4.5.3 with the reason.

Reading over IMAP

Any login can read its own mailbox over IMAP: INBOX, Sent, Junk and the rest. simmail supports IDLE, so your app hears about new mail at once.

To read a person’s mailbox over IMAP (to see what Dana received, say), create a login for her address. You can also read every mailbox with the API: see Mail and mailboxes.

Next

• Sending from common stacks: Node, Python and a .env file.
• Chaos and faults: make SMTP refuse, defer or hang up on purpose.