Developers

Alias API

Create and manage aliases from your own code, scripts and apps. The 886.bot API follows the addy.io API, so tools built for addy.io work by changing the server URL to https://886.bot. It’s free, with no monthly request quota.

Base URL

https://886.bot/api/v1

Authentication

Send a personal access token as Authorization: Bearer 886al_…. Create tokens in Webmail → Aliases → API & apps.

Format

Requests and responses are JSON. Send Content-Type: application/json and Accept: application/json.

Rate limit

Up to 600 requests per minute for each token, generous enough for any app or script.

Use 886.bot with existing apps

Official addy.io browser extension and mobile apps

Open the extension or app, choose to use a self-hosted instance, and enter https://886.bot. Then sign in with your 886.bot address (or a username that can sign in) and password, or paste an API token. If you use two-factor authentication, you’ll be asked for a code.

Bitwarden and other password managers

In the username generator, choose Forwarded email alias, select addy.io, set the server URL to https://886.bot, paste an API token and choose your alias domain.

The 886.bot browser extension

Our own lightweight extension for Chrome, Edge and Firefox. Download and install it.

Signing in from an app

Apps can exchange a username and password for a token, so people don’t have to copy tokens by hand.

Method	Path	Description
POST	/api/auth/login	{"username", "password", "device_name", "expiration": null\|"day"\|"week"\|"month"\|"year"} returns {"api_key", "expires_at"}. If two-factor authentication is on, the response is 422 with {"mfa_key"}.
POST	/api/auth/mfa	{"mfa_key", "otp", "device_name", "expiration"} returns {"api_key", "expires_at"}. The otp is a 6-digit authenticator code or a backup code.
POST	/api/auth/logout	Revokes the token sent in the Authorization header.

Account

Method	Path	Description
GET	/api-token-details	Name, creation date and expiry of the token in use.
GET	/account-details	Your account: defaults, totals and webhook secret.
GET	/app-version	The addy.io API version this server follows (currently 1.7.4).
GET	/domain-options	Domains you can create aliases on, plus your default domain and format.
GET	/chart-data	Forwards, replies, sends and blocks for the last 7 days.

Aliases

Method	Path	Description
GET	/aliases	List aliases. Filters: filter[search], filter[active]=true\|false, filter[pinned]=true\|false, filter[deleted]=with\|only, filter[label], filter[domain]. Sort with sort=email or sort=-created_at. Paginate with page[number] and page[size] (up to 100).
POST	/aliases	Create an alias: {"domain", "format", "local_part", "description", "from_name", "recipient_ids", "label_ids"}. Formats: random_characters, random_words, random_noun, random_male_name, random_female_name, uuid, custom.
GET	/aliases/{id}	Get one alias.
PATCH	/aliases/{id}	Update {"description", "from_name", "active", "pinned", "attached_recipients_only"}.
DELETE	/aliases/{id}	Delete an alias. Mail to it is rejected until you restore it.
PATCH	/aliases/{id}/restore	Restore a deleted alias.
DELETE	/aliases/{id}/forget	Forget an alias for good. It can never be used again.
POST · DELETE	/active-aliases · /active-aliases/{id}	Activate {"id"} or deactivate an alias.
POST · DELETE	/pinned-aliases · /pinned-aliases/{id}	Pin {"id"} or unpin an alias.
POST · DELETE	/attached-recipients-only · /attached-recipients-only/{id}	Allow only the alias’s own recipients to reply and send.
POST	/alias-recipients	Set recipients: {"alias_id", "recipient_ids": [...]}. An empty list uses your default recipient.
POST	/alias-labels	Set labels: {"alias_id", "label_ids": [...]}.
POST	/aliases/{id}/contacts	Get the address to send from an alias: {"email": "someone@example.com"}.
POST	/aliases/{action}/bulk	Bulk actions on {"ids": [...]}: get, activate, deactivate, pin, unpin, delete, restore, forget, recipients ({"recipient_ids"}) and labels ({"label_ids"}).

Recipients

Method	Path	Description
GET	/recipients	List recipients. filter[verified]=true returns only verified ones.
POST	/recipients	Add {"email"}. A verification link is emailed to the address.
GET · PATCH · DELETE	/recipients/{id}	Get, update {"description"} or remove a recipient.
POST	/recipients/email/resend	Resend the verification email: {"recipient_id"}.
PATCH · DELETE	/recipient-keys/{id}	Add {"key_data"} or remove an OpenPGP public key.
POST · DELETE	/encrypted-recipients[/{id}]	Turn encryption on {"id"} or off. Similar endpoints: /inline-encrypted-recipients, /protected-headers-recipients, /remove-pgp-keys-recipients, /remove-pgp-signatures-recipients, /allowed-recipients and /active-recipients.

Usernames

Method	Path	Description
GET · POST	/usernames	List usernames, or add one: {"username", "description"}.
GET · PATCH · DELETE	/usernames/{id}	Get, update {"description", "from_name", "auto_create_regex"} or remove a username and its aliases.
PATCH	/usernames/{id}/default-recipient	Set {"default_recipient"} (a recipient ID, or null for your account default).
POST · DELETE	/active-usernames · /catch-all-usernames · /loginable-usernames	Turn a username, its catch-all or sign-in with it on {"id"} or off (/…/{id}).

Custom domains

Method	Path	Description
GET · POST	/domains	List domains, or add one: {"domain"}. Add the ownership TXT record first.
GET · PATCH · DELETE	/domains/{id}	Get, update {"description", "from_name", "auto_create_regex"} or remove a domain and its aliases.
GET	/domains/{id}/check-sending	Check the MX, SPF, DKIM and DMARC records now.
PATCH	/domains/{id}/default-recipient	Set {"default_recipient"}.
POST · DELETE	/active-domains · /catch-all-domains	Turn a domain or its catch-all on {"id"} or off (/…/{id}).

Rules

Method	Path	Description
GET · POST	/rules	List rules, or create one: {"name", "conditions", "actions", "operator": "AND"\|"OR", "forwards", "replies", "sends"}.
GET · PATCH · DELETE	/rules/{id}	Get, update or delete a rule.
POST	/reorder-rules	Set the order: {"ids": [...]}.
POST · DELETE	/active-rules · /active-rules/{id}	Turn a rule on {"id"} or off.

Labels, blocklist and failed deliveries

Method	Path	Description
GET · POST	/labels	List labels, or create one: {"name", "colour"}.
GET · PATCH · DELETE	/labels/{id}	Get, rename or delete a label.
GET · POST	/blocklist	List blocked senders and domains, or block one: {"value", "type": "email"\|"domain"}.
POST	/blocklist/bulk · /blocklist/delete/bulk	Block {"values": [...]} or unblock {"ids": [...]} several at once.
DELETE	/blocklist/{id}	Unblock.
GET	/failed-deliveries	List failed and quarantined messages. filter[quarantined]=true\|false, filter[email_type].
GET · DELETE	/failed-deliveries/{id}	Get or delete a failed delivery.
GET	/failed-deliveries/{id}/download	Download the stored message as an .eml file.
POST	/failed-deliveries/{id}/resend	Resend a stored message: {"recipient_ids"} (optional).

Example

curl -X POST https://886.bot/api/v1/aliases \
  -H "Authorization: Bearer 886al_…" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"domain":"886.bot","format":"random_words","description":"Newsletter"}'

HTTP/1.1 201 Created
{"data":{"id":12,"email":"brave_otter482@886.bot","active":true,"description":"Newsletter","emails_forwarded":0,…}}

Webhooks

A rule can call your HTTPS endpoint when mail matches. Each request is a JSON POST with an X-Addy-Event header and an X-Addy-Signature header: the hex HMAC-SHA256 of the raw request body, made with your webhook secret (Webmail → Aliases → Settings). Failed requests are retried; after five failures in a row the webhook is paused for one hour and you’re notified by email.

Errors

Status	Meaning
401	The token is missing, invalid, revoked or expired.
403	The account is suspended, or the action isn’t allowed.
404	The item doesn’t exist, or belongs to someone else.
422	The input is invalid. The body is {"message", "errors": {"field": ["…"]}}.
429	Too many requests. Wait a moment, then try again.