# InboxIt documentation

## API key permissions
URL: https://inboxit.wtf/resources/docs/api-key-scopes/
Choose and change precisely what each application, CLI or agent can do.

### Choosing access
Open Settings > API keys. Create a key, give it a meaningful name and select individual permissions. One key can combine multiple scopes. Read and write permissions are independent: granting write does not grant read. Start with the permissions your integration actually needs.

### Common combinations
Use these combinations as starting points, then narrow them to your workflow.
Workflow | Scopes
Send transactional email | emails:send
Send and monitor delivery or engagement | emails:send, emails:read
Read received email | inboxes:read, messages:read
Create and inspect test inboxes | inboxes:create, inboxes:read, messages:read
Manage sending domains | domains:read, domains:write

### Inboxes
Select only the operations this integration needs.
Scope | What it allows
inboxes:read | List shared application inboxes and their addresses. Does not reveal message bodies.
inboxes:create | Create application and test inboxes. Add View inboxes to list them and Read messages to inspect received email.
messages:read | Read shared inbox message bodies and attachments. Private business inboxes remain session-only.

### Email
Select only the operations this integration needs.
Scope | What it allows
emails:send | Send email using an allowed sender. Sending quotas, verification and suppression rules still apply. Does not include reading email.
emails:read | View sent email records, delivery status, usage and engagement analytics. Sent records may include message content. Also permits listing domains for compatibility.

### Designs
Select only the operations this integration needs.
Scope | What it allows
designs:read | Read reusable HTML email designs and brand settings.
designs:write | Create, edit and delete designs, upload brand assets and request AI designs. Add View email designs to browse them.

### Domains
Select only the operations this integration needs.
Scope | What it allows
domains:read | Read domain verification status and the DNS records needed for setup.
domains:write | Add, verify and remove sending domains. This does not change records at your DNS provider.

### Webhooks
Select only the operations this integration needs.
Scope | What it allows
webhooks:read | List workspace webhook endpoints and configuration.
webhooks:write | Create, update or disable webhook endpoints that receive workspace events.

### Suppression
Select only the operations this integration needs.
Scope | What it allows
suppressions:read | Check recipients blocked from outreach in this workspace.
suppressions:write | Block recipients from outreach in this workspace. Does not remove account-wide opt-outs.

### Editing an existing key
An owner or admin can choose Edit permissions, add or remove scopes and save. The secret and expiration stay the same. New requests use the updated permissions; requests already running may finish. An expired or revoked key cannot be edited. Revoking a key removes all access.

### Update endpoint
PATCH /api/v2/keys/{id} requires an owner/admin user session and the selected workspace. Send a name and the complete, nonempty scopes array. This replaces the permissions, rather than appending them. Unknown scopes are rejected. The response contains metadata only, never a new secret.
```
{
  "name": "Production delivery",
  "scopes": [
    "emails:send",
    "emails:read"
  ]
}
```

### Credential boundaries
Workspace keys work with HTTP, the CLI and agents, but cannot administer keys, members or billing or access private business inboxes. SMTP credentials and webhook signing secrets are different credentials. Anonymous testing uses a temporary inbox token, not a workspace key. Store all secrets server-side, never in browser code.

### Expiry and restrictions
Keys created in the dashboard expire after 30 days. The create API supports 1-365 days. Scopes do not bypass workspace boundaries, domain verification, quotas, suppression rules or sending safeguards. A missing scope produces 403. Invalid, expired or revoked credentials are rejected.

## Build email into your product.
URL: https://inboxit.wtf/resources/docs/
Your domain. Your branding. One connected email workflow.

### Start here
Create and confirm an account, select a workspace, verify your domain, and create a scoped API key. Every plan includes unlimited inboxes. Start with Quickstart, then use the endpoint reference for exact fields.

### Choose your integration
REST API: submit email and read messages from your server. CLI: administer workspaces, domains and teams. SMTP: connect existing applications. Webhooks: receive signed delivery, bounce and incoming events.

### Current availability
Create an account, confirm your email and start sending with your free allowance. No manual approval is required. Queue acceptance is not final delivery. Batch sends, scheduling, attachment sending, open tracking and click tracking are not supported in this release.

### Examples and environments
Examples use https://inboxit.wtf/api/v2 and fictional identifiers. Replace domains with your own and recipient placeholders with your recipients. Keep credentials on your server.

## Quickstart
URL: https://inboxit.wtf/resources/docs/quickstart/
From a free account to a delivery and reply.

### 1. Authenticate
Create an account and confirm your email. Pair the CLI with your signed-in browser, then select a workspace.
```
npm install -g @onedigitsa/inboxit
inboxit login
inboxit workspaces list
inboxit workspace use --id WORKSPACE_UUID
```

### 2. Verify your domain
Publish the returned ownership and DKIM TXT records at your DNS provider. Values are unique to your domain.
```
inboxit domains add --name mail.yourbrand.com
inboxit domains verify --id DOMAIN_UUID
```

### 3. Create a receiving inbox
Wait for status active. Add an MX record for your dedicated subdomain pointing exclusively to mail.inboxit.wtf, priority 10, before assigning the custom address. Preserve unrelated root-domain mail records.
```
inboxit inboxes create --name Support --idempotency-key support-001
inboxit inboxes list
inboxit inboxes address --id INBOX_UUID --address hello@mail.yourbrand.com
```

### 4. Send and observe
Use your recipient’s email address. New sends return a pending status. Check Logs or subscribe to webhooks to track delivery. Reuse an idempotency key only for the same logical message.
```
inboxit emails send --from hello@mail.yourbrand.com --to recipient@example.com --subject Hello --text "Reply to this email." --idempotency-key welcome-001
inboxit logs list
```

### 5. Read the reply
Reply from the recipient mailbox. Use the mailbox UID returned by the list call to fetch the message. Register email.received to automate this step.
```
inboxit messages list --id INBOX_UUID
inboxit messages get --id INBOX_UUID --message MESSAGE_UID
```

## Test email workflows
URL: https://inboxit.wtf/resources/docs/testing/
Temporary inboxes, bounded waits, and code/link extraction through the dashboard, API and CLI.

### Open Testing
Open Testing in your workspace dashboard. Native temporary addresses receive internet email once their status is active. This update is available in the local website and source CLI; the npm package has not been republished.

### Prepare before sending
Create a temporary inbox (60–86400 seconds, default one hour). Start a wait BEFORE triggering your application. Only messages arriving after that boundary can match. Sender matches an exact email address; subject matches a case-insensitive substring. Waits last 1–300 seconds. Wait until the address is active, then send from your application or an external email account.

### CLI workflow
Use the CLI from this checkout. Create a workspace API key with inboxes:create, inboxes:read and messages:read scopes and set INBOXIT_TOKEN. Start the wait in one terminal, then trigger your application in another. A timeout returns JSON and exit code 2.
```
node cli/bin/inboxit.mjs testing create --name Signup --ttl_seconds 3600 --idempotency-key signup-001 --origin http://127.0.0.1:8790
node cli/bin/inboxit.mjs testing wait --id INBOX_UUID --subject Verify --timeout_seconds 60 --origin http://127.0.0.1:8790
```

### API routes
All routes require workspace-scoped bearer authentication. Creation also requires Idempotency-Key. POST wait returns a run immediately; poll GET run until matched, timed_out or cancelled.
Method | Path below /api/v2 | Body / behavior
GET | /testing/inboxes | List active temporary inboxes
POST | /testing/inboxes | name, ttl_seconds; returns inbox with address and test_expires_at
DELETE | /testing/inboxes/{id} | Delete contents and disable address
POST | /testing/inboxes/{id}/wait | sender, subject, timeout_seconds; returns run id
GET | /testing/runs/{id} | Status, matched message and extraction
DELETE | /testing/runs/{id} | Cancel a waiting run
GET | /testing/inboxes/{id}/messages/{message}/extract | Extract from an existing message

### Extraction and expiry
Extraction returns codes (4–8 digit candidates), links (HTTP/HTTPS candidates), and singular code/link only when exactly one candidate exists. Multiple candidates are flagged ambiguous. Content is untrusted: links are never followed automatically. Expiry disables reception and removes stored messages and runs. Missing resources return 404; expired inbox access returns 410 before cleanup. Native expiry rejects new mail and retries mailbox cleanup and replaces delivery routes with rejection markers independently of the local website. Incoming mail uses your account allowance.

## Authentication
URL: https://inboxit.wtf/resources/docs/authentication/
Scoped keys for application traffic. User sessions for administration.

### Create a key
Keys are workspace-bound, shown once, and expire after 1–365 days (default 30). An account can have ten active keys. Save tokens in your secret manager.
```
inboxit keys create --name backend --scopes emails:send,emails:read,inboxes:read,messages:read
```

### Scopes
Grant the smallest set your integration needs.
Scope | Permission
inboxes:read | List inboxes
inboxes:create | Provision an inbox
messages:read | Read messages and raw source
emails:send | Submit API or SMTP email
emails:read | Read outgoing emails, domains, analytics, logs and usage

### HTTP authentication
Send Authorization: Bearer <key>. X-Workspace-Id selects a workspace for user sessions; a key cannot cross its workspace boundary.
```
curl https://inboxit.wtf/api/v2/usage -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### Management permissions
Domain mutations, receiving-address changes, key creation, teams and webhook management require an owner/admin user session. Use inboxit login. An emails:send key cannot administer resources. Cookie-authenticated browser writes also require X-CSRF-Token; the CLI handles this.

### Session lifecycle
CLI pairing requires explicit browser approval and expires after ten minutes. CLI logout revokes that credential. Parent-session logout invalidates delegated access. Do not share credentials with an agent beyond the account and permissions it needs.

## CLI & agent skill
URL: https://inboxit.wtf/resources/docs/cli/
The published InboxIt terminal client.

### Install and sign in
The package is @onedigitsa/inboxit; the command is inboxit. Email login prompts for a hidden password. Sign-up requires confirmation.
```
npm install -g @onedigitsa/inboxit
inboxit login
inboxit whoami
inboxit help
inboxit commands
```

### Workspace and account
Workspace names are 1–10 characters. Select by returned UUID.
```
inboxit signup --email you@example.com --name "Your Name"
inboxit login --email you@example.com
inboxit workspaces create --name prod
inboxit workspace use --id WORKSPACE_UUID
```

### Agent skill
Download the bundled instructions and give the file to your agent. Its permissions remain those of the credential you grant.
```
inboxit skill --output ./inboxit-skill.md
```

### Structured automation
JSON goes to stdout; errors go to stderr with a nonzero exit. --data accepts JSON, @file.json or - for stdin. --query accepts a JSON object. --output creates a file without overwriting. Writes are not automatically retried.
```
inboxit emails send --data @email.json --idempotency-key order-001
inboxit logs list --query '{"status":"failed","limit":20}'
inboxit messages raw --id INBOX_UUID --message 42 --output message.eml
```

### Configuration
--workspace overrides the selected workspace. --origin or INBOXIT_ORIGIN overrides the HTTPS origin. INBOXIT_TOKEN supplies a scoped API key. Login credentials are stored per origin in ~/.inboxit/credentials.json; INBOXIT_CONFIG_DIR overrides this directory. Keep it private.

### Coverage
Endpoint pages include matching commands. billing get maps to /usage. smtp create-key maps to key creation. request can call implemented routes; it does not add unsupported features. Whole-account/workspace deletion is not implemented.
```
inboxit request GET /usage
inboxit logout
```

## Domains & DNS
URL: https://inboxit.wtf/resources/docs/domains/
Authenticate your sender and receive on your own domain.

### Add a domain
Use a domain or subdomain without a scheme, path or email address. The returned records array has purpose, type, host, value and required. Pending domains count toward account limits.
```
inboxit domains add --name mail.yourbrand.com
inboxit domains provider --id DOMAIN_UUID
```

### Publish and verify
Ownership and DKIM TXT records are required; DMARC is recommended. Hosts are fully qualified: providers that append the zone may need a relative host. Preserve existing mail records. Verification returns status, checks and checked_at. Wait at least ten seconds between checks.
```
inboxit domains verify --id DOMAIN_UUID
```

### Receiving DNS
For a dedicated receiving subdomain, set MX to mail.inboxit.wtf with priority 10. Assignment requires MX records to point exclusively to that host. Do not replace root-domain MX used by another provider. A verified sending domain alone does not create a receiving inbox.

### Remove safely
Remove custom receiving routes before deleting a domain. A domain with attached addresses returns 409. Address removal does not delete the inbox or messages.
```
inboxit inboxes remove-address --id INBOX_UUID
inboxit domains delete --id DOMAIN_UUID
```

## Send branded email
URL: https://inboxit.wtf/resources/docs/sending/
Text and HTML from a verified sender.

### Sender and branding
Use an active platform inbox address or a verified domain in the selected workspace. from is a bare address; from_name supplies its display name. text is required even with html. HTML is your branding, without an InboxIt marketing footer.

### Delivery lifecycle
201 means accepted. pending means awaiting processing, queued means handed to delivery, delivered means remote server acceptance. It does not guarantee inbox placement. Native provider failures may appear as failed while emitting email.bounced.

### Idempotency
Idempotency-Key is required: 1–100 letters, digits, underscores or hyphens. Reuse the same key and payload after an ambiguous timeout. A different payload with the same key returns 409. If the delivery status is uncertain, check the logs before sending again.

### Outreach and unsubscribe
Set purpose to outreach for paced API delivery with unsubscribe controls. By default InboxIt adds a workspace unsubscribe footer and one-click headers. Use unsubscribe_url for your HTTPS preference page on an exact hostname verified in this workspace. The one-click header still uses InboxIt unless you also supply unsubscribe_one_click_url. A custom one-click endpoint must accept unauthenticated form POSTs with List-Unsubscribe=One-Click. Your backend must immediately call POST /workspace-suppressions with the recipient and reason unsubscribe, and stop your own follow-ups. Do not unsubscribe on GET: link scanners visit links. Use opaque recipient tokens, not exposed email addresses.

### Integration controls
Use a separate workspace and scoped API key per customer. Domain, webhook and workspace-suppression APIs support explicitly granted scopes. POST /suppressions remains session-admin only and account-wide. GET /emails/:id reports status and next_attempt; POST /emails/:id/cancel cancels pending jobs only. Your campaign engine owns sequences, schedules, sender rotation and stop-on-reply. API outreach defaults to 50 sends per domain across the account in 24 hours, with 120 seconds between dispatches and a 24-hour queue expiry. Unlimited Enterprise volume does not remove these safeguards.

### Content limits
One recipient. Subject up to 200 characters; text up to 10,000; HTML up to 80,000; display name up to 100. Up to five attachments, 2 MB each and 5 MB total. No CC/BCC, scheduled or batch sends. Quotas, suppressions and account verification apply.

## Receive email
URL: https://inboxit.wtf/resources/docs/receiving/
Provision inboxes and fetch incoming messages.

### Provisioning
POST /inboxes returns 202. Poll the list until active. All plans have unlimited inboxes; volume, storage and retention still apply.

### Custom addresses
POST /inboxes/{id}/receiving-address assigns or renames an address. Verify its domain and MX first. A routing 503 can mean a pending durable change; inspect receiving_status before retrying. DELETE removes the custom route.

### Pagination and IDs
List responses contain uid_validity, messages and next_before. Pass next_before as before; limit defaults to 20, maximum 50. IDs here are mailbox UIDs, not outbound UUIDs. Persist inbox ID, UID validity and UID together.

### Events and raw messages
email.received contains message identifiers, not the body. Fetch details separately. /messages/{uid}/raw downloads an application/octet-stream .eml. New webhook endpoints do not replay historical incoming mail. Read messages before retention expires.

## Replies & threads
URL: https://inboxit.wtf/resources/docs/threads/
Connect responses to their original messages.

### Store Message-ID
Store message_id from the send response alongside your conversation ID. This RFC Message-ID differs from the outbound UUID.

### Route replies
Send from your assigned custom receiving address, or set reply_to to it. Domain verification enables sending; an active receiving route and MX enable receiving.

### Reply with context
Set in_reply_to to the incoming message’s Message-ID, including angle brackets. Read In-Reply-To and References from message headers/raw source to map conversations. There is no separate threads endpoint. Subject matching alone is unreliable.
```
inboxit emails send --data @reply.json --idempotency-key reply-001

// reply.json
{"from":"hello@mail.yourbrand.com","to":"recipient@example.com","subject":"Re: Hello","text":"Thanks!","in_reply_to":"<original@example.com>"}
```

## Webhooks & signatures
URL: https://inboxit.wtf/resources/docs/webhooks/
Signed delivery, bounce and incoming events.

### Register
An owner/admin can register five active endpoints per workspace. Public HTTPS port 443 is required; private destinations and redirects are blocked. Store the returned secret immediately.
```
inboxit webhooks create --url https://yourbrand.com/hooks/inboxit --events email.delivered,email.bounced,email.received
```

### Payloads
Envelope: id, type, created_at, workspace_id, data. Native delivery/bounce data: email_id, message_id, from, to, provider_status. Incoming data: inbox_id, uid, uid_validity, address, message_id. Fetch message bodies separately.
```
{"id":"EVENT_UUID","type":"email.received","created_at":"2026-10-23T12:00:00Z","workspace_id":"WORKSPACE_UUID","data":{"inbox_id":"INBOX_UUID","uid":"42","uid_validity":"123456","address":"hello@mail.yourbrand.com","message_id":"<reply@example.com>"}}
```

### Verify signatures
Use the unmodified raw request Buffer before parsing JSON. Headers: webhook-id, webhook-timestamp, webhook-signature. Sign id.timestamp.rawBody with HMAC-SHA256 using the secret as a UTF-8 string. Enforce a five-minute window, then persist/deduplicate event IDs.
```
import {createHmac, timingSafeEqual} from 'node:crypto';



export function verify(rawBody, headers, secret) {



  const id = headers['webhook-id'];



  const time = headers['webhook-timestamp'];



  const signature = headers['webhook-signature'];



  if (!id || !/^\d+$/.test(time || '') || !signature) return false;



  if (Math.abs(Date.now() / 1000 - Number(time)) > 300) return false;



  const hex = createHmac('sha256', secret)



    .update(id + '.' + time + '.').update(rawBody).digest('hex');



  const expected = Buffer.from('v1=' + hex);



  const actual = Buffer.from(signature);



  return actual.length === expected.length && timingSafeEqual(actual, expected);



}



// After verification: persist/deduplicate event.id, enqueue work, return 2xx.
```

### Retries
At-least-once delivery: non-2xx/network failures retry up to eight total attempts, exponential delays from 30 seconds capped at one hour. IDs stay stable; ordering is not guaranteed. Acknowledge only after durable acceptance. GET /webhooks includes the latest 100 delivery records.
```
inboxit webhooks list
inboxit webhooks retry --id DELIVERY_UUID
```

### Disable and rotate
DELETE disables an endpoint and cancels queued deliveries; an in-flight request may arrive. No update/rotation endpoint exists. Create a replacement, configure its secret, then disable the old endpoint. Deduplicate during overlap.

## Delivery logs
URL: https://inboxit.wtf/resources/docs/logs/
Filter and paginate workspace activity.

### Query logs
status: all, pending, queued, delivered, bounced, failed, uncertain, received. limit defaults to 50, maximum 100. Pass next unchanged as before; null ends pagination.
```
inboxit logs list --query '{"status":"failed","limit":25}'
```

### Fields
items contain id, email_id, status, recipient, subject, created_at, delivered_at, failure_code and attempts. Incoming email_id/subject may be null. No message bodies. Results are newest first by timestamp and ID.

### Investigate
Correlate email_id with outgoing records/webhooks. Check sender DNS, suppression, plan usage and recipient address and suppression status. Do not resend uncertain deliveries with a new key blindly. Webhook transport failures are separate records in GET /webhooks.

## Analytics
URL: https://inboxit.wtf/resources/docs/analytics/
UTC workspace activity and delivery outcomes.

### Time series
GET /analytics?days=30 accepts 7, 30 or 90 days. Returns days, timezone, series and totals. Series items contain day, sent, delivered, bounced, failed and received.
```
inboxit analytics get --days 30
```

### Definitions
Outbound counts use creation day and current status, so historical totals can change as delivery completes. sent counts submitted rows. Incoming counts use recorded incoming usage. Native hard failures can count as failed rather than bounced.

### Scope
Analytics is workspace-scoped. GET /usage is account-wide. Opt-in HTML sends expose opened/clicked unique email counts, opens/clicks event totals, and per-link counts. Use tracking: {opens: true, clicks: true} when sending, or CLI --track-opens --track-clicks with --data @email.json. Image blocking can hide opens and privacy proxies/link scanners can inflate events. Direct SMTP tracking and engagement webhooks are not included. delivered means remote mail-server acceptance.

## Usage & limits
URL: https://inboxit.wtf/resources/docs/usage/
Unlimited inboxes with account-wide allowances.

### Read usage
Fields: plan, name, domain_limit, daily_limit, monthly_limit, incoming_limit, storage_limit, retention_days, inbox_limit, price, daily_used, monthly_used, incoming_used, sending_paused, pause_reason and mode. null inbox_limit means unlimited; null daily_limit means no daily cap.
```
inboxit usage get
```

### Counters
Outgoing counters count submitted rows, including unsuccessful messages, in the current UTC day/month. Incoming has a separate monthly allowance. All owner workspaces share quotas. Pending domains count. Usage does not report current storage bytes.

### Plan allowances
Monthly outgoing and incoming allowances are separate and equal.
Plan | Monthly volume / price | Domains | Storage / retention
Free | 1,000 each / $0; 100 outgoing/day | 1 | 100 MiB / 7 days
Build | 50,000 / $12; 75,000 / $22 | 5 | 1 GiB / 30 days
Scale | 100,000 / $39; 250,000 / $79; 500,000 / $149; 1,000,000 / $279 | 25 | 5 GiB / 30 days

### Abuse controls
Unlimited inboxes does not remove volume, storage or retention limits. Suppressed recipients cannot be sent to. Complaints or excessive bounces can pause sending. Inspect pause_reason and contact support; a new key does not bypass a pause.

## SMTP integration
URL: https://inboxit.wtf/resources/docs/smtp/
Connect existing applications, including Supabase.

### Connection
Require STARTTLS and certificate verification. Password is a workspace API key with emails:send.
Setting | Value
Host | mail.inboxit.wtf
Port | 587
TLS | STARTTLS required (not implicit TLS)
Username | inboxit
Password | Sending API key

### Credentials
Use a dedicated expiring key for each integration. Revoking it disables SMTP access.
```
inboxit smtp create-key --name supabase --scopes emails:send
inboxit smtp get
```

### Node.js
Install nodemailer separately. Supply your key from the server environment. Use a verified sender and your recipient’s address.
```
import nodemailer from 'nodemailer';



const smtp = nodemailer.createTransport({



  host: 'mail.inboxit.wtf', port: 587, secure: false, requireTLS: true,



  auth: {user: 'inboxit', pass: process.env.INBOXIT_API_KEY}



});



await smtp.sendMail({from: 'Your Brand <hello@mail.yourbrand.com>',



  to: 'recipient@example.com', subject: 'Welcome', text: 'Your account is ready.'});
```

### Supabase
Enter these settings in custom SMTP, with your verified sender and display name. Configure auth redirect URLs for your app separately. The password is an InboxIt key, not a Supabase service-role key. The auth provider may enforce its own email limits.

### Limits and errors
One recipient, 100,000 raw bytes, no attachments. Envelope sender must match From. Same sender/quota/suppression/account checks as REST. Success means queued. Identical raw submissions use a content-derived idempotency key. 535: authentication; 452: recipients; 552: size; 553: sender mismatch; 554: attachments; 451: temporary failure; 550: application rejection.

## Plans & billing
URL: https://inboxit.wtf/resources/docs/billing/
Monthly subscriptions, confirmed payments and account allowances.

### Plan changes
Choose a plan on Pricing and review the recurring ZAR amount in Settings → Billing. PayFast collects card payment. Confirmed payments activate your account allowance and issue a downloadable receipt. Cancel future renewals in Billing; paid access remains until the confirmed period ends. Existing plan changes require billing support. DIGIGAP TECHNOLOGIES is not VAT registered and charges no VAT.

### Read entitlements
billing get is an alias for GET /usage. It returns plan, volume, price and consumption, not invoices. Workspace admins cannot grant themselves paid plans. The owner’s plan controls shared limits.
```
inboxit billing get
```

## Workspaces & teams
URL: https://inboxit.wtf/resources/docs/teams/
Explicit roles and invitations that survive sign-up.

### Workspace boundaries
Workspaces isolate resources, but account quotas are shared. Names are 1–10 characters; an account can own 20 workspaces.
```
inboxit workspaces list
inboxit workspace use --id WORKSPACE_UUID
```

### Invitations
Owners/admins invite admin or operator roles. Pending invitations persist after signup/sign-in. The matching verified email must explicitly accept.
```
inboxit team invite --email teammate@example.com --role operator
inboxit invitations list
inboxit invitations respond --id INVITATION_UUID --action accept
```

### Role management
Admins manage members and invitations. Operators cannot administer keys, domains or members. Owner/self membership cannot be changed or removed through these endpoints.
```
inboxit team update-member --id MEMBER_UUID --role admin
```

## Errors & retries
URL: https://inboxit.wtf/resources/docs/errors/
Handle failures without duplicate messages.

### Error body
JSON contains an error string; branch on HTTP status, not exact wording.
```
{"error":"A valid Idempotency-Key is required"}
```

### Statuses
Creates normally return 201; inbox provisioning returns 202; other successes return 200.
Status | Meaning / action
400 | Invalid fields, cursor or idempotency key
401 | Authenticate or replace expired/revoked key
403 | Check scopes, role, workspace and eligibility
404 | Missing/inaccessible resource or unsupported route
409 | Conflict, plan limit or pending operation
413 | Reduce payload size
429 | Respect Retry-After and back off
503 | Temporarily unavailable; reconcile writes before retry

### Rate limits
Account and edge limits apply. Backend 429 responses include Retry-After: 60. DNS checks have a ten-second guard. Use exponential backoff with jitter; a rate ceiling is not a delivery throughput guarantee.

### Write recovery
For sends/inbox creation reuse the original idempotency key and payload. For other writes read current state after ambiguous failures. Receiving-route 503 can mean pending durable work. Do not retry every 4xx.

## API reference
URL: https://inboxit.wtf/resources/docs/api-reference/introduction/
Implemented routes, permissions and request contracts.

### Base URL
https://inboxit.wtf/api/v2. JSON requests use Content-Type: application/json. Raw-message downloads return binary .eml content.

### Authentication
Scoped-key endpoints accept Authorization: Bearer <API key>. User-session routes are best called with the documented CLI command after inboxit login. Owner/admin routes reject ordinary workspace API keys.

### Pagination
Logs use an opaque before cursor. Messages use a UID next_before. Outgoing email lists return the last 100 with no pagination. There is no universal pagination contract.

### Examples
Identifiers and response values are illustrative. Unsupported methods are not implied by a resource name. Every endpoint below corresponds to a current backend route.

## Email testing without signup
URL: https://inboxit.wtf/resources/docs/anonymous-testing/
Create a private temporary inbox using HTTP. No account, session, domain setup or CLI required.

### Create an inbox
POST the public endpoint with a unique 16–128 character Idempotency-Key (letters, numbers, underscore or hyphen). No Authorization header is required. Save the returned token privately; reuse the same idempotency key on the same network only when retrying this creation.
```
curl -X POST 'https://inboxit.wtf/api/v2/public/inboxes' -H 'Idempotency-Key: signup-test-unique-001'
```

### Trigger and read
Use the returned address in your application test. Read using the returned inbox token, not a workspace API key. Wait matches sender/subject substrings case-insensitively and message IDs greater than after. Read the last message ID before triggering the test to avoid matching an older message.
```
curl 'https://inboxit.wtf/api/v2/public/inboxes/wait?subject=Verify&after=0&timeout=20' -H "Authorization: Bearer $INBOX_TOKEN"
```

### Inspect the message
A matched wait includes the message. You can also list messages and retrieve an individual message by ID. Treat email content and extracted links as untrusted; only follow the expected application domain. A waiting result is not an error; wait again after poll_after_seconds.

### Delete and handle expiry
Receive-only: 24 hours from creation, up to 100 incoming emails and 10 MB per inbox. Up to three creations per network per UTC day and three active inboxes; browser/API share limits. Service-wide capacity also applies. Never put the secret token in URLs, logs or public code. DELETE the base endpoint using the inbox token when finished. Expired, removed or invalid inbox capabilities are unavailable; create a new inbox for a new test.

### Limits and retries
120 requests per network per minute. Only one wait per inbox; timeout is 1–20 seconds. Respect Retry-After on 429 and poll_after_seconds. Do not retry creation with a new key after a network failure: reuse the original key. This API cannot send email.

## Retrieve email
URL: https://inboxit.wtf/resources/docs/api-reference/emails/get/
GET /api/v2/emails/{id}

### Authorization
emails:read. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/emails/RESOURCE_UUID' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit emails get --id RESOURCE_UUID
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "id": "EMAIL_UUID",
  "status": "delivered",
  "track_opens": true,
  "track_clicks": true,
  "open_count": 1,
  "click_count": 0,
  "tracking_links": []
}
```

### Behavior & errors
Response excerpt. Includes first opened_at/clicked_at timestamps and per-link url, clicks, first_clicked_at and last_clicked_at where tracked. Workspace and private inbox access rules apply. Tracking must be opted into when sending HTML; no retroactive tracking or direct SMTP tracking. No open/click webhook events yet. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## List temporary inboxes
URL: https://inboxit.wtf/resources/docs/api-reference/testing/list/
GET /api/v2/testing/inboxes

### Authorization
inboxes:read. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/testing/inboxes' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit testing list
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "inboxes": []
}
```

### Behavior & errors
Lists unexpired temporary inboxes, including pending/failed provisioning states. Available through the dashboard, API and CLI. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Create a temporary inbox
URL: https://inboxit.wtf/resources/docs/api-reference/testing/create/
POST /api/v2/testing/inboxes

### Authorization
inboxes:create. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
Required header: Idempotency-Key (1–100 alphanumeric, underscore or hyphen characters).
Name | Type | Contract
name | string · required | 1–60 characters
ttl_seconds | integer · optional | 60–86400; default 3600

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X POST 'https://inboxit.wtf/api/v2/testing/inboxes' \
  -H "Authorization: Bearer $INBOXIT_API_KEY" \
  -H "Content-Type: application/json" --data @request.json \
  -H "Idempotency-Key: request-001"
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "name": "Signup test",
  "ttl_seconds": 3600
}
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit testing create --data @request.json --idempotency-key request-001
```

### Response
HTTP 201. Example values are illustrative; excerpts are marked.
```
{
  "id": "INBOX_UUID",
  "address": "agent-generated@agents.inboxit.wtf",
  "status": "pending",
  "test_expires_at": "2026-10-23T20:00:00Z"
}
```

### Behavior & errors
Native provisioning is asynchronous. Poll list until active. Idempotency-Key required. Same key with changed parameters returns 409. Incoming volume and storage limits apply. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Delete a temporary inbox
URL: https://inboxit.wtf/resources/docs/api-reference/testing/delete/
DELETE /api/v2/testing/inboxes/{id}

### Authorization
inboxes:create. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X DELETE 'https://inboxit.wtf/api/v2/testing/inboxes/RESOURCE_UUID' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit testing delete --id RESOURCE_UUID
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "id": "INBOX_UUID",
  "deleted": true
}
```

### Behavior & errors
Disables the temporary address, deletes its content and run records, and removes its credentials and replaces the native delivery route with a rejection marker. A cleanup failure is retried by the server timer. Permanent inboxes are rejected. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Wait for a new email
URL: https://inboxit.wtf/resources/docs/api-reference/testing/wait/
POST /api/v2/testing/inboxes/{id}/wait

### Authorization
messages:read. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID
sender | string · optional | Exact email address, case insensitive
subject | string · optional | Subject substring, case insensitive
timeout_seconds | integer · optional | 1–300; default 60

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X POST 'https://inboxit.wtf/api/v2/testing/inboxes/RESOURCE_UUID/wait' \
  -H "Authorization: Bearer $INBOXIT_API_KEY" \
  -H "Content-Type: application/json" --data @request.json
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "subject": "Verify",
  "timeout_seconds": 60
}
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit testing wait --id RESOURCE_UUID --data @request.json
```

### Response
HTTP 201. Example values are illustrative; excerpts are marked.
```
{
  "id": "RUN_UUID",
  "status": "waiting",
  "after_id": "0",
  "uid_validity": "1234",
  "deadline": "2026-10-23T19:01:00Z"
}
```

### Behavior & errors
Start BEFORE triggering your application. Existing messages are excluded using a mailbox UID boundary. API returns immediately; poll testing result. CLI waits and exits 2 on timeout. Inbox must be active (409 otherwise). Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Retrieve a test result
URL: https://inboxit.wtf/resources/docs/api-reference/testing/result/
GET /api/v2/testing/runs/{id}

### Authorization
messages:read. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/testing/runs/RESOURCE_UUID' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit testing result --id RESOURCE_UUID
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "id": "RUN_UUID",
  "status": "matched",
  "matched_id": "1",
  "extraction": {
    "codes": [
      "482951"
    ],
    "links": [
      "https://example.com/confirm"
    ],
    "code": "482951",
    "link": "https://example.com/confirm",
    "ambiguous": false,
    "untrusted_content": true
  }
}
```

### Behavior & errors
Response excerpt. Status is waiting, matched, timed_out or cancelled. Matched response includes plain-text message. Mailbox reset returns 409; expiry returns 410 or 404 after cleanup. Does not follow extracted links. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Cancel a wait
URL: https://inboxit.wtf/resources/docs/api-reference/testing/cancel/
DELETE /api/v2/testing/runs/{id}

### Authorization
messages:read. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X DELETE 'https://inboxit.wtf/api/v2/testing/runs/RESOURCE_UUID' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit testing cancel --id RESOURCE_UUID
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "id": "RUN_UUID",
  "status": "cancelled"
}
```

### Behavior & errors
Cancels a waiting run; completed/missing runs return 404. Does not delete its inbox. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Extract codes and links
URL: https://inboxit.wtf/resources/docs/api-reference/testing/extract/
GET /api/v2/testing/inboxes/{id}/messages/{message}/extract

### Authorization
messages:read. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID
message | path · required | Positive mailbox UID

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/testing/inboxes/RESOURCE_UUID/messages/42/extract' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit testing extract --id RESOURCE_UUID --message 42
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "codes": [
    "482951"
  ],
  "links": [],
  "code": "482951",
  "link": null,
  "ambiguous": false,
  "untrusted_content": true
}
```

### Behavior & errors
Extracts 4–8 digit candidates and HTTP/HTTPS links from a message in an active temporary inbox. Multiple candidates make the singular value null; maximum 30 per kind. Content is untrusted. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Send email
URL: https://inboxit.wtf/resources/docs/api-reference/emails/send/
POST /api/v2/emails

### Authorization
emails:send. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
Required header: Idempotency-Key (1–100 alphanumeric, underscore or hyphen characters).
Name | Type | Contract
from | string · required | Bare sender email; active inbox or verified workspace domain
to | string · required | One recipient address
subject | string · required | Nonempty, at most 200 characters; no newlines
text | string · required | Nonempty plain text, at most 10,000 characters
html | string · optional | Up to 80,000 characters
tracking | object · optional | opens and clicks boolean flags, both default false; HTML only
from_name | string · optional | Display name up to 100 characters
reply_to | string · optional | Valid reply destination
in_reply_to | string · optional | RFC Message-ID including <angle brackets>

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X POST 'https://inboxit.wtf/api/v2/emails' \
  -H "Authorization: Bearer $INBOXIT_API_KEY" \
  -H "Content-Type: application/json" --data @request.json \
  -H "Idempotency-Key: request-001"
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "from": "hello@mail.yourbrand.com",
  "to": "recipient@example.com",
  "subject": "Welcome",
  "text": "Thanks for joining.",
  "html": "<h1>Welcome</h1><p>Thanks for joining.</p>",
  "tracking": {
    "opens": true,
    "clicks": true
  }
}
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit emails send --data @request.json --idempotency-key request-001
```

### Response
HTTP 201. Example values are illustrative; excerpts are marked.
```
{
  "id": "EMAIL_UUID",
  "status": "pending",
  "message_id": "<id@mail.yourbrand.com>"
}
```

### Behavior & errors
Idempotency-Key is required. Same key and payload returns the existing result; a changed payload returns 409. Account quotas, suppression, verified sender and account verification checks apply. 201 is queue acceptance, not delivery. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## List emails
URL: https://inboxit.wtf/resources/docs/api-reference/emails/list/
GET /api/v2/emails

### Authorization
emails:read. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/emails' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit emails list
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "emails": []
}
```

### Behavior & errors
Returns the last 100 workspace outbound records, newest first. Each item has id, sender, recipient, subject, status, message_id and created_at. GET /emails/{id} returns one email. Tracking fields include track_opens, track_clicks, opened_at, clicked_at, open_count, click_count and tracking_links. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## List domains
URL: https://inboxit.wtf/resources/docs/api-reference/domains/list/
GET /api/v2/domains

### Authorization
emails:read or user session. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/domains' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit domains list
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "allowance": {
    "domain_limit": 1,
    "domains_used": 0,
    "can_add_domain": true
  },
  "domains": []
}
```

### Behavior & errors
Allowance also includes plan entitlements. Domains contain id, name, status, checks, checked_at, created_at and records. Pending domains count toward the account limit. Example allowance is an excerpt. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Add domain
URL: https://inboxit.wtf/resources/docs/api-reference/domains/add/
POST /api/v2/domains

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
name | string · required | Public domain or subdomain, no URL/path/email, maximum 253 characters

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit domains add --data @request.json
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "name": "mail.yourbrand.com"
}
```

### Response
HTTP 201. Example values are illustrative; excerpts are marked.
```
{
  "id": "DOMAIN_UUID",
  "name": "mail.yourbrand.com",
  "status": "pending",
  "records": [
    {
      "purpose": "ownership",
      "type": "TXT",
      "host": "_inboxit.mail.yourbrand.com",
      "value": "inboxit-verification=GENERATED_TOKEN",
      "required": true
    }
  ]
}
```

### Behavior & errors
Response excerpt: actual records also include generated DKIM and recommended DMARC. Copy returned values, never example tokens. Existing workspace domain returns its record; exhausted plan or conflicting domain returns 409. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Verify domain
URL: https://inboxit.wtf/resources/docs/api-reference/domains/verify/
POST /api/v2/domains/{id}/verify

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit domains verify --id RESOURCE_UUID
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "id": "DOMAIN_UUID",
  "name": "mail.yourbrand.com",
  "status": "verified",
  "checks": {},
  "checked_at": "2026-10-23T12:00:00Z"
}
```

### Behavior & errors
Response excerpt; also returns records and created_at. Resolves ownership and DKIM TXT. DMARC is recommended, not required. Checking within ten seconds returns 429; otherwise failed DNS checks leave status pending. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Detect DNS provider
URL: https://inboxit.wtf/resources/docs/api-reference/domains/provider/
GET /api/v2/domains/{id}/provider

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit domains provider --id RESOURCE_UUID
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "provider": null,
  "nameservers": [],
  "zone": null,
  "status": "unknown"
}
```

### Behavior & errors
Best-effort lookup: status is found, unknown or unavailable. Detected provider has name and url; nameservers is a string array and zone is the resolved zone. Does not edit DNS. Use the dashboard or inspect the returned result for provider navigation. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Delete domain
URL: https://inboxit.wtf/resources/docs/api-reference/domains/delete/
DELETE /api/v2/domains/{id}

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit domains delete --id RESOURCE_UUID
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "removed": true
}
```

### Behavior & errors
409 if any receiving address still uses the domain. Remove its receiving routes first. Domain deletion removes sending authorization. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## List inboxes
URL: https://inboxit.wtf/resources/docs/api-reference/inboxes/list/
GET /api/v2/inboxes

### Authorization
inboxes:read. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/inboxes' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit inboxes list
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "inboxes": []
}
```

### Behavior & errors
Items: id, name, address, status, receiving_address, receiving_status, created_at. Wait until status active before message access or custom address assignment. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Create inbox
URL: https://inboxit.wtf/resources/docs/api-reference/inboxes/create/
POST /api/v2/inboxes

### Authorization
inboxes:create. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
Required header: Idempotency-Key (1–100 alphanumeric, underscore or hyphen characters).
Name | Type | Contract
name | string · required | 1–60 characters

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X POST 'https://inboxit.wtf/api/v2/inboxes' \
  -H "Authorization: Bearer $INBOXIT_API_KEY" \
  -H "Content-Type: application/json" --data @request.json \
  -H "Idempotency-Key: request-001"
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "name": "Support"
}
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit inboxes create --data @request.json --idempotency-key request-001
```

### Response
HTTP 202. Example values are illustrative; excerpts are marked.
```
{
  "id": "INBOX_UUID",
  "name": "Support",
  "address": "agent-generated@agents.inboxit.wtf",
  "status": "pending",
  "created_at": "2026-10-23T12:00:00Z"
}
```

### Behavior & errors
Idempotency-Key required (1–100 letters/digits/_/-). Same key with different name returns 409. Provisioning runs asynchronously. Unlimited inboxes on every plan; volume and storage quotas still apply. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Assign receiving address
URL: https://inboxit.wtf/resources/docs/api-reference/inboxes/address/
POST /api/v2/inboxes/{id}/receiving-address

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID
address | string · required | Complete email, maximum 254 characters; local part maximum 64

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit inboxes address --id RESOURCE_UUID --data @request.json
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "address": "hello@mail.yourbrand.com"
}
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "id": "INBOX_UUID",
  "address": "hello@mail.yourbrand.com",
  "status": "active"
}
```

### Behavior & errors
Assigns or renames the receiving address on an active inbox. Domain must be verified in this workspace and MX must point exclusively to mail.inboxit.wtf. Routing 503 may mean a pending persisted change; inspect receiving_status. A conflicting pending change returns 409. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Remove receiving address
URL: https://inboxit.wtf/resources/docs/api-reference/inboxes/remove-address/
DELETE /api/v2/inboxes/{id}/receiving-address

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit inboxes remove-address --id RESOURCE_UUID
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "id": "INBOX_UUID",
  "address": null,
  "status": "none"
}
```

### Behavior & errors
Removes the custom route through durable cleanup. Does not delete the inbox or its stored messages. Reconcile pending routing after a temporary failure. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## List sent messages
URL: https://inboxit.wtf/resources/docs/api-reference/inboxes/sent/
GET /api/v2/inboxes/{id}/sent

### Authorization
messages:read AND emails:read. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/inboxes/RESOURCE_UUID/sent' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit inboxes sent --id RESOURCE_UUID
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "messages": []
}
```

### Behavior & errors
Returns sent messages associated with the selected inbox, including stored outbound content. The inbox must belong to this workspace. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## List messages
URL: https://inboxit.wtf/resources/docs/api-reference/messages/list/
GET /api/v2/inboxes/{id}/messages

### Authorization
messages:read. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID
limit | query integer · optional | 1–50, default 20
before | query UID · optional | Positive mailbox UID; use next_before from the previous page

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/inboxes/RESOURCE_UUID/messages?limit=20' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit messages list --id RESOURCE_UUID --query '{"limit":"20"}'
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "uid_validity": "123456",
  "messages": [],
  "next_before": null
}
```

### Behavior & errors
Requires an active inbox (409 otherwise). Scope persisted UIDs by inbox and uid_validity. null next_before ends pagination. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Retrieve message
URL: https://inboxit.wtf/resources/docs/api-reference/messages/get/
GET /api/v2/inboxes/{id}/messages/{message}

### Authorization
messages:read. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID
message | path · required | Positive mailbox UID

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/inboxes/RESOURCE_UUID/messages/42' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit messages get --id RESOURCE_UUID --message 42
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "id": "42",
  "subject": "Re: Hello",
  "from": "recipient@example.com",
  "to": "hello@mail.yourbrand.com",
  "date": "Fri, 23 Oct 2026 12:00:00 +0000",
  "message_id": "<reply@example.com>",
  "in_reply_to": "<original@mail.yourbrand.com>",
  "references": "<original@mail.yourbrand.com>",
  "received_at": "2026-10-23T12:00:00+00:00",
  "text": "Thanks!",
  "attachments": [],
  "untrusted_content": true
}
```

### Behavior & errors
The message path parameter is a positive mailbox UID, not an outgoing email UUID. Missing message returns 404. Use raw download when exact MIME source is needed. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Download raw message
URL: https://inboxit.wtf/resources/docs/api-reference/messages/raw/
GET /api/v2/inboxes/{id}/messages/{message}/raw

### Authorization
messages:read. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID
message | path · required | Positive mailbox UID

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/inboxes/RESOURCE_UUID/messages/42/raw' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit messages raw --id RESOURCE_UUID --message 42
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
Binary RFC email source (.eml), Content-Type: application/octet-stream.
```

### Behavior & errors
Save bytes directly; do not JSON-parse this response. CLI --output refuses to overwrite an existing file. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Retrieve analytics
URL: https://inboxit.wtf/resources/docs/api-reference/analytics/get/
GET /api/v2/analytics

### Authorization
emails:read. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
days | query integer · optional | 7, 30 or 90; default 30

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/analytics?days=30' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit analytics get --query '{"days":"30"}'
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "days": 30,
  "timezone": "UTC",
  "series": [
    {
      "day": "2026-10-23",
      "sent": 2,
      "delivered": 1,
      "bounced": 0,
      "failed": 0,
      "received": 1
    }
  ],
  "totals": {
    "sent": 2,
    "delivered": 1,
    "bounced": 0,
    "failed": 0,
    "received": 1
  }
}
```

### Behavior & errors
Example series is shortened. Workspace-scoped; outbound grouped by creation day and current status. Also returns open_tracked, click_tracked, opened, clicked, opens and clicks in totals and series, plus up to 100 recent emails with per-link counts. opened/clicked count unique emails; opens/clicks count events. Rates use tracked emails as denominators. Events are grouped by email creation day, not event day. Proxies/scanners can inflate counts; image blocking can hide opens. Native provider failures may count as failed instead of bounced. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## List logs
URL: https://inboxit.wtf/resources/docs/api-reference/logs/list/
GET /api/v2/logs

### Authorization
emails:read. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
status | query enum · optional | all, pending, queued, delivered, bounced, failed, uncertain, received
limit | query integer · optional | 1–100, default 50
before | query string · optional | Opaque next cursor from previous response

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/logs?status=all&limit=50' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit logs list --query '{"status":"all","limit":"50"}'
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "items": [],
  "next": null
}
```

### Behavior & errors
Items: id, email_id, status, recipient, subject, created_at, delivered_at, failure_code, attempts. Incoming email_id/subject can be null. Newest first; next=null ends pagination. No message bodies. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Retrieve usage
URL: https://inboxit.wtf/resources/docs/api-reference/usage/get/
GET /api/v2/usage

### Authorization
emails:read. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/usage' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit usage get
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "plan": "free",
  "name": "Free",
  "domain_limit": 1,
  "daily_limit": 100,
  "monthly_limit": 1000,
  "incoming_limit": 1000,
  "storage_limit": 104857600,
  "retention_days": 7,
  "inbox_limit": null,
  "price": 0,
  "daily_used": 0,
  "monthly_used": 0,
  "incoming_used": 0,
  "sending_paused": false,
  "pause_reason": null,
  "mode": "native"
}
```

### Behavior & errors
Account-wide, shared across workspaces. Counters use UTC day/month. Outgoing counts submitted rows, not only successful delivery. Incoming allowance is separate. null inbox_limit means unlimited. Does not return current storage bytes or invoices. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Retrieve SMTP settings
URL: https://inboxit.wtf/resources/docs/api-reference/smtp/get/
GET /api/v2/smtp

### Authorization
Authenticated API key or user session. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/smtp' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit smtp get
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "host": "mail.inboxit.wtf",
  "port": 587,
  "encryption": "STARTTLS",
  "username": "inboxit",
  "password": "Use a workspace API key with emails:send scope",
  "max_recipients": 1,
  "max_bytes": 100000,
  "attachments": false
}
```

### Behavior & errors
Returns connection instructions, not a secret. Create a dedicated emails:send key for SMTP. See the SMTP guide for limits and Supabase setup. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## List webhooks
URL: https://inboxit.wtf/resources/docs/api-reference/webhooks/list/
GET /api/v2/webhooks

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit webhooks list
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "endpoints": [],
  "deliveries": []
}
```

### Behavior & errors
Endpoints: id, url, events, enabled, created_at. Deliveries: id, endpoint_id, type, state, attempts, last_status, last_error, next_attempt, updated_at. Last 100 deliveries. Secrets never appear. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Create webhook
URL: https://inboxit.wtf/resources/docs/api-reference/webhooks/create/
POST /api/v2/webhooks

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
url | string · required | Public HTTPS port 443; no private destinations/redirects
events | string[] · required | Nonempty subset: email.delivered, email.bounced, email.received

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit webhooks create --data @request.json
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "url": "https://yourbrand.com/hooks/inboxit",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.received"
  ]
}
```

### Response
HTTP 201. Example values are illustrative; excerpts are marked.
```
{
  "id": "ENDPOINT_UUID",
  "secret": "ONE_TIME_SIGNING_SECRET"
}
```

### Behavior & errors
Five active endpoints per workspace. Store the secret immediately. See the webhook guide for raw-body signature verification and retries. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Delete webhook
URL: https://inboxit.wtf/resources/docs/api-reference/webhooks/delete/
DELETE /api/v2/webhooks/{id}

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit webhooks delete --id RESOURCE_UUID
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "disabled": true
}
```

### Behavior & errors
Disables rather than erases the endpoint and cancels queued deliveries. An in-flight request may still arrive. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Retry webhook delivery
URL: https://inboxit.wtf/resources/docs/api-reference/webhooks/retry/
POST /api/v2/webhook-deliveries/{id}/retry

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit webhooks retry --id RESOURCE_UUID
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "queued": true
}
```

### Behavior & errors
Path id is a delivery ID, not endpoint/event ID. Only failed deliveries on enabled workspace endpoints can be retried. Resets attempts and queues immediately; otherwise 404. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## List keys
URL: https://inboxit.wtf/resources/docs/api-reference/keys/list/
GET /api/v2/keys

### Authorization
Authenticated user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit keys list
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "keys": []
}
```

### Behavior & errors
Key metadata: id, name, prefix, scopes, created_at, expires_at, revoked_at. Operators receive an empty list. Tokens are never returned here. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Create API key
URL: https://inboxit.wtf/resources/docs/api-reference/keys/create/
POST /api/v2/keys

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
name | string · required | 1–60 characters
scopes | string[] · required | Nonempty supported scopes; see Authentication
expires_in_days | integer · optional | 1–365, default 30

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit keys create --data @request.json
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "name": "Backend",
  "scopes": [
    "emails:send",
    "emails:read"
  ],
  "expires_in_days": 30
}
```

### Response
HTTP 201. Example values are illustrative; excerpts are marked.
```
{
  "id": "KEY_UUID",
  "name": "Backend",
  "prefix": "iit_…",
  "scopes": [
    "emails:send",
    "emails:read"
  ],
  "expires_at": "2026-11-22T12:00:00Z",
  "token": "iit_ONE_TIME_SECRET"
}
```

### Behavior & errors
Ten active keys per account. Save token once; it is not recoverable from list responses. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Revoke API key
URL: https://inboxit.wtf/resources/docs/api-reference/keys/revoke/
DELETE /api/v2/keys/{id}

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit keys revoke --id RESOURCE_UUID
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "id": "KEY_UUID",
  "revoked": true
}
```

### Behavior & errors
Revokes the selected workspace key, including SMTP access. Repeated revocation is safe. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## List workspaces
URL: https://inboxit.wtf/resources/docs/api-reference/workspaces/list/
GET /api/v2/workspaces

### Authorization
Authenticated user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit workspaces list
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "workspaces": [],
  "activeWorkspaceId": "WORKSPACE_UUID"
}
```

### Behavior & errors
Workspace items: id, name, created_at, role. Includes owned workspaces and memberships. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Create workspace
URL: https://inboxit.wtf/resources/docs/api-reference/workspaces/create/
POST /api/v2/workspaces

### Authorization
Authenticated user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
name | string · required | Trimmed 1–10 characters

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit workspaces create --data @request.json
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "name": "prod"
}
```

### Response
HTTP 201. Example values are illustrative; excerpts are marked.
```
{
  "id": "WORKSPACE_UUID",
  "name": "prod",
  "created_at": "2026-10-23T12:00:00Z"
}
```

### Behavior & errors
Maximum 20 owned workspaces. Account quotas are shared, not reset by creating a workspace. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Update workspace
URL: https://inboxit.wtf/resources/docs/api-reference/workspaces/update/
PATCH /api/v2/workspace

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
name | string · required | Trimmed 1–10 characters

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit workspaces update --data @request.json
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "name": "prod"
}
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "id": "WORKSPACE_UUID",
  "name": "prod"
}
```

### Behavior & errors
Updates the selected workspace. There is no workspace deletion endpoint. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Retrieve profile
URL: https://inboxit.wtf/resources/docs/api-reference/profile/get/
GET /api/v2/profile

### Authorization
Authenticated user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit profile get
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "display_name": "Your Name",
  "avatar": null,
  "identity_provider": "supabase",
  "created_at": "2026-10-23T12:00:00Z",
  "is_admin": false
}
```

### Behavior & errors
Returns the signed-in user profile. is_admin is platform administration, not the workspace role. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Update profile
URL: https://inboxit.wtf/resources/docs/api-reference/profile/update/
PATCH /api/v2/profile

### Authorization
Authenticated user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
name | string · required | Trimmed 1–80 characters

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit profile update --data @request.json
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "name": "Your Name"
}
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "display_name": "Your Name",
  "avatar": null
}
```

### Behavior & errors
Updates display name, not email or password. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Update profile photo
URL: https://inboxit.wtf/resources/docs/api-reference/profile/photo/
PATCH /api/v2/profile/photo

### Authorization
Authenticated user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
avatar | string or null · required | JPEG data URL under 150 KB; null removes photo

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit profile photo --data @request.json
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "avatar": null
}
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "display_name": "Your Name",
  "avatar": null
}
```

### Behavior & errors
JPEG signature is checked. No PNG upload or multipart endpoint. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Retrieve account
URL: https://inboxit.wtf/resources/docs/api-reference/account/get/
GET /api/v2/account

### Authorization
Authenticated API key or user session. Use a workspace-scoped bearer key or an authorized user session.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract

### Request
Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.
```
curl -X GET 'https://inboxit.wtf/api/v2/account' \
  -H "Authorization: Bearer $INBOXIT_API_KEY"
```

### CLI equivalent
Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.
```
inboxit account get
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "id": "ACCOUNT_UUID",
  "inbox_limit": null,
  "created_at": "2026-10-23T12:00:00Z"
}
```

### Behavior & errors
Legacy account metadata. Use /usage for current plan entitlements; inbox_limit here is not the authoritative plan quota. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## List notifications
URL: https://inboxit.wtf/resources/docs/api-reference/notifications/list/
GET /api/v2/notifications

### Authorization
Authenticated user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit notifications list
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "events": []
}
```

### Behavior & errors
Latest 30 workspace audit events with id, action, created_at. Not a webhook event stream. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## List team
URL: https://inboxit.wtf/resources/docs/api-reference/team/list/
GET /api/v2/team

### Authorization
Authenticated user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit team list
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "actor_id": "USER_UUID",
  "role": "owner",
  "workspace": "prod",
  "members": [],
  "invitations": []
}
```

### Behavior & errors
Members include id, display_name, email and role. Pending invitations are visible to owner/admin only. workspace is the display name, not an object. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Invite a member
URL: https://inboxit.wtf/resources/docs/api-reference/team/invite/
POST /api/v2/team/invites

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
email | string · required | Invitee email
role | enum · optional | admin or operator; default operator

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit team invite --data @request.json
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "email": "teammate@example.com",
  "role": "operator"
}
```

### Response
HTTP 201. Example values are illustrative; excerpts are marked.
```
{
  "id": "INVITATION_UUID",
  "mail_status": "pending"
}
```

### Behavior & errors
20 invitations per day per inviter. Existing membership conflicts with 409. Pending invitations persist through signup and require explicit acceptance by the matching verified email. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Revoke invitation
URL: https://inboxit.wtf/resources/docs/api-reference/team/revoke-invite/
DELETE /api/v2/team/invites/{id}

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit team revoke-invite --id RESOURCE_UUID
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "revoked": true
}
```

### Behavior & errors
Only pending invitations can be revoked; missing/nonpending returns 404. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Update member role
URL: https://inboxit.wtf/resources/docs/api-reference/team/update-member/
PATCH /api/v2/team/members/{id}

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID
role | enum · required | admin or operator

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit team update-member --id RESOURCE_UUID --data @request.json
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "role": "operator"
}
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "user_id": "USER_UUID",
  "role": "operator"
}
```

### Behavior & errors
Cannot change owner or your own role. ID is the member user ID. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Remove member
URL: https://inboxit.wtf/resources/docs/api-reference/team/remove-member/
DELETE /api/v2/team/members/{id}

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit team remove-member --id RESOURCE_UUID
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "removed": true
}
```

### Behavior & errors
Cannot remove owner or yourself. Removes membership access to this workspace. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## List invitations
URL: https://inboxit.wtf/resources/docs/api-reference/invitations/list/
GET /api/v2/invitations

### Authorization
Authenticated user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit invitations list
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "invitations": [
    {
      "id": "INVITATION_UUID",
      "role": "operator",
      "expires_at": "2026-10-30T12:00:00Z",
      "workspace_name": "prod",
      "inviter_email": "owner@example.com"
    }
  ]
}
```

### Behavior & errors
Discovers invitations matching the authenticated email after signup/sign-in; no automatic acceptance. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Respond to invitation
URL: https://inboxit.wtf/resources/docs/api-reference/invitations/respond/
POST /api/v2/invitations/{id}

### Authorization
Authenticated user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
id | path · required | Resource UUID
action | enum · required | accept or decline

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit invitations respond --id RESOURCE_UUID --data @request.json
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "action": "accept"
}
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "workspace_id": "WORKSPACE_UUID",
  "status": "accepted"
}
```

### Behavior & errors
Requires the matching verified email. Acceptance is idempotent for an already accepted invitation. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Add suppression
URL: https://inboxit.wtf/resources/docs/api-reference/suppressions/add/
POST /api/v2/suppressions

### Authorization
Owner/admin user session (use inboxit login). Use the CLI login flow; a workspace API key cannot call this operation.

### Parameters
All resource access is checked against the selected workspace and user permissions.
Name | Type | Contract
recipient | string · required | Email address up to 254 characters

### Request
Run inboxit login first. The CLI supplies authenticated user credentials.
```
inboxit suppressions add --data @request.json
```

### JSON body
Save this JSON as request.json for the request above. Replace example values with your own.
```
{
  "recipient": "recipient@example.com"
}
```

### Response
HTTP 200. Example values are illustrative; excerpts are marked.
```
{
  "suppressed": true
}
```

### Behavior & errors
Adds an account-wide manual suppression. No customer unsuppress endpoint exists. Applies across owner workspaces. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.

## Create anonymous test inbox
URL: https://inboxit.wtf/resources/docs/api-reference/public-testing/create/
POST /api/v2/public/inboxes

### Authorization
No authentication or signup required. Creation is rate-limited by network.

### Contract
Required Idempotency-Key: 16–128 letters, numbers, underscore or hyphen. No request body required. Returns HTTP 201 with address, token and poll_after_seconds.

### HTTP request
Use from an agent, test runner or HTTP client. No CLI required.
```
curl -X POST 'https://inboxit.wtf/api/v2/public/inboxes' -H 'Idempotency-Key: signup-test-unique-001'
```

### Limits and errors
Receive-only: 24 hours from creation, up to 100 incoming emails and 10 MB per inbox. Up to three creations per network per UTC day and three active inboxes; browser/API share limits. Service-wide capacity also applies. Never put the secret token in URLs, logs or public code. 400 invalid parameters; 401 missing/invalid token; 404 unavailable resource; 410 expired resource where applicable; 429 rate/capacity limit (respect Retry-After); 503 unavailable. The complete walkthrough is under Guides → Email testing without signup.

## Read anonymous test inbox
URL: https://inboxit.wtf/resources/docs/api-reference/public-testing/read/
GET /api/v2/public/inboxes

### Authorization
Authorization: Bearer INBOX_TOKEN, returned by creation. It grants access only to that inbox. No login, session or workspace API key required.

### Contract
Returns inbox information and message list.

### HTTP request
Use from an agent, test runner or HTTP client. No CLI required.
```
curl -X GET 'https://inboxit.wtf/api/v2/public/inboxes' -H "Authorization: Bearer $INBOX_TOKEN"
```

### Limits and errors
Receive-only: 24 hours from creation, up to 100 incoming emails and 10 MB per inbox. Up to three creations per network per UTC day and three active inboxes; browser/API share limits. Service-wide capacity also applies. Never put the secret token in URLs, logs or public code. 400 invalid parameters; 401 missing/invalid token; 404 unavailable resource; 410 expired resource where applicable; 429 rate/capacity limit (respect Retry-After); 503 unavailable. The complete walkthrough is under Guides → Email testing without signup.

## Read a test message
URL: https://inboxit.wtf/resources/docs/api-reference/public-testing/message/
GET /api/v2/public/inboxes/messages/{id}

### Authorization
Authorization: Bearer INBOX_TOKEN, returned by creation. It grants access only to that inbox. No login, session or workspace API key required.

### Contract
id is a positive numeric mailbox message ID. Returns message content.

### HTTP request
Use from an agent, test runner or HTTP client. No CLI required.
```
curl -X GET 'https://inboxit.wtf/api/v2/public/inboxes/messages/1' -H "Authorization: Bearer $INBOX_TOKEN"
```

### Limits and errors
Receive-only: 24 hours from creation, up to 100 incoming emails and 10 MB per inbox. Up to three creations per network per UTC day and three active inboxes; browser/API share limits. Service-wide capacity also applies. Never put the secret token in URLs, logs or public code. 400 invalid parameters; 401 missing/invalid token; 404 unavailable resource; 410 expired resource where applicable; 429 rate/capacity limit (respect Retry-After); 503 unavailable. The complete walkthrough is under Guides → Email testing without signup.

## Wait for a test email
URL: https://inboxit.wtf/resources/docs/api-reference/public-testing/wait/
GET /api/v2/public/inboxes/wait

### Authorization
Authorization: Bearer INBOX_TOKEN, returned by creation. It grants access only to that inbox. No login, session or workspace API key required.

### Contract
Optional query: after numeric message ID (default 0), sender substring (max 254), subject substring (max 200), timeout integer 1–20 (default 20). HTTP 200 status matched with message, or waiting with poll_after_seconds.

### HTTP request
Use from an agent, test runner or HTTP client. No CLI required.
```
curl -X GET 'https://inboxit.wtf/api/v2/public/inboxes/wait' -H "Authorization: Bearer $INBOX_TOKEN"
```

### Limits and errors
Receive-only: 24 hours from creation, up to 100 incoming emails and 10 MB per inbox. Up to three creations per network per UTC day and three active inboxes; browser/API share limits. Service-wide capacity also applies. Never put the secret token in URLs, logs or public code. 400 invalid parameters; 401 missing/invalid token; 404 unavailable resource; 410 expired resource where applicable; 429 rate/capacity limit (respect Retry-After); 503 unavailable. The complete walkthrough is under Guides → Email testing without signup.

## Delete anonymous test inbox
URL: https://inboxit.wtf/resources/docs/api-reference/public-testing/delete/
DELETE /api/v2/public/inboxes

### Authorization
Authorization: Bearer INBOX_TOKEN, returned by creation. It grants access only to that inbox. No login, session or workspace API key required.

### Contract
Deletes the inbox and its content. This cannot be undone.

### HTTP request
Use from an agent, test runner or HTTP client. No CLI required.
```
curl -X DELETE 'https://inboxit.wtf/api/v2/public/inboxes' -H "Authorization: Bearer $INBOX_TOKEN"
```

### Limits and errors
Receive-only: 24 hours from creation, up to 100 incoming emails and 10 MB per inbox. Up to three creations per network per UTC day and three active inboxes; browser/API share limits. Service-wide capacity also applies. Never put the secret token in URLs, logs or public code. 400 invalid parameters; 401 missing/invalid token; 404 unavailable resource; 410 expired resource where applicable; 429 rate/capacity limit (respect Retry-After); 503 unavailable. The complete walkthrough is under Guides → Email testing without signup.