API Keys and the MailerLogic API
MailerLogic provides API keys that let your applications and connected tools access account data and perform supported actions. You can use the API to manage contacts, send emails, retrieve analytics, enroll contacts in automations, and manage webhooks.
This guide explains the difference between account API keys and integration API keys, how to generate and rotate keys, how to authenticate API requests, and how to troubleshoot common errors.
Understand the Two Types of API Keys
MailerLogic supports two types of API keys. Choose the type that matches your integration.
| Account API key | Integration API key | |
|---|---|---|
| Where to find it | Profile | Integrations → Apps |
| Purpose | Access the account API from your own backend | Connect third-party applications and automation tools |
| Permissions | Broad account-level access | Limited to the permissions you select |
| Key management | Rotate the account key to replace it | Manage or revoke the individual connection |
| Examples | Your application's backend | Zapier, Make, Pabbly, and other connected tools |
Which should you use?
Use an account API key when you control the application and its backend. Use a scoped integration API key when connecting a third-party application, so it receives only the permissions it needs.
Generate Your Account API Key
An account API key authenticates requests made by your application to MailerLogic.
Step 1: Generate the API key
Go to 'Profile', find the 'API' section, and click 'Generate'.
Copy the key immediately and save it in a secure secrets manager.
The full key is displayed only once. After that, MailerLogic shows only a short prefix so you can identify the active key.
ml_live_a1b2…, so you can identify the active key.If you lose the key, you cannot retrieve the original value. You must generate a replacement by rotating the account API key.
API keys are available on paid plans. If you're on the Free plan, follow the upgrade prompt to access this feature.
Rotate Your Account API Key
Rotating your account API key generates a new key and revokes the previous account API key. All systems using the old key must be updated.
Only the 'account owner' can rotate the account API key. Admins and other team members cannot perform this action.
Before rotating the key
Prepare every application and service that uses the existing key. This may include backend applications, scheduled jobs, deployment environments, and internal tools.
Step 2: Rotate the API Key
Click the 'Rotate API Key' button.
Step 3: Copy the New API Key
Copy the 'New API Key' and store it securely in your secrets manager or the application that uses it.
Create a Scoped Integration API Key
Integration API keys let you give third-party applications only the permissions they need.
Step 4: Connect an App
Go to 'Integrations' → 'Apps' and connect the application you want to use.
Step 5: Select API Scopes
Select the required permissions or 'Scopes' and 'Generate the API key'.
Choose the Required Permissions
Integration keys use scopes to determine which API operations an application can perform.
| Scope | Permission |
|---|---|
contacts:read | Read contacts |
contacts:write | Create and update contacts |
contacts:tags | Tag contacts |
emails:send | Send emails |
templates:read | Read saved templates |
events:read | Read events |
analytics:read | Read analytics |
webhooks:read | Read webhooks |
webhooks:write | Create and update webhooks |
suppressions:read | Read suppressions |
suppressions:write | Manage suppressions |
automations:enroll | Enroll contacts in automations |
Select only the scopes required by the connected application.
For example, an integration that syncs new signups into MailerLogic needs contacts:write. It does not need emails:send unless it also sends email.
Limiting permissions reduces the potential impact if an integration is compromised.
Step 6: Store the API Key
Store the key securely in the connected application or its secrets manager.
Update or Revoke an Integration Key
From 'Integrations' → 'Apps', open the relevant connection and use the available management options to:
Change the permissions granted to the connection.
Regenerate its key, when supported.
Revoke the connection when it is no longer needed.
Revoking an integration key prevents that connection from using the revoked key. If you regenerate a key, update the connected application with the replacement.
Authenticate API Requests
Send your API key in the authentication header required by the MailerLogic developer documentation. Make requests over HTTPS.
Never place an API key in a URL query string. URLs can be recorded in server logs, browser history, and referrer information.
Keep Your API Key Secure
Use environment variables or a secrets manager. Do not hardcode keys in your application source.
Keep keys on your server. Never expose them in front-end JavaScript, mobile application binaries, or other code users can inspect.
Do not commit keys to source control. This applies even to private repositories.
Limit access. Share keys only with systems and people that require them.
Use scoped keys for third-party tools. Grant only the permissions needed for each integration.
Your frontend should communicate with your backend, and your backend should make authenticated requests to MailerLogic.
For the required authentication header, endpoint paths, and request formats, refer to the developer documentation linked from 'Integrations' → 'Apps'.
What Can You Do With the MailerLogic API?
The API supports several common email and contact-management workflows.
| Feature | Supported operations |
|---|---|
| Contacts | Create, update, look up, tag, and manage contacts |
| Email sending | Send transactional and campaign emails through supported endpoints |
| Templates | Retrieve saved templates |
| Events and analytics | Access delivery, engagement, and other supported event data |
| Suppressions | Read and manage suppression records |
| Automations | Enroll contacts in automations |
| Webhooks | Create and manage webhook endpoints programmatically |
Available operations depend on the endpoint, the permissions assigned to your integration key, and your account's plan.
Consult the developer documentation linked from 'Integrations' → 'Apps' for the complete endpoint reference, request paths, parameters, and payload formats.
Send Transactional Emails Through the API
A specific user action or system event triggers transactional emails. Examples include:
Password resets.
Order confirmations and receipts.
Account activation links.
Important account notifications.
You can send transactional emails through the API or SMTP. Campaigns are generally used for planned marketing communications to lists or segments.
| Transactional email | Campaign or marketing email | |
|---|---|---|
| Trigger | A user action or system event | A planned marketing send |
| Recipients | Usually an individual recipient | A list or segment |
| Purpose | Deliver information related to a transaction or account event | Promote products, services, or offers |
| Unsubscribe requirements | Depends on the message and applicable law | Marketing emails generally require an unsubscribe mechanism |
Keep transactional messages focused on their intended purpose. Adding promotional content may change how a message is classified and affect compliance and deliverability.
Transactional emails sent through the API still count toward your plan's sending limits.
Understand API Rate Limits
MailerLogic limits API requests per account. The applicable rate limit depends on your plan.
The Free plan allows 60 requests per minute, with a maximum of 100 recipients per call. Paid plans may have higher limits.
Check 'Usage' → 'Rate Limiting' & 'Throughput' for your account's current limits.
Best Practices for Handling Rate Limits
Handle HTTP 429 responses: Reduce the request rate and retry after an appropriate delay.
Use exponential backoff: Increase the wait time between repeated retries.
Batch requests: Use batch operations when the endpoint supports them.
Cache data: Avoid repeatedly requesting information that has not changed.
Monitor usage: Review your account's usage and rate-limit information when requests are frequently throttled.
Avoid repeatedly retrying requests without a delay, as this can prolong rate-limit issues.
Troubleshooting
401: Authentication Failed
The request could not be authenticated.
Check the following:
Confirm that you're using the correct API key.
Check whether the account API key was rotated and your application still uses the old value.
Ensure the key has no extra spaces or newline characters.
Confirm that the key is supplied in the required authentication header, not a query parameter.
403: Forbidden
The request was authenticated, but the key does not have permission to perform the operation.
For integration keys, open Integrations → Apps and review the connection's assigned scopes. Add the required permission if appropriate and permitted.
Also verify that the selected account and plan support the requested operation.
429: Too Many Requests
Your application has exceeded the applicable API rate limit.
Reduce the request rate, implement exponential backoff, and retry after an appropriate delay. Check Usage → Rate Limiting & Throughput if the issue continues.
Email Sends Are Rejected
If an email request fails, check the following:
Verify that your sending domain has the required SPF and DKIM configuration.
Review your daily and monthly sending limits under Usage.
Check whether your account is still in its email warmup period.
I Lost My Account API Key
The full account API key cannot be recovered after generation.
The account owner must rotate the key, securely store the replacement, and update every system that uses it.
An Integration Cannot Access an Endpoint
Check that the integration key has the scope required by the endpoint. If the key was regenerated or revoked, update the connected application with a valid key.
Frequently Asked Questions
Can I have more than one account API key?
No. MailerLogic provides one account API key per account. If different systems need separate credentials, use scoped integration keys where supported. For applications that send through SMTP, you can also use separate SMTP credentials.
Do API keys expire automatically?
Account API keys do not expire on a fixed timer. Integration keys may have an expiration date, which is displayed on the connection when applicable.
Should I use the API or SMTP?
SMTP is a convenient option when an existing application already supports SMTP sending. The API supports additional workflows, including contact management, analytics, automation enrollment, and other programmatic operations.
You can use both, depending on your application's requirements.
Does API usage count toward my sending limit?
Emails sent through the API count toward your sending limits. Read-only API requests do not consume email-sending volume, but they count toward the API rate limit.
Can team members generate or rotate API keys?
Rotating the account API key is restricted to the account owner. Integration management is also subject to account permissions. See Managing Teams and User Invitations for details about role permissions.
What should I do if an API key is exposed?
Rotate the account API key immediately if it has been exposed. For an exposed integration key, revoke or regenerate the affected connection as appropriate. Update any legitimate systems that need the replacement credentials.
MailerLogic API keys let your applications connect securely to email and contact-management features. Keep account keys private, use scoped integration keys for third-party tools, and rotate exposed credentials promptly. Review permissions and rate limits regularly to keep your integrations secure and reliable.
