API keys: how to create and manage them
An API key is a unique code that lets another application (your website, your CRM, your online store or your own software) connect to your Mailrelay account without using your username and password. With it, those systems can add subscribers, send transactional emails or check statistics automatically.
You will need an API key if you are going to integrate Mailrelay with another tool, if you use a plugin or connector that asks for one, or if your development team is going to work with the Mailrelay API. API keys are available on all accounts, including the free account.
Where to find your API keys
In your Mailrelay account, go to Settings > API keys. In this section you can see your existing keys, create new ones, edit them and delete the ones you no longer need.
At the top of the page you will also find a link to the API documentation, which includes code examples to make your development team's work easier.
How to create an API key step by step
- In Settings > API keys, click +Add.
- The New API key page will open. In Name, enter a name that helps you identify the key, for example "CRM" or "Website integration". This field is required.
- In the User drop-down, choose the account user the key will be assigned to.
- In Expiration, choose when the key will stop working: 7 days, 14 days, 1 month, 3 months, 6 months, 1 year, No expiration or Custom. Below the field you will see the date it expires. If you choose Custom, a field appears where you pick the date and time the key stops working.
- In Allowed IP addresses, you can specify which addresses the key can be used from: an IPv4 or IPv6 address, or a CIDR range. +Add more adds another field for one more address, and Add my IP fills it in with the IP address you are currently connected from. If you leave the field empty, requests are allowed from any IP.
- In Permissions, choose what the key can do:
- Full access: everything its user can do, including areas added to the API later.
- Restricted (recommended): you choose the access for each area: Contacts, Email campaigns, Transactional email, SMS, Transactional SMS, WhatsApp, Transactional WhatsApp, Ecommerce, Media library and Webhooks. Every area starts with no access. Below each area you can see what it includes, and in its drop-down you choose the level, for example Read or Read and write.
- Click Create API key.
- The API key created window will open with your new key. Copy it with the button next to it and keep it in a safe place. For security reasons, the full key is only displayed this once: after you close the window, you won't be able to see it again.
- Click Close.
The new key will appear in the list. For each key you will see its name, the user it is assigned to, the first characters of the key (so you can identify it), its status, the expiration date and time, the allowed IP addresses and the date it was last used.
Why each key is assigned to a user
Every action performed with an API key is logged under the user the key is assigned to. In addition, the key can only do what both its permissions and its user allow: even if you choose Full access, it can never do more than that user's role allows.
That is why we recommend creating a specific user for each integration (for example, "Website integration" or "CRM"). This way you will know which system made each change and you can manage each integration separately.
If you need to create that user, see How to add a user to the account and Users. To see how each user's permissions are defined, see Roles.
How to edit an API key
In the list in Settings > API keys, click the green edit button to the right of the key. The Edit API key page will open, with the same fields as when you created it: Name, User, Expiration, Allowed IP addresses and Permissions. Expiration also includes the Keep current expiration option. When you are done, click Update API key to save your changes.
How to delete an API key
If an integration is no longer in use or you think a key has been compromised, delete it from the list in Settings > API keys using the red trash button to the right of each key. You will be asked to confirm that you want to delete it. From that moment on, any system still using that key will lose access to your account.
How to check that the key works
The API documentation, "First request" section, explains how to send a first request to check that your key is valid.
What you can do with the Mailrelay API
With an API key you can automate, among other things:
- Adding, updating or unsubscribing subscribers, and managing their groups and tags.
- Sending transactional emails, SMS and WhatsApp messages.
- Creating and sending campaigns, and checking their statistics: opens, clicks and unsubscribes.
- Managing senders, custom fields and imports.
- Receiving automatic notifications when certain events happen in your account.
For example, you can connect your website or online store so that new contacts are added to your newsletter list automatically, without having to import them by hand before each bulk email send.
Sending transactional emails through the API requires the SMTP + API package. All other API endpoints remain available.
You will find all available endpoints, with their parameters and examples, in the API documentation. You may also be interested in these articles:
API usage limits
The API has request limits. The current values are in the API documentation, "Rate limiting" section.
Security best practices
An API key gives access to your account, so you should protect it just like a password:
- Don't share it by email or include it in your website's public code.
- Use a different key for each integration, assigned to its own user.
- If an integration doesn't need every area, choose Restricted in Permissions, which is the option the dashboard recommends, and give it access only to what it uses.
- Store your keys in a password manager or in your server's secure configuration.
- If you think a key has been compromised, create a new one, update your integrations and delete the old one.
- Review the list from time to time and delete the keys you no longer use.
Frequently asked questions
I've lost my API key. Can I recover it?
No. For security reasons, the full key is only displayed when it is created. Create a new key, update the integrations that used the old one and delete the old key from the list.
Can I use the API with the free account?
Yes. The API keys section is also available on the free account. To send transactional emails through the API you need the SMTP + API package.
Can I have several API keys?
Yes. You can create several keys and assign each one to a different account user.
Can I limit what an API key can do?
Yes. When you create or edit the key, choose Restricted in Permissions and give each area only the access it needs. You can also specify in Allowed IP addresses which addresses it can be used from.
Can I change the expiration of a key I've already created?
Yes. On the Edit API key page, choose a new option in Expiration, or leave Keep current expiration if you don't want to change it.
Where can I find my account domain?
It's the domain shown in your browser's address bar when you log in to your Mailrelay dashboard, for example yourcompany.ipzmarketing.com.