# Use the API and webhooks

Create a token, call the API from your own scripts and tools, get webhook events, and revoke a token.

Updated 2026-11-21

The One Bit Mail API lets your own scripts and tools read and send mail, and lets admins manage the
workspace. You connect with a **token**. A token never reaches further than the person who created
it, and everything sent through the API follows the same rules as the app.

## Two kinds of token

| | Personal token | Admin token |
| --- | --- | --- |
| Who can create it | Any user, for themselves | Admins only |
| What it reaches | The mailboxes you can open, or fewer if you choose | The workspace's users, shared mailboxes, domains and plan |
| Reads mail | Yes, with the **Read mail** scope | Never |
| Longest expiry | 1 year | 90 days |

A personal token and an admin token are separate on purpose: a script that manages users can't read
mail, and a mail integration can't create users. If you need both, create two tokens.

## Create a personal token

1. Open **Settings** → **API tokens**.
2. Under **New personal token**, give the token a **Name** you will recognise, for example
   *CRM sync*.
3. Choose its **Scopes**, only the ones your tool needs:
   - **Mailboxes**: list mailboxes and unread counts.
   - **Read mail**: read, search and move conversations, and mark them read.
   - **Drafts**: create and change drafts.
   - **Send mail**: send messages and drafts. Sending limits and holds still apply.
4. Under **Mailboxes**, keep **Every mailbox I can open**, or pick only some.
5. Choose when it **Expires after**: 7, 30 or 90 days, or 1 year.
6. Choose **Create token**, then copy it. **It is shown once.** If you lose it, revoke it and create
   a new one.

## Create an admin token (admins)

Admins see a **Workspace (admins)** section on the same page. Under **New admin token**, choose its
scopes (**Users**, **Shared mailboxes**, **Domains** and **Billing (read only)**) and an expiry of at
most 90 days. An admin token can never read mail, the same as the Admin console. See
[How One Bit Mail works](https://onebitmail.com/help/how-one-bit-mail-works/#who-sees-what).

## Call the API

Send requests to `https://app.onebitmail.com/api/v1` with the header
`Authorization: Bearer` followed by your token. Keep tokens on servers and in scripts, never in a web
page or an app other people can see.

- **Sending** goes through the same sending limits, reviews and attachment checks as the app. A
  message can be held for review, exactly as in the app. See [Sending limits](https://onebitmail.com/help/sending-limits/#what-counts)
  and [Delivery status](https://onebitmail.com/help/delivery-status/#held-for-review).
- **Each token can send up to 60 messages an hour** (30 on the Free plan), on top of the workspace's
  sending limits, so one runaway script can't use up the whole day's allowance.
- **Requests are rate limited.** If you send too many at once, the API answers with status 429:
  wait a moment and try again.

## Webhooks

A webhook tells your system when something happens, so it doesn't have to keep asking. Create one
through the API with a personal token that has the **Read mail** scope, and give it an `https://`
address.

- **Events**: a message arrived in a mailbox the token reaches, or a message was sent through the API
  or an AI assistant.
- **What an event contains**: details such as the mailbox, the sender and the subject, never the
  message body. Your system then fetches the message with its token, so access is checked again.
- **Signed**: each event is signed with the endpoint's secret, in the Standard Webhooks format. Check
  the signature before you trust an event. The secret is shown once when you create the endpoint;
  you can rotate it, and the old secret keeps working for 24 hours.
- **Retried**: if your system doesn't answer with a success status, the event is sent again with
  growing gaps for up to 3 days. An endpoint that fails for 3 days in a row is turned off.

## See and revoke tokens

**Settings** → **API tokens** → **Your tokens** lists your tokens with when each was created, when it
expires and when it was last used. Open **Activity** to see what a token changed, such as messages
sent or drafts saved. Reads through the API are not listed one by one.

To revoke a token, choose **Revoke** next to it and confirm. Anything using it stops working at once,
and its webhooks are turned off. This can't be undone. Admins see every live token in the workspace
under **Other users' tokens** and can revoke any of them.

Tokens also stop working by themselves when:

- they expire;
- their user is suspended or deleted;
- an admin token's owner is no longer an admin.

## Related

- [Connect an AI assistant (MCP)](https://onebitmail.com/help/connect-an-ai-assistant/)
- [Sending limits](https://onebitmail.com/help/sending-limits/)
