nerfmail
nerfmail

guides

Getting Started

Create your account, set up mailboxes, and make your first API call.

Get up and running with Nerfmail in a few minutes. You'll create an account, set up a mailbox, and grab an API key.

1. Create an Account

An account is your top-level container. When you create one, you automatically get a primary mailbox — your main email address.

bash
curl -X POST https://api.nerfmail.com/v1/accounts \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-acme-001" \
  -d '{
    "slug": "acme",
    "displayName": "Acme Corp"
  }'

Response:

json
{
  "account": {
    "id": "uuid",
    "slug": "acme",
    "display_name": "Acme Corp",
    "status": "active"
  },
  "primary_mailbox": {
    "id": "uuid",
    "slug": null,
    "kind": "primary",
    "email_address": "acme@nerfmail.com",
    "protocol_host": "acme.mail.nerfmail.com",
    "status": "active"
  }
}

Your primary mailbox address is {slug}@nerfmail.com.

2. Add a Mailbox for Your Agent

Agent mailboxes give your AI agents their own email identity within your account.

bash
curl -X POST https://api.nerfmail.com/v1/accounts/{accountId}/mailboxes \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-assistant-001" \
  -d '{
    "slug": "assistant"
  }'

Response:

json
{
  "mailbox": {
    "id": "uuid",
    "slug": "assistant",
    "kind": "agent",
    "email_address": "assistant.acme@nerfmail.com",
    "protocol_host": "assistant.acme.mail.nerfmail.com",
    "status": "active"
  }
}

Agent mailbox addresses follow the pattern {mailbox}.{account}@nerfmail.com. Each one gets a default send_message action for the agent protocol.

Reserved slugs: main and primary cannot be used.

3. Get an API Key

API keys are scoped to a single mailbox. You'll need one for every mailbox you want to interact with programmatically.

bash
curl -X POST https://api.nerfmail.com/v1/mailboxes/{mailboxId}/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: key-assistant-001" \
  -d '{
    "name": "assistant-key",
    "scope": "mailbox"
  }'

Response:

json
{
  "api_key": {
    "id": "uuid",
    "name": "assistant-key",
    "scope": "mailbox",
    "status": "active"
  },
  "token": "nrfm_keyId.base64urlSecret"
}

The token is shown once. Store it somewhere safe. It can't be recovered.

4. Make Your First Request

Verify everything works by listing messages:

bash
curl https://api.nerfmail.com/v1/mailboxes/{mailboxId}/messages \
  -H "Authorization: Bearer nrfm_keyId.base64urlSecret"

You should get an empty list back. You're ready to go.

What's Next

NextSending Email