Skip to content

Messages

Messages are emails sent and received through AgentMail inboxes.

Send a Message

suspend fun sendMessageExample() {
    val client = AgentMailClient()
    val response = client.sendMessage {
        from = "inbox-id"
        to = listOf("recipient@example.com")
        subject = "Hello!"
        text = "Plain text body"
        html = "<h1>Hello!</h1><p>HTML body</p>"
    }
    println("Message ID: ${response!!.messageId}")
    println("Thread ID: ${response.threadId}")
    client.close()
}

CC and BCC

suspend fun sendWithCcBccExample() {
    val client = AgentMailClient()
    client.sendMessage {
        from = "inbox-id"
        to = listOf("primary@example.com")
        cc = listOf("copy@example.com")
        bcc = listOf("hidden@example.com")
        subject = "Team Update"
        text = "Here's the latest update."
    }
    client.close()
}

List Messages

suspend fun listMessagesExample() {
    val client = AgentMailClient()
    val result = client.listMessages("inbox-id") {
        limit = 20
        ascending = false
    }
    for (message in result.messages) {
        println("${message.subject} — from ${message.from}")
    }
    client.close()
}

Filter Messages

suspend fun filterMessagesExample() {
    val client = AgentMailClient()
    val result = client.listMessages("inbox-id") {
        labels = listOf("important")
        includeSpam = false
        includeTrash = false
    }
    for (message in result.messages) {
        println(message.subject)
    }
    client.close()
}

Full Message Content

List operations return message summaries without body content. Use toFullMessage() to fetch the complete message:

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

    // List returns message summaries (no body content)
    val result = client.listMessages("inbox-id")
    val summary = result.messages.first()

    // Fetch the full message with body content
    val full = client.toFullMessage(summary)
    println("Subject: ${full.subject}")
    println("Text: ${full.text}")
    println("HTML: ${full.html}")

    client.close()
}

Reply

suspend fun replyExample() {
    val client = AgentMailClient()
    val messages = client.listMessages("inbox-id")
    val message = messages.messages.first()

    client.replyToMessage(message) {
        text = "Thanks for reaching out!"
    }
    client.close()
}

Reply All

suspend fun replyAllExample() {
    val client = AgentMailClient()
    val messages = client.listMessages("inbox-id")
    val message = messages.messages.first()

    client.replyAllToMessage(message) {
        text = "Thanks everyone!"
    }
    client.close()
}

Forward

suspend fun forwardExample() {
    val client = AgentMailClient()
    val messages = client.listMessages("inbox-id")
    val message = messages.messages.first()

    client.forwardMessage(message) {
        to = listOf("colleague@example.com")
        text = "FYI — see the forwarded message below."
    }
    client.close()
}

Update Labels

Replace all labels on a message:

suspend fun updateMessageExample() {
    val client = AgentMailClient()
    val messages = client.listMessages("inbox-id")
    val message = messages.messages.first()

    // Replace all labels
    client.updateMessage(message) {
        labels = listOf("important", "reviewed")
    }
    client.close()
}

Add / Remove Labels

Incrementally add or remove labels without replacing the full set. This is useful for tracking read/unread state:

suspend fun addRemoveLabelsExample() {
    val client = AgentMailClient()
    val messages = client.listMessages("inbox-id")
    val message = messages.messages.first()

    // Mark as read
    client.updateMessage(message) {
        addLabels("read")
        removeLabels("unread")
    }
    client.close()
}

Attachments

suspend fun attachmentExample() {
    val client = AgentMailClient()
    val messages = client.listMessages("inbox-id")
    val message = client.toFullMessage(messages.messages.first())

    for (attachment in message.attachments) {
        val data = client.getAttachment(message, attachment.attachmentId)
        println("${attachment.filename}: ${data.contentType} (${data.data.size} bytes)")
    }
    client.close()
}

Raw Message

Get the raw RFC 822 formatted email:

suspend fun rawMessageExample() {
    val client = AgentMailClient()
    val messages = client.listMessages("inbox-id")
    val message = messages.messages.first()

    val raw = client.getRawMessage(message)
    println(raw.raw) // RFC 822 formatted email
    client.close()
}

Next Steps

  • Threads — list and manage conversation threads
  • Drafts — create, update, and send drafts
  • Monitoring — poll for new messages in real time