Authentication
Securely authenticate your requests to the Emailable API.
Overview
Emailable uses API keys to allow access to our API. To get started, sign up for an account here.
Emailable expects the API key to be included in all API requests to the server as a URL parameter, or as POST data for POST endpoints.
Alternatively, you can use an HTTP Authorization header with your API key. In the header, specify the Bearer scheme followed by your API key. (e.g. "Authorization: Bearer YOUR_API_KEY").
Security
Emailable has two types of API Keys. Please use the proper API key for your application.
Private API Keys
This type of key is meant to be used on the server-side of your application. These keys should never be exposed because they are not protected.
Should a Private API key be compromised, you should immediately generate a new one by using the “roll key” function in the dashboard.
To enhance security, you can specify a list of trusted IP addresses for each Private API key. If specified, only requests originating from one of the IP addresses you have listed will be accepted.
Private API keys can be used to access any API endpoint.
Public API Keys
This type of key is meant to be used anywhere that the key will be exposed publicly. One example would be using the API in the JavaScript of a website to verify that user entered email addresses are valid.
To prevent abuse of your account, we require that you set up a list of trusted domains when you create a Public API key. All requests that are made using a Public API key will only work if they originate from a trusted domain. They will also be rate limited to 10 unique requests per day per user.
If you’ve configured a captcha provider for your API key, you will need to
send a captcha_response parameter with the request. This will be used to
validate the captcha with your captcha provider. If the captcha fails to
verify, the API will return a 403 status code.
Public API keys are limited to authenticating requests to the /verify
endpoint. Attempting to use a Public API key for any other endpoint will fail.
Testing
For either type of API key (Public or Private), a test key can be used instead
of a live key. When creating an API key, you will be asked whether you want to
create a test key or a live key. If you choose to create a test key, the key
you generate will begin with "test_" instead of "live_".
Any requests made with a test key will not use credits or perform real verifications. Instead, a simulated response will be returned. This is useful for testing whether your application is correctly making API calls without having to waste credits.
You can also use a test key with certain test email addresses to generate responses with specific attributes. This is documented in Emails.
Batches created with a test key will be automatically deleted after 24 hours.
Trusted IP address and trusted domain restrictions will still apply to test keys. Domain-based rate limits for Public API keys are not enforced for test keys.
OAuth Apps
If you’ve authenticated a user with an OAuth App, you should have an access
token for that user. You can use the access token to authenticate to the
Emailable API by sending an access_token parameter instead of an api_key
parameter. Alternatively, you can use an HTTP Authorization header with the
access token. In the header, specify the Bearer scheme followed by the access
token. (e.g. "Authorization: Bearer YOUR_ACCESS_TOKEN").
See OAuth for more information on OAuth endpoints, including instructions for obtaining an access token.