# create-mailbox

Paid through the standard Exact-EVM rail ($9.99/yr fixed, operator-configurable). Provisions a working IMAP/SMTP mailbox for one year and returns its credentials.

## Input

| Field | Required | Notes |
|---|---|---|
| `address` | yes | Full address. Shared domain (from the provider's list) or your own custom domain. |
| `dnsSetup` | no | `manual` (default) or `automatic`. Automatic is only for payer-owned domains with DNS delegated to the Daski registrar. |
| `contactEmail` | no | Optional email address you monitor. Daski and the provider may email about the order, required actions, support and renewals, including T-30/T-7 expiry reminders. Explain this to the user before submitting their email. |

Purchase is authorized and dispatched by the Daski gateway using the standard payer wallet.

## Flow

1. Run `check-availability` with the intended `payer`. For manual setup, publish all returned mail and ownership records. An external domain requires TXT `_daski-mail.<mail-domain>` with exact value `daski-mail-owner=<lowercase payer address>`. MX and SPF alone do not prove ownership.
2. A Daski-managed domain uses its current owner as proof. If availability advertises `autoConfigurable: true`, optionally pass `dnsSetup: "automatic"` to both availability and this call. The paid request authorizes additive MX/SPF setup and, after the mailbox domain exists, additive DKIM and (when no policy applies) DMARC `p=none` records; conflicting records and externally delegated DNS refuse automatic setup. The order waits for verification before creating the mailbox. Manual mode requires records before payment. On mainnet verification uses public DNS; isolated registrar sandbox domains use their registrar zone. Shared Daski domains need no records and use manual mode.
3. Request `daski_get_payment_challenge` with `payerAddress`; the provider verifies readiness before issuing a payable quote. Use the same payer to purchase through `daski_buy_outcome`.
4. The provider rechecks before provisioning. During automatic DNS propagation, or if DNS regresses after payment, the order stays `working` with `operations.fulfillment.phase: dns_pending` and checks again every five minutes. Inspect `missingRecords` and `nextCheckAt`. Do not pay again. `waiting_capacity` means the order is queued for its next authorized step, either automatic DNS preparation or mailbox provisioning. `operator_attention` names a condition the payer or an operator must clear, such as a creation ban or a lost domain claim; the order is still rechecked and resumes once it clears. An order waiting for DNS can be canceled until mailbox creation starts. Cancellation preserves any DNS records already configured; it does not delete potentially shared mail routing.
5. Credentials become available in the protected `mailbox_created` artifact after fulfillment.
6. Sender authentication follows and never delays the order: the provider prepares a DKIM key for the domain. Daski-managed automatic DNS receives the records directly; otherwise `get-mailbox-authentication` lists them in `authentication.requiredRecords`. Signing starts once the key resolves publicly.

## Result artifact — `mailbox_created`

```jsonc
{
  "address": "scout@agentmail.example",
  "credentials": {
    "username": "scout@agentmail.example",
    "password": "…",                       // SHOWN ONCE — see policy below
    "imap": { "host": "…", "port": 993, "security": "SSL/TLS" },
    "smtp": { "host": "…", "port": 465, "security": "SSL/TLS" },
    "webmail_url": "…"
  },
  "expiresAt": "2027-07-02T…",
  "domainKind": "shared",
  "dnsStatus": "verified",                  // custom domains
  "credentialPolicy": "…"
}
```

## Credential policy

The password is server-generated and retained encrypted for authorized artifact recovery for 7 days, after which it is permanently redacted. Later password recovery uses `change-password` (EIP-712-signed).

## Failure handling

Readiness before payment never reveals whether a wallet is banned. An active sender-reputation creation ban is enforced once the payer is proven by payment: the working order is held for human Review without supplier provisioning, with reason `payer_creation_banned` in its authenticated status. The message remains exactly: `Sender reputation too low for shared email address.` A terminal supplier failure remains recorded on the order and does not automatically reverse payment at launch.

For support, send `daski_contact_order_support` with signed request `{requestId,message}`. Keep a stable request ID for an identical message; a lost response requires a fresh challenge/signature with the same body. The accepted receipt names a human Review, not an email delivery. An operator's reply appears in the order's authenticated status as `operations.support.lastReply`. An operator can assess and approve recovery of eligible failed mailbox creation. Track `operations.recovery` on the original order: successful remediation is **Completed after recovery**. The original failed financial/reputation outcome and payment receipt remain history; recovery never requires a second purchase.