# MailToAPI Agent API

Base URL: https://mailtoapi.app

Use a bearer API key:

```http
Authorization: Bearer mtapi_...
```

## Create an inbox

```http
POST /api/v1/inboxes
content-type: application/json
```

```json
{
  "name": "Lead Intake",
  "fields": [
    { "key": "name", "type": "string", "required": true },
    { "key": "email", "type": "string", "required": true },
    { "key": "phone", "type": "string", "required": false },
    { "key": "message", "type": "string", "required": true },
    { "key": "source", "type": "string", "required": false }
  ],
  "destination": {
    "url": "https://example.com/api/leads",
    "headers": { "authorization": "Bearer secret" }
  },
  "allowlist": {
    "emails": [],
    "domains": ["example.com"]
  }
}
```

The response includes an address like `lead-intake@in.mailtoapi.app`.

Return that generated inbox address to the operator.

## Payload

MailToAPI POSTs only extracted JSON:

```json
{
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "phone": "+1 555 0100",
  "message": "Please call me.",
  "source": "website"
}
```

Any destination `2xx` response consumes one credit. Non-`2xx` responses do not consume credits and can be manually replayed.

## Billing

`POST /api/v1/billing/checkout` accepts either:

```json
{ "kind": "subscription", "plan": "starter" }
```

or:

```json
{ "kind": "topup" }
```