Skip to main content

​
What is an API key?

An API key is a unique token that authenticates your requests to the MailChannels Email API. It serves two purposes: proving who you are, and determining what you are allowed to do.

​
Authenticating a request

Every request to the Email API must include your API key. The examples below send a minimal email and demonstrate how the key is set. 
#!/usr/bin/env bash
set -u
: "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"
: "${FROM_EMAIL:?Set FROM_EMAIL (must be on a Domain-Lockdown-authorized domain)}"
: "${TO_EMAIL:?Set TO_EMAIL}"

curl -X POST https://api.mailchannels.net/tx/v1/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MAILCHANNELS_API_KEY" \
  -d @- <<JSON
{
  "personalizations": [
    { "to": [{ "email": "$TO_EMAIL", "name": "Recipient" }] }
  ],
  "from": {
    "email": "$FROM_EMAIL",
    "name": "Your Name"
  },
  "subject": "Hello from MailChannels",
  "content": [
    {
      "type": "text/plain",
      "value": "Hello! This is a plain-text email."
    }
  ]
}
JSON
Similar to a password, an API key grants access to your account. Store it securely and never commit it to source control or expose it in client-side code.

​
API key management

​
Creating an API key

Visit the API Keys page in the Console to create a key for your account.
  1. Click Create API Key.
  2. Add a descriptive label.
  3. Set the scope to Sending Email.
  4. Click Create API Key and copy the key. You won’t be able to see it again.
The full key is shown exactly once at the moment it is created. The redacted version is available via the Console and API, but never the original key. There is no way to recover a key.

​
Scope

Scope determines what an API key is allowed to do. Scope is assigned when the key is created in the Console and cannot be changed afterwards. The API currently supports the following scopes: Sending Email (api) and Managing Inbound Filtering (inbound). If you create a key with Sending Email, you can access every endpoint specified in the Email API reference. If you create a key with Managing Inbound Filtering, you have access to MailChannels Inbound Filtering. Inbound filtering blocks unwanted mail before it reaches your infrastructure. If you would like to learn more, view the Inbound Filtering documentation.

​
Deleting an API key

Delete an API key in the Console by clicking the Revoke button next to it. In the dialog that appears, click Revoke API Key to confirm. All subsequent requests that use the key will fail.

​
Sub-account key management

API keys for sub-accounts can be managed via the API. The parent account can create, list, and delete keys for each sub-account it owns.

​
Creating a key

#!/usr/bin/env bash
set -u
: "${PARENT_API_KEY:?Set PARENT_API_KEY before running}"
: "${SUB_ACCOUNT_HANDLE:?Set SUB_ACCOUNT_HANDLE (the sub-account to create a key for)}"

curl -X POST \
  "https://api.mailchannels.net/tx/v1/sub-account/$SUB_ACCOUNT_HANDLE/api-key" \
  -H "X-Api-Key: $PARENT_API_KEY"

​
Listing keys

#!/usr/bin/env bash
set -u
: "${PARENT_API_KEY:?Set PARENT_API_KEY before running}"
: "${SUB_ACCOUNT_HANDLE:?Set SUB_ACCOUNT_HANDLE (the sub-account whose keys you want to list)}"

curl "https://api.mailchannels.net/tx/v1/sub-account/$SUB_ACCOUNT_HANDLE/api-key" \
  -H "X-Api-Key: $PARENT_API_KEY"

​
Deleting a key

#!/usr/bin/env bash
set -u
: "${PARENT_API_KEY:?Set PARENT_API_KEY before running}"
: "${SUB_ACCOUNT_HANDLE:?Set SUB_ACCOUNT_HANDLE}"
: "${API_KEY_ID:?Set API_KEY_ID (the id of the key to delete)}"

curl -X DELETE \
  "https://api.mailchannels.net/tx/v1/sub-account/$SUB_ACCOUNT_HANDLE/api-key/$API_KEY_ID" \
  -H "X-Api-Key: $PARENT_API_KEY"

​
Key limits

Each account can have 100 API keys. Each sub-account can have 100 API keys. Sub-account keys do not count towards the parent account’s limit. Attempting to create another key past that limit returns an error. Delete an unused key before creating a new one.

​
Best practices

​
Storage

Use a secrets manager or environment variable to store your API key, rather than hard-coding it in source code. This reduces the risk of accidental exposure.

​
Rotation

Regularly rotate your API keys to minimize the impact of a potential compromise. To rotate a key, create a new one, update your applications to use it, and then revoke the old key.

​
One key per application

Use a unique API key for each application or service that integrates with the Email API. Then, if a key is compromised, you can revoke it without affecting other applications.