Docs · Pushbox, Tokenmail and Ping

Tokenmail: inboxes

Email addresses for agents, on froogmail.com or a domain of yours: an agent signs up for a service with one, then reads the one-time code or follows the verification link itself, and keeps a mailbox with threads, labels, search and events. $2 per inbox a month, on a subscription of its own (separate from the wallet). See froog Tokenmail. Sending isn't turned on yet: the send, reply, forward and draft-send endpoints are in the API and answer 503 mail_send_off until it is.

$ froog inbox create --username signup --name "acme trial"   # prints signup-k3f9qz@froogmail.com (Stripe Checkout opens the first time)
$ froog inbox wait signup-k3f9qz@froogmail.com --code        # waits for mail with a code, prints just the code
$ froog inbox wait signup-k3f9qz@froogmail.com --link --from acme   # or the verification link
$ froog inbox messages signup-k3f9qz@froogmail.com           # newest first; --label, --sent, --all
$ froog inbox read signup-k3f9qz@froogmail.com msg_…         # one message; --html, --raw
$ froog inbox threads ADDRESS · thread ADDRESS thr_…          # conversations
$ froog inbox search "invoice" [--inbox ADDRESS]              # full text, best match first
$ froog inbox label ADDRESS msg_… --add done --remove unread
$ froog inbox attachment ADDRESS msg_… att_0                  # saves it under its own name
$ froog inbox events --follow                                  # received, labels, deliveries… as they happen
$ froog inbox list · billing · rm ADDRESS

# for the agent in a VM: attach one, and it's $FROOG_EMAIL there from the VM's next start
$ froog inbox create --sandbox my-vm          # or: froog inbox attach ADDRESS my-vm · detach ADDRESS
$ CODE=$(froog inbox wait "$FROOG_EMAIL" --code)   # inside my-vm

Each message comes with the one-time codes and verification links found in it, most likely first, so an agent doesn't have to parse mail. A code is 4 to 8 digits (123456, 123-456) or 6 to 8 capitals and digits, next to a word like "code" or "verify". Prices, years and phone numbers aren't codes. Footer links (unsubscribe, privacy, social) are left out. wait also counts mail from the last minute, so start it right after submitting the form. --subject Filters too, --timeout is in seconds (default 300), and --json prints the whole message. Name an inbox by its full address, the part before @, or its id. Mail to name+anything@froogmail.com goes to name@froogmail.com.

Messages, threads and labels. A message has its sender, to, cc and reply_to, its Message-ID and the ids it answers, its attachments (each att_0, att_1… with name, type and size, download one by id), its text and HTML, and extracted_text/extracted_html: the new part of a reply, without the quoted message under it or the sender's signature. Getting one message also gives its headers. Messages join the thread of the message they answer (In-Reply-To, then References). A thread lists its senders, recipients, labels, message count and its messages oldest first. Labels: froog sets received, sent, unread, unauthenticated, blocked, bounced. You can add and remove your own (1-64 characters, lowercased) and unread, spam and trash, on a message, a whole thread, or up to 100 messages at once. Lists and waits leave out spam, blocked, unauthenticated and trash unless you ask (include_spam=true and so on). Filter by labels, sender, recipient, subject, direction and time, newest or oldest first, 100 to a page with next_page_token. Search looks in subjects, senders, recipients and bodies (each word matches as a prefix), best match first, with the text around the match.

Who sent it. Received mail is checked with SPF, DKIM and DMARC (the results are on the message as auth). Mail that fails DMARC where the sender's domain asks for reject or quarantine is refused while the sender is connected. Mail that passes neither SPF nor DKIM is kept with the unauthenticated label, so a forged "your code is…" never reaches a wait. To see it: the dashboard's Unverified senders folder (search finds it too), froog inbox messages ADDRESS --unverified, or include_unauthenticated=true on lists and wait. froog inbox wait --code that times out says when unverified mail arrived meanwhile, and --unverified counts it. Lookups that time out never count against a message.

Moving an agent off your Gmail. An agent that signs in to your Google account acts as you, so if its activity gets the account flagged, it's your whole account at risk. Give it an inbox instead, and when it needs to work on mail you already get, forward just that mail from Gmail: froog inbox create --username invoices, then in Gmail open Settings, Forwarding and POP/IMAP, and add the new address. Google emails it a confirmation: froog inbox wait ADDRESS --from google.com waits for it, and you enter the code from it back in Gmail. Then make a Gmail filter for the mail the agent should see (a sender, a subject, some words) and set "Forward it to" to the address. Only new mail that matches is forwarded, the agent never has your Google login, and the inbox's key reads that inbox and nothing else. Forwarded mail keeps the sender's DKIM signature, so it passes the checks above. A message its sender never signed arrives with the unauthenticated label (include_unauthenticated=true lists it).

Inbox settings. An inbox has a display name (the name in From), your own client_id (making an inbox with one you used before returns that inbox, so retries are safe), metadata (up to 64 keys, a PATCH merges, null removes a key), a signature added to everything it sends, expiry_hours (delete its messages sooner than the 30 days), and a status: a deactivated inbox refuses mail and can't send, now or at a deactivate_at time. Find inboxes by the start of a word of their address or name with GET /v1/inboxes/search?q=.

Events. Everything that happens is an event: message.received (or message.received.spam, .blocked, .unauthenticated), message.sent, message.delivered, message.bounced, message.complained, message.rejected, label.added, label.removed and domain.verified, with the message and its thread (bodies over 64 KiB left out). Get them three ways: webhooks that list the event (optionally only for some inboxes, label events aren't sent to webhooks), the feed GET /v1/inboxes/events?after=CURSOR&wait=55 (kept 30 days, wait holds the request until there's something, for agents that can't take incoming HTTP), or a WebSocket at /v1/inboxes/events/ws (each event one JSON message, send {"type":"subscribe","inboxes":[…],"types":[…]} to change what you get). GET /v1/inboxes/metrics counts events per type and per day, with bounce and complaint rates and what's stored.

Allow and block lists. froog inbox rules add receive block spam.example: lists for who inboxes take mail from (receive), send new mail to (send) and reply to (reply), of addresses or domains (a domain covers its subdomains), for the account or one inbox (--inbox). The inbox's lists come first, then the account's. Once an allow list has entries, only what's on it gets through. Blocked mail is kept with the blocked label. A send to a refused address fails before anything goes out.

Your own domain. froog inbox domain add example.com lists the DNS records to publish: MX (to receive), an ownership TXT record at _froog-verify.example.com, SPF, a DKIM key made for the domain, and DMARC (recommended). While sending is off, only MX and the ownership record are required: SPF and DKIM are listed for later and become required once sending is on. SPF: a domain may have only one v=spf1 record. If yours already has one, add include:_spf.froogmail.com to it (before its ~all or -all) instead of adding a second record, which would make SPF fail for all of the domain's mail. After the first check, the SPF value froog shows is your existing record with the include merged in. It verifies by itself within about 10 minutes of the records appearing (froog inbox domain verify example.com looks now). Then froog inbox create --username sales --domain example.com makes exactly sales@example.com, and with --subdomains any name@team.example.com. froog inbox domain zone prints the records as a zone file, and froog inbox domain link a public page with them for whoever runs your DNS. A domain whose records go missing keeps working for 7 days. Several accounts can add a domain while it's unverified. Only the one whose ownership record is published gets it.

Sending (not on yet). When it's on: froog inbox send ADDRESS --to x@example.com --subject … --text … (or POST /v1/inboxes/{inbox}/messages/send with to, cc, bcc, reply_to, text, html, base64 attachments, labels, X- headers), reply and reply-all (in the same thread, Re: and threading headers set for you), and forward (with the original's attachments). Mail goes out signed with DKIM for the inbox's domain. An Idempotency-Key header makes a send safe to retry. send_at Schedules it. Each recipient's delivery shows on the message as delivery and in events. An address that hard-bounces or reports spam goes on the account's suppression list (GET /v1/inboxes/suppressions, delete one to try it again). Limits: 50 recipients a message, 10 MB of attachments, 100 messages per 5 minutes and 1,000 a day per account, and in an account's first week 25 new addresses a day that haven't written to it first. Drafts (/v1/inboxes/{inbox}/drafts): new, reply, reply-all or forward drafts with attachments and labels. With send_at one is scheduled and goes by itself. Auto-forwarding: copy received mail to up to 5 addresses for the account or one inbox. Each address confirms with a code we email it first. Spam, blocked and unauthenticated mail isn't forwarded. Forwarding sends mail, so it can't be set up until sending is on (verifying an address answers 503 mail_send_off): until then, read mail with froog inbox wait or the API, or get it pushed with a message.received webhook.

Paying. Inboxes are seats on a Stripe subscription of their own, separate from the wallet: no free tier, no trial. The first froog inbox create opens Checkout and waits until you've paid. After that, each new inbox uses a free seat or adds one, with the rest of the month charged at once. Delete an inbox and its seat stays paid until the period ends (a new inbox can use it). At the renewal you're billed for the inboxes you have, with no credit for removals. With none left, the subscription ends at the period's end. If a payment fails and the subscription lapses, mail to your inboxes is refused until it's paid. froog inbox billing shows seats, inboxes and the renewal. Cancel or change the card in Manage billing (the Stripe customer portal).

In the dashboard. Tokenmail is a mail client. New inbox walks through naming the address, paying for the first inbox at Stripe Checkout when there's no inbox subscription yet, and a ready screen with the address, a welcome email to send to it, and an API key that can only use inboxes. In the mailbox: an inbox switcher, Compose, and the folders Inbox, Sent, Drafts, Scheduled, All mail, Unverified senders, Spam and Trash, search, and the open message (HTML, text, or raw with every header) with the rest of its conversation above it, its code and verification link at the top, and Reply, Reply all, Forward, Mark unread, Spam and Trash. While sending is off, Compose, Reply and Forward are shown but disabled. Domains adds a domain and shows its records, zone file and a link for your DNS admin, checks DNS and deletes it. Settings has forwarding, the account's allow and block lists, suppressions and 30-day metrics. Opening a message marks it read. HTML mail shows in a locked-down frame, with no scripts and no remote images, and its links open in a new tab. The page checks for new mail every 15 seconds.

In a VM. VMs don't get an inbox by themselves. Attach one (one per VM) and it's $FROOG_EMAIL there from the VM's next start. The key inside the VM uses only that inbox: it can read, label, delete and (when sending is on) send there, but a key limited to some sandboxes sees only their inboxes and can't buy, create, change or delete inboxes or change account-wide settings (domains, lists, forwarding). Deleting the VM detaches the inbox. It stays yours.

Only mail for an existing inbox is accepted. Anything else is refused while the sender is still connected, so nobody gets a bounce from us later. Mail arrives over TLS when the sender supports it. Messages are kept 30 days. A deleted inbox's address is never given out again, so nobody receives a previous owner's codes.

Use them for services that allow it. Don't use them to create accounts in bulk, to get around a ban, or to get past a CAPTCHA: when a sign-up shows one, solve it yourself in the VM's desktop and let the agent carry on (see the acceptable use policy).

API (the whole list is in the OpenAPI document): inboxes GET/POST /v1/inboxes, GET /v1/inboxes/search, GET/PATCH/DELETE /v1/inboxes/{inbox}. Messages GET …/{inbox}/messages (filters above), …/messages/search?q=, GET/PATCH (labels)/DELETE …/messages/{id}, …/raw, …/attachments/{att}, POST …/messages/batch-get and batch-update, POST …/messages/send, …/{id}/reply, reply-all, forward. Threads GET …/{inbox}/threads, GET/PATCH/DELETE …/threads/{thread}. Drafts …/{inbox}/drafts[/{id}[/send]]. Across every inbox GET /v1/inboxes/messages, /messages/search, /threads, /threads/{thread}, /drafts. GET /v1/inboxes/{inbox}/wait (holds the request until a matching message arrives, up to 120 seconds, null on timeout). Events /v1/inboxes/events, /events/ws, …/{inbox}/events. /v1/inboxes/metrics. Lists /v1/inboxes[/{inbox}]/lists/{receive|send|reply}/{allow|block}[/{entry}]. Domains /v1/inboxes/domains[/{domain}[/verify|/zone-file|/setup-link]]. Forwarding /v1/inboxes[/{inbox}]/forwarding and /v1/inboxes/forwarding/verifications[/confirm]. /v1/inboxes/suppressions. Billing GET /v1/inboxes/billing, POST /v1/inboxes/billing/checkout. Reading needs inbox.read, sending, replying and forwarding inbox.send, the rest inbox.write (making an inbox can add a paid seat). The SDKs have them as createInbox, listInboxThreads, searchInboxMessages, sendInboxMessage, replyToInboxMessage, listMailEvents, createMailDomain, waitForInboxMessage and so on.