Configuration

The AgentMailClient is configured using a DSL builder. All settings have sensible defaults.

Full Configuration

suspend fun fullConfig() {
  val client = AgentMailClient {
    apiKey = "your-api-key"
    baseUrl = "https://api.agentmail.to"

    timeout {
      connect = 15.seconds
      request = 1.minutes
      socket = 1.minutes
    }

    retry {
      maxRetries = 5
      retryOnServerErrors = true
    }

    perSenderRateLimiter {
      maxMessages = 5
      window = 10.seconds
      onLimitExceeded = RateLimitAction.SKIP
    }

    perRecipientRateLimiter {
      maxMessages = 1
      window = 5.seconds
      onLimitExceeded = RateLimitAction.STOP
    }
  }
  // ... use the client
  client.close()
}

Defaults

When no configuration is provided, the following defaults apply:

suspend fun defaults() {
  // All defaults are applied automatically:
  //   apiKey       = AGENTMAIL_API_KEY environment variable
  //   baseUrl      = "https://api.agentmail.to"
  //   connect      = 10 seconds
  //   request      = 30 seconds
  //   socket       = 30 seconds
  //   maxRetries   = 3
  //   retryOnServerErrors = true
  val client = AgentMailClient()
  client.close()
}

Timeouts

Configure connection, request, and socket timeouts using Kotlin's Duration type:

suspend fun timeoutConfig() {
  val client = AgentMailClient {
    timeout {
      connect = 5.seconds   // Time to establish connection
      request = 30.seconds  // Total request timeout
      socket = 30.seconds   // Time between data packets
    }
  }
  client.close()
}

Parameter	Default	Description
`connect`	10 seconds	Time to establish a connection
`request`	30 seconds	Total request timeout
`socket`	30 seconds	Time between data packets

Retries

Configure automatic retry behavior for failed requests:

suspend fun retryConfig() {
  val client = AgentMailClient {
    retry {
      maxRetries = 3              // Number of retry attempts
      retryOnServerErrors = true  // Retry on 5xx errors
    }
  }
  client.close()
}

Parameter	Default	Description
`maxRetries`	3	Number of retry attempts
`retryOnServerErrors`	true	Retry on 5xx server errors

Rate Limiting

Configure client-side rate limiting for outgoing messages. Limits are enforced per sender or per recipient using a sliding time window.

suspend fun rateLimitConfig() {
  val client = AgentMailClient {
    perSenderRateLimiter {
      maxMessages = 5          // Max messages per sender
      window = 10.seconds      // Within this time window
      onLimitExceeded = RateLimitAction.STOP  // Default: throw RateLimitExceededException
    }

    perRecipientRateLimiter {
      maxMessages = 1
      window = 5.seconds
      onLimitExceeded = RateLimitAction.SKIP  // Log warning, return null
    }
  }
  client.close()
}

Parameter	Default	Description
`maxMessages`	1	Max messages allowed within the window
`window`	5 seconds	Sliding time window duration
`onLimitExceeded`	`STOP`	Action when limit is exceeded

Actions

Action	Behavior
`STOP`	Throws `RateLimitExceededException`
`SKIP`	Logs a warning and returns `null` without sending
`DELAY`	Suspends until the window clears, then sends

When using SKIP, send functions return SendMessageResponse? — check for null to detect skipped messages.

Delay Example

Use DELAY to automatically throttle without dropping or failing:

suspend fun rateLimitDelay() {
  val client = AgentMailClient {
    perSenderRateLimiter {
      maxMessages = 10
      window = 60.seconds
      onLimitExceeded = RateLimitAction.DELAY  // Suspend until window clears
    }
  }
  client.close()
}

Next Steps

Inboxes — create and manage inboxes
Messages — send, reply, and forward messages
Threads — list and manage conversation threads