Credentials
Create and manage SMTP credentials to authenticate email sending through your unMTA cluster.
Overview
SMTP credentials authenticate applications and services when sending email through your unMTA cluster. Each credential consists of a username and password that your application uses to connect to the SMTP server.
Credentials provide two key security features:
- Domain restrictions — Limit which sending domains a credential can use
- IP restrictions — Limit which IP addresses can connect using the credential
These restrictions help you follow the principle of least privilege. A web application server might only need to send from notifications.example.com, while a marketing platform might need access to all your domains.
Each credential belongs to a single cluster and can be configured with any combination of domain and IP restrictions.
Domain Restrictions
By default, new credentials are restricted to specific domains. You must explicitly select which domains the credential can send from.
| Setting | Behavior |
|---|---|
| All domains | Credential can send from any domain in the cluster |
| Specific domains | Credential can only send from the selected domains |
When you add a new domain to your cluster, credentials set to "All domains" will automatically gain access to it. Credentials restricted to specific domains will not.
IP Restrictions
IP restrictions control which source IP addresses can authenticate using a credential. By default, credentials allow connections from any IP address.
| Setting | Behavior |
|---|---|
| All IPs | Accept connections from any IP address (default) |
| Specific IPs | Only accept connections from the listed IP addresses |
Supported IP Formats
When specifying allowed IPs, you can use:
- IPv4 addresses:
192.0.2.1 - IPv4 CIDR ranges:
198.51.100.0/24 - IPv6 addresses:
2001:db8::1 - IPv6 CIDR ranges:
2001:db8::/32
CIDR notation lets you allow entire subnets with a single entry. For example, 203.0.113.0/24 allows any IP from 203.0.113.0 to 203.0.113.255.
Creating a Credential
- Navigate to the Credentials page from the sidebar
- Click the Add credentials button
- Enter a username for the credential
- Configure domain restrictions:
- Check All domains to allow sending from any domain, or
- Leave unchecked and select specific domains from the list
- Configure IP restrictions:
- Leave All IPs checked to allow connections from anywhere, or
- Uncheck and enter specific IP addresses or CIDR ranges
- Click Save
Username Requirements
- Maximum 255 characters
- Allowed characters: letters, numbers, and
+ = , . @ _ - - Must be unique within the cluster
Password Generation
When you create a credential, the system automatically generates a secure 32-character password. This password is displayed only once—immediately after creation.
Copy the password immediately and store it securely. The password cannot be retrieved later. If you lose it, you'll need to delete the credential and create a new one.
Using Credentials
Credentials authenticate your application when sending email through unMTA. You can connect via SMTP or HTTPS—use whichever fits your application best.
To find your cluster's endpoint hostname and available ports, see Clusters.
SMTP Connection
| Setting | Value |
|---|---|
| Host | Your cluster's SMTP endpoint |
| Port | 25, 587, or 2587 |
| Username | The credential username you created |
| Password | The generated password |
| Encryption | STARTTLS required on all ports |
HTTPS Connection
| Setting | Value |
|---|---|
| Endpoint | Your cluster's HTTPS endpoint |
| Port | 443 |
| Authentication | HTTP Basic Auth with credential username and password |
For complete details on message formats and sending options, see Sending Messages.
Managing Credentials
Viewing Credentials
The Credentials page displays all credentials for your current cluster, showing:
- Username
- Permission summary (e.g., "All domains, all IPs" or "2 domains, 3 IPs")
- Creation date
Editing a Credential
To modify a credential's restrictions:
- Click the credential's username in the table, or click the menu and select Edit
- Update the domain and/or IP restrictions
- Click Save
You cannot change a credential's username or regenerate its password. To change either, delete the credential and create a new one.
Deleting a Credential
To delete a credential:
- Click the menu button next to the credential
- Select Delete credential
- Type the credential username to confirm
- Click Delete
Deleting a credential is immediate and irreversible. Any applications using this credential will no longer be able to send email.
Security Best Practices
Use Specific Domain Restrictions
Instead of granting "All domains" access, restrict each credential to only the domains it needs. This limits the impact if a credential is compromised.
Restrict by IP When Possible
If your sending application has a static IP address or uses a known IP range, configure IP restrictions. This adds an extra layer of security—even if the credential is leaked, it can't be used from unauthorized locations.
Use Separate Credentials for Each Application
Create a dedicated credential for each application or service that sends email. This allows you to:
- Track which application sent specific emails
- Revoke access for a single application without affecting others
- Apply appropriate restrictions for each use case
Rotate Credentials Periodically
Consider deleting and recreating credentials periodically, especially for sensitive applications. Since you can't regenerate a password, rotation requires creating a new credential and updating your application configuration.
API Reference
For programmatic credential management, see the Credentials API documentation.