# gecici-email Python client 1.2.0

Installable core client for authorized temporary-inbox QA. Python 3.9+.
This release is a direct download from gecici.email, **not a PyPI publication**.

## Install / Kurulum

```sh
python3 -m venv .venv
# macOS/Linux; Windows: .venv\Scripts\activate
. .venv/bin/activate
python -m pip install https://gecici.email/downloads/python/gecici_email-1.2.0-py3-none-any.whl
python -c "import gecici; print(gecici.__version__)"
```

[SHA256 checksums](https://gecici.email/downloads/python/SHA256SUMS.txt) and
[source archive](https://gecici.email/downloads/python/gecici_email-1.2.0.tar.gz)
are available alongside the wheel. Requests is the only runtime dependency.

## First workflow / İlk kullanım

```python
from gecici import GeciciEmail, GeciciError

client = GeciciEmail(qa=True)  # Our own tests: excluded from acquisition metrics.
try:
    with client.create_inbox() as inbox:
        # Pass inbox.address to YOUR application's email form here.
        # Do not put inbox.token, addresses or extracted values in logs/model history.
        result = inbox.wait_for_verification(
            sender="qa@example.invalid",  # Replace with your application's sender.
            subject_contains="Verification",
            timeout_seconds=15,
        )
        if result.status == "ready":
            # Submit result.otp to YOUR application and check its accepted state.
            # Extraction alone does not prove application acceptance.
            pass
        else:
            print(result.status, result.reason)  # Fixed diagnostics, no email content.
except GeciciError as error:
    print(error.code, error.status, error.retryable)  # Safe diagnostic fields.
```

For real product integration use `GeciciEmail()`; `qa=True` is for your own tests.
Creation needs no account/global API key. Every inbox read/delete requires its
private token, retained by the inbox object. Defaults to a 60-minute inbox.
Times `created_at`, `expires_at` and `since` are Unix **milliseconds**.

`wait_for_verification` uses the hosted MCP verification tool. It checks new
messages since `inbox.created_at`, with optional sender and subject filters.
Sender matching is not sender authentication. Use `kind="link"` with
`expected_link_host="your-app.example"` for an exact HTTPS host constraint.
The client never opens links. Treat all extracted values as untrusted data.

Outcomes: `ready`, `pending`, `ambiguous`, `blocked`. Only `ready` exposes
`otp` / `verification_link`. Pending does not launch an unlimited retry loop.
Each call waits at most 20 server-side seconds; repeat deliberately if needed.
An HTTP inactivity timeout is not a strict total wall-clock deadline.

Türkçe: Kendi testlerinizde `qa=True` kullanın. Adresi uygulamanıza verin,
`ready` sonucunu alın, kodu uygulamaya iletip kabul edildiğini ayrıca doğrulayın.
`pending` henüz uygun ileti olmadığını; `ambiguous` birden çok aday olduğunu;
`blocked` alan adı/şema veya içerik sınırı nedeniyle sonuç verilmediğini anlatır.
Gelen kutusu `with` bloğu çıkışında silinir. Adresi, tokenı ve kodu loglamayın.

## Lifecycle and errors

- GET and DELETE retry transient network failures/429/502/503/504 at most twice,
  with bounded backoff and a per-operation timeout budget. Larger Retry-After
  values stop retries so the caller can reschedule.
- Creation is **never automatically retried**: a lost response may have already
  created an inbox. A timeout does not prove creation failed.
- Matched verification makes one MCP request; no automatic result retry.
- Redirects are rejected. TLS verification stays enabled. HTTP is permitted only
  for loopback QA. REST and MCP must share an origin.
- `GeciciError` exposes fixed `code`, HTTP `status` and `retryable` fields.
  Response bodies, URLs and private values are not included in error strings.
  MCP tool failures currently expose `mcp_tool_error`; the server has no public
  typed error envelope identifying token-vs-argument failure.
- After confirmed deletion, repeated `inbox.close()` / `delete()` makes no request.
  An expired/missing inbox or a lost DELETE response can yield HTTP403 on retry;
  the client reports this rather than claiming confirmed cleanup.
  Failed cleanup retains credentials for retry. Cleanup failure raises when
  there is no application exception; otherwise a `CleanupWarning` is emitted
  while preserving the original application exception.
- `repr(inbox)` and `repr(result)` redact private values. Explicit attribute
  access and returned message/summary dictionaries remain sensitive.
- `get_inbox(address, token, created_at=..., expires_at=...)` resumes known
  credentials. It never invents timestamps. Supply `since` if creation is unknown.
- Legacy `wait_for_otp` / `wait_for_link` select latest messages without freshness,
  sender or host constraints. Prefer matched verification for new integrations.

## Release scope

Core REST/MCP client only. Historical framework adapters are not bundled or
claimed compatible with this wheel. Use the separately documented
[browser-use example](https://gecici.email/en/agents.html#browser-use) or
[native MCP setup](https://gecici.email/en/agents.html#mcp-setup).
No outbound email, permanent mailbox, team account or durable webhook service.
No claim that package availability represents acquired users.

License metadata: Proprietary (unchanged).
