smtp

SMTP email client for Kit using native Zig FFI

Files

Dependencies

No Kit package dependencies.

This package uses native Zig FFI and requires the ffi and net capabilities

for SMTP connections.

Installation

kit add gitlab.com/kit-lang/packages/kit-smtp.git

Usage

import Kit.Smtp as SMTP

main = fn =>
  result = SMTP.send {
    host: "smtp.example.com", 
    port: 25, 
    sender: "sender@example.com", 
    to: "recipient@example.com", 
    subject: "Hello from Kit", 
    body: "This message was sent from Kit.", 
  }

  match result
    | Ok _ -> println "Email sent"
    | Err err -> println "SMTP failed: ${show err}"

main

Manual SMTP sessions are also supported:

import Kit.Smtp as SMTP

main = fn =>
  match SMTP.connect "smtp.example.com" 25
    | Err err -> println "Connect failed: ${show err}"
    | Ok conn ->
        defer SMTP.quit conn

        SMTP.mail-from conn "sender@example.com"
        SMTP.rcpt-to conn "recipient@example.com"
        SMTP.data conn "Subject: Hello\r\n\r\nMessage body"

main

SMTP.send accepts a record with:

SMTP Notes

SMTP.send performs the full SMTP flow: connect, optional authentication,

MAIL FROM, RCPT TO, DATA, and QUIT.

For manual sessions, SMTP.connect performs the initial server greeting and

EHLO handshake. Use SMTP.auth for AUTH LOGIN or SMTP.auth-plain for AUTH

PLAIN when your server supports authentication on the active connection.

SMTP.send-raw expects an envelope string in "from@example.com,to@example.com"

format and message data that already contains the headers and body.

The current native implementation uses plain TCP SMTP. STARTTLS and SMTPS are

not implemented in this package.

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit
kit run examples/error-handling.kit
kit run examples/raw-message.kit

Compile an example to a native binary:

kit build examples/basic.kit && ./basic

The checked-in examples are offline and deterministic so they can run in

parity checks without a live SMTP server.

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

1. Format and check source files in src/
2. Type check examples in examples/
3. Run tests in tests/ with coverage

Running Parity Checks

Run interpreter/compiler parity checks for examples:

kit parity --failures-only

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html.

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/smtp/, making it available

for import as Kit.Smtp in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Exported Functions & Types

SMTPError

SMTP error type for typed error handling. Variants distinguish between different failure modes.