# Message

> For the complete documentation index, see [llms.txt](https://effectkit.dev/llms.txt).

The EmailMessage schema, its address and attachment shapes, validation rules, and SendOptions.

Source: https://effectkit.dev/docs/emails/reference/message

`email.send` takes an `EmailMessage` and optional `SendOptions`. Messages are validated on every call, and unknown keys fail with `InvalidMessageError`.

## `EmailMessage` [#emailmessage]

| Field         | Type            | Rules                                            |
| ------------- | --------------- | ------------------------------------------------ |
| `from`        | `Address`       | Required.                                        |
| `to`          | `Recipients`    | Required.                                        |
| `cc`          | `Recipients`    | Optional.                                        |
| `bcc`         | `Recipients`    | Optional.                                        |
| `replyTo`     | `Recipients`    | Optional.                                        |
| `subject`     | `string`        | Required. Not blank, no control characters.      |
| `text`        | `string`        | Required if `html` is absent. Not blank, no NUL. |
| `html`        | `string`        | Required if `text` is absent. Not blank, no NUL. |
| `headers`     | `CustomHeaders` | Optional.                                        |
| `attachments` | `Attachment[]`  | Optional.                                        |

A message must have `text`, `html` or both. The bytes of attachments are copied when the message is accepted.

## `EmailAddress` [#emailaddress]

A bare ASCII address, up to 254 characters with a local part of up to 64. It has no control characters and no display name. `"Ada <ada@example.com>"` is not valid.

## `Mailbox` [#mailbox]

An object with an address and an optional display name.

| Field   | Type                | Description                                     |
| ------- | ------------------- | ----------------------------------------------- |
| `email` | `EmailAddress`      | The address.                                    |
| `name`  | `string` (optional) | Display name. Not blank, no control characters. |

## `Address` [#address]

An `EmailAddress` string or a `Mailbox`.

## `Recipients` [#recipients]

One `Address` or a non-empty array of them. An empty array fails when the message is decoded.

## `Attachment` [#attachment]

| Field         | Type                | Rules                                                                                           |
| ------------- | ------------------- | ----------------------------------------------------------------------------------------------- |
| `filename`    | `string`            | Not blank, no control characters.                                                               |
| `content`     | `Uint8Array`        | The bytes. Paths and URLs are never read.                                                       |
| `contentType` | `string`            | A `type/subtype` media type.                                                                    |
| `contentId`   | `string` (optional) | No whitespace or angle brackets. Marks the attachment as inline. Must be unique in the message. |

## `CustomHeaders` [#customheaders]

A record of header name to value.

- Names use only letters, digits and the characters ``! # $ % & ' * + . ^ _ ` | ~ -``, and are unique ignoring case.
- Values have no control characters.
- These names are reserved: `from`, `sender`, `to`, `cc`, `bcc`, `reply-to`, `subject`, `date`, `message-id`, `mime-version`, `return-path`, `received`, `authentication-results`, `dkim-signature`, `authorization`, `proxy-authorization`, `host`, `idempotency-key`, `x-smtpapi`.
- These prefixes are reserved: `content-`, `resent-`, `resend-`, `x-ses-`, `x-mc-`, `x-mailgun-`, `x-mailin-`, `x-pm-`.

## `SendOptions` [#sendoptions]

| Field            | Type                | Description                                                                                                 |
| ---------------- | ------------------- | ----------------------------------------------------------------------------------------------------------- |
| `idempotencyKey` | `string` (optional) | Not blank, no control characters. Supported by four providers. See [Idempotency](/docs/emails/idempotency). |

## `NormalizedEmailMessage` [#normalizedemailmessage]

The `EmailMessage` an adapter receives. `from` is a `Mailbox`, and `to`, `cc`, `bcc` and `replyTo` are arrays of `Mailbox`. `EmailTest` also records this type.

## `EmailRequest` [#emailrequest]

One entry of `Email.sendMany`: `{ message: EmailMessage, options?: SendOptions }`.

## `BatchOptions` [#batchoptions]

| Field         | Type                | Description                           |
| ------------- | ------------------- | ------------------------------------- |
| `concurrency` | `number` (optional) | An integer from 1 to 1000. Default 5. |

`Email.sendMany` takes up to 1,000 requests.