Skip to content

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

Example Request

Code
curl https://anon.li/api/v1/recipient \
  -H "Authorization: Bearer ak_..."

Response

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"
    },
    {
      "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
}

Add Recipient

Add a new forwarding email address. A verification email is sent automatically.

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

Body Parameters

FieldTypeRequiredDescription
emailstringYesThe email address to add as a recipient.

Example Request

Code
curl -X POST https://anon.li/api/v1/recipient \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "newinbox@example.com" }'

Response (201 Created)

Code
{
  "data": {
    "id": "rec_ghi789",
    "email": "newinbox@example.com",
    "verified": false,
    "is_default": false,
    "created_at": "2026-03-20T14:00:00.000Z"
  }
}

Verification required: New recipients must click the verification link sent to their email before they can receive forwarded messages. Use the Resend Verification endpoint if the email didn't arrive.

Get Recipient

Retrieve a single recipient by ID.

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

Example Request

Code
curl https://anon.li/api/v1/recipient/rec_abc123 \
  -H "Authorization: Bearer ak_..."

Response

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"
  }
}

Update Recipient

Set a recipient as the default forwarding address. New aliases will forward to the default recipient unless a specific recipient is specified.

PATCHhttps://anon.li/api/v1/recipient/:id

Body Parameters

FieldTypeRequiredDescription
is_defaultbooleanNoSet to true to make this the default recipient.

Example Request

Code
curl -X PATCH https://anon.li/api/v1/recipient/rec_def456 \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{ "is_default": true }'

Response

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"
  }
}

Delete Recipient

Remove a recipient. Aliases currently forwarding to this recipient will fall back to the default recipient.

DELETEhttps://anon.li/api/v1/recipient/:id

Example Request

Code
curl -X DELETE https://anon.li/api/v1/recipient/rec_ghi789 \
  -H "Authorization: Bearer ak_..."

Response (200 OK)

Code
{
  "data": {
    "deleted": true
  }
}

Resend Verification

Resend the verification email for a pending recipient.

POSThttps://anon.li/api/v1/recipient/:id/verify

Example Request

Code
curl -X POST https://anon.li/api/v1/recipient/rec_ghi789/verify \
  -H "Authorization: Bearer ak_..."

Response

Code
{
  "data": {
    "sent": true
  }
}

Set PGP Key

Upload a PGP public key for a recipient. When set, all emails forwarded to this recipient are encrypted with the key before delivery.

PUThttps://anon.li/api/v1/recipient/:id/pgp

Body Parameters

FieldTypeRequiredDescription
public_keystringYesThe ASCII-armored PGP public key.
namestringNoA label for the key (max 100 characters).

Example Request

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"
  }'

Response

Code
{
  "data": {
    "id": "rec_abc123",
    "pgp_fingerprint": "A1B2C3D4E5F6...",
    "pgp_key_name": "Main key"
  }
}

Remove PGP Key

Remove the PGP key from a recipient. Emails will be forwarded unencrypted.

DELETEhttps://anon.li/api/v1/recipient/:id/pgp

Example Request

Code
curl -X DELETE https://anon.li/api/v1/recipient/rec_abc123/pgp \
  -H "Authorization: Bearer ak_..."

Response

Code
{
  "data": {
    "removed": true
  }
}

Common Workflow: Change Where an Alias Forwards

To update the inbox an alias forwards to:

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" }'

See the Alias API for the full alias update endpoint documentation.

Error Responses

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