# 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

You can create API keys in two ways:

- In the **API Keys** dashboard page.
- Using the [MailBlastr API](https://www.mailblastr.com/docs/api/api-keys-create).

To create a new API key from the MailBlastr dashboard:

1. **Open the API Keys page** — In your MailBlastr dashboard, navigate to the **API Keys** page.
2. **Click Create API Key** — Click the **Create API Key** button to open the creation modal.
3. **Name your key** — Choose a name (maximum 50 characters) to identify your key — for example `production-server` or `staging`.
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. This [permission](https://www.mailblastr.com/docs/api/api-keys-create) can be updated at any time.
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.

> **Warning:** 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. **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. **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**

```sh
MAILBLASTR_API_KEY=mb_xxxxxxxxx
```

> **Note:** 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.

> **Note:** 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**

```bash
curl -X POST 'https://api.mailblastr.com/emails' \
  -H "Authorization: Bearer $MAILBLASTR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <hello@yourdomain.com>",
    "to": ["delivered@example.com"],
    "subject": "Hello from MailBlastr",
    "html": "<p>It works!</p>"
  }'
```

**Node.js**

```js
import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr(process.env.MAILBLASTR_API_KEY);

const { data, error } = await mb.emails.send({
  from: 'Acme <hello@yourdomain.com>',
  to: ['delivered@example.com'],
  subject: 'Hello from MailBlastr',
  html: '<p>It works!</p>',
});
console.log({ data, error });
```

**Python**

```python
import os
import requests

res = requests.post(
    "https://api.mailblastr.com/emails",
    headers={"Authorization": f"Bearer {os.environ['MAILBLASTR_API_KEY']}"},
    json={
        "from": "Acme <hello@yourdomain.com>",
        "to": ["delivered@example.com"],
        "subject": "Hello from MailBlastr",
        "html": "<p>It works!</p>",
    },
)
print(res.json())
```

> **Warning:** Treat API keys like passwords. Never commit them or expose them in client-side code — always call the API from your server. See [Authentication](https://www.mailblastr.com/docs/authentication) for the full permission model.

## Next steps

- [Add a domain](https://www.mailblastr.com/docs/add-a-domain) you own and verify it to start sending.
- Send your first transactional email with the [Quickstart](https://www.mailblastr.com/docs/quickstart).
- Review the [Authentication](https://www.mailblastr.com/docs/authentication) permission levels and error codes.