Skip to content
Docs
Email & messaging

Email

Let hires read, search, reply to and send email from any mailbox, on your own mail server or at a provider.

Explore 10 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With email connected, a hire can list and search mail in the folders you allow, read a message or a whole conversation, draft a reply for someone to check, reply and send new mail, and move or mark messages. Replies stay in their conversation in everyone's mail app. It works with any mailbox that offers IMAP and SMTP: your own mail server, Microsoft 365, Google Workspace, Zoho, Fastmail and most others.

Mail goes out in your business's name, like "Bayt Studio Accounts", never a made-up person's. Every email ends with that name as its signature.

1. Get the mailbox's details

You need, from your mail provider or whoever runs your mail server:

  • the IMAP server and SMTP server, like imap.example.com and smtp.example.com, and their ports;
  • the mailbox's username (usually its email address) and password.

Many providers don't let other apps use your account password. Make an app password for Roster instead, and paste that:

ProviderWhere
Google Workspacemyaccount.google.com/apppasswords (needs 2-Step Verification)
Microsoft 365Ask your IT team to allow SMTP AUTH and IMAP for the mailbox
Zoho MailMy Account → Security → App Passwords
iCloudappleid.apple.com → Sign-In and Security → App-Specific Passwords

We suggest a mailbox just for the hire's work, like accounts@yourbusiness.com, so you can see everything it sends and receives.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for Email and choose it.

  2. Username and Password: the mailbox's sign-in (or app password).

  3. IMAP server and SMTP server, with their ports and security:

    SecurityIMAP portSMTP port
    TLS993465
    STARTTLS143587

    Choose None only for a mail server inside your own network that has no encryption.

  4. From address: the address mail is sent from, usually the mailbox's own.

  5. From name: your business or team name, shown as the sender and in the signature.

  6. Keep a copy of sent mail: Yes puts each email sent in the Sent folder. Choose No if your provider does that itself (Gmail does).

  7. Click Connect. Roster signs in to the mailbox over IMAP first, and the connection shows Connected as its address. If the server refuses the username and password, Roster says so (and that many providers need an app password) and saves nothing.

3. Give hires access

On the hire's Tools tab, click Give access on Email:

  • Read only: it can list folders, list, search and read messages and conversations, and nothing else.
  • Read and write: it can also draft replies, reply, send new mail, and move and mark messages.
  • Folders: the folders it may use, like INBOX or Invoices. Leave it empty for every folder. Anything outside the list is refused.
  • Who it may email: domains it may send to, like yourclient.com. Leave it empty to let it email anyone.

If you'd like to check emails before they go, give the hire Read and write and ask it to draft replies: they wait in the mailbox's Drafts folder, in their conversation, for someone to send from their own mail app.

First emails to new people

A first email to someone outside your team that this mailbox has never written to waits for a person's approval: the hire asks in the thread with the recipient and the message, and when the approver says yes, Roster sends exactly that email. After that, writing to them again doesn't ask, and replies never do. People at your team's domains never count as new. To change this for a hire, use When it asks first on its Tools tab.

Saying it's an AI assistant

A hire never pretends to be a person, and always says it's AI when asked. If you also want every email to say so up front, turn on Say it's an AI assistant in first messages to outsiders under Settings → Workspace (more). Each email's signature then adds a line saying an AI assistant wrote it for your business.

Waking a hire when mail arrives

A hire's responsibility can watch email: when new mail lands in its folders (or the inbox, if it has none listed), the hire is woken with a line for each new email. Checking costs nothing when nothing arrived.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Email (IMAP and SMTP) and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

User name and password or key pair

The mailbox's sign-in, usually its email address. Many providers (Gmail, Outlook, iCloud, Zoho) need an app password here, not the account password.

No fixed permission list is declared for this connection. Review the sign-in consent screen, the account's roles, and the service's own documentation before connecting.

Connection fields

Email (IMAP and SMTP) connection fields
FieldWhat to provide
Username
username
Optional		The mailbox's sign-in, usually its email address. Many providers (Gmail, Outlook, iCloud, Zoho) need an app password here, not the account password.
Password
password
Optional · sealed secret		Use the value for your account or connection.
IMAP server
imapHost
Required		Use the value for your account or connection.
IMAP port
imapPort
Optional		Use the value for your account or connection.

Starts with: 993.

IMAP security
imapSecurity
Optional		Use the value for your account or connection.

Choices: TLS (usually port 993 for IMAP, 465 for SMTP) (tls); STARTTLS (usually port 143 for IMAP, 587 for SMTP) (starttls); None (only inside your own network) (none).

Starts with: tls.

SMTP server
smtpHost
Required		Use the value for your account or connection.
SMTP port
smtpPort
Optional		Use the value for your account or connection.

Starts with: 465.

SMTP security
smtpSecurity
Optional		Use the value for your account or connection.

Choices: TLS (usually port 993 for IMAP, 465 for SMTP) (tls); STARTTLS (usually port 143 for IMAP, 587 for SMTP) (starttls); None (only inside your own network) (none).

Starts with: tls.

From address
fromAddress
Required		The address mail is sent from: the mailbox's own, or one it may send as.
From name
fromName
Required		Your business or team name, shown as the sender and in the signature. Never a made-up person's name.
Keep a copy of sent mail
saveSent
Optional		Puts a copy of each email sent in the Sent folder. Choose No if your provider does that itself (Gmail does).

Choices: Yes, in the Sent folder (yes); No (no).

Starts with: yes.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

Email (IMAP and SMTP) per-hire limits
FieldWhat to provide
Folders
folders
Optional		Folders the hire may read and change, like INBOX or Invoices. Leave empty for every folder. A watch checks these (or INBOX).
Who it may email
recipientDomains
Optional		Domains the hire may send to, like example.com. Leave empty to let it email anyone.

Actions

10 actions: 5 only read and 5 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

10 of 10 actions. Open an action for its arguments and full input schema.

list_foldersRead only

The mail folders this hire can use, with how many messages and unread ones each has.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
list_messagesRead only

The newest messages in a folder, newest first: number, date, sender, subject, and whether read.

Approval: Uses your workspace and hire approval settings.

Arguments for list_messages
ArgumentTypeDetails
folderOptionalstringfolder, e.g. INBOXDefault: "INBOX"
unread_onlyOptionalbooleanSee input schema below.Default: false
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "folder": {
      "default": "INBOX",
      "description": "folder, e.g. INBOX",
      "type": "string",
      "minLength": 1
    },
    "unread_only": {
      "default": false,
      "type": "boolean"
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  }
}
searchRead only

Search a folder by words (in the subject or text), sender, subject or date. Newest matches first.

Approval: Uses your workspace and hire approval settings.

Arguments for search
ArgumentTypeDetails
folderOptionalstringfolder, e.g. INBOXDefault: "INBOX"
textOptionalstringwords anywhere in the message
fromOptionalstringpart of the sender's address or name
subjectOptionalstringSee input schema below.
sinceOptionalstringonly messages on or after this day, YYYY-MM-DD
unread_onlyOptionalbooleanSee input schema below.Default: false
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "folder": {
      "default": "INBOX",
      "description": "folder, e.g. INBOX",
      "type": "string",
      "minLength": 1
    },
    "text": {
      "description": "words anywhere in the message",
      "type": "string",
      "minLength": 1
    },
    "from": {
      "description": "part of the sender's address or name",
      "type": "string",
      "minLength": 1
    },
    "subject": {
      "type": "string",
      "minLength": 1
    },
    "since": {
      "description": "only messages on or after this day, YYYY-MM-DD",
      "type": "string",
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
    },
    "unread_only": {
      "default": false,
      "type": "boolean"
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  }
}
read_messageRead only

Read one message: who it's from and to, its date, subject and Message-ID, its text and its attachments' names. Doesn't mark it read.

Approval: Uses your workspace and hire approval settings.

Arguments for read_message
ArgumentTypeDetails
folderOptionalstringfolder, e.g. INBOXDefault: "INBOX"
uidRequiredintegerthe message's number in its folder, from list_messages or search
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "folder": {
      "default": "INBOX",
      "description": "folder, e.g. INBOX",
      "type": "string",
      "minLength": 1
    },
    "uid": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the message's number in its folder, from list_messages or search"
    }
  },
  "required": [
    "uid"
  ]
}
read_threadRead only

Read the whole conversation a message belongs to, oldest first, from this folder and the Sent folder: each message's sender, date and own words.

Approval: Uses your workspace and hire approval settings.

Arguments for read_thread
ArgumentTypeDetails
folderOptionalstringfolder, e.g. INBOXDefault: "INBOX"
uidRequiredintegerthe message's number in its folder, from list_messages or search
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "folder": {
      "default": "INBOX",
      "description": "folder, e.g. INBOX",
      "type": "string",
      "minLength": 1
    },
    "uid": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the message's number in its folder, from list_messages or search"
    }
  },
  "required": [
    "uid"
  ]
}
draft_replyRead and write

Write a reply to a message and keep it in the Drafts folder for a person to check and send. It stays in the message's thread. Write the message only: no greeting-card sign-off and never a person's name. Roster adds a signature in the business's name.

Approval: Uses your workspace and hire approval settings.

Arguments for draft_reply
ArgumentTypeDetails
folderOptionalstringfolder, e.g. INBOXDefault: "INBOX"
uidRequiredintegerthe message's number in its folder, from list_messages or search
bodyRequiredstringthe reply, plain text
reply_allOptionalbooleanalso to everyone else on the messageDefault: false
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "folder": {
      "default": "INBOX",
      "description": "folder, e.g. INBOX",
      "type": "string",
      "minLength": 1
    },
    "uid": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the message's number in its folder, from list_messages or search"
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "description": "the reply, plain text"
    },
    "reply_all": {
      "default": false,
      "description": "also to everyone else on the message",
      "type": "boolean"
    }
  },
  "required": [
    "uid",
    "body"
  ]
}
replyRead and write

Send a reply to a message, in its thread. Write the message only: no greeting-card sign-off and never a person's name. Roster adds a signature in the business's name.

Approval: Uses your workspace and hire approval settings.

Arguments for reply
ArgumentTypeDetails
folderOptionalstringfolder, e.g. INBOXDefault: "INBOX"
uidRequiredintegerthe message's number in its folder, from list_messages or search
bodyRequiredstringthe reply, plain text
reply_allOptionalbooleanalso to everyone else on the messageDefault: false
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "folder": {
      "default": "INBOX",
      "description": "folder, e.g. INBOX",
      "type": "string",
      "minLength": 1
    },
    "uid": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the message's number in its folder, from list_messages or search"
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "description": "the reply, plain text"
    },
    "reply_all": {
      "default": false,
      "description": "also to everyone else on the message",
      "type": "boolean"
    }
  },
  "required": [
    "uid",
    "body"
  ]
}
sendRead and write

Send a new email (not a reply: use reply for that, so it stays in its thread). Write the message only: no greeting-card sign-off and never a person's name. Roster adds a signature in the business's name.

Approval: Uses your workspace and hire approval settings.

Arguments for send
ArgumentTypeDetails
toRequiredstring[]email addresses
ccOptionalstring[]email addressesDefault: []
subjectRequiredstringSee input schema below.
bodyRequiredstringplain text
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "to": {
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3
      },
      "description": "email addresses"
    },
    "cc": {
      "default": [],
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3
      },
      "description": "email addresses"
    },
    "subject": {
      "type": "string",
      "minLength": 1,
      "maxLength": 250
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "description": "plain text"
    }
  },
  "required": [
    "to",
    "subject",
    "body"
  ]
}
moveRead and write

Move messages from one folder to another (both must be folders this hire can use).

Approval: Uses your workspace and hire approval settings.

Arguments for move
ArgumentTypeDetails
folderOptionalstringfolder, e.g. INBOXDefault: "INBOX"
uidsRequiredinteger[]See input schema below.
toRequiredstringthe folder to move them to
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "folder": {
      "default": "INBOX",
      "description": "folder, e.g. INBOX",
      "type": "string",
      "minLength": 1
    },
    "uids": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991,
        "description": "the message's number in its folder, from list_messages or search"
      }
    },
    "to": {
      "type": "string",
      "minLength": 1,
      "description": "the folder to move them to"
    }
  },
  "required": [
    "uids",
    "to"
  ]
}
markRead and write

Mark messages read or unread, or flag and unflag them.

Approval: Uses your workspace and hire approval settings.

Arguments for mark
ArgumentTypeDetails
folderOptionalstringfolder, e.g. INBOXDefault: "INBOX"
uidsRequiredinteger[]See input schema below.
asRequired"read" | "unread" | "flagged" | "unflagged"See input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "folder": {
      "default": "INBOX",
      "description": "folder, e.g. INBOX",
      "type": "string",
      "minLength": 1
    },
    "uids": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991,
        "description": "the message's number in its folder, from list_messages or search"
      }
    },
    "as": {
      "type": "string",
      "enum": [
        "read",
        "unread",
        "flagged",
        "unflagged"
      ]
    }
  },
  "required": [
    "uids",
    "as"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • No incoming webhook handler is declared for this integration.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

Discord

Read and post messages in a Discord server as a bot.

Gmail

Let hires read, search, reply to and send email in a Gmail or Google Workspace mailbox.

On this page

1. Get the mailbox's details2. Connect it in Roster3. Give hires accessFirst emails to new peopleSaying it's an AI assistantTools and permissions reference