Authentication

MailShield API uses Bearer token authentication combined with optional IP allowlisting.

Creating an API Token

Organization owners and admins can create tokens:

1. Navigate to Settings > API in your MailShield dashboard
2. Click Create Token
3. Enter a descriptive name (e.g., "Production Monitoring")
4. Optionally set an expiration date
5. Optionally make the token read-only
6. Optionally add allowed IP addresses or CIDR ranges
7. Click Create Token

Important

Your API token will only be displayed once. Copy it immediately and store it securely.

Using Your Token

Include your token in the Authorization header of every request:

curl -H "Authorization: Bearer ms_your_token_here" \
  https://app.mailshield.app/api/v1/domains

Python Example

import requests

headers = {
    "Authorization": "Bearer ms_your_token_here"
}

response = requests.get(
    "https://app.mailshield.app/api/v1/domains",
    headers=headers
)

data = response.json()
print(data["data"])

Node.js Example

const response = await fetch('https://app.mailshield.app/api/v1/domains', {
  headers: {
    'Authorization': 'Bearer ms_your_token_here'
  }
});

const { data } = await response.json();
console.log(data);

Token Format

MailShield tokens follow this format:

• Prefix: ms_
• Body: 32 bytes of cryptographically random data (base64url encoded)
• Example: ms_Abc123XyzDefGhi456JklMnoP789QrsT

The ms_ prefix helps identify MailShield tokens and prevents accidentally using tokens from other services.

Read-only Tokens

A read-only token can only make GET requests. Anything else (POST, PATCH, DELETE) returns 403 Forbidden:

{
  "error": {
    "code": "forbidden",
    "message": "This token is read-only."
  }
}

Use read-only tokens for dashboards and reporting. The setting is chosen when the token is created and can't be changed afterwards.

IP Allowlisting

For enhanced security, you can restrict token usage to specific IP addresses:

• Single IP: 192.168.1.100 or 2001:db8::1
• CIDR range: 10.0.0.0/8 or 2001:db8::/32
• Multiple entries: One per line in the settings UI

Entries that aren't a valid IP address or CIDR range are rejected when you save. IPv6 entries match however the address is written (case and abbreviation don't matter), and an IPv4 entry also matches the same address in IPv4-mapped IPv6 form.

When an IP allowlist is configured:

• Requests from allowed IPs proceed normally
• Requests from other IPs receive a 403 Forbidden response that names the IP the request came from

Best Practice

For production integrations, always configure an IP allowlist to limit the blast radius if a token is compromised.

Token Expiration

Tokens can be configured to expire on a specific date:

• Never (default): the token remains valid until revoked
• Custom date: the token works until 23:59 UTC on that date

After expiration, the token returns 401 Unauthorized on all requests.

Revoking Tokens

To revoke a token:

1. Go to Settings > API
2. Find the token in the list
3. Click the revoke button
4. Confirm the action

Revoked tokens:

• Cannot be restored
• Return 401 Unauthorized on subsequent requests
• Keep their activity log (the last 100 requests from the past 30 days) and audit trail

Security Best Practices

1. Never commit tokens to version control: use environment variables
2. Use read-only tokens for anything that only reads data
3. Rotate tokens periodically: create new tokens and revoke old ones
4. Use IP allowlisting: restrict where tokens can be used from
5. Set expiration dates, especially for temporary integrations
6. Use descriptive names so you know which token is used where
7. Monitor usage: check "Last Used" and the token's activity to detect anomalies

Authentication Errors

Code	Status	Description
unauthorized	401	Missing or invalid Authorization header
unauthorized	401	Invalid, revoked or expired API token
forbidden	403	Request from an IP address outside the token's allowlist
forbidden	403	Read-only token used for a request other than GET
forbidden	403	The plan doesn't include API access (upgrade required)
forbidden	403	API access is paused because a payment is overdue