Mailgentic

Quickstart: send your first email

Sixty seconds from signup to a delivered message. No DNS, no card, nothing to install.

1. Sign up

Create a free account with just an email and password. Verify the email, and the console drops you into a three-step wizard:

  1. Domain — the shared agents.mailgentic.ai domain is preselected. Keep it.
  2. Mailbox — name your first mailbox, e.g. agent → agent@agents.mailgentic.ai.
  3. Connect — copy the API key and the ready-to-run curl command.

A default workspace (tenant) is created for you behind the scenes. You can rename it later.

2. Send

The wizard’s curl is already filled in with your inbox id, key and your own address. It looks like this:

export MAILGENTIC_KEY="cfx_..."
export API="https://api.mailgentic.ai"
export INBOX_ID="..."

curl -X POST "$API/v1/inboxes/$INBOX_ID/messages" \
  -H "Authorization: Bearer $MAILGENTIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["you@yourcompany.com"],
    "subject": "Hello from Mailgentic",
    "text": "If you can read this, the pipe works."
  }'
{ "message_id": "0f3c…", "queued": 1, "held": 0, "suppressed": 0, "duplicate": false }

202 Accepted means the message is in the delivery queue. The From is always the inbox’s own address, so DKIM alignment is handled for you. Add an Idempotency-Key header to make retries safe; a repeat returns the original message_id with duplicate: true instead of sending twice.

Free-tier limits while you test

Until you upgrade, an account can send to its own verified address only (the one you signed up with), 50 messages a day, from the shared domain. That is enough to wire up an agent end to end; upgrading lifts all three limits instantly. Sending to anyone else returns 403 trial_recipient; sending from your own domain returns 403 trial_domain.

3. Watch it travel

curl "$API/v1/inboxes/$INBOX_ID/messages?folder=sent" -H "Authorization: Bearer $MAILGENTIC_KEY"
curl "$API/v1/events?message_id=$MESSAGE_ID"           -H "Authorization: Bearer $MAILGENTIC_KEY"

Events go accepted → delivered (or deferred / bounced). For push delivery, register a webhook or open a WebSocket on the inbox.

4. Reply to what comes back

Anything sent to agent@agents.mailgentic.ai lands in the same inbox, already screened by Agent Shield:

curl "$API/v1/inboxes/$INBOX_ID/messages?folder=inbox" -H "Authorization: Bearer $MAILGENTIC_KEY"

curl -X POST "$API/v1/inbox-messages/$MESSAGE_ID/reply" \
  -H "Authorization: Bearer $MAILGENTIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Thanks — on it."}'

The inbox quickstart goes deeper: threads, folders, policy, and giving each agent its own scoped key.

5. Or do it all from the API

Everything the wizard does is three calls with an account key (Console → API keys):

# your default workspace and the shared domain
curl "$API/v1/tenants" -H "Authorization: Bearer $MAILGENTIC_KEY"
curl "$API/v1/domains" -H "Authorization: Bearer $MAILGENTIC_KEY"     # shared domains are listed first

# a mailbox on it
curl -X POST "$API/v1/tenants/$TENANT_ID/inboxes" \
  -H "Authorization: Bearer $MAILGENTIC_KEY" -H "Content-Type: application/json" \
  -d '{"domain_id": "'$DOMAIN_ID'", "local_part": "agent"}'

# a key that can only touch that mailbox
curl -X POST "$API/v1/api-keys" \
  -H "Authorization: Bearer $MAILGENTIC_KEY" -H "Content-Type: application/json" \
  -d '{"name": "agent", "inbox_id": "'$INBOX_ID'", "scopes": ["read", "send"]}'

6. Sending from your own domain

On a paid plan you can register a domain, publish the DNS records the API hands back, and send as any address on it through the relay endpoint — with tags, metadata and per-recipient delivery records:

curl -X POST "$API/v1/messages" \
  -H "Authorization: Bearer $MAILGENTIC_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-user-1042" \
  -d '{
    "tenant_id": "'$TENANT_ID'",
    "from": "Acme <hello@mail.acme.com>",
    "to": ["user@example.com"],
    "subject": "Welcome to Acme",
    "text": "Thanks for signing up.",
    "tags": ["onboarding"],
    "metadata": {"user_id": "1042"}
  }'

Or over SMTP: create a tenant SMTP credential (POST /v1/tenants/$TENANT_ID/smtp-credentials) and point any mail library at smtp.mailgentic.ai:465. SMTP submissions go through exactly the same quotas, suppression list, DKIM signing and Guardian checks as the REST API, and produce the same events. Details in Domains and deliverability and SMTP and IMAP.

Next