Skip to content

Scoped Access

The SDK provides two ways to interact with resources: top-level DSL functions and scoped access. Scoped access is useful when performing multiple operations on the same inbox or pod.

Inbox Scope

Use client.inboxes(inboxId) to get a scoped view of an inbox's resources:

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

    // Get a scoped view of an inbox's resources
    val scope = client.inboxes("inbox-id")

    // Access messages, threads, drafts, etc. within this inbox
    val messages = scope.messages.list()
    val threads = scope.threads.list()
    val drafts = scope.drafts.list()

    println("Messages: ${messages.messages.size}")
    println("Threads: ${threads.threads.size}")
    println("Drafts: ${drafts.drafts.size}")

    client.close()
}

Available Resources

suspend fun inboxScopeResourcesExample() {
    val client = AgentMailClient()
    val scope = client.inboxes("inbox-id")

    // All resources available on an InboxScope:
    scope.messages    // MessageResource — send, list, reply, forward
    scope.threads     // ThreadResource — list, get, delete
    scope.drafts      // DraftResource — create, list, send
    scope.lists       // ListResource — allow/block lists
    scope.metrics     // MetricsResource — query metrics
    scope.apiKeys     // ApiKeyResource — manage API keys

    client.close()
}

Pod Scope

Use client.pods(podId) to get a scoped view of a pod's resources:

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

    // Get a scoped view of a pod's resources
    val scope = client.pods("pod-id")

    // Access inboxes, threads, etc. within this pod
    val inboxes = scope.inboxes.list()
    val threads = scope.threads.list()

    println("Inboxes in pod: ${inboxes.inboxes.size}")
    println("Threads in pod: ${threads.threads.size}")

    client.close()
}

Available Resources

suspend fun podScopeResourcesExample() {
    val client = AgentMailClient()
    val scope = client.pods("pod-id")

    // All resources available on a PodScope:
    scope.inboxes     // InboxResource — manage pod inboxes
    scope.threads     // ThreadResource — list, get, delete
    scope.drafts      // DraftResource — create, list, send
    scope.domains     // DomainResource — manage pod domains
    scope.lists       // ListResource — allow/block lists
    scope.metrics     // MetricsResource — query metrics
    scope.apiKeys     // ApiKeyResource — manage API keys

    client.close()
}

DSL vs Scoped Access

Both approaches access the same API. Choose based on your use case:

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

    // DSL approach — convenient for one-off operations
    val messages = client.listMessages("inbox-id") { limit = 10 }

    // Scoped approach — efficient when doing multiple operations on the same inbox
    val scope = client.inboxes("inbox-id")
    val msgs = scope.messages.list { limit = 10 }
    val threads = scope.threads.list { limit = 10 }
    val drafts = scope.drafts.list { limit = 10 }

    client.close()
}

Use DSL functions when performing a single operation — they're concise and read naturally.

Use scoped access when performing multiple operations on the same inbox or pod — you avoid passing the ID repeatedly and make the grouping explicit.

Next Steps