Quickstart

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 instead and start with 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 if you do not have an account yet. The whole thing takes a few minutes.

Before you startCopy Anchor Link

Install the OpenEmail CLI with Homebrew. If you do not have Homebrew yet, follow the instructions at brew.sh first.

brew install Open-Email/tap/openemail

Confirm the install and check your version:

openemail version

This guide is written for CLI v0.1.1.

1. Sign inCopy Anchor Link

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:

openemail whoami

2. Add your domainCopy Anchor Link

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.

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:

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:

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

openemail domains dns example.com

There is no SPF record to add, since the bounce CNAME handles it. See 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 mailboxCopy Anchor Link

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:

openemail mailboxes use <mailboxId>

4. Send it a real emailCopy Anchor Link

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 JSONCopy Anchor Link

openemail messages list --json

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

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 mailboxCopy Anchor Link

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.

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 stepsCopy Anchor Link

• 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.
• See every command. See the CLI reference.

Own your email. Program all of it.