> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/database/schema/field-types/email.md).

# Email

A string field with format email: the server accepts only a valid e-mail address.

An **Email** field is a [Text](/codemash/cloud/database/schema/field-types/text.md) field with `format: "email"`. The server refuses a value that is not an e-mail address; Cloud shows the field with an envelope icon.

**Builder:** Form fields panel → **Email** · widget `email` · data type `string.schema.v1`

## Data schema

```json
{
  "email": {
    "type": "string",
    "format": "email",
    "unique": true
  }
}
```

| Keyword                                                  | Required          | What it does                                                       | Example          |
| -------------------------------------------------------- | ----------------- | ------------------------------------------------------------------ | ---------------- |
| `type`                                                   | yes               | Always `"string"`.                                                 | `"string"`       |
| `format`                                                 | yes for this type | `"email"`.                                                         | `"email"`        |
| `minLength`, `maxLength`, `pattern`, `default`, `unique` | no                | As on [Text](/codemash/cloud/database/schema/field-types/text.md). | `"unique": true` |

### What the server refuses

Every write — insert, update, replace; from Cloud, the API, an SDK, the CLI or an AI agent — is checked against the published schema. A broken value is answered with one error per field: the code, and `Field '<name>' is invalid: <reason>`. Nothing is written.

| Case                                  | Code                     | The reason it gives     |
| ------------------------------------- | ------------------------ | ----------------------- |
| a required field is missing or `null` | `CM-ERRORS-DATABASE-030` | `a value is required`   |
| the value is not a string             | `CM-ERRORS-DATABASE-039` | `must be a string`      |
| not an e-mail address                 | `CM-ERRORS-DATABASE-042` | `must be a valid email` |

A keyword that is not in the table above is refused when the schema is **saved**, not when a record is written: `CM-ERRORS-SCHEMA-010` — `Data schema violates meta-schema: Property 'sort' has not been defined and the schema does not allow additional properties. Path 'properties.email.sort' (field 'properties.email' checked as string.schema.v1).`

## UI schema

The cell uses the `email` widget.

```json
{
  "colSpan": 4,
  "element": {
    "fieldId": "email",
    "meta": { "widget": "email", "label": "Email", "placeholder": "ada@example.com" }
  }
}
```

Every cell also takes the common layout options: `label`, `placeholder`, `help` (the text under the input), `required`, `readonly` and `hidden`. Keys outside this list — `watermark`, `hint`, `permissions` — are refused when the schema is saved (`CM-ERRORS-SCHEMA-012`), see [Schema authoring guide](/codemash/cloud/database/schema.md#one-contract-no-second-dialect).

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-ebf915cf71f4945a3c0d5bf9ef1529c892da44f4%2Ffield-types-text-1.png?alt=media" alt="The Text tab of the all-types record form with the field String format email shown as an input with an envelope icon"><figcaption><p>An email cell (String format email) on the Text tab.</p></figcaption></figure>

## Records

A record the schema accepts:

```json
{ "email": "ada@example.com" }
```

A record it refuses:

```json
{ "email": "not-an-address" }
```

The answer: `CM-ERRORS-DATABASE-042` — `Field 'email' is invalid: must be a valid email`. In Cloud the same sentence is shown under the field before the form is sent; the server repeats the check on every API write.

## Good to know

* The check is the address shape only; nothing is sent to the address.
* `unique: true` is the usual choice for an e-mail — one record per address in the environment.

## Do it from code

```ts
await norbix.api.database.insertOne({
  collectionName: 'contacts',
  document: JSON.stringify({ email: 'ada@example.com' }),
});
```

```sh
norbix api database one insert --collectionName contacts --document '{"email":"ada@example.com"}'
```

The client setup is on the [Database page](/codemash/cloud/database.md#use-it-from-code). API: [Insert One](/codemash/api-reference/database/collections/insert-one.md) · [Save Database Schema](/codemash/api-reference/database/schemas/save-database-schema.md)

## Related

[Text](/codemash/cloud/database/schema/field-types/text.md) · [URI](/codemash/cloud/database/schema/field-types/uri.md) · [Field type reference](/codemash/cloud/database/schema/field-types.md) · [Schema authoring guide](/codemash/cloud/database/schema.md) · [Create a schema](/codemash/cloud/database/collections/create-schema.md)