# User Email Addresses API Reference

Manage email addresses for the authenticated user and (for admins) other users.

---

## User Email Endpoints

### List Emails

```
GET /user/emails
```

Returns all email addresses associated with the authenticated user.

```bash
curl -s "${FORGEJO_URL}/api/v1/user/emails" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Add Emails

```
POST /user/emails
```

**JSON Body:**

| Field  | Type          | Required | Description                    |
|--------|---------------|----------|--------------------------------|
| emails | array[string] | yes      | Email addresses to add         |

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/user/emails" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["newemail@example.com", "work@example.com"]}'
```

### Delete Emails

```
DELETE /user/emails
```

**JSON Body:**

| Field  | Type          | Required | Description                    |
|--------|---------------|----------|--------------------------------|
| emails | array[string] | yes      | Email addresses to remove      |

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/user/emails" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["oldemail@example.com"]}'
```

---

## Email Response Object

Each email in the response array has these fields:

| Field    | Type    | Description                                    |
|----------|---------|------------------------------------------------|
| email    | string  | The email address                              |
| verified | boolean | Whether the email has been verified            |
| primary  | boolean | Whether this is the user's primary email       |

**Example response:**

```json
[
  {
    "email": "{username}@example.com",
    "verified": true,
    "primary": true
  },
  {
    "email": "{email}",
    "verified": true,
    "primary": false
  },
  {
    "email": "new@example.com",
    "verified": false,
    "primary": false
  }
]
```

---

## Email Verification

- **Newly added emails require verification** before they can be used as the primary email address or for commit attribution.
- When an email is added via `POST /user/emails`, Forgejo sends a verification email to that address (if email sending is configured on the instance).
- The `verified` field indicates whether the user has clicked the verification link.
- You cannot set an unverified email as primary through the API.
- If the instance has email verification disabled in its configuration, emails may be automatically marked as verified upon addition.

---

## Admin Email Endpoints

These endpoints require **site admin** privileges.

### List All User Emails

```
GET /admin/emails
```

**Query Parameters:**

| Parameter | Type    | Description              |
|-----------|---------|--------------------------|
| page      | integer | Page number (1-based)    |
| limit     | integer | Page size                |

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/emails?page=1&limit=50" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Search Emails

```
GET /admin/emails/search
```

**Query Parameters:**

| Parameter | Type    | Description                      |
|-----------|---------|----------------------------------|
| q         | string  | Search query (matches email)     |
| page      | integer | Page number (1-based)            |
| limit     | integer | Page size                        |

```bash
# Search for emails matching a domain
curl -s "${FORGEJO_URL}/api/v1/admin/emails/search?q={domain}q=example.com&limit=50limit=50" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Search for a specific email
curl -s "${FORGEJO_URL}/api/v1/admin/emails/search?q={email}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Get a Specific User's Emails (Admin)

```
GET /admin/users/{username}/emails
```

**Path Parameters:**

| Parameter | Type   | Required | Description  |
|-----------|--------|----------|--------------|
| username  | string | yes      | Target user  |

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/users/{username}/emails" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Delete a User's Email (Admin)

```
DELETE /admin/users/{username}/emails
```

**Path Parameters:**

| Parameter | Type   | Required | Description  |
|-----------|--------|----------|--------------|
| username  | string | yes      | Target user  |

**JSON Body:**

| Field  | Type          | Required | Description                    |
|--------|---------------|----------|--------------------------------|
| emails | array[string] | yes      | Email addresses to remove      |

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/admin/users/{username}/emails" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["old@example.com"]}'
```

---

## Common Patterns

### Check Which Email is Primary

```bash
PRIMARY=$(curl -s "${FORGEJO_URL}/api/v1/user/emails" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  | jq -r '.[] | select(.primary == true) | .email')

echo "Primary email: ${PRIMARY}"
```

### Check if All Emails are Verified

```bash
EMAILS=$(curl -s "${FORGEJO_URL}/api/v1/user/emails" \
  -H "Authorization: token ${FORGEJO_PAT}")

UNVERIFIED=$(echo "$EMAILS" | jq '[.[] | select(.verified == false)] | length')

if [ "$UNVERIFIED" -gt 0 ]; then
  echo "You have ${UNVERIFIED} unverified email(s):"
  echo "$EMAILS" | jq -r '.[] | select(.verified == false) | .email'
else
  echo "All emails are verified."
fi
```

### Add Email and Wait for Verification

```bash
# Add a new email
curl -s -X POST "${FORGEJO_URL}/api/v1/user/emails" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["newemail@example.com"]}'

echo "Verification email sent. Check your inbox."

# Poll for verification status
while true; do
  VERIFIED=$(curl -s "${FORGEJO_URL}/api/v1/user/emails" \
    -H "Authorization: token ${FORGEJO_PAT}" \
    | jq -r '.[] | select(.email == "newemail@example.com") | .verified')
  
  if [ "$VERIFIED" = "true" ]; then
    echo "Email verified!"
    break
  fi
  echo "Still unverified. Checking again in 30s..."
  sleep 30
done
```

### Remove All Non-Primary Emails

```bash
NON_PRIMARY=$(curl -s "${FORGEJO_URL}/api/v1/user/emails" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  | jq -r '[.[] | select(.primary == false) | .email]')

if [ "$NON_PRIMARY" != "[]" ]; then
  curl -s -X DELETE "${FORGEJO_URL}/api/v1/user/emails" \
    -H "Authorization: token ${FORGEJO_PAT}" \
    -H "Content-Type: application/json" \
    -d "{\"emails\": ${NON_PRIMARY}}"
  echo "Removed non-primary emails."
fi
```

---

## Notes

- You cannot delete your primary email without first changing the primary to another verified email (done through the Forgejo web UI or user settings API, not through the email endpoints).
- The primary email is used for commit attribution and notifications.
- Admin endpoints return the same Email response object but for all users across the instance.
