API Token Management

API tokens allow you to access the MailShield REST API programmatically. This guide covers how to create, manage, and secure your API tokens.

Creating a Token

1. Navigate to Settings > API Tokens
2. Click Create Token
3. Enter a descriptive name (e.g., "CI/CD Pipeline" or "Monitoring Script")
4. Optionally add a description
5. Configure security settings (see below)
6. Click Create

Important

The full token is only shown once when created. Copy it immediately and store it securely. You won't be able to see it again.

Token Security Settings

IP Allowlist

Restrict which IP addresses can use this token. Leave empty to allow any IP.

Examples:

• Single IP: 203.0.113.50
• Multiple IPs: 203.0.113.50, 203.0.113.51

TIP

Use IP allowlists for production tokens to add an extra layer of security.

Expiration Date

Set an optional expiration date for the token. After this date, the token will no longer work.

Recommended for:

• Temporary access for contractors
• Time-limited integrations
• Compliance requirements

Token Visibility

For security, tokens are stored as SHA-256 hashes. In the dashboard, you'll see:

• Token name and description
• Last 4 characters (e.g., ...a1b2)
• Creation date
• Last used timestamp and IP
• Expiration status

Managing Tokens

Viewing Token Activity

Click on a token to see recent API activity including:

• Request timestamps
• Endpoints accessed
• Response status codes
• IP addresses

Updating Settings

You can update a token's:

• Name and description
• IP allowlist
• Expiration date

The token value itself cannot be changed.

Revoking Tokens

To revoke a token:

1. Go to Settings > API Tokens
2. Find the token and click Revoke
3. Confirm the action

DANGER

Revoking a token is immediate and permanent. Any integrations using this token will stop working.

Best Practices

Use Descriptive Names

Name tokens after their purpose:

• GitHub Actions - Deploy
• Datadog Integration
• Weekly Report Script

Principle of Least Privilege

Create separate tokens for different integrations rather than sharing one token across multiple systems.

Regular Rotation

Periodically rotate tokens, especially for long-running integrations:

1. Create a new token
2. Update your integration
3. Verify it works
4. Revoke the old token

Monitor Usage

Regularly review the API Access Logs to:

• Detect unusual activity
• Identify unused tokens
• Verify integrations are working

API Access Logs

All API requests are logged with:

• Timestamp
• Token used (by name)
• Endpoint and method
• Request/response summary
• IP address
• Response status

Access logs are available in Settings > API Tokens > Access Logs.

Plan Requirements

API access requires a Pro plan or higher. Free and Starter plans do not include API access.

Plan	API Access
Free	No
Starter	No
Pro	Yes
Business	Yes
Enterprise	Yes