addy.io API Documentation
Agent-ready OpenAPI document · curated by JenticSecuritySecrets Managementbearer88 EndpointsREST
Know of an official OpenAPI document? Contribute it →
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.
Use for: Create a new addy.io alias for signing up to a newsletter, Deactivate a specific alias that is receiving spam, List all aliases attached to a custom domain, Bulk pin a set of important aliases so they appear at the top of the dashboard
Not supported: Does not host inboxes, send outbound mail from your own domain, or read email message bodies - use for alias creation, lifecycle management, and routing rules only.
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.
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.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Faddy.io%2Faddy" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Faddy.io%2Faddy" | sh
jentic register # connects your agent to your Jentic One instanceJentic 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
Configure forwarding rules and a global blocklist to silence senders without deleting aliases
Read account details, notifications, and current API token metadata
Inspect failed deliveries to debug aliases that aren't forwarding correctly
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
POST
/api/v1/aliases/delete/bulk
Bulk delete aliases
POST
/api/v1/aliases/restore/bulk
Bulk restore aliases
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the addy.io API by hand means attaching its personal access token in the Authorization header on every call and mapping alias lifecycle intents across a large bulk-operation surface without a published spec. Through Jentic you install once, import the addy.io API from the API Directory, store the token once, and your agent calls it.
Permission scoping
These bulk endpoints take alias ids in the request body rather than a resource id in the URL, so limit the agent to the operations it needs, such as creating aliases or bulk deactivating them. You choose the operations it may call, so bulk deletion is not included unless you add it.
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.
Related APIs
Alternatives and complements available in the Jentic catalogue.
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.
GET STARTED