Sending from common stacks

Any SMTP client works. You need four things from your account page: the host, a port, and a login (address and password) made under Settings → Mail logins in your universe. See SMTP and IMAP.

The examples use c1.simmail.dev, port 2525 with STARTTLS, and the login app@yourcompany.test. Port 4650 is the same service with TLS from the first byte.

import nodemailer from "nodemailer";

const transport = nodemailer.createTransport({
  host: process.env.SMTP_HOST,            // c1.simmail.dev
  port: Number(process.env.SMTP_PORT),    // 2525
  secure: false,                          // true for port 4650
  requireTLS: true,                       // upgrade with STARTTLS, never send the password in clear
  auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS },
});

const info = await transport.sendMail({
  from: '"Acme" <app@yourcompany.test>',
  to: "dana@harbor.test",
  subject: "Your house on Clark Street",
  text: "Hi Dana, would you consider an offer of 165,000?",
  html: "<p>Hi Dana, would you consider an offer of <b>165,000</b>?</p>",
});

console.log(info.messageId); // use it as in_reply_to when you wait for her reply

If the universe’s certificate is self-signed, either trust it (download it from GET /api/connection/cert and pass it as tls: { ca: [cert] }) or, for a local test rig only, add tls: { rejectUnauthorized: false }.

import os
import smtplib
import ssl
from email.message import EmailMessage
from email.utils import make_msgid

msg = EmailMessage()
msg["From"] = "Acme <app@yourcompany.test>"
msg["To"] = "dana@harbor.test"
msg["Subject"] = "Your house on Clark Street"
msg["Message-ID"] = make_msgid(domain="yourcompany.test")
msg.set_content("Hi Dana, would you consider an offer of 165,000?")

ctx = ssl.create_default_context()
with smtplib.SMTP(os.environ["SMTP_HOST"], int(os.environ["SMTP_PORT"])) as smtp:   # port 2525
    smtp.starttls(context=ctx)
    smtp.login(os.environ["SMTP_USER"], os.environ["SMTP_PASS"])
    smtp.send_message(msg)

print(msg["Message-ID"])  # use it as in_reply_to when you wait for her reply

For port 4650, use smtplib.SMTP_SSL(host, 4650, context=ctx) and skip starttls().

If the universe’s certificate is self-signed, trust it: download it from GET /api/connection/cert and use ssl.create_default_context(cafile="simmail.crt").

Most frameworks read SMTP settings from the environment. The names differ, but the values are the same:

# Sending
SMTP_HOST=c1.simmail.dev
SMTP_PORT=2525
SMTP_SECURE=false        # STARTTLS on 2525; use 4650 with SMTP_SECURE=true for TLS
SMTP_USER=app@yourcompany.test
SMTP_PASS=a-long-password

# Reading, if your app reads mail
IMAP_HOST=c1.simmail.dev
IMAP_PORT=9930           # TLS; 1143 for STARTTLS
IMAP_USER=app@yourcompany.test
IMAP_PASS=a-long-password

# For your tests (the SDKs read these)
SIMMAIL_URL=https://c1.simmail.dev
SIMMAIL_API_KEY=smk_your_key

SIMMAIL_URL is the server address without /api. The SDKs add the path themselves.

Checking it arrived

Wait for the message in a test:

curl -s -G https://c1.simmail.dev/api/wait \
  -H "Authorization: Bearer smk_your_key" \
  --data-urlencode "to=dana@harbor.test" \
  --data-urlencode "subject=Clark Street" \
  --data-urlencode "existing=true"

Or open the universe’s dashboard and look under Mail. See the wait API.