Aliases

Endpoints for managing email aliases

Note: the underlying REST endpoints are still mounted at /api/v1/addresses for backward compatibility with installed clients. The product concept they manage is what we now call an alias in the dashboard. The JSON address field contains the email string itself (e.g. xxx@junkmail.site); the JSON alias field is the optional friendly label you can attach.

List Aliases

Retrieves the list of your aliases.

GET /api/v1/addresses

Required scope: emails:read

Query Parameters

Parameter	Type	Description
limit	number	Number of results (default: 20, max: 100)
offset	number	Offset for pagination
status	string	Filter by status: active, expired

Example

curl -X GET "https://api.aliasify.app/api/v1/addresses?limit=10&status=active" \
  -H "Authorization: Bearer jm_live_xxxx"

Response

{
  "data": {
    "addresses": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "address": "test@junkmail.site",
        "alias": "test",
        "isActive": true,
        "createdAt": "2024-01-15T10:00:00Z",
        "expiresAt": "2024-01-22T10:00:00Z"
      }
    ],
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}

In this payload:

• address is the alias's email string (what senders write to).
• alias is the optional label you set to recognise it.

---

Create an Alias

Creates a new email alias.

POST /api/v1/addresses

Required scope: emails:write

Request Body

Field	Type	Required	Description
alias	string	No	Optional label for the alias (max 100 characters). Visible only to you.
domain	string	No	Custom domain (must be verified, Business plan)
platformDomainId	string	No	UUID of an Aliasify platform domain (Pro/Business pool)
expiresIn	number	No	Time to live in seconds (min: 60, max: depends on plan)
forwardToId	string	No	UUID of a verified forwarding address to enable automatic forwarding

Time to Live by Plan

Plan	Default TTL	Maximum TTL
Free	24 hours	24 hours
Pro	7 days	7 days
Business	30 days	30 days

Example

curl -X POST https://api.aliasify.app/api/v1/addresses \
  -H "Authorization: Bearer jm_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "support",
    "domain": "my-startup.com",
    "expiresIn": 3600
  }'

Example with Forwarding

curl -X POST https://api.aliasify.app/api/v1/addresses \
  -H "Authorization: Bearer jm_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "newsletter",
    "forwardToId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }'

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "address": "support@my-startup.com",
    "alias": "support",
    "isActive": true,
    "createdAt": "2024-01-15T10:00:00Z",
    "expiresAt": "2024-01-15T11:00:00Z",
    "forwarding": null
  }
}

With forwardToId:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "address": "newsletter@junkmail.site",
    "alias": "newsletter",
    "isActive": true,
    "createdAt": "2024-01-15T10:00:00Z",
    "expiresAt": "2024-01-22T10:00:00Z",
    "forwarding": {
      "forwardToId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "forwardToEmail": "john@gmail.com",
      "isActive": true
    }
  }
}

---

Delete an Alias

Deletes an alias and all associated emails.

DELETE /api/v1/addresses/:id

Required scope: emails:write

Example

curl -X DELETE https://api.aliasify.app/api/v1/addresses/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer jm_live_xxxx"

Response

{
  "message": "Alias deleted successfully"
}

If the alias does not exist:

{
  "error": "Alias not found"
}