Skip to content

API Keys

API keys authenticate your mobile app, AI agents, and other integrations with MailJawn's REST API and MCP server. Keys are scoped to your organization — any project within the organization can be accessed with the same key.

Creating a Key

  1. Go to Dashboard → API Keys
  2. Click Create API Key
  3. Give it a name (e.g., "Production SDK" or "Claude MCP")
  4. Choose a scope bundle (see below)
  5. Click Create

MailJawn generates a key that starts with mj_ and displays it exactly once. Copy it immediately — you won't be able to see it again.

Warning

Copy your key before closing the dialog. MailJawn stores a hash of the key, not the key itself. If you lose it, you'll need to create a new one.

Scope Bundles

When creating a key, choose the scope bundle that matches your use case:

Bundle Best For What It Can Do
SDK Mobile app integration Add subscribers and track events
MCP AI agent integration (Claude, etc.) Read/write subscribers, campaigns, sequences, assets, stats, and send emails
Full Access Administrative scripts, full API access Everything

Tip

Follow the principle of least privilege — choose the narrowest scope bundle that covers your needs. An SDK key that only needs to add subscribers doesn't need full access.

Individual Scopes

Each bundle includes a set of granular scopes. For the full list and what each scope permits, see REST API → Authentication.

Using Your Key

Include the API key in the Authorization header of your requests:

Authorization: Bearer mj_your_key_here

The key is validated by matching its prefix (first 8 characters) to find the record, then verifying the full key against the stored hash.

Rate Limits

API requests are rate-limited per key:

Operation Limit
Read (GET requests) 100 requests/minute
Write (POST/PUT/DELETE) 30 requests/minute
MCP 60 requests/minute
Email send 10 requests/minute

If you exceed a rate limit, you'll receive an HTTP 429 response. Wait and retry after the limit window resets.

Managing Keys

Viewing Keys

Your API keys list shows the key name, scope bundle, creation date, and last used timestamp. The key itself is not shown — only the mj_ prefix is visible for identification.

Revoking a Key

To revoke a key:

  1. Go to Dashboard → API Keys
  2. Click Revoke next to the key you want to disable

Revoking is immediate — any request using that key will start failing with a 401 error. Revoked keys are soft-deleted and kept for audit purposes.

Rotating a Key

There's no built-in rotation button. To rotate a key:

  1. Create a new key with the same scope bundle
  2. Update your app or integration to use the new key
  3. Verify the new key works
  4. Revoke the old key

Tip

You can have multiple active keys at once. This makes zero-downtime rotation easy — deploy the new key first, then revoke the old one after confirming everything works.

Multiple Keys

You can create as many keys as you need. Common patterns:

  • One key per environment — separate keys for development and production
  • One key per integration — a dedicated key for your iOS app, another for your MCP agent
  • One key per team member — each developer gets their own key (revoke individually when someone leaves)