# Link types

Source: https://developers.leonai.io/docs/guides/link-types/

A short link doesn't have to point at a web page. The `linkType` field lets one short
link resolve to an email, phone, or SMS action — the API composes the correct URI for
you from structured fields, so you never have to hand-encode a `mailto:` string.
Requires `links:write`. Available on **all tiers**.

| `linkType` | Destination         | Required fields | Optional fields   |
| ---------- | ------------------- | --------------- | ----------------- |
| `url`      | A web URL (default) | `longUrl`       | —                 |
| `mailto`   | An email compose    | `email`         | `subject`, `body` |
| `tel`      | A phone dial        | `phone`         | —                 |
| `sms`      | An SMS compose      | `phone`         | —                 |

When `linkType` is omitted it defaults to `url` and behaves exactly like a normal short
link.

## Create a mailto link

```bash
curl -X POST https://api.short.leonai.io/api/v1/links \
  -H "X-API-Key: $LEONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkType": "mailto",
    "email": "sales@example.com",
    "subject": "Demo request",
    "body": "Hi, I would like a demo."
  }'
```

Response (`201 Created`):

```json
{
  "success": true,
  "data": {
    "id": "link_...",
    "shortCode": "a1b2c3",
    "shortUrl": "https://short.leonai.io/a1b2c3",
    "linkType": "mailto",
    "longUrl": "mailto:sales@example.com?subject=Demo%20request&body=Hi%2C%20I%20would%20like%20a%20demo.",
    "clicks": 0,
    "createdAt": "2026-07-11T12:00:00.000Z"
  }
}
```

The API assembles and percent-encodes the final `mailto:` URI (shown in `longUrl`).

## Create a tel / sms link

```bash
curl -X POST https://api.short.leonai.io/api/v1/links \
  -H "X-API-Key: $LEONAI_API_KEY" -H "Content-Type: application/json" \
  -d '{ "linkType": "tel", "phone": "+15551234567" }'
```

Use `"linkType": "sms"` with the same `phone` field to compose an SMS instead. The
composed URI becomes `tel:+15551234567` (or `sms:+15551234567`).

## Error codes

| Status | When                                                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Missing the field required for the chosen `linkType` (e.g. `email` for `mailto`, `phone` for `tel`/`sms`), or a malformed email/phone |

## Related

- [Links](https://developers.leonai.io/docs/guides/links/) — all other link fields and operations
- [API Reference](https://developers.leonai.io/docs/api-reference/) — the full OpenAPI spec and Swagger UI