Skip to content

Monitoring

Monitor an inbox for new messages by polling at a configurable interval. Returns a coroutine Job that runs in the background.

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

    val job = client.monitor("inbox-id") {
        pollInterval = 10.seconds

        onMessage { message ->
            println("New message: ${message.subject}")
        }

        onError { error ->
            println("Error: ${error.message}")
        }
    }

    // Monitor runs in the background as a coroutine Job
    delay(5.minutes)
    job.cancel() // Stop monitoring
    client.close()
}

Full Message Content

Use onFullMessage instead of onMessage to receive complete message bodies:

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

    val job = client.monitor("inbox-id") {
        pollInterval = 15.seconds
        includeSpam = false
        includeBlocked = false

        // Use onFullMessage to get complete message bodies
        onFullMessage { message ->
            println("From: ${message.from}")
            println("Subject: ${message.subject}")
            println("Body: ${message.text}")
        }

        onError { error ->
            System.err.println("Monitor error: ${error.message}")
        }
    }

    delay(10.minutes)
    job.cancel()
    client.close()
}

Filtering Messages

Use filterBy to only process messages that match a predicate. The filter has access to all Message attributes — labels, sender, subject, attachments, etc.

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

    // Only process unread messages, then mark them as read
    val job = client.monitor("inbox-id") {
        filterBy { "unread" in it.labels }

        onMessage { message ->
            println("Unread: ${message.subject}")
            client.updateMessage(message) {
                removeLabels("unread")
                addLabels("read")
            }
        }
    }

    delay(5.minutes)
    job.cancel()
    client.close()
}

You can combine multiple conditions in a single filter:

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

    // Combine multiple conditions
    val job = client.monitor("inbox-id") {
        filterBy {
            it.from.endsWith("@example.com") && it.attachments.isNotEmpty()
        }

        onFullMessage { message ->
            println("${message.from} sent ${message.attachments.size} attachment(s)")
        }
    }

    delay(5.minutes)
    job.cancel()
    client.close()
}

Poll

poll() is a simplified wrapper around monitor() for the common case of just handling messages:

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

    // poll() is a simplified wrapper around monitor()
    val job = client.poll("inbox-id", interval = 10.seconds) { message ->
        println("${message.subject} — from ${message.from}")
    }

    delay(5.minutes)
    job.cancel()
    client.close()
}

poll() also accepts a filter parameter:

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

    // Only poll for messages with attachments
    val job = client.poll(
        "inbox-id",
        interval = 10.seconds,
        filter = { it.attachments.isNotEmpty() },
    ) { message ->
        println("${message.subject} has ${message.attachments.size} attachment(s)")
    }

    delay(5.minutes)
    job.cancel()
    client.close()
}

Next Steps