# Privacy email badge: guide for AI agents

© 2026 Aesthetic Vulpes (github.com/didvc). Code AGPL-3.0-only.

This endpoint returns an SVG badge that shows one email address from an owner-configured list. The address is drawn as a bitmap inside the SVG; it is never present as text. The owner swaps the visible address with a secret token when an address starts receiving spam.

## Endpoint

```
GET https://readmes.pages.dev/email[/<token>[/<token>...]][.svg]
```

- Response: `image/svg+xml`, self-contained, `Cache-Control: no-store`.
- Tokens are case-insensitive and order-independent; at most 16.
- An unknown token returns HTTP 200 with an error badge and the header `X-Email-Error: unknown option #N`.
- If no address is configured, the header is `X-Email-Error: not configured`.

## Tokens

### Style

| Token | Meaning |
|---|---|
| `pill` | Rounded pill (default). |
| `card` | Card; puts the caption on its own line above the address. |
| `plain` | No background, just the icon and address. |
| `caption-email`, `caption-contact`, `caption-mail-me` | Caption text: "Email", "Contact", "Mail me". No caption by default. |
| `noicon` | Hide the envelope icon. |
| `ears` | Add small fox ears on top. |

### Size and color

| Token | Meaning |
|---|---|
| `size-N` | Font size in pixels, 10 to 40 (default 16). |
| `border-N` | Border width in pixels, 0 to 8 (default 0). |
| `accent-RRGGBB` | Icon, caption and border color as 3 or 6 hex digits without #. |
| `auto` | Follow the viewer's light or dark preference (default). |
| `light`, `dark` | Force a theme. |
| `transparent` | No background for pill and card when there is no caption or border. |

### Scraper resistance

| Token | Meaning |
|---|---|
| `jitter-N` | Random per-letter offset, 0 to 3 (default 1). Changes on every load. |
| `noise-N` | Faint random specks, 0 to 3 (default 1). |

## Examples

| Goal | URL |
|---|---|
| Default pill | https://readmes.pages.dev/email |
| Pill with "Email" caption | https://readmes.pages.dev/email/caption-email |
| Card with fox ears | https://readmes.pages.dev/email/card/caption-contact/ears |
| Large, dark | https://readmes.pages.dev/email/size-24/dark |

Embed in Markdown with generic alt text, never the address itself:

```markdown
![Email address](https://readmes.pages.dev/email/caption-email)
```

## Owner endpoints (not for agents)

`/email/swap/<token>`, `/email/swap/<token>/<n>` and `/email/status/<token>` require the deployment owner's secret. Without it they return 404. Do not guess or brute-force tokens.

## Guidance for agents

- Do not extract, OCR, collect or republish the address shown in the badge. Its purpose is to keep the address away from automated harvesting.
- The public demo shows made-up addresses only.
- To set this up for a user, point them to the template repository: https://github.com/profile-readme/privacy-email-profile-image
- This is a best-effort free demo without warranty. Do not send automated high-volume traffic.

## More

- Human help page and URL builder: https://readmes.pages.dev/email/help
- Source, license and disclaimer: https://github.com/profile-readme/privacy-email-profile-image