# Email mailbox format

`email-mailbox-format` · version 1.0.0 · Communications · free, no key needed

Render a canonical RFC 5322 mailbox from decoded parts, without a delivery claim.

**Use when you need to: render canonical rfc 5322 mailbox · format mailbox from local part and domain · quote display name words for a mailbox.**

## Decide before calling

Read the [versioned contract](/v1/tools/email-mailbox-format/versions/1.0.0) and the supported scope below. Reuse `email-mailbox-format@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `email-mailbox-format@1.0.0` for render canonical rfc 5322 mailbox. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- render canonical rfc 5322 mailbox
- format mailbox from local part and domain
- quote display name words for a mailbox
- build name-addr from decoded parts
- render a domain literal mailbox
- write canonical addr-spec text
- הרכבת תיבת דואר תקנית

## Not supported

- parse a raw mailbox string
- fold a header line to 78 characters
- encode RFC 2047 display names
- send mail or check that the domain exists

## Behavior

- Inputs are already-decoded parts. local_part is quoted only when it is not a dot-atom. Each display word is an atom when it is 1*atext, otherwise one quoted-string. Words are joined by a single space. domain_form dot-atom (the default when omitted) writes a dot-atom; domain-literal writes [dtext] with no IP check.
- angles defaults to false and yields an addr-spec. angles true with no display words yields <addr-spec>. Display words require angles true. utf8 defaults to false; true allows RFC 6532 UTF-8 scalars and does not normalize or convert to A-labels.
- Omitted domain_form means dot-atom. Omitted display_words means no phrase. Case is preserved. This rendering is syntax only: no DNS lookup and no deliverability claim.

## Input

- `local_part` (string, required): min length 0; max length 64
- `domain` (string, required): min length 0; max length 190
- `domain_form` (one of "dot-atom", "domain-literal", optional)
- `display_words` (array of string, optional): max items 8; each min length 0; each max length 64
- `angles` (boolean, optional)
- `utf8` (boolean, optional)

## Output

- `mailbox` (string, required): min length 3; max length 1600
- `form` (one of "addr-spec", "name-addr", required)

## Limits

- max local part chars: 64
- max domain chars: 190
- max display words: 8
- max word chars: 64
- max output bytes: 2048

## Example

Request input:

```json
{
  "local_part": "john.q.public",
  "domain": "example.com",
  "display_words": [
    "Joe Q. Public"
  ],
  "angles": true
}
```

Response:

```json
{
  "result": {
    "mailbox": "\"Joe Q. Public\" <john.q.public@example.com>",
    "form": "name-addr"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "email-mailbox-format",
  "version": "1.0.0",
  "input": {
    "local_part": "john.q.public",
    "domain": "example.com",
    "display_words": [
      "Joe Q. Public"
    ],
    "angles": true
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/email-mailbox-format/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"local_part":"john.q.public","domain":"example.com","display_words":["Joe Q. Public"],"angles":true}'
```

The machine-readable contract is at [/v1/tools/email-mailbox-format/versions/1.0.0](/v1/tools/email-mailbox-format/versions/1.0.0).

### CLI

```sh
node cli.mjs run email-mailbox-format 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Email address list format](/tools/email-address-list-format): Format mailboxes and groups as one deterministic RFC 5322 address-list.
- [Email mailbox parse](/tools/email-mailbox-parse): Parse one RFC 5322 mailbox into parts and canonical text, without a delivery claim.
- [Email address list deduplicate](/tools/email-address-list-deduplicate): Drop duplicate mailboxes in an RFC 5322 address-list, keeping the first one.
- [Email address list parse](/tools/email-address-list-parse): Parse an RFC 5322 address-list into ordered mailboxes, groups, and a canonical form.
- [Email address list validate](/tools/email-address-list-validate): Check RFC 5322 address-list syntax, including dots, quotes, comments, and groups.
- [Email mailbox validate](/tools/email-mailbox-validate): Check one RFC 5322 mailbox for syntax only and return a stable reason code.