Email

HTML & web

Email sending and address-verification tokens for auth flows.

verificationToken / verifyToken mint and check time-limited HS256 JWTs (claim purpose = "email.verify") with the same crypto as Jwt. send delivers through SMTP or a JSON HTTP webhook. Pass config explicitly (same pattern as JWT secrets and Repo config; no magic env vars).

Use message for plain text, or htmlMessage for multipart/alternative HTML plus a plaintext alternative. Build HTML bodies with Email.Mjml. Rate limiting stays in the app.

Types

Config

type Config = Config

SMTP relay or HTTP provider settings. Construct with smtp or http.

Examples

Email.smtp
    { host = "localhost"
    , smtpPort = 1025
    , from = "app@example.com"
    , username = ""
    , password = ""
    , tls = False
    , tlsInsecure = False
    }

Message

type Message = Message

Outbound message. Construct with message or htmlMessage.

Examples

Email.message
    { to = "user@example.com"
    , subject = "Hello"
    , body = "Hi there"
    }

Error

type Error
= BadConfig String
| SendFailed String
| BadToken

Why send or token verification failed.

Examples

case err of
    Email.BadToken ->
        "expired or invalid"

    _ ->
        Email.errorToString err

Values

smtp

smtp : { host : String , smtpPort : Int , from : String , username : String , password : String , tls : Bool , tlsInsecure : Bool } -> Config

SMTP relay.

username / password empty skips AUTH. tls = True uses ssl:connect (typical for submission on 465) and verifies the peer certificate against the system CA store (OTP public_key:cacerts_get) with hostname checks. Set tlsInsecure = True only for local TLS mocks with self-signed certs. Plain TCP (tls = False) suits Mailpit / MailHog on 1025. (port is a reserved word, so the field is smtpPort.)

Examples

Email.smtp
    { host = "smtp.example.com"
    , smtpPort = 465
    , from = "noreply@example.com"
    , username = "user"
    , password = "secret"
    , tls = True
    , tlsInsecure = False
    }

http

http : { url : String , from : String , authorization : String } -> Config

HTTP JSON webhook.

POSTs { from, to, subject, body } as JSON (and html when sending htmlMessage). Non-empty authorization sets an Authorization header (for example "Bearer …"). Treat 2xx as success.

Examples

Email.http
    { url = "https://api.example.com/send"
    , from = "noreply@example.com"
    , authorization = "Bearer tok"
    }

message

message : { to : String , subject : String , body : String } -> Message

Build a plain-text message from address, subject, and body.

Examples

Email.message
    { to = "user@example.com"
    , subject = "Welcome"
    , body = "Thanks for signing up."
    }

htmlMessage

htmlMessage : { to : String , subject : String , html : String , text : String } -> Message

Build an HTML message with an explicit plaintext alternative.

SMTP sends multipart/alternative. The HTTP webhook includes both body (plaintext) and html.

Examples

Email.htmlMessage
    { to = "user@example.com"
    , subject = "Welcome"
    , html = "<p>Thanks!</p>"
    , text = "Thanks!"
    }

send

send : Config -> Message -> Result Error ()

Send message through config.

Examples

Email.send config msg

verificationToken

verificationToken : String -> Int -> String -> String

Mint a verification (or magic-link) token for email.

ttlSeconds must be positive. Uses HS256 with secret (same rules as Jwt.signWithExp).

Examples

Email.verificationToken secret 3600 "user@example.com"

verifyToken

verifyToken : String -> String -> Result Error String

Verify a token from verificationToken.

Returns the email on success. Wrong secret, bad signature, wrong purpose, missing email claim, or expired exp are Err BadToken.

Examples

Email.verifyToken secret token

errorToString

errorToString : Error -> String

Human-readable form of an Error for logs.

Examples

Email.errorToString Email.BadToken