FAQ

Short answers to the things that come up before and during a first integration.

Is this a real email address?

Yes. you@carlyemail.com receives mail from Gmail, Outlook and anything else, and mail sent from it arrives with SPF, DKIM and DMARC passing. Not a webhook that looks like email, and not a relay through your own mailbox.

How is this different from just using Gmail's API?

Gmail's API lets an agent read and write your mailbox. That makes the agent an assistant looking over your shoulder.

CarlyEmail gives the agent its own address. People write to it, reply to it and add it to threads — a participant rather than a reader, and nothing it does touches your personal mail.

Do you run the agent?

No. CarlyEmail is the email layer, not the agent runtime. You keep the agent you already have — LangChain, the Claude Agent SDK, the OpenAI Agents SDK, your own loop — running wherever you run it, on your own model key, billed to you by whichever model provider you chose.

We do three things: receive the mail, send you a signed event, and send the reply. That is the whole of it. See add email to any agent.

What does it cost?

Free is $0 for 3 inboxes and 1,000 emails a month, no card — enough to build against and not enough to run on. Startup is $20 a month for 25 inboxes and 10,000 emails, Business $200 for 250 and 100,000. Every plan gets the whole API — the tiers differ in volume, not in features. See pricing.

Do I need my own domain?

No. Every account can send from carlyemail.com immediately. Bring your own domain when you want mail to come from your brand — see custom domains.

Can an agent create its own inbox?

Yes, with one unauthenticated call, so it can do this mid-conversation without a human present.

npx carlyemail signup

Why can't I send mail yet?

The owner email has not been confirmed. An unverified account can read, label and organise its own mail, and email one address: the owner it was signed up under.

Confirm the six-digit code and sending to anyone is enabled immediately.

npx carlyemail verify 123456

What happens when I hit a limit?

The request is refused with 429 and a code naming what ran out — inbox_limit_reached, daily_limit_reached, and so on.

GET /v0/organizations reports every count beside every limit, so you can check before you are refused. See plans and limits.

Storage is the exception: over your allowance, sending is refused and so is creating an inbox. Deleting messages frees the space back.

How do I stop my agent emailing the wrong people?

Three mechanisms, strongest last:

• Block lists — refuse specific addresses or whole domains at send time
• Drafts — the agent writes, a person approves. See the answer below
• Scoped keys — issue a key with draft_create but not message_send, and sending returns 403 however the agent reasons

Can an agent reach an inbox other than its own?

Not if you scope its key. A key pinned to one inbox cannot reach a sibling, and a resource belonging to another organisation returns 404, not 403.

How do I stop just anyone emailing my agent?

Subscribe to message.received and nothing else. Mail failing SPF, DKIM or DMARC arrives as message.received.unauthenticated, and spam as message.received.spam, so a forged sender never reaches your handler. That check is on the authentication verdict, which cannot be forged.

Then filter on the sender in your own code, where the rule can be anything you can express. Doing it in that order matters: From is a header anyone can write, so checking it only means something once the verdict check has run.

How do I know a webhook really came from you?

Every delivery carries an HMAC signature over the raw body, signed with the secret returned when the webhook was created. Verify it with a constant-time comparison before doing anything — without that check, anyone who guesses your URL can make your agent act. See verifying webhooks.

Do replies land in the right thread?

Yes. Replies are matched on In-Reply-To and References, falling back to subject matching when a client sends no chain. Reply to a message rather than composing a new one and we set the headers for you.

Is there an SDK?

TypeScript and Python.

npm install carlyemail
pip install carlyemail

See SDKs. For any other language, generate a client from the OpenAPI spec.

Can I connect this to Claude or ChatGPT directly?

Yes. There is an MCP server with 28 tools at https://api.carlyemail.com/mcp. No client id to configure — add it as a custom connector and it works. It serves the search and fetch pair the ChatGPT connector requires, so it installs there too.

Do you read my mail?

We store it. We do not sell it, share it for advertising, or train models on it. The privacy policy has the retention table.

How do I cancel?

From the console, or carlyemail billing. You drop to the free tier at the end of the period and keep every address and message.