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

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 tokenAdmin token
Who can create itAny user, for themselvesAdmins only
What it reachesThe mailboxes you can open, or fewer if you chooseThe workspace's users, shared mailboxes, domains and plan
Reads mailYes, with the Read mail scopeNever
Longest expiry1 year90 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.

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 and Delivery status.
  • 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.

Still need help?

Write to support@onebitmail.com. A person reads every message.