Skip to main content

Authentication Prerequisites​

After creating an account, you will need to set up three things before you can send email using MailChannels Email API:

  1. A valid SMTP password (note: this requirement will be removed soon);
  2. A valid API key with the correct scope; and,
  3. A Domain Lockdown record in the DNS for each domain from which you plan to send email.

To get started, sign into the MailChannels Console and navigate to Settings > Accounts.

1. Create an SMTP Password:​

Under SMTP Passwords, click New Password (found at the right side of the page) to create a new SMTP password. There must be at least one active SMTP password on your account to send mail using Email API, even though the password is not used in Email API requests.

2. Generate an API Key:​

Under API-Keys, click Create API Key to generate a new API key with the api scope. A dialog box will open asking you for an optional API key description that may help you to remember the purpose for which the key was created. Under the Scope drop-down, select api.

3. Set up Domain Lockdown records for each of your domains:​

Domain Lockdown is a unique DNS-based security feature from MailChannels that

  1. verifies that you have control of the domains from which you wish to send email; and,
  2. specifies which MailChannels accounts are authorized to send email on behalf of your domain.

To get started with Domain Lockdown, you'll need your unique MailChannels account ID, which can be found in the upper-right corner of the MailChannels Console next to the text Account ID.

For each domain you wish to send email from, you'll need to create a TXT record for the subdomain _mailchannels. This record contains fields specifying the accounts that are authorized to send email from your domain. For example, assuming your domain name is example.com and your MailChannels account id is examplecorp, the following Domain Lockdown record would permit your account to send email for email addresses at example.com:

_mailchannels.example.com TXT v=mc1 auth=examplecorp

Making requests using your API key​

After creating an SMTP password, API key, and Domain Lockdown record, you're now ready to send requests to Email API.

Every time you send an HTTP request to Email API, you must provide a valid API key in the X-Api-Key header of your HTTP request. The API key must have the api scope set as defined above.

The code snippets below illustrate how to set your API key when making requests. Replace YOUR-API-KEY with the key you created in the console:

-H 'X-Api-Key: YOUR-API-KEY'