API reference

Groups

A group is an address that delivers each message to all of its members: mailboxes of your company or outside addresses. The groups endpoints follow the same rules as the console.

Every endpoint needs a full-access key. A group is named by its address in the path, URL-encoded (team%40acme.com) 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 groups with a script, see Managing mailboxes, aliases and groups.

Libraries and CLI
Endpoint	Node.js	Python	CLI
GET /groups	`groups.list`	`groups.list`	`tsmart groups list`
POST /groups	`groups.create`	`groups.create`	`tsmart groups create`
GET /groups/{address}	`groups.get`	`groups.get`	`tsmart groups get`
PATCH /groups/{address}	`groups.update`	`groups.update`	`tsmart groups update`
DELETE /groups/{address}	`groups.remove`	`groups.remove`	`tsmart groups delete`

Permissions

A full-access key acts with the console rights of the person who created it. Reading groups needs the View groups privilege, creating and changing them Manage groups, and deleting a group is the company owner's right. 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; each member added or removed gets its own entry.

The group object

Name	Type	Description
`object`	string	Always "group".
`address`	string	The group's address, lowercase. It names the group in every path.
`name`	string	The group's name, or an empty string.
`members`	string[]	Member addresses, lowercase: mailboxes of the company or outside addresses. A group without members discards its mail.
`active`	boolean	Whether mail to the address is accepted.

Who may send to a group and other access settings are managed in the console; a group created through the API gets the console's defaults.

GET `/groups`

Lists the company's groups, ordered by address.

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

Query

Name	Type	Description
`limit`	integer	1 to 100, default 20.
`after`	string	An address: return the groups that come after it. Pass the address of the last group of a page to get the next page.
`before`	string	An address: return the groups that come before it. Use either after or before.
`domain`	string	Only groups in this domain, which must be one of the company's verified domains.

Request

cURL

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

Response

200 OK

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "group",
      "address": "team@acme.com",
      "name": "Team",
      "members": ["jane@acme.com", "partner@example.org", "sam@acme.com"],
      "active": true
    }
  ]
}

Errors

Status	Name	When
401	`restricted_api_key`	A sending-access key.
403	`invalid_permission`	The key's creator lacks View groups.
422	`validation_error`	`limit` out of range, both `after` and `before`, a cursor that is not an address, or a `domain` that is not a verified domain of the company.

POST `/groups`

Creates a group.

Permission: full access; the key's creator needs Manage groups.

Body

Name	Type	Description
`address` required	string	A free address in one of the company's verified domains. The part before @ may use letters, digits and . _ + -, and must start and end with a letter or digit.
`name`	string	The group's name, at most 160 characters.
`members`	string[]	Up to 200 member addresses (duplicates and case are ignored); never the group itself. Default: no members.

Request

cURL

curl -X POST https://send.tsmart.ai/groups \
  -H "Authorization: Bearer $TSMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "team@acme.com",
    "name": "Team",
    "members": ["jane@acme.com", "sam@acme.com", "partner@example.org"]
  }'

Node.js

const { data, error } = await tsmart.groups.create({
  address: "team@acme.com",
  name: "Team",
  members: ["jane@acme.com", "sam@acme.com", "partner@example.org"],
});

Python

client.groups.create({"address": "team@acme.com", "name": "Team", "members": ["jane@acme.com", "sam@acme.com"]})

Response

200 OK

{
  "object": "group",
  "address": "team@acme.com",
  "name": "Team",
  "members": ["jane@acme.com", "partner@example.org", "sam@acme.com"],
  "active": true
}

Errors

Status	Name	When
401	`restricted_api_key`	A sending-access key.
403	`invalid_permission`	The key's creator lacks Manage groups.
409	`already_exists`	The address is already a mailbox, a group or an alternate email.
422	`missing_required_field`	`address` is missing.
422	`validation_error`	`address` is not an address, its part before @ is not allowed or its domain is not a verified domain of the company; `name` is not text; `members` is not a list of addresses, has more than 200 entries, or contains the group itself.
502	`mail_server_error`	The mail server refused the group.

GET `/groups/{address}`

Returns one group with its members.

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

Path

Name	Type	Description
`address` required	string	The group's address (URL-encoded; case does not matter).

Request

cURL

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

Response

200 OK

{
  "object": "group",
  "address": "team@acme.com",
  "name": "Team",
  "members": ["jane@acme.com", "partner@example.org", "sam@acme.com"],
  "active": true
}

Errors

Status	Name	When
401	`restricted_api_key`	A sending-access key.
403	`invalid_permission`	The key's creator lacks View groups.
404	`not_found`	No such group in the company's domains ("Group not found").

PATCH `/groups/{address}`

Renames a group and/or replaces its member list. Send at least one field. The new member list is checked before anything changes; members that are left out lose their role in the group.

Permission: full access; the key's creator needs Manage groups.

Path

Name	Type	Description
`address` required	string	The group's address (URL-encoded).

Body

Name	Type	Description
`name`	string	New name, at most 160 characters (an empty string removes it).
`members`	string[]	The complete new member list, up to 200 addresses. [] removes every member.

Request

cURL

curl -X PATCH https://send.tsmart.ai/groups/team%40acme.com \
  -H "Authorization: Bearer $TSMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Team EU", "members": ["jane@acme.com", "lee@acme.com"] }'

Node.js

// Add one member: read the list, change it, send it back
const { data: group } = await tsmart.groups.get("team@acme.com");
await tsmart.groups.update("team@acme.com", { members: [...group.members, "lee@acme.com"] });

Python

group = client.groups.get("team@acme.com")
members = [m for m in group["members"] if m != "sam@acme.com"]
client.groups.update("team@acme.com", {"members": members})

Response

The group after the change.

200 OK

{
  "object": "group",
  "address": "team@acme.com",
  "name": "Team EU",
  "members": ["jane@acme.com", "lee@acme.com"],
  "active": true
}

Errors

Status	Name	When
401	`restricted_api_key`	A sending-access key.
403	`invalid_permission`	The key's creator lacks Manage groups.
404	`not_found`	No such group in the company's domains.
422	`validation_error`	No field to change ("Nothing to update: send `name` or `members`"), `name` is not text, or `members` is not a list of addresses, has more than 200 entries, or contains the group itself.
502	`mail_server_error`	The mail server refused the change.

DELETE `/groups/{address}`

Deletes a group with its access settings and member roles. Mail to its address is no longer accepted; the members' mailboxes are not affected.

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

Path

Name	Type	Description
`address` required	string	The group's address (URL-encoded).

Request

cURL

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

Response

200 OK

{
  "object": "group",
  "address": "team@acme.com",
  "deleted": true
}

Errors

Status	Name	When
401	`restricted_api_key`	A sending-access key.
403	`invalid_permission`	The key was not created by a company owner.
404	`not_found`	No such group in the company's domains.
502	`mail_server_error`	The mail server refused to delete the group.

Groups

Permissions

The group object

GET /groups

Query

Request

Response

Errors

POST /groups

Body

Request

Response

Errors

GET /groups/{address}

Path

Request

Response

Errors

PATCH /groups/{address}

Path

Body

Request

Response

Errors

DELETE /groups/{address}

Path

Request

Response

Errors

GET `/groups`

POST `/groups`

GET `/groups/{address}`

PATCH `/groups/{address}`

DELETE `/groups/{address}`