# Quickstart

Bring your own domain onto the platform, create a mailbox on it, send it a real email, and read that message back as JSON.

This quickstart is written for building against the API. Every step is a CLI
command, and it finishes with a message read back as JSON. If you are setting up
email for yourself or your team rather than writing code, use the
[app](/docs/app) instead and start with
[Add your domain](/docs/add-your-domain).

Add `--json` to any command below to see the exact payload the API returns.

You will need an OpenEmail account, a domain you own, and access to that
domain's DNS. Sign up at [app.open.email](https://app.open.email/signup) if you do not
have an account yet. The whole thing takes a few minutes.

## Before you start

Install the OpenEmail CLI with [Homebrew](https://brew.sh). If you do not have
Homebrew yet, follow the instructions at [brew.sh](https://brew.sh) first.

```bash
brew install Open-Email/tap/openemail
```

Confirm the install and check your version:

```bash
openemail version
```

This guide is written for CLI v0.1.1.

## 1. Sign in

```bash
openemail login
```

Paste your password and press enter to authenticate.

The CLI mints its own per-device key from the one you paste, stores it in your
OS keychain, and discards the pasted key. Nothing you run afterwards needs the
original.

Confirm it worked:

```bash
openemail whoami
```

## 2. Add your domain

A domain has to exist on the platform before anything can be built on it:
addresses on a domain we do not know about are refused. Adding one is a loop:
publish a DNS record, run the command again, and it tells you what is still
missing.

```bash
openemail domains create example.com
```

The first run refuses, because nothing proves the domain is yours yet, and
prints the record that will:

```
! example.com is not verified yet.
Publish this DNS record, then run the same command again:
```

Publish it at your registrar. The value carries your account's own verification
token, so the command is the only place you need to look it up.

Run the same command again once the record is live:

```bash
openemail domains create example.com
```

This time it confirms the domain is verified and lists what is left:

```
✓ Domain example.com is verified
Still to publish (re-run this command afterwards to activate sending):
```

Those remaining records are your MX, which starts mail arriving, plus the
bounce and DKIM records, which switch on sending:

| Type | Name | Value | |
| --- | --- | --- | --- |
| MX | `example.com` | `smtp.open.email` (priority 10) | Receiving |
| CNAME | `oe-bounce.example.com` | `oe-bounce.open.email` | Sending |
| CNAME | `oe1._domainkey.example.com` | `oe1.dkim.open.email` | Sending |
| CNAME | `oe2._domainkey.example.com` | `oe2.dkim.open.email` | Sending |

Publish them, then run `openemail domains create example.com` one more time to
activate sending. Check progress at any point with:

```bash
openemail domains dns example.com
```

There is no SPF record to add, since the bounce CNAME handles it. See
[Add your domain](/docs/add-your-domain) for why, for the DMARC record you
should publish alongside these, and for what each refusal means.

You can carry on to step 3 as soon as the domain is verified. Only step 6 needs
sending switched on.

## 3. Create a mailbox

```bash
openemail mailboxes create --address you@example.com --json
```

Use your own domain and pick whatever local part you like.

`--address` creates the mailbox and its route in a single atomic operation, so
the address starts receiving mail the moment your MX resolves. An address
already in use answers `409` with nothing created, so there is no half-built
mailbox to clean up.

Note the `mailboxId` in the response, then set it as your default so later
commands do not need `-m`:

```bash
openemail mailboxes use <mailboxId>
```

## 4. Send it a real email

Send a message to the address you just created. You can send from any email
address you already own, including Gmail, Outlook, or your work email.

If nothing arrives, your MX has most likely not propagated yet. Run
`openemail domains dns example.com`. It reports which records are live and what
it actually sees at each name, which is usually enough to spot a typo.

## 5. Read it back as JSON

```bash
openemail messages list --json
```

Take the message id from that list and fetch the decoded content, headers,
bodies, and attachment list:

```bash
openemail messages content <messageId> --json
```

That is an ordinary inbound email, fully parsed. The MIME handling, character
sets, and multipart nesting were resolved on the way in.

## 6. Send from your mailbox

This is the step that needs sending switched on: the bounce CNAME and both DKIM
CNAMEs live, and the domain claimed once more since you published them.

```bash
openemail send --from you@example.com --to your@personal.address --subject "Hello from OpenEmail" --text "Sent over HTTP." --save
```

`--save` writes a copy to the mailbox's Sent label. Check your personal inbox to
confirm it arrived. Because your domain is signing with DKIM and aligning SPF
through the bounce domain, it should land authenticated rather than in spam.

## Next steps

- **Watch live events.** `openemail watch` tails a mailbox's changes over a
  WebSocket as JSON lines, so you can react to mail instead of polling for it.
- **Open it in a real email client.** `openemail credentials` issues IMAP/SMTP
  credentials for Apple Mail, Thunderbird, or your phone. Same mailbox, same
  messages.
- **Route more addresses.** `openemail routes` binds one exact address to a
  destination. `openemail patterns` binds a whole glob like `team-*`.
- **Browse interactively.** See [Interactive console](/docs/cli#interactive-console).
- **See every command.** See the [CLI](/docs/cli) reference.

---

*Own your email. Program all of it.*