WGTemporaryEmail - Temporary Email Service

API Documentation

Complete REST API reference for WGTemporaryEmail. Every read-only endpoint can be tested live with one click.

Base URL:

User API: the access token is returned when creating an address (POST /api/v1/addresses). It is used in the URL path.

Admin API: requires the admin token in the Authorization header: Bearer <admin.token>.

User API (public)

GET/api/v1/domains

List the domains available for creating addresses.

Example (curl)

curl -X GET "/api/v1/domains"

POST/api/v1/addresses

Create a temporary address. Body: username (optional, 3-64 chars), domain (optional, must be configured).

Example (curl)

curl -X POST "/api/v1/addresses" \
  -H "Content-Type: application/json" \
  -d '{"username": "myemail", "domain": "example.com"}'

GET/api/v1/{token}/emails

List emails of an address. Query: page, per_page (max 100), unread_only, search.

Example (curl)

curl "/api/v1/{token}/emails?page=1&per_page=50&search=invoice"

GET/api/v1/{token}/emails/{email_id}

Get full email details. Query: mark_read=false to keep unread.

Example (curl)

curl "/api/v1/{token}/emails/{email_id}"

DELETE/api/v1/{token}/emails/{email_id}

Delete an email of the address.

Example (curl)

curl -X DELETE "/api/v1/{token}/emails/{email_id}"

GET/api/v1/{token}/emails/{email_id}/raw

Download the raw RFC 5322 message (.eml).

Example (curl)

curl "/api/v1/{token}/emails/{email_id}/raw" -o message.eml

GET/api/v1/{token}/emails/{email_id}/attachments/{attachment_id}

Download an attachment of the email.

Example (curl)

curl "/api/v1/{token}/emails/{email_id}/attachments/{attachment_id}" -o file.bin

Admin API (requires token)

GET/api/v1/admin/stats

System-wide statistics for the dashboard.

Example (curl)

curl -H "Authorization: Bearer <admin.token>" "/api/v1/admin/stats"

GET/api/v1/admin/addresses

List all addresses. Query: page, per_page, search.

Example (curl)

curl -H "Authorization: Bearer <admin.token>" "/api/v1/admin/addresses?page=1&per_page=20"

GET/api/v1/admin/addresses/{id}

Get one address with its emails.

Example (curl)

curl -H "Authorization: Bearer <admin.token>" "/api/v1/admin/addresses/{id}"

DELETE/api/v1/admin/addresses/{id}

Delete an address and all its emails. Destructive.

Example (curl)

curl -X DELETE -H "Authorization: Bearer <admin.token>" "/api/v1/admin/addresses/{id}"

GET/api/v1/admin/emails

List all received emails. Query: page, per_page, search.

Example (curl)

curl -H "Authorization: Bearer <admin.token>" "/api/v1/admin/emails?page=1&per_page=20"

GET/api/v1/admin/emails/{id}

Get full details of one email.

Example (curl)

curl -H "Authorization: Bearer <admin.token>" "/api/v1/admin/emails/{id}"

DELETE/api/v1/admin/emails/{id}

Delete an email. Destructive.

Example (curl)

curl -X DELETE -H "Authorization: Bearer <admin.token>" "/api/v1/admin/emails/{id}"

GET/api/v1/admin/domains

List configured domains with usage counts.

Example (curl)

curl -H "Authorization: Bearer <admin.token>" "/api/v1/admin/domains"

POST/api/v1/admin/domains

Add a domain (hot-reloaded; MX picks it up within 15s).

Example (curl)

curl -X POST -H "Authorization: Bearer <admin.token>" \
  -H "Content-Type: application/json" \
  -d '{"domain": "temp.example.com"}' "/api/v1/admin/domains"

DELETE/api/v1/admin/domains/{domain}

Remove a domain. Destructive.

Example (curl)

curl -X DELETE -H "Authorization: Bearer <admin.token>" "/api/v1/admin/domains/{domain}"

GET/api/v1/admin/config

View the current configuration (secrets masked).

Example (curl)

curl -H "Authorization: Bearer <admin.token>" "/api/v1/admin/config"

PUT/api/v1/admin/config

Partially update whitelisted config keys (hot-reloaded).

Example (curl)

curl -X PUT -H "Authorization: Bearer <admin.token>" \
  -H "Content-Type: application/json" \
  -d '{"tempmail": {"address_lifetime_hours": 48}}' "/api/v1/admin/config"

POST/api/v1/admin/cleanup/run

Run expired-address cleanup and storage-cap enforcement now. Destructive.

Example (curl)

curl -X POST -H "Authorization: Bearer <admin.token>" "/api/v1/admin/cleanup/run"

Setup API

GET/api/v1/setup/status

Whether the first-run setup wizard has been completed.

Example (curl)

curl "/api/v1/setup/status"

POST/api/v1/setup/complete

Write the initial configuration. Only works before initialization.

Example (curl)

curl -X POST "/api/v1/setup/complete" \
  -H "Content-Type: application/json" \
  -d '{"domains": ["example.com"], "hostname": "mail.example.com"}'