> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/puiusabin/bun-smtp/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration
> Complete reference for SMTPServer constructor options
Pass options to the `SMTPServer` constructor:
```typescript theme={null}
import { SMTPServer } from "bun-smtp";
const server = new SMTPServer({
// options here
});
```
***
## Connection
Start in implicit TLS mode (port 465 style). When `false`, STARTTLS is offered instead.
Reject AUTH and MAIL until the client completes STARTTLS.
Server hostname included in the `220` greeting and EHLO response.
Extra text appended to the `220` greeting line.
Use LMTP instead of SMTP. Clients open with `LHLO` and `onData` may return per-recipient responses.
Format string for the HELO/EHLO response. First `%s` is the server name, second is the client hostname.
***
## Authentication
SASL methods advertised in EHLO. Supported values: `"PLAIN"`, `"LOGIN"`, `"CRAM-MD5"`, `"XOAUTH2"`.
Allow clients to skip AUTH entirely.
Allow AUTH over a plain (non-TLS) connection.
Custom error message for the `530` response when auth is required.
By default, AUTH is disabled over non-TLS connections. Set `allowInsecureAuth: true` to permit plaintext authentication.
***
## Capability Flags
These options hide extensions from the EHLO response. The extension still works — it is just not advertised.
Hide `STARTTLS` from EHLO.
Hide the `SIZE` extension.
Hide `PIPELINING`.
Hide `DSN` (Delivery Status Notification).
Hide `ENHANCEDSTATUSCODES`.
Hide `REQUIRETLS`.
Hide `8BITMIME`.
Hide `SMTPUTF8`.
Block specific SMTP commands entirely (e.g. `["AUTH", "STARTTLS"]`).
***
## Limits
Maximum message size in bytes. Advertised via the `SIZE` extension. The `onData` stream's `sizeExceeded` flag is set when the limit is hit.
Maximum number of simultaneous connections. New connections are rejected with `421` when the limit is reached.
Milliseconds of inactivity before an idle connection is closed.
Milliseconds to wait for connections to drain during `server.close()`. Connections still open after this are forcibly terminated.
Maximum commands allowed before authentication. Set to `false` to disable the limit.
Setting `maxAllowedUnauthenticatedCommands` to `false` may expose your server to abuse. Use with caution.
***
## Proxy / X-headers
Trust Postfix `XCLIENT` headers. When enabled, `session.xClient` is populated.
Trust Postfix `XFORWARD` headers. When enabled, `session.xForward` is populated.
Parse HAProxy `PROXY` protocol header. Pass an array of trusted proxy IP addresses to restrict which proxies are trusted.
Only enable proxy headers if you trust the upstream proxy. Malicious clients can forge these headers.
***
## DNS
Skip reverse DNS lookup on new connections. When `false`, `session.clientHostname` is resolved from the client's IP.
Custom DNS resolver. Must implement `reverse(ip, callback)` with the same signature as `dns.reverse`.
```typescript theme={null}
{
reverse: (
ip: string,
callback: (err: Error | null, hostnames?: string[]) => void
) => void
}
```
***
## TLS
All standard TLS options. See the [TLS & STARTTLS guide](/guides/tls) for usage examples.
Private key in PEM format.
Certificate in PEM format.
CA bundle for client certificate verification.
Request a client certificate during TLS handshake.
Reject clients with invalid or unverifiable certificates.
Minimum TLS version string (e.g. `"TLSv1.2"`).
Maximum TLS version string.
Per-hostname TLS configuration for SNI (Server Name Indication).
```typescript theme={null}
sniOptions: {
"mail.example.com": {
key: exampleKey,
cert: exampleCert
},
"mail.other.com": {
key: otherKey,
cert: otherCert
}
}
```
If no TLS options are provided, the server uses a default self-signed certificate for development.
***
## Callbacks
All lifecycle callbacks can be set as constructor options. See [Callbacks](/api/callbacks) for full signatures and examples.
Called on new connection.
```typescript theme={null}
(session: SMTPSession, callback: (err?: Error | null) => void) => void
```
Called after TLS handshake.
```typescript theme={null}
(
socket: Socket,
session: SMTPSession,
callback: (err?: Error | null) => void
) => void
```
Called on AUTH attempt.
```typescript theme={null}
(
auth: AuthObject,
session: SMTPSession,
callback: (err: Error | null, response?: AuthResponse) => void
) => void
```
Called on MAIL FROM.
```typescript theme={null}
(
address: SMTPAddress,
session: SMTPSession,
callback: (err?: Error | null) => void
) => void
```
Called on RCPT TO.
```typescript theme={null}
(
address: SMTPAddress,
session: SMTPSession,
callback: (err?: Error | null) => void
) => void
```
Called when DATA transfer begins.
```typescript theme={null}
(
stream: DataStream,
session: SMTPSession,
callback: (
err: Error | null,
message?: string | Array
) => void
) => void
```
Called when connection closes.
```typescript theme={null}
(session: SMTPSession) => void
```
***
## Complete Example
```typescript theme={null}
import { SMTPServer } from "bun-smtp";
const server = new SMTPServer({
// Connection
secure: false,
name: "mail.example.com",
banner: "Welcome to Example Mail",
// Authentication
authMethods: ["PLAIN", "LOGIN", "CRAM-MD5"],
authOptional: false,
allowInsecureAuth: false,
// Limits
size: 10 * 1024 * 1024, // 10 MB
maxClients: 100,
socketTimeout: 60000,
// TLS
key: await Bun.file("key.pem").text(),
cert: await Bun.file("cert.pem").text(),
// Callbacks
onAuth(auth, session, callback) {
if (auth.username === "user" && auth.password === "pass") {
callback(null, { user: auth.username });
} else {
callback(new Error("Invalid credentials"));
}
},
onData(stream, session, callback) {
const chunks = [];
stream.pipeTo(new WritableStream({
write(chunk) {
chunks.push(chunk);
},
close() {
const message = Buffer.concat(chunks);
console.log(`Received ${message.length} bytes`);
callback(null);
},
abort(err) {
callback(err);
}
}));
}
});
server.listen(2525);
```