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 API key with api scope;
  2. A Domain Lockdown record in the DNS for each domain from which you plan to send email; and,
  3. An updated SPF record for each domain to authorize MailChannels to send email on your behalf.

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

1. 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.

2. 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

For more information on Domain Lockdown, see the Domain Lockdown Help Page.

3. Update your SPF record:​

For each domain you send email from, you must add MailChannels to your domain's SPF record to authorize MailChannels to send email on your behalf. Without this, recipient mail servers may reject or mark your messages as spam. Include MailChannels in your SPF record by adding include:relay.mailchannels.net to your existing SPF TXT record. For example:

example.com TXT "v=spf1 include:relay.mailchannels.net ~all"

If your domain already has an SPF record, add include:relay.mailchannels.net before the final all mechanism rather than creating a new record (a domain must not have more than one SPF record).

note

If your domain does not have either an A or MX record, MailChannels may block outgoing messages from that domain. Ensure at least one of these records is present in your DNS configuration.

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'