Recipient API - Anon.li Docs | anon.li

Recipient API

Manage forwarding recipients, set defaults, and configure PGP encryption via the Recipient API.

The Recipient API lets you manage the email addresses that your aliases forward to. Recipients must be verified before they can receive forwarded emails. You can also configure PGP public keys for end-to-end encrypted forwarding.

Authentication

All API requests must be authenticated using an API Key. Generate keys in your Dashboard.

Code

Authorization: Bearer ak_your_api_key_here

Base URL

Code

https://anon.li/api/v1

Endpoints

List Recipients

Retrieve all your recipients.

GEThttps://anon.li/api/v1/recipient

{
  "data": [
    {
      "id": "rec_abc123",
      "email": "personal@example.com",
      "verified": true,
      "is_default": true,
      "pgp_fingerprint": "A1B2C3D4E5F6...",
      "pgp_key_name": "Main key",
      "alias_count": 12,
      "created_at": "2026-01-10T08:00:00.000Z"
    },
    {
      "id": "rec_def456",
      "email": "work@company.com",
      "verified": true,
      "is_default": false,
      "pgp_fingerprint": null,
      "pgp_key_name": null,
      "alias_count": 5,
      "created_at": "2026-02-15T10:00:00.000Z"
    }
  ],
  "total": 2,
  "limit": 2,
  "offset": 0
}

Field	Type	Required	Description
`email`	string	Yes	The email address to add as a recipient.

Code

{
  "data": {
    "id": "rec_abc123",
    "email": "personal@example.com",
    "verified": true,
    "is_default": true,
    "pgp_fingerprint": "A1B2C3D4E5F6...",
    "pgp_key_name": "Main key",
    "alias_count": 12,
    "created_at": "2026-01-10T08:00:00.000Z"
  }
}

Field	Type	Required	Description
`is_default`	boolean	No	Set to `true` to make this the default recipient.

Code

{
  "data": {
    "id": "rec_def456",
    "email": "work@company.com",
    "verified": true,
    "is_default": true,
    "pgp_fingerprint": null,
    "pgp_key_name": null,
    "alias_count": 5,
    "created_at": "2026-02-15T10:00:00.000Z"
  }
}

Field	Type	Required	Description
`public_key`	string	Yes	The ASCII-armored PGP public key.
`name`	string	No	A label for the key (max 100 characters).

Code

curl -X PUT https://anon.li/api/v1/recipient/rec_abc123/pgp \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...\n-----END PGP PUBLIC KEY BLOCK-----",
    "name": "Main key"
  }'

Code

# 1. Add a new recipient (if not already added)
curl -X POST https://anon.li/api/v1/recipient \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "newinbox@example.com" }'
# Returns: { "data": { "id": "rec_new123", ... } }

# 2. Wait for the recipient to click the verification link in their email

# 3. Update the alias to forward to the new recipient
curl -X PATCH https://anon.li/api/v1/alias/ALIAS_ID \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{ "recipient_id": "rec_new123" }'

Status	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Plan limit reached
`404`	Not Found - Recipient doesn't exist
`409`	Conflict - Recipient email already exists
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Recipient API

Authentication

Base URL

Endpoints

List Recipients

On this page

Add Recipient

Get Recipient

Update Recipient

Delete Recipient

Resend Verification

Set PGP Key

Remove PGP Key

Common Workflow: Change Where an Alias Forwards

Error Responses