REST API guide

Base URL: https://gecici.email/api/v1. Use HTTPS. Creating an inbox returns an address, access token, and expiry. Treat the token as a secret: all inbox reads and changes require Authorization: Bearer <token>.

Create an inbox

POST /inbox/generate
Content-Type: application/json

{}

POST /inbox/custom
Content-Type: application/json

{"prefix":"example-123"}

A custom prefix must be 4–32 ASCII characters, contain a digit and an internal -, _, or ., and not be a reserved role name.

Read an inbox

GET /inbox/{address}
GET /inbox/{address}/messages
GET /inbox/{address}/otp
GET /inbox/{address}/links
Authorization: Bearer <token>

The OTP and link endpoints return extracted values when available; they never visit an external link. An empty result is not proof that a message was delivered. Encode the address as a URL path segment.

Manage an inbox

POST /inbox/{address}/extend
Authorization: Bearer <token>
Content-Type: application/json

{"minutes":30}

DELETE /inbox/{address}
Authorization: Bearer <token>

Deletion removes logical database records; it is not a guarantee of irreversible erasure from disk pages, backups, or infrastructure logs.

More examples

See the public English REST examples and downloadable client. The service is free for users and agents, but delivery time and external acceptance are not guaranteed.