Choose who sees mail and how your base mails

The base's builders always see Mail, and they choose which other roles see it in Settings, Mail. That page, for the base's builders, holds all that Mail needs: the mail the base takes (Turn mail on for your base), the triagers (Choose who gives new mail an owner), who sees Mail, and the base's addresses.

1. Click Settings, then Mail.
2. Under Who sees mail, "Builders always see mail. Turn on a role to let its users see every open mail in their Inbox, answer it and be its owner.", turn on the roles that should, such as Manager.
3. Click Save settings.

The users of such a role read mail, answer it, take it and give it back, mark it Done and make items from it, in the lists they may add to. You can also ask the assistant, such as "Let managers see Mail", and apply its card.

A role that is not on does not see Mail at all: no mail in its Inbox, nothing through an API token or an AI client, and its users cannot be owners or triagers. A customer of the business, with an external role, as in the customer portal, never sees Mail, and the switch does not list such roles (Roles and their types: admin, staff and external).

The first mail to a customer asks whether customers may answer, because a customer cannot answer the emails of a base that takes no mail. The first time a user who may change the settings, a user of an admin role, clicks a button that mails a customer, such as Mail the order on an order, the button asks before any mail goes. It asks in one dialog, the one that says who gets the mail: "Customers can answer this mail. You see their answers on this order.", with the box ticked. The line under the box says that this also changes one setting in Settings, Mail. A customer is any address that is not a user of the base. If the base has no payment method, Mail the order first says so; after you add one on Stripe, the order says that the mail is not sent yet and offers to send it, and that offer opens the same one dialog. Click the dialog's button, Mail the order:

• With the box ticked, the base takes Automations only, as if you picked it in Settings, Mail, and the mail goes. A customer's answer goes to the order's own address and becomes a comment on the order (Mail a comment and get the answer on the item). Your own address is never in the mail.
• With the box cleared, the mail goes with no address to answer to, Settings, Mail stays Off, and the base does not ask again. To let customers answer later, turn mail on in Settings, Mail (Turn mail on for your base).

While the base takes mail, or after a cleared box, the button sends with no question. The users of other roles are never asked: their mail goes as before. An automation, a workflow and the base's code never ask either, because no person clicked. Through an API token and an agent, the same question comes as an answer of the action (Use Mail with an API token or an AI client).

The mails of the apps show amounts in your base's currency, such as "$46.00", and never ask a customer to answer while the base takes no mail. The order's mail lists the order's lines, its total and how to pay, with the order's PDF attached.

Base Captain checks each mail first, with the checks that prove a mail comes from its sender's domain. A mail that fails them, which may be someone writing in the sender's name (spoofing), does not come into the Inbox. It waits in Activity, Held mail until one of the base's builders releases it or deletes it (Release or delete held mail):

1. Click Activity, then Held mail, and open the mail.
2. Click Release to put it in the Inbox, or Delete to drop it.

Every email your base sends goes out from Base Captain's own address, under your base's name followed by "via Base Captain", such as "Shop via Base Captain". So the person who gets it sees who sends it, on a phone too. This holds for the emails from automations, workflows, agents and the base's code, the notifications to your users, your team's answers in Mail and comments sent by mail.

The sender's name

The sender's name is the base's Name in Settings, General. A base's name cannot contain @. Such a name, such as "[email protected]", is refused with "A base's name cannot contain @", in Settings, General, when you create the base, through the API and through the assistant. A name such as "Ana's Bakery" saves.

The Report this mail link

Each email ends with one line under its text: "Sent by Shop with Base Captain. Report this mail" and a link. Each address the email went to gets a link of its own, which works for 30 days. The link opens a page of Base Captain that asks "Report this mail from Shop?", with one button, Report. Opening the page reports nothing: only the button does, as mail programs open the links of a mail to check them. After Report, the page says "Thank you. Shop will not mail you again. Base Captain will look at this base."

A report stops your base's mail to that address: other bases still mail it. A report counts as a mail marked as spam, so many reports pause your base's mail (Run actions when an item changes), and Base Captain's team is told of each report at once and looks at the base. A link reports once: a second Report counts nothing. A link that is not valid, or older than 30 days, shows "This link is not valid or has expired."

Where the answers go: the Sender address

The Sender address in Settings, Mail is where the answers to your base's emails go (the reply-to address). It takes one email address, such as [email protected], with no name. Another value, such as "Ana <[email protected]>" or two addresses, is refused with "Enter an email address", on the page, through the API and through the assistant. If you leave it empty, the answers come back to your base (Get mail at your base's own address).

Mail to invited users

A user you invite who has not joined yet counts as an address outside the base for its mail, until they accept the invitation. On the Free plan with no payment method, the base does not mail them (Turn mail on for your base). With a payment method, or on the Pro plan, a mail to them counts in the base's mails to outside addresses (What happens past a limit). The invitation itself always goes.

Automatic mail is mail sent by a program, not by a person: an out-of-office reply, a newsletter, or the mail of a mailing list. Such a mail makes no item and no comment, whatever address of the base it comes to: an automation's address, an item's own address or the answer to an email the base sent. It comes into Mail with the mark Automatic, in the Inbox and in its pane, so nothing is lost. A base that takes the mail of its automations only also keeps it in Mail. A mail from a person works as usual.

The emails your base sends by itself, from automations, workflows, agents and the base's code, say that they are automatic. So the other side's programs know it, and two automatic replies cannot answer each other with no end. An email that a person writes, such as an answer to a mail or a comment sent by mail, does not say it.

Mail in Base Captain has these limits:

• At most 5 automatic emails go to one address in an hour. The others wait, and the base sends them, the oldest first, as soon as fewer than 5 went to that address in the last hour. The emails about notifications to the users of your base are not in this limit.
• Nobody starts a new mail in the base: mails only come in.
• Only the base's builders may delete a mail.

Mail works with an API token too, as you, seeing what you see (Use your base from a script with an API token). Mail is the list _mail.

Read the mail

• GET /api/tables/_mail/items lists the mails. q searches their subject, sender and text, and filter keeps the open ones, as on any list: filter=[{"field":"status","op":"eq","value":"open"}], URL-encoded, or "done".
• GET /api/tables/_mail/items/<id> reads one mail, with its assigned_to, and …/<id>/comments its answers and replies.
• "automatic": true marks an automatic mail (Automatic mail and out-of-office replies), in these routes, in GET /api/me/inbox and in the tools list_mail and read_mail.
• GET /api/me/inbox lists, under mail, every open mail you may see, the oldest first, each with its owner and assigned_to ("" for none), files when it has files, and at, when it came or a reply opened it again. "waits": true marks those that wait for you: those you own, and, while you are a triager, those with no owner.
• GET /api/mail/users lists the users who may see Mail, each with its id, name and role, and the triagers' ids as they are now.

Give a mail an owner, or give it back

• POST /api/tables/_mail/items/<id>/assign with {"to": "<user id>", "from": "<the owner you read>"}, "" for none, gives the mail to that user; your own id takes it. If the owner is no longer the one you read, it is refused with "Ben Ionescu took this mail already." and nothing changes. A user who may not see Mail is refused with "This user may not see Mail".
• The same route with {"to": "", "from": "<your id>", "reason": "Not a billing question"} gives the mail back; the reason is not necessary. Anyone but the owner is refused with "Only its owner gives a mail back.".
• A PUT cannot change assigned_to.

Answer, close or turn a mail into an item

• POST /api/tables/_mail/items/<id>/comments with the text, the files and "mail": true answers a mail.
• PUT /api/tables/_mail/items/<id> with {"data": {"status": "done"}} marks a mail Done, and with "open" opens it again.
• POST /api/tables/_mail/items/<id>/item with the table, the new item's values and, if you like, files, the name of a files field of the table, makes an item from the mail and links them. A mail already linked is refused with "This mail is already linked to an item".
• DELETE /api/tables/_mail/items/<id> deletes a mail, for the base's builders.

The first mail to a customer

With an API token, POST /api/tables/<table>/actions/<key> asks the same question as the first mail to a customer on the web (Let customers answer your first mail), and sends nothing: it answers 409 with {"error": "Let customers answer?", "ask": "replies", "singular": "Order"}. To tick the box, set the settings' mail to "automations", then run the action again. To clear it, run the action again with "replies": false in its body. The assistant and the AI clients get the same question from the tool run_action: the agent asks you before it sends, then turns on Automations only or sends with no address to answer to, as you said.

The settings

The base's builders set the triagers with the settings' mail_triagers, a list of user ids, and the mail the base takes with the settings' mail, "off", "automations" or "all", through the builder API, and the assistant and AI clients with put_settings.

The tools of the assistant and AI clients

The assistant and the AI clients that reach the base through Base Captain's MCP server use these tools, offered only to the users who see Mail:

• list_mail lists the mails by status or a word q of the subject, the sender or the text, with each mail's owner;
• read_mail reads one mail with its answers and replies, its earlier owners with their reasons, and the users it may be given to;
• set_mail_status marks a mail Done or Open;
• assign_mail takes a mail, gives it to a user or gives it back with a reason, as the route does;
• mail_to_item makes an item from a mail.

What the tools change says in its history how: by the assistant, by an agent, or through the API for an AI client. No tool sends an answer: only a person does.