Mailgi

xyz.mailgiPublished by mailgi.xyzOfficial publisherv1.0.0Updated Nov 1, 2026

Email for AI agents: register a real inbox with no human, then send, receive and read mail.

VerifiedStreamable HTTPWeb executableCommunication & CollaborationBusiness & Commerce

Overview

AI-generated overview

Mailgi gives an AI agent its own real email address, letting it send, receive, read and organize mail over a hosted API.

What you can do
  • Register an agent and manage its API keys, profile and usage counters
  • List, read, send, move, flag and trash messages, and create or rename folders
  • Check the wallet balance, ledger and top-up payment links
  • Register webhook endpoints for incoming mail, review deliveries and resend them
  • Sign in to the dashboard by emailed code and manage organizations, members and roles
When to use it
Useful when an assistant needs a genuine deliverable inbox rather than a mock: signing up for services, receiving verification mail, sending notifications, or triaging incoming messages with webhooks.
Requirements
Remote streamable HTTP endpoint at api.mailgi.xyz; no local install needed. Agent tools need an Authorization bearer API key, which register_agent issues. Organization tools need an X-Mailgi-Session token obtained via org_login_request_code and org_login_verify. Outbound mail to outside addresses is billed to a wallet.
Before you install
API keys, webhook signing secrets and session tokens are shown only once, so store them safely. Sending mail to outside addresses costs money and top-ups are paid by card through a link handed to a human. Several tools are destructive or irreversible: agent_delete wipes the agent, mailbox and keys, and folder, message and webhook deletions change stored data. Mail content and addresses pass through a third-party service.

Installation

In SourceWeft

  1. Open Mailgi in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/xyz.mailgi%2Fmailgi/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "mailgi": {
      "type": "http",
      "url": "https://api.mailgi.xyz/mcp"
    }
  }
}

README

Mailgi

Email for AI agents. Every agent gets a real, deliverable mailbox and uses it entirely over REST — no SMTP or IMAP client required.

This repository

PathWhatStatus
packages/typescriptTypeScript SDK + mailgi CLI — npm @mailgi/mailgipublished
packages/pythonPython SDK — PyPI mailgiplanned
apps/uiReact developer UI for inspecting mailboxesdev tool
specopenapi.json — the contract every SDK targets—

The API and mail infrastructure live in a separate private repository.

Quick start

bash
npm install -g @mailgi/mailgi
mailgi register --label my-agent          # saves to ~/.mailgi/config.jsonmailgi send --agent <handle> --to [email protected] --subject Hi --body Hellomailgi inbox --agent <handle>

Or from code:

ts
import { AgentMailboxClient } from "@mailgi/mailgi";
const client = AgentMailboxClient.withApiKey("https://api.mailgi.xyz", process.env.MAILGI_API_KEY!);await client.sendMail({ to: ["[email protected]"], subject: "Hi", textBody: "Hello" });

Working on this repo

bash
npm install                      # installs all workspacesnpm run build                    # builds every packagenpm test                         # runs every package's testsnpm run dev -w @mailgi/ui        # developer UI on :5173

Workspaces are listed explicitly in the root package.json rather than globbed, so non-Node packages such as packages/python can sit alongside them without confusing npm.

Release tags are namespaced per package — ts-sdk-v0.2.0, py-sdk-v0.1.0 — because the SDKs version independently.

License

MIT

Source: README.md at commit fcb0912

Tools

67

register_agent

Register an agent

Creates a new agent with its own email address and returns its API key, shown once.

ParametersdidlabellocalPartdomainToken

org_login_request_code

Request dashboard login code

Emails a 6-digit dashboard login code to a human's address. Creates the account on first login.

Parametersemailrequired

org_login_verify

Verify dashboard login code

Exchanges an emailed login code for a dashboard session token.

Parameterscoderequiredemailrequired

topup_lookup

Look up a top-up

Shows which wallet a top-up for a Mailgi address would credit, and the allowed amounts.

Parametersaddressrequired

topup_start

Start a top-up

Creates a card payment link for the wallet behind any Mailgi address. Give it to a human to pay.

ParametersaddressrequiredamountUsdrequired

topup_status

Check a top-up

Returns whether a top-up payment has been paid and credited.

ParameterssessionIdrequired

health

Service health

Checks that the Mailgi API, its database and the mail server are up.

Takes no parameters.

agent_get

Get agent profile

Returns this agent's profile: its addresses, label and domain.

Takes no parameters.

agent_usage

Get agent usage

Returns this agent's daily send and API counters; the latest day is partial.

Parameterstofrom

agent_delete

Delete agent

Permanently deletes this agent, its mailbox and all its API keys.

Takes no parameters.

mail_list

List messages

Lists message headers in the mailbox, newest first by default; filter by folder with mailboxId.

ParameterssortlimitpositionmailboxId

mail_get

Read a message

Returns one message with its full text and HTML body.

Parametersidrequired

mail_send

Send email

Sends an email from this agent's address. Mail to outside addresses is charged to the wallet.

ParameterscctorequiredbccreplyTosubjectrequiredhtmlBodytextBody

mail_delete

Move message to Trash

Moves a message to the Trash folder.

Parametersidrequired

mail_move

Move message

Moves a message to another folder.

ParametersidrequiredmailboxIdrequired

mail_set_flags

Set message flags

Marks a message as seen or unseen, flagged or unflagged.

Parametersidrequiredseenflagged

mailbox_list

List folders

Lists all folders, including Inbox, Sent and Trash.

Takes no parameters.

mailbox_create

Create folder

Creates a folder, optionally nested under another.

ParametersnamerequiredparentId

mailbox_rename

Rename folder

Renames a folder.

Parametersidrequirednamerequired

mailbox_delete

Delete folder

Deletes a custom folder.

Parametersidrequired

apikey_list

List API keys

Lists this agent's API keys. Key values are never shown again.

Takes no parameters.

apikey_create

Create API key

Creates another API key for this agent. The key is shown once.

ParameterslabelexpiresAt

apikey_revoke

Revoke API key

Revokes an API key immediately.

ParameterskeyIdrequired

billing_get

Get wallet

Returns the wallet this agent spends from: balance, prices and how to top up.

Takes no parameters.

billing_topup

Create top-up link

Creates a card payment link for this agent's wallet. Give it to a human to pay.

ParametersamountUsdrequired

billing_transactions

List wallet transactions

Lists the wallet ledger, newest first.

Parameterslimitoffset

webhook_list

List webhooks

Lists this agent's webhook endpoints.

Takes no parameters.

webhook_create

Create webhook

Registers an HTTPS URL to be notified when mail arrives. The signing secret is shown once.

ParametersurlrequiredeventTypes

webhook_delete

Delete webhook

Deletes a webhook endpoint.

Parametersidrequired

webhook_deliveries

List webhook deliveries

Lists recent delivery attempts for a webhook endpoint.

Parametersidrequired

webhook_resend

Resend webhook delivery

Queues a delivery attempt to be sent again.

ParametersidrequireddeliveryIdrequired

webhook_enable

Re-enable webhook

Re-enables a webhook endpoint that was switched off after repeated failures.

Parametersidrequired

org_me

Who am I

Returns the signed-in user and the organizations they belong to.

Takes no parameters.

org_logout

Sign out

Revokes the current dashboard session token.

Takes no parameters.

org_list

List organizations

Lists the organizations the signed-in user belongs to.

Takes no parameters.

org_create

Create organization

Creates an organization; the signed-in user becomes its owner.

Parametersnamerequiredslug

org_get

Get organization

Returns one organization.

ParametersorgIdrequired

org_rename

Rename organization

Renames an organization.

ParametersnamerequiredorgIdrequired

org_member_list

List members

Lists an organization's members and their roles.

ParametersorgIdrequired

org_member_set_role

Change member role

Changes a member's role.

ParametersrolerequiredorgIdrequireduserIdrequired

org_member_remove

Remove member

Removes a member from the organization, or leaves it when userId is your own.

ParametersorgIdrequireduserIdrequired

org_invite_create

Invite member

Emails an invitation to join the organization.

ParametersroleemailrequiredorgIdrequired

org_invite_list

List invites

Lists pending invitations.

ParametersorgIdrequired

org_invite_revoke

Revoke invite

Revokes a pending invitation.

ParametersorgIdrequiredinviteIdrequired

invite_accept

Accept invite

Accepts an organization invitation with the token from the invite email.

Parameterstokenrequired

domain_attach

Attach domain

Attaches a custom domain and returns the DNS records to publish.

ParametersorgIdrequireddomainrequired

domain_list

List domains

Lists an organization's custom domains.

ParametersorgIdrequired

domain_get

Get domain

Returns a domain's verification status and the DNS records it needs.

ParametersorgIdrequireddomainIdrequired

domain_verify

Verify domain

Re-checks the domain's DNS records and verifies it if they are correct.

ParametersorgIdrequireddomainIdrequired

domain_detach

Detach domain

Detaches a custom domain from the organization.

ParametersorgIdrequireddomainIdrequired

domain_inbox_list

List inboxes

Lists the inboxes (agents) on a domain.

ParametersorgIdrequireddomainIdrequired

domain_inbox_create

Create inbox

Creates an inbox with a chosen address on a domain. Its API key is shown once.

ParameterslabelorgIdrequireddomainIdrequiredlocalPartrequired

domain_inbox_delete

Delete inbox

Removes an inbox and its mail from a domain.

ParametersorgIdrequiredagentIdrequireddomainIdrequired

regtoken_create

Create registration token

Creates a token that lets an agent register its own address on this domain. Shown once.

ParameterslabelorgIdrequireddomainIdrequired

regtoken_list

List registration tokens

Lists a domain's registration tokens.

ParametersorgIdrequireddomainIdrequired

regtoken_revoke

Revoke registration token

Revokes a registration token.

ParametersorgIdrequiredtokenIdrequireddomainIdrequired

org_usage

Get organization usage

Returns daily send, receive and API counters across the organization.

ParameterstofromorgIdrequiredbreakdown

domain_usage

Get domain usage

Returns daily send, receive and API counters for one domain.

ParameterstofromorgIdrequireddomainIdrequiredbreakdown

org_billing_get

Get organization wallet

Returns the organization's shared wallet: balance, prices and how to top up.

ParametersorgIdrequired

org_billing_topup

Create organization top-up link

Creates a card payment link for the organization wallet.

ParametersorgIdrequiredamountUsdrequired

org_billing_transactions

List organization transactions

Lists the organization wallet ledger, newest first.

ParameterslimitorgIdrequiredoffset

org_webhook_list

List organization webhooks

Lists webhook endpoints across the organization's inboxes.

ParametersorgIdrequired

org_webhook_create

Create organization webhook

Registers an HTTPS URL to be notified when mail arrives at one of the organization's inboxes.

ParametersurlrequiredorgIdrequiredagentIdrequiredeventTypes

org_webhook_delete

Delete organization webhook

Deletes a webhook endpoint.

ParametersidrequiredorgIdrequired

org_webhook_deliveries

List organization webhook deliveries

Lists recent delivery attempts for a webhook endpoint.

ParametersidrequiredorgIdrequired

org_webhook_resend

Resend organization webhook delivery

Queues a delivery attempt to be sent again.

ParametersidrequiredorgIdrequireddeliveryIdrequired

org_webhook_enable

Re-enable organization webhook

Re-enables a webhook endpoint that was switched off after repeated failures.

ParametersidrequiredorgIdrequired

Version history

1
  1. v1.0.0LatestNov 1, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts