addy.io API Documentation

Name: addy.io API Documentation API
Brand: addy.io API
Availability: InStock

★ Only Publicly Available OpenAPI DocumentSecuritySecrets Managementbearer88 EndpointsREST

For Agents

Create, activate, deactivate, pin, and delete addy.io email aliases; manage recipients, custom domains, blocklists, and forwarding rules. Used by privacy-focused agents to automate alias hygiene and recipient routing.

Install Jentic One Beta

Connect the addy.io API Documentation to your agent

Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the addy.io API Documentation, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.

Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.

Step 1: Jentic One Host machine

# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh

Step 2: Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register       # connects your agent to your Jentic One instance

Jentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.

Capabilities

What an agent can do with addy.io API Documentation API.

Create and manage anonymous email aliases that forward to real recipient addresses

Bulk activate, deactivate, pin, unpin, delete, restore, or forget aliases via dedicated bulk endpoints

Manage recipients (the underlying inboxes) and custom domains used to issue aliases

GET STARTED

Start building with addy.io API Documentation API

Explore with Jentic

View OpenAPI Document

Jentic publishes the only available OpenAPI specification for addy.io API Documentation, keeping it validated and agent-ready. addy.io is an anonymous email forwarding service that lets users create unlimited aliases backed by their real inbox, then activate, deactivate, pin, or delete those aliases as relationships with senders change. The API exposes account details, alias bulk actions, individual aliases, blocklists, recipients, custom domains, usernames, rules, failed deliveries, and more - covering every concept in the addy.io UI. Authentication is a personal access token passed as a bearer token in the Authorization header.

Use Cases

Patterns agents use addy.io API Documentation API for, with concrete tasks.

★ Per-signup alias generation

Privacy-conscious users create a unique alias every time they sign up to a service so they can later disable any one address that starts attracting spam. The aliases endpoints support creating, deactivating, and deleting addresses individually, and a bulk endpoint supports operating on many aliases at once. An automation can mint an alias on demand and pass it to a password manager or signup form.

Call the create-alias operation with description 'Newsletter X' and a target recipient, then return the generated alias address so it can be pasted into the signup form.

Alias hygiene and bulk cleanup

Power users accumulate hundreds of aliases over time and need to disable swathes of them at once - for example, every alias tied to a vendor whose data leaked. The bulk endpoints (POST /api/v1/aliases/deactivate/bulk, /delete/bulk, /pin/bulk) accept lists of alias IDs and apply the same action to all of them in one call. This avoids chaining dozens of single-resource updates.

POST /api/v1/aliases/deactivate/bulk with the list of alias IDs known to be tied to a leaked vendor, then POST /api/v1/aliases/restore/bulk if the cleanup proves too aggressive.

Custom domain alias management for teams

Small teams using a custom domain on addy.io want to issue aliases per project (project-x@team.example) and then delete them when the project ends. The custom-domain and aliases endpoints together let an automation provision aliases on the team domain, attach them to a shared recipient inbox, and tear them down on schedule.

Look up the team custom domain, create a new alias on it for the project, and route forwarding to the shared recipient inbox.

AI agent alias operations via Jentic

An AI privacy assistant inside a password manager uses Jentic to call addy.io whenever the user asks for a new alias for a service. The agent searches 'create addy.io alias', loads the schema, and executes - Jentic injects the bearer token from your Jentic One instance and returns the alias to the user. The same flow handles deactivation when the user reports spam from a specific sender.

Use Jentic to search 'create addy.io alias', load the create-alias schema, execute with description 'GitHub' and the user's default recipient, and return the alias to the user.

Key Endpoints

88 endpoints — jentic publishes the only available openapi specification for addy.

METHOD

PATH

DESCRIPTION

GET

/api/v1/api-token-details

Get details about the current API token

GET

/api/v1/account-details

Get all account details

POST

/api/v1/aliases/get/bulk

Bulk fetch specific aliases

POST

/api/v1/aliases/activate/bulk

Bulk activate aliases

POST

/api/v1/aliases/deactivate/bulk

Bulk deactivate aliases

POST

/api/v1/aliases/delete/bulk

Bulk delete aliases

POST

/api/v1/aliases/restore/bulk

Bulk restore aliases

GET

/api/v1/api-token-details

Get details about the current API token

GET

/api/v1/account-details

Get all account details

POST

/api/v1/aliases/get/bulk

Bulk fetch specific aliases

POST

/api/v1/aliases/activate/bulk

Bulk activate aliases

POST

/api/v1/aliases/deactivate/bulk

Bulk deactivate aliases

Why Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

Your addy.io personal access token is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context.

Intent-based discovery

Agents search Jentic by intent such as 'create an addy.io alias' or 'bulk deactivate aliases', and Jentic returns the matching addy.io operation with its input schema so the agent calls the right endpoint without browsing the reference docs, which matters because addy.io does not publish a public OpenAPI spec.

Time to first call

FAQs

Specific to using addy.io API Documentation API through Jentic.

Why is there no official OpenAPI spec for addy.io API Documentation?

addy.io does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call addy.io API Documentation via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

What authentication does the addy.io API use?

The API uses HTTP bearer tokens - a personal access token created in the addy.io settings is sent in the Authorization header as Bearer <token>. Jentic stores the token in your Jentic One instance and injects it at execute time, so the raw token never reaches agent context.

Can I bulk-deactivate aliases through the addy.io API?

Yes. POST /api/v1/aliases/deactivate/bulk accepts a list of alias IDs and deactivates all of them in one call. The matching /activate/bulk, /delete/bulk, /restore/bulk, /pin/bulk, and /unpin/bulk endpoints exist for the inverse operations.

How do I create a new alias through Jentic?

Search Jentic for 'create addy.io alias', load the create-alias schema, and execute with the description (what the alias is for) and the recipient that should receive forwarded mail. Jentic returns the new alias address from the addy.io response.

Are there rate limits on the addy.io API?

addy.io applies per-account rate limits scaled to plan tier; the spec does not declare a fixed value. If a 429 is returned through Jentic, back off and retry - bulk endpoints are the right way to avoid hitting limits when operating on many aliases.

Does this API let me read the contents of forwarded email?

No. addy.io is a forwarder, not a mailbox host - the API exposes alias and routing metadata but not message bodies. The actual email content lives in the recipient's underlying inbox, which you would access via a separate IMAP or Gmail/Outlook API.

Can I limit what my agent is allowed to do with the addy.io API?

Yes. Because you self-host Jentic One, your own rules decide which addy.io operations and credentials the agent can use, so you can allow only what it needs, such as creating aliases or bulk deactivating them. The bulk endpoints take alias IDs in the request body rather than a resource ID in the URL, so you scope the agent at the operation level: bulk deletion is not available to it unless you explicitly add that operation. Read-only operations like retrieving account details or failed deliveries can be granted without exposing any destructive alias actions.

addy.io API Documentation

Connect the addy.io API Documentation to your agent

Capabilities

Start building with addy.io API Documentation API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs