API reference

Mailboxes

The mailboxes endpoints manage the mailboxes of your company and their alternate emails. They follow the same rules as the console: addresses only in the company's verified domains, the plan's user limit and mailbox size, and the console privileges of the person who created the key.

Every endpoint needs a full-access key. A mailbox is named by its address in the path, URL-encoded (jane%40acme.com; an unencoded @ works too) and in any case. The endpoints can also return the common errors listed in the overview. Request bodies may be at most 64 KB. For setting up many mailboxes with a script, see Managing mailboxes, aliases and groups.

Permissions

A full-access key acts with the console rights of the person who created it. Each endpoint needs one of their console privileges; a role limited to an organisational unit can change only the mailboxes of that unit. A sending-access key gets 401 restricted_api_key, and a key whose creator lacks the right gets 403 invalid_permission.

Every change is recorded in the company's audit log under the key's name, like the same change made in the console.

The mailbox object

A password or its hash is never returned. The only exception is the temporary password in the answer of POST /mailboxes and POST /mailboxes/{email}/password, which is shown once and not stored anywhere readable.

The alias object

An alternate email (alias) is another address of a mailbox: mail to it is delivered to the mailbox, and the mailbox may also send as it.

GET /mailboxes

Lists the company's mailboxes, ordered by address.

Permission: full access; the key's creator needs View users.

Query

Request

curl "https://send.tsmart.ai/mailboxes?domain=acme.com&limit=100" \
  -H "Authorization: Bearer $TSMART_API_KEY"

Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "mailbox",
      "email": "jane@acme.com",
      "name": "Jane Doe",
      "domain": "acme.com",
      "active": true,
      "quota_mb": 2048,
      "used_bytes": 13002342,
      "messages": 120,
      "force_password_change": false,
      "org_unit": { "id": 12, "name": "Sales" },
      "aliases": ["j.doe@acme.com"],
      "last_sign_in_at": "2026-10-12 08:15:02.123000+00"
    }
  ]
}

Errors

POST /mailboxes

Creates a mailbox and returns it with a temporary password. The mailbox gets the console's settings for new users: encrypted connections are required for its incoming and outgoing mail, it is placed in its organisational unit and takes that unit's storage and mail app policies at once, and the user must choose a new password at the first sign-in. Creates for one company run one at a time, so requests sent in parallel wait for each other and can never go past the plan's user limit together.

Permission: full access; the key's creator needs Create users for the target unit.

Body

Request

curl -X POST https://send.tsmart.ai/mailboxes \
  -H "Authorization: Bearer $TSMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@acme.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "quota_mb": 2048,
    "org_unit_id": 12
  }'

const { data, error } = await tsmart.mailboxes.create({
  email: "jane@acme.com",
  first_name: "Jane",
  last_name: "Doe",
  quota_mb: 2048,
});
// data.temporary_password: give it to Jane over a safe channel

box = client.mailboxes.create({"email": "jane@acme.com", "name": "Jane Doe", "quota_mb": 2048})
print(box["temporary_password"])

Response

{
  "object": "mailbox",
  "email": "jane@acme.com",
  "name": "Jane Doe",
  "domain": "acme.com",
  "active": true,
  "quota_mb": 2048,
  "used_bytes": 0,
  "messages": 0,
  "force_password_change": true,
  "org_unit": { "id": 12, "name": "Sales" },
  "aliases": [],
  "last_sign_in_at": null,
  "temporary_password": "Xy7kQ2mN9pR4sT6vW8zA"
}

Errors

GET /mailboxes/{email}

Returns one mailbox.

Permission: full access; the key's creator needs View users.

Path

Request

curl https://send.tsmart.ai/mailboxes/jane%40acme.com \
  -H "Authorization: Bearer $TSMART_API_KEY"

Response

{
  "object": "mailbox",
  "email": "jane@acme.com",
  "name": "Jane Doe",
  "domain": "acme.com",
  "active": true,
  "quota_mb": 2048,
  "used_bytes": 13002342,
  "messages": 120,
  "force_password_change": false,
  "org_unit": { "id": 12, "name": "Sales" },
  "aliases": ["j.doe@acme.com"],
  "last_sign_in_at": "2026-10-12 08:15:02.123000+00"
}

Errors

PATCH /mailboxes/{email}

Changes a mailbox: its name and size, suspends or restores it, or switches the forced password change. Send at least one field. Each field needs its own privilege; if one is missing, nothing changes.

Permission: full access; the key's creator needs the privilege of each field, for this mailbox.

Path

Body

Request

curl -X PATCH https://send.tsmart.ai/mailboxes/jane%40acme.com \
  -H "Authorization: Bearer $TSMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jane Smith", "quota_mb": 4096 }'

await tsmart.mailboxes.update("jane@acme.com", { active: false }); // suspend

client.mailboxes.update("jane@acme.com", {"active": True})  # restore

Response

The mailbox after the change.

{
  "object": "mailbox",
  "email": "jane@acme.com",
  "name": "Jane Smith",
  "domain": "acme.com",
  "active": true,
  "quota_mb": 4096,
  "used_bytes": 13002342,
  "messages": 120,
  "force_password_change": false,
  "org_unit": { "id": 12, "name": "Sales" },
  "aliases": ["j.doe@acme.com"],
  "last_sign_in_at": "2026-10-12 08:15:02.123000+00"
}

Errors

DELETE /mailboxes/{email}

Deletes a mailbox with all its mail, its alternate emails and its directory entries (organisational unit, profile, group roles). Group memberships of the address are not changed. This cannot be undone.

Permission: full access; the key must be created by a company owner.

Path

Request

curl -X DELETE https://send.tsmart.ai/mailboxes/jane%40acme.com \
  -H "Authorization: Bearer $TSMART_API_KEY"

Response

{
  "object": "mailbox",
  "email": "jane@acme.com",
  "deleted": true
}

Errors

POST /mailboxes/{email}/password

Sets a new 20-character temporary password and returns it once. The old password stops working at once, and the user must choose a new password at the next sign-in. The request has no body.

Permission: full access; the key's creator needs Reset user passwords for this mailbox.

Path

Request

curl -X POST https://send.tsmart.ai/mailboxes/jane%40acme.com/password \
  -H "Authorization: Bearer $TSMART_API_KEY"

Response

{
  "object": "mailbox",
  "email": "jane@acme.com",
  "force_password_change": true,
  "temporary_password": "Ab3dEf5hJk7mNp9qRs2t"
}

Errors

GET /mailboxes/{email}/aliases

Lists the alternate emails of a mailbox, ordered by address. The list is never paged (has_more is always false).

Permission: full access; the key's creator needs View users.

Path

Request

curl https://send.tsmart.ai/mailboxes/jane%40acme.com/aliases \
  -H "Authorization: Bearer $TSMART_API_KEY"

Response

{
  "object": "list",
  "has_more": false,
  "data": [
    { "object": "alias", "address": "j.doe@acme.com", "mailbox": "jane@acme.com", "active": true }
  ]
}

Errors

POST /mailboxes/{email}/aliases

Adds an alternate email to a mailbox. The mailbox receives its mail at once and may send as it.

Permission: full access; the key's creator needs Update users for this mailbox.

Path

Body

Request

curl -X POST https://send.tsmart.ai/mailboxes/jane%40acme.com/aliases \
  -H "Authorization: Bearer $TSMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "address": "j.doe@acme.com" }'

await tsmart.mailboxes.aliases.create("jane@acme.com", { address: "j.doe@acme.com" });

client.mailboxes.aliases.create("jane@acme.com", {"address": "j.doe@acme.com"})

Response

{
  "object": "alias",
  "address": "j.doe@acme.com",
  "mailbox": "jane@acme.com",
  "active": true
}

Errors

DELETE /mailboxes/{email}/aliases/{address}

Removes an alternate email from a mailbox. Mail sent to it is no longer accepted.

Permission: full access; the key's creator needs Update users for this mailbox.

Path

Request

curl -X DELETE https://send.tsmart.ai/mailboxes/jane%40acme.com/aliases/j.doe%40acme.com \
  -H "Authorization: Bearer $TSMART_API_KEY"

Response

{
  "object": "alias",
  "address": "j.doe@acme.com",
  "mailbox": "jane@acme.com",
  "deleted": true
}

Errors