Skip to content

Getting Started

API Key

The SDK requires an AgentMail API key. You can provide it in two ways:

Set the AGENTMAIL_API_KEY environment variable:

export AGENTMAIL_API_KEY="your-api-key"

Then create a client with no arguments:

suspend fun createClientFromEnv() {
    // Reads AGENTMAIL_API_KEY from the environment automatically
    val client = AgentMailClient()
    // ... use the client
    client.close()
}

Explicit API Key

Pass the API key directly in the configuration block:

suspend fun createClientExplicit() {
    val client = AgentMailClient {
        apiKey = "your-api-key"
    }
    // ... use the client
    client.close()
}

Send Your First Message

Create an inbox and send a message:

suspend fun quickStart() {
    val client = AgentMailClient()

    // Create an inbox
    val inbox = client.createInbox("support", "example.com", "Support Team")
    println("Created inbox: ${inbox.email}")

    // Send a message
    val response = client.sendMessage {
        from = inbox.inboxId
        to = listOf("user@example.com")
        subject = "Hello from AgentMail!"
        text = "This is a test message sent with agentmail4k."
    }
    println("Sent message: ${response!!.messageId}")

    client.close()
}

Resource Cleanup

AgentMailClient implements Closeable. Use Kotlin's use extension to ensure the client is closed automatically:

suspend fun useCloseable() {
    AgentMailClient().use { client ->
        val inbox = client.createInbox("hello", "example.com", "Hello")
        println("Inbox: ${inbox.email}")
    } // client is automatically closed
}

Next Steps

  • Configuration — customize timeouts, retries, and more
  • Inboxes — create and manage inboxes
  • Messages — send, reply, and forward messages