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

1. In Settings > API keys, click +Add.
2. The New API key window will open. In the User drop-down, choose the account user the key will be assigned to.
3. Click Create API key.

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

5. Click Close.

The new key will appear in the list. For each key you will see the user it is assigned to, the first characters of the key (so you can identify it), the creation date 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. 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.

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. From that moment on, any system still using that key will lose access to your account.

The last used column helps you spot keys that are no longer in use and can be safely deleted.

How to check that the key works

To verify that the key is valid, you can send a test request to the /ping endpoint. The key is sent in the X-AUTH-TOKEN header. If everything is correct, the API will respond with HTTP status code 204.

curl -X GET --header 'X-AUTH-TOKEN: YOUR-API-KEY' 'https://YOUR-ACCOUNT.ipzmarketing.com/api/v1/ping'

Replace YOUR-API-KEY with the key you created and YOUR-ACCOUNT.ipzmarketing.com with your Mailrelay account domain, which is the one shown in your browser's address bar when you log in to your dashboard.

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.

You will find all available endpoints, with their parameters and examples, in the API documentation. You may also be interested in these articles:

• SMS using our API
• Event subscription
• What are transactional emails? SMTP and API options

API usage limits

The API has request limits that apply per account:

• Sending emails, SMS and WhatsApp messages: 1,000 requests per minute.
• All other operations: 250 requests every 5 minutes.

If the limit is exceeded, the API will return a 429 error until the period ends. The Retry-After header tells you how many seconds to wait, and the X-RateLimit-Remaining header shows how many requests you have left before reaching the limit.

Security best practices

An API key gives full 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.
• 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.

Can I have several API keys?

Yes. You can create several keys and assign each one to a different account user.

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.