DocumentationAPI ReferenceKnowledge Base
Get started

Create an API key

Get started sending email by creating an API key to authenticate your MailBlastr requests.

What is an API key?

API keys are secret tokens used to authenticate your requests. They are unique to your account and should be kept confidential.

You must create at least one API key to use the MailBlastr platform through code — for example from your server, a script, or any HTTP client.

Create an API key

API keys are created on the API Keys page of the MailBlastr dashboard, and only there. An API key can never create, re-scope, or revoke another key — a key that calls POST /api-keys, PATCH /api-keys/:id, or DELETE /api-keys/:id is refused with 403 dashboard_only, no matter what permission it holds. This keeps a leaked sending key from quietly promoting itself into an administrative one.

This is a breaking change. If you previously scripted key creation, permission changes, or revocation against the API with a full-access key, those calls now return 403 dashboard_only and the steps must be done by a signed-in person in the dashboard. Reading your keys still works over the API: GET /api-keys returns key metadata (never the token).

To create a new API key from the MailBlastr dashboard:

  1. 1
    Open the API Keys page

    In your MailBlastr dashboard, navigate to the API Keys page.

  2. 2
    Click Create API Key

    Click the Create API Key button to open the creation modal.

  3. 3
    Name your key

    Choose a name (maximum 50 characters) to identify your key — for example production-server or staging.

  4. 4
    Select a permission

    Choose Sending access to grant access to only sending email, unless your key needs Full access to create, delete, get, and update any resource. You can change the permission later by editing the key on the same API Keys page — but only from the dashboard, never with an API key.

  5. 5
    (Optional) Restrict to a domain

    If you selected Sending access, you can further restrict the key to a single verified domain, so it can only send from addresses on that domain.

For security reasons, the full API key is shown only once, at creation. MailBlastr stores only a hash of the key afterward — copy it immediately and store it somewhere safe. If you lose it, revoke the key and create a new one.

Use the API key in your code

Authenticate your requests by adding your MailBlastr API key to your project as an environment variable, then sending it as a Bearer token on every request.

  1. 1
    Create and store an environment variable

    Store your API key as an environment variable rather than hardcoding it. For example, Node.js projects commonly keep secrets in a .env file at the project root.

  2. 2
    Pass the variable to your code

    Read the variable at runtime and send it in the Authorization header. Your environment variables are not automatically available to MailBlastr — you must pass the value explicitly on each request.

.env
MAILBLASTR_API_KEY=mb_xxxxxxxxx
If you store secrets in a project file, add that file to .gitignore to keep it out of version control. Many frameworks add .env to .gitignore by default, so this may already be done.
On Node.js v20 and later you can load a .env file into process.env with the built-in --env-file=.env flag (for example node --env-file=.env app.js). On earlier versions, use a loader such as the dotenv package.

Read the key from the environment and send it as a Bearer token:

curl -X POST 'https://www.mailblastr.com/api/emails' \
  -H "Authorization: Bearer $MAILBLASTR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <hello@yourdomain.com>",
    "to": ["delivered@mailblastr.dev"],
    "subject": "Hello from MailBlastr",
    "html": "<p>It works!</p>"
  }'
Treat API keys like passwords. Never commit them or expose them in client-side code — always call the API from your server. See Authentication for the full permission model.

Next steps