Addresses

Endpoints for managing temporary email addresses

List Addresses

Retrieves the list of your temporary addresses.

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.junkmail.dev/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
  }
}

---

Create an Address

Creates a new temporary email address.

POST /api/v1/addresses

Required scope: emails:write

Request Body

Field	Type	Required	Description
alias	string	No	Custom alias (max 100 characters)
domain	string	No	Custom domain (must be verified)
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.junkmail.dev/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.junkmail.dev/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 Address

Deletes an address and all associated emails.

DELETE /api/v1/addresses/:id

Required scope: emails:write

Example

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

Response

{
  "message": "Address deleted successfully"
}

If the address does not exist:

{
  "error": "Address not found"
}