Forwarding

Manage automatic email forwarding to your personal addresses

Forwarding allows you to automatically forward emails received on your temporary addresses to a personal email address (Gmail, Outlook, etc.).

Workflow

1. Add a forwarding address -- the destination address (e.g.: john@gmail.com)
2. Verify the address -- a verification email is sent, click the link
3. Configure a rule -- associate the verified address with a temporary address

You can also assign forwarding directly when creating an address via the forwardToId field.

---

Forwarding Addresses

List Addresses

Retrieves the list of your forwarding addresses.

GET /api/v1/forwarding-addresses

Required scope: forwarding:manage

Query Parameters

Parameter	Type	Description
limit	number	Number of results (default: 20, max: 100)
offset	number	Offset for pagination

Example

curl -X GET "https://api.junkmail.dev/api/v1/forwarding-addresses?limit=10" \
  -H "Authorization: Bearer jm_live_xxxx"

Response

{
  "data": {
    "addresses": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "email": "john@gmail.com",
        "isVerified": true,
        "verifiedAt": "2024-01-10T12:00:00Z",
        "createdAt": "2024-01-10T10:00:00Z"
      },
      {
        "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
        "email": "backup@outlook.com",
        "isVerified": false,
        "verifiedAt": null,
        "createdAt": "2024-01-15T14:00:00Z"
      }
    ],
    "total": 2,
    "limit": 10,
    "offset": 0
  }
}

---

Add an Address

Adds a forwarding address and sends a verification email.

POST /api/v1/forwarding-addresses

Required scope: forwarding:manage

Request Body

Field	Type	Required	Description
email	string	Yes	Destination email address

Example

curl -X POST https://api.junkmail.dev/api/v1/forwarding-addresses \
  -H "Authorization: Bearer jm_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@gmail.com"
  }'

Response

{
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "email": "john@gmail.com",
    "isVerified": false,
    "createdAt": "2024-01-15T10:00:00Z"
  },
  "message": "Verification email sent. Please check your inbox."
}

A verification email is sent automatically. The address must be verified before it can be used in a forwarding rule.

---

Address Details

GET /api/v1/forwarding-addresses/:id

Required scope: forwarding:manage

Example

curl -X GET https://api.junkmail.dev/api/v1/forwarding-addresses/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer jm_live_xxxx"

Response

{
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "email": "john@gmail.com",
    "isVerified": true,
    "verifiedAt": "2024-01-10T12:00:00Z",
    "createdAt": "2024-01-10T10:00:00Z"
  }
}

---

Delete an Address

Deletes a forwarding address. Associated rules will also be deleted.

DELETE /api/v1/forwarding-addresses/:id

Required scope: forwarding:manage

Example

curl -X DELETE https://api.junkmail.dev/api/v1/forwarding-addresses/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer jm_live_xxxx"

Response

{
  "message": "Forwarding address deleted successfully"
}

---

Resend Verification Email

Resends the verification email if the address is not yet verified.

POST /api/v1/forwarding-addresses/:id/resend-verification

Required scope: forwarding:manage

Example

curl -X POST https://api.junkmail.dev/api/v1/forwarding-addresses/a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11/resend-verification \
  -H "Authorization: Bearer jm_live_xxxx"

Response

{
  "message": "Verification email resent."
}

If the address is already verified:

{
  "error": "Address is already verified."
}

---

Forwarding Rules

Forwarding rules are linked to a temporary address. Each temporary address can have one forwarding rule.

View the Rule

Retrieves the forwarding rule for a temporary address.

GET /api/v1/addresses/:addressId/forwarding

Required scope: forwarding:manage

Example

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

Response (with active rule)

{
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "forwardToId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "forwardToEmail": "john@gmail.com",
    "filterSender": null,
    "filterSubject": null,
    "isActive": true
  }
}

Response (without rule)

{
  "data": {
    "id": null,
    "forwardToId": null,
    "forwardToEmail": null,
    "filterSender": null,
    "filterSubject": null,
    "isActive": false
  }
}

---

Update the Rule

Creates or updates the forwarding rule for a temporary address.

PATCH /api/v1/addresses/:addressId/forwarding

Required scope: forwarding:manage

Request Body

Field	Type	Required	Description
forwardToId	string | null	No	UUID of the verified forwarding address. null to disable.
filterSender	string	No	Filter by sender (max 255 characters)
filterSubject	string	No	Filter by subject (max 255 characters)
isActive	boolean	No	Enable/disable the rule

Example -- Enable forwarding

curl -X PATCH https://api.junkmail.dev/api/v1/addresses/550e8400-e29b-41d4-a716-446655440000/forwarding \
  -H "Authorization: Bearer jm_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "forwardToId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "isActive": true
  }'

Example -- Disable forwarding

curl -X PATCH https://api.junkmail.dev/api/v1/addresses/550e8400-e29b-41d4-a716-446655440000/forwarding \
  -H "Authorization: Bearer jm_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "forwardToId": null
  }'

Example -- Add a filter

curl -X PATCH https://api.junkmail.dev/api/v1/addresses/550e8400-e29b-41d4-a716-446655440000/forwarding \
  -H "Authorization: Bearer jm_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "filterSender": "@important-service.com",
    "filterSubject": "facture"
  }'

Response

{
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "forwardToId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "forwardToEmail": "john@gmail.com",
    "filterSender": "@important-service.com",
    "filterSubject": "facture",
    "isActive": true
  }
}