Developers

Email your code can create, read and answer.

Mailcycle is inbound email infrastructure with an HTTP API. Create an address, read what arrives, send from it. The console you sign in to is built on the same API you get.

Read the quickstart Create an account

JSON over HTTPS at api.mailcycle.email · Free tier, no card · API keys from Operator

First request

A bearer token and a URL.

Nothing to install, no SDK required, and the same base URL for every call.

API conventions

List your email addresses

curl https://api.mailcycle.email/inboxes \
  -H "Authorization: Bearer $MAILCYCLE_API_KEY"

What comes back

{
  "inboxes": [
    {
      "id": "ibx_3f9c2a…",
      "emailAddress": "signup-x7k2@example-pool.email",
      "label": "mca2:…"   // sealed on your device
    }
  ],
  "nextCursor": null
}

What the API does

The whole product, over HTTP.

Anything the Operator console can do can be done in code, because the console does it this way too.

Create email addresses

Mint an address on a shared domain or one you brought, label it, list them, and delete one to free its place on your plan. An address receives mail once it carries a public key derived from your recovery phrase.

Email address endpoints

Read the mail that arrives

List messages for one address or across every address a device holds, fetch bodies and attachments, mark read, star, and move between inbox, junk and trash. Content comes back sealed.

Reading mail

Send from your own addresses

Send and reply from an address the account owns. Signed in with the recovery phrase or from a paired device this works from Personal; from an API key or an agent it needs Scale. The copy kept in Sent is sealed to the address's key.

Sending mail

Pair and manage devices

Pair a phone, a browser or a headless runner, then list, rename, tag, disable and revoke it. A device holds a credential rather than an account, and can be removed on its own.

Pairing devices

Get the events

Webhooks POST your account's events to a URL you choose, signed with HMAC-SHA256 and retried. The same events reach connected code over a WebSocket. Webhooks, and the stream for API keys, are on Operator and above.

Webhooks and events

Authenticate a script

API keys on Operator and above, so a script does not run the recovery-phrase handshake. They have no expiry. Managing keys, devices, webhooks, sessions and the plan still needs a signed-in session.

Authentication

Sealed data

The API hands you ciphertext.

Incoming mail is sealed to the address's public key before it is stored, so the API has nothing else to return. Your code holds the key that opens it.

How the encryption works

TypeScript SDK

// npm install mailcycle-sdk
const mc = await Mailcycle.signIn({ phrase: process.env.MAILCYCLE_PHRASE })
const address = await mc.addresses.create({ prefix: "signup" })

// Waits for mail, then opens it here, not on our servers.
const message = await mc.messages.waitFor({ inboxId: address.id })
console.log(message.subject, message.text)

Message bodies, attachments, address labels and device names are all sealed. Because the server never holds the key, there is no server-side search: searching runs wherever the mail is opened.

SDKs

Your language, with the encryption done.

Each SDK signs in with the recovery phrase or an API key, creates addresses that receive mail, opens what arrives and sends. The phrase stays on your machine, and mail sealed by one opens in any other.

TypeScript

mailcycle-sdk on npm

npm install mailcycle-sdk

TypeScript email SDK Guide

Python

mailcycle on PyPI

pip install mailcycle

Python email SDK Guide

Go

mailcycle.email/go

go get mailcycle.email/go

Go email SDK Guide

Rust

mailcycle on crates.io

cargo add mailcycle

Rust email SDK Guide

Swift

mailcycle.email/swift/mailcycle.git

.package(url: "https://mailcycle.email/swift/mailcycle.git", from: "0.1.0")

Swift email SDK Guide

PHP

mailcycle/mailcycle from mailcycle.email/php

composer config repositories.mailcycle composer https://mailcycle.email/php
composer require mailcycle/mailcycle

PHP email SDK Guide

Java

email.mailcycle:mailcycle on Maven Central

implementation("email.mailcycle:mailcycle:0.3.0")

Java email SDK Guide

.NET

Mailcycle on NuGet

dotnet add package Mailcycle

.NET email SDK Guide

Ruby

mailcycle on RubyGems

gem install mailcycle

Ruby email SDK Guide

Compare every SDK

Webhooks and the event stream

Find out the moment mail lands.

Rather than polling, take the event. A webhook POSTs it to your URL, signed and retried; a WebSocket carries the same events to code that is already connected. Webhooks, and the stream for API keys, are on Operator and above.

Events carry ids, never content. To show a message, fetch it by id and open it in your client, exactly as you would otherwise.

The event stream

Every event a Mailcycle webhook or the event stream can carry
Event	When it fires
message.received	Mail arrives at an address
message.sent	Mail is sent from an address
inbox.created	An email address is created
inbox.deleted	An email address is deleted
inbox.assigned	An address is given to a device
inbox.removed	An address is taken off a device
worker.paired	A device or agent is added
worker.connected	A device reported gone is active again
worker.disconnected	A device has been quiet for two hours
worker.removed	A device is removed
subscription.updated	The plan changes, or a change is scheduled

Conventions

Predictable enough to write against once.

The things that decide how much of your integration you rewrite later.

Identifiers are prefixed and opaque: ibx_ for an email address, msg_ for a message, wkr_ for a device, evt_ for an event.
Errors carry a stable machine-readable code alongside the human message. Match on the code, never on the text.
Timestamps are ISO 8601 in UTC, and money is integer minor units, so 9900 is $99.00.
Lists page with ?limit= and a ?cursor= from the previous response. A null nextCursor means the end.
A record you do not own answers 404, the same as one that never existed.

Questions

Before you start building.

Yes, and it is what the product is built around. Create an address over the API, and mail sent to it is sealed and stored for you to fetch, or pushed to your webhook the moment it lands. There is no forwarding rule and no shared mailbox in the middle. See email addresses.

Because it is stored that way. Incoming mail is sealed to the address's public key before anything is written down, and the private half is derived from your recovery phrase on your own machine. Your client decrypts it, which each SDK does for you. The format is published, so a client in any language can be written against it. One consequence worth planning for: there is no server-side search.

Either. A session from the recovery-phrase handshake does everything, on every plan. API keys start at Operator and suit scripts, because a key is a bearer token with no expiry and no handshake to run. Some calls are session-only by design: managing keys, sessions and the plan, pairing, changing or removing devices, assigning addresses, and changing webhooks, so a key cannot mint access that outlives it. Those answer session_required.

No. Mailcycle is inbound email infrastructure, and sending is there to answer what arrives. Sending is capped at 60 messages an hour per account and 20 an hour per device or agent (more on Fleet and Enterprise), with a daily limit on top, and the acceptable use policy rules out bulk, marketing and outreach mail.

The call returns 429 with a Retry-After header in seconds and a code saying which limit it was. GET /usage reports how much of each quota the account has spent and when each counter starts again, so a job can check before it runs rather than after it fails.

TypeScript (mailcycle-sdk on npm), Python (mailcycle on PyPI), Go (mailcycle.email/go), Rust (mailcycleon crates.io), Swift (mailcycle.email/swift/mailcycle.git), PHP (mailcycle/mailcycle from mailcycle.email/php), Java (email.mailcycle:mailcycle on Maven Central), .NET (Mailcycle on NuGet) and Ruby (mailcycleon RubyGems). Each derives the keys from the recovery phrase on your machine, so it can create addresses that receive mail and open what arrives. For any other language, the encryption format is published, so a client can be written against it; the API is plain JSON over HTTPS and needs no SDK at all.

Yes, through MCP rather than raw HTTP. The mailcycle-mcp server runs on the agent's own machine and gives it tools to wait for, read and reply to mail, open attachments and send files, decrypted there. It is on Scale and above. See email for AI agents and the MCP server.

Give your code an address of its own.

Create an account, create an address, and read what arrives. The free tier needs no card.

Get started Read the docs

Email your code can create, read and answer.

A bearer token and a URL.

The whole product, over HTTP.

Create email addresses

Read the mail that arrives

Send from your own addresses

Pair and manage devices

Get the events

Authenticate a script

The API hands you ciphertext.

Your language, with the encryption done.

Find out the moment mail lands.

Predictable enough to write against once.

Before you start building.

Can I receive email programmatically with Mailcycle?

Why does message content come back encrypted?

Do I need an API key, or will the recovery phrase do?

Is this an API for sending bulk or marketing email?

What happens when I hit a rate limit?

Which languages have an SDK?

Can an AI agent use this?

Give your code an address of its own.