Control Your Email Sending with Scoped Credentials


Managing email sending credentials is a critical part of maintaining security and control over your communication infrastructure. At AhaSend, we understand the importance of ensuring that only authorized sources can send emails using your account. That's why we offer Scoped Credentials, a powerful feature designed to give you granular control over your SMTP and API Key usage.

This feature allows you to bind specific credentials to specific sending domains within your account. This means you can create credentials that are only valid for sending emails from one or more designated domains, significantly enhancing your security posture and reducing the risk of unauthorized sending.

Global vs. Scoped Credentials

When you create credentials in AhaSend, you now have two options for their scope:

  • Global: This is the default setting. A Global credential (either SMTP or API Key) can be used to send emails from any valid, verified domain that exists within your AhaSend account. This is convenient if you have credentials used across multiple domains or for general account access.

  • Scoped to specific domains: This option allows you to select one or more specific domains from your account that this credential will be authorized to send from. If you attempt to use a Scoped credential to send an email from a domain not on its approved list, the sending request will be rejected.

The key difference lies in the level of restriction. Global credentials are wide-reaching, while Scoped credentials are tightly controlled, offering a layer of defense against potential misuse or errors.

How to Create Scoped Credentials

Creating a Scoped credential is a straightforward process within your AhaSend dashboard. It follows the same steps as creating any other credential, with one additional step to define the scope.

  1. Begin by logging into your AhaSend Dashboard.

  2. Once logged in, find and click on the Credentials section in your dashboard menu. This page lists all your existing SMTP and API Key credentials.

  3. Click on the + Add Credential button. This will open a form to configure your new credential.

  4. Configure Credential Details:

  5. Define the Scope: This is where you set up domain scoping. Locate the Scope field.

    • By default, it will be set to "Global".

    • Click on the field and select Scope to specific domains.

    • Once you select this option, a list of the domains verified in your AhaSend account will appear.

    • Select the checkbox next to each domain that this specific credential should be authorized to send emails from. You can select one or multiple domains.

      A screenshot of the AhaSend dashboard's "Add Credential" form. The form shows fields for Credential Type, Name, and Scope. The "Scope" field is expanded, showing the options "Global" and "Scope to specific domains". "Scope to specific domains" is selected, and a list of domains with checkboxes appears below it, allowing the user to select domains.

       

  6. Create the Credential: After selecting the desired domains, click the Create Credential button at the bottom of the form.

AhaSend will then generate your new Scoped credential. You will receive the username and password for SMTP or the API Key, depending on the type you chose. These credentials are now restricted to sending only from the domains you selected during creation.

You can also edit existing credentials to change them from Global to Scoped, or edit the list of authorized domains for the credentials.

Please note that it can take up to 1 minute for changes to SMTP credentials to propagate through all our servers and SMTP relays.

How Scoped Credentials Work

Once a credential is set as "Scoped" and linked to specific domains, AhaSend enforces this rule on every sending request made using that credential.

  • When an email is sent via SMTP using a Scoped credential, our system checks the MAIL FROM address against the list of domains allowed for that specific credential.

  • When an email is sent via the API using a Scoped API Key, our system checks the domain of the from.email address in the request payload against the list of domains allowed for that specific API Key.

If the domain in the sending request is not among the domains assigned to the Scoped credential, the request is denied, and the email will not be sent.

What Happens When Using an Unscoped Credential

Attempting to send an email using a Scoped credential from a domain that is outside its defined scope will result in an error. This immediate rejection is a key part of the security provided by this feature.

Here are the specific error messages you will receive depending on the sending method:

  • SMTP Relay Error: If you are sending via SMTP, the connection will be rejected with an authentication authorization error. You will see a message similar to this:

    authz_id 'YOUR_USERNAME' is not authorized to send as tenant 'YOUR_ACCOUNT_ID' or from this domain

    This clearly indicates that the username (your SMTP credential username) is not authorized to send from the domain specified in the email transaction for your account ('YOUR_ACCOUNT_ID').

  • API Error: If you are sending via the API, the API request will return an error response in JSON format:

    {
        "status": "API Key is not scoped for this domain"
    }

    This status message explicitly tells you that the API Key used in the request does not have permission to send from the domain specified in the from.email field of the payload.

These clear error messages help developers and administrators quickly identify when a credential is being used incorrectly based on its defined scope.

Benefits of Using Scoped Credentials

Implementing Scoped Credentials offers several significant advantages for your email sending operations:

  • Enhanced Security: This is the primary benefit. By limiting credentials to specific domains, you reduce the attack surface. If a credential is compromised, the potential damage is confined only to the domains it is scoped for, rather than allowing unauthorized sending from any domain in your account.

  • Improved Control: Scoped credentials give you finer control over which applications or teams can send emails from which domains. You can issue unique credentials for different services (e.g., one for your marketing platform sending from marketing.example.com, another for transactional emails from app.example.com), ensuring that each service uses only the credentials it needs for its designated domain.

  • Reduced Risk of Errors: Scoping helps prevent accidental sending from the wrong domain. For example, a developer working in a staging environment might accidentally configure their application to send from a production domain. If the staging credential is scoped only to staging domains, this mistake is caught immediately by AhaSend, preventing an unwanted email from being sent to real users from the wrong domain.

  • Easier Management: While it might seem like more credentials to manage, scoping actually simplifies management in larger or more complex setups. You know exactly which credential is tied to which domain(s), making it easier to revoke access for a specific domain or application without affecting others.

Scoped credentials are a valuable tool for any organization looking to tighten security and improve control over their email sending infrastructure. By taking a few extra moments during credential creation, you can add a significant layer of protection and clarity to your sending processes.

Implementing Scoped Credentials is a simple yet effective way to enhance the security and manageability of your email sending within AhaSend. Take advantage of this feature to ensure your SMTP and API keys are used exactly as intended, only from the domains you authorize.

Category
AhaSend
Send up to 1,000 emails per month on us, no credit card required!