Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      Mailboxes

      Hosted mailboxes and their members. Business mail only.

      Every endpoint needs Authorization: Bearer lk_live_.... See Conventions for headers, status codes and error shape.

      List mailboxes

      GET /v1/mailboxes  ·  scope mailboxes:read

      Returns mailboxes under the calling tenant, active and soft-deleted. ?limit=N between 1 and 200 (default 50).

      Parameters

      Name In Type Notes
      limit query integer

      Response 200

      Mailbox list.

      Field Type Notes
      data array of Mailbox Required.
      limit integer Required.

      Errors: 401, 403

      Create a mailbox

      POST /v1/mailboxes  ·  scope mailboxes:write

      Creates a mailbox on a tenant-verified domain. If password is omitted, lockally generates a 16-char password and returns it in the response, shown once.

      Gate. The mailbox’s domain must already be registered AND verified for this tenant (via /v1/domains + /v1/domains/{domain}/verify).

      Idempotent. Re-posting the same email returns the existing mailbox UNTOUCHED, password is NOT regenerated. To change a password, use PATCH instead.

      Request body

      Field Type Notes
      email string Required.
      password string Optional; lockally generates if absent.
      quota_bytes integer 5 GB default.

      Response 200

      Mailbox already existed for this tenant (idempotent).

      Field Type Notes
      id string Required.
      tenant_id string Required.
      domain_id string Required.
      email string Required.
      quota_bytes integer Required.
      disabled boolean Required.
      disabled_at string
      soft_deleted_at string
      hard_delete_after string
      created_at string Required.
      password string ONLY present on POST response when lockally generated the password. Shown once.

      Errors: 400, 401, 403, 409

      Get a mailbox

      GET /v1/mailboxes/{email}  ·  scope mailboxes:read

      Response 200

      Mailbox info.

      Field Type Notes
      id string Required.
      tenant_id string Required.
      domain_id string Required.
      email string Required.
      quota_bytes integer Required.
      disabled boolean Required.
      disabled_at string
      soft_deleted_at string
      hard_delete_after string
      created_at string Required.
      password string ONLY present on POST response when lockally generated the password. Shown once.

      Errors: 401, 403, 404

      Update a mailbox

      PATCH /v1/mailboxes/{email}  ·  scope mailboxes:write

      Supply at least one of password, quota_bytes, disabled. Returns the updated mailbox.

      Request body

      Field Type Notes
      password string
      quota_bytes integer
      disabled boolean

      Response 200

      Updated mailbox.

      Field Type Notes
      id string Required.
      tenant_id string Required.
      domain_id string Required.
      email string Required.
      quota_bytes integer Required.
      disabled boolean Required.
      disabled_at string
      soft_deleted_at string
      hard_delete_after string
      created_at string Required.
      password string ONLY present on POST response when lockally generated the password. Shown once.

      Errors: 400, 401, 403, 404

      Soft-delete a mailbox

      DELETE /v1/mailboxes/{email}  ·  scope mailboxes:write

      Sets soft_deleted_at = now() and hard_delete_after = now() + 90d per design D25. A background sweep (planned) will hard-delete after the window. The mailbox is also disabled immediately.

      Response 204

      Soft-deleted.

      Errors: 401, 403, 404

      Request a mailbox export

      POST /v1/mailboxes/{email}/export  ·  scope tenant:admin

      Issues a one-shot “presigned” download URL for the mailbox’s content in mbox format. The URL works without an Authorization header, the token in the query string is the authz. TTL is 5 minutes; the token is consumed on first GET.

      v1 caveat: the synthesized mbox only contains outbound mail (sent mail only). A later version will cover received mail for full inbox + folder structure + flags. The endpoint contract stays unchanged.

      Scope changed: this used to accept mailboxes:read. It takes any mailbox in the tenant and returns that mailbox’s mail, so it now requires tenant:admin, matching POST /v1/ediscovery/export. A key scoped mailboxes:read gets 403 and has to be reissued; admin console sessions are unaffected.

      Response 201

      Export token issued.

      Field Type Notes
      url string Required. Relative download URL. Caller appends to the API host.
      expires_at string Required.
      format string (mbox) Required.

      Errors: 401, 403, 404

      Download a previously-issued mailbox export

      GET /v1/mailboxes/{email}/export/download

      Public endpoint (no Authorization header). Validates the one-shot token from the URL, marks it used, and streams an mbox file. Second GET with the same token returns 404, tokens are single-use.

      Response 200

      mbox stream.

      Errors: 400, 403, 404

      List shared mailbox members

      GET /v1/mailboxes/{email}/members  ·  scope mailboxes:read

      Response 200

      Members of the shared mailbox.

      Field Type Notes
      data array of SharedMember Required.

      Errors: 401, 403, 404

      Add a shared mailbox member

      POST /v1/mailboxes/{email}/members  ·  scope mailboxes:write

      Request body

      Field Type Notes
      member_email string Required.
      role string (manager, member)

      Response 201

      Member added.

      Field Type Notes
      id string Required.
      mailbox_id string Required.
      tenant_id string Required.
      member_email string Required.
      role string (manager, member) Required.
      created_at string Required.

      Errors: 400, 401, 403, 404, 409

      Remove a shared mailbox member

      DELETE /v1/mailboxes/{email}/members/{memberEmail}  ·  scope mailboxes:write

      Response 204

      No content

      Errors: 401, 403, 404