API keys and integrations

EmailConnect's REST API enables powerful integrations with automation platforms, custom applications, and third-party services. Here's how to create and manage API keys for seamless connectivity.

Creating API keys

Access API settings

1. Navigate to Settings > API Keys
2. Click "Create new API key"

Configure key permissions

Scopes are strings in the form resource:action. A key carries a list of them, and every request is checked against the scope the endpoint requires.

Full access (default)

• Scope: *
• Complete access to all API endpoints
• Suitable for trusted applications

Individual scopes

Scope	What it allows
domains:read	Read domain information
domains:write	Create, verify, and delete domains
domains:config	Update domain configuration (allowAttachments, includeEnvelopeData only)
domains:status	Check domain verification status
domains:*	All of the above
aliases:read	Read alias information
aliases:write	Create, update, and delete aliases
aliases:*	All of the above
webhooks:read	Read webhook information
webhooks:write	Create, update, and delete webhooks
webhooks:*	All of the above
metrics:read	Read usage metrics and statistics
logs:read	Read email processing logs
logs:retry	Retry or replay a webhook delivery
emails:delete	Delete an email record and its attachments (Business+)
billing:read	Read plan, billing info, usage, and limits
billing:update	Change plan, buy credits, manage auto-reload and subscription
billing:*	All of the above
settings:read	Read account settings
settings:update	Update account settings, test S3 connections
settings:*	All of the above
storage:read	Read storage connection configurations
storage:write	Create, update, delete, and test storage connections
storage:*	All of the above

A resource:* wildcard covers every action on that resource. There is no emails:*, no metrics:* and no logs:* wildcard — list those scopes individually.

Preset bundles

Preset	Scopes
Full access	*
Read-only	domains:read, domains:status, aliases:read, webhooks:read, metrics:read, logs:read, billing:read, settings:read, storage:read
API user	domains:read, domains:status, domains:config, aliases:*, webhooks:*
Monitoring	metrics:read, logs:read, billing:read

Generate and save

1. Choose key name (e.g., "Zapier Integration")
2. Select permissions
3. Click "Generate key"
4. Important: Save the key immediately - it won't be shown again

API documentation

Access comprehensive API documentation at emailconnect.eu/docs:

• Interactive API explorer
• Request/response examples
• Authentication details
• Rate limits and quotas

Popular integrations

Zapier

Connect EmailConnect to 5,000+ apps:

1. Create API key with full scope
2. Add EmailConnect as a Zapier app
3. Use API key for authentication
4. Build zaps to process emails

Example Zapier workflows:

• Email → EmailConnect → Google Sheets
• Email → EmailConnect → Slack notification
• Email → EmailConnect → CRM update

Make (formerly Integromat)

Visual automation platform:

1. Create API key in EmailConnect
2. Add HTTP module in Make
3. Configure with EmailConnect API endpoints
4. Process emails in complex workflows

Example Make scenarios:

• Parse invoices and update accounting software
• Extract leads from emails to CRM
• Trigger multi-step approval workflows

N8n (self-hosted automation)

Open-source workflow automation:

1. Install official EmailConnect n8n node
2. Create API key with required scopes
3. Configure node with your API key
4. Build automation workflows

n8n advantages:

• Native EmailConnect integration
• Self-hosted for data privacy
• Complex workflow capabilities
• Cost-effective for high volume

Common API operations

Authenticate every request with the X-API-KEY header.

List domains

curl https://app.emailconnect.eu/api/domains \
  -H "X-API-KEY: your-api-key-here"

Scope: domains:read

Create a webhook

Create the webhook first — an alias must point at an existing webhook.

curl -X POST https://app.emailconnect.eu/api/webhooks \
  -H "X-API-KEY: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support intake",
    "url": "https://your-app.com/webhook",
    "description": "Support ticket intake",
    "generateSecret": true,
    "customHeaders": {
      "X-Custom-Header": "value"
    }
  }'

Required fields: name, url. Everything else is optional. generateSecret: true returns a webhookSecret in the response — it is shown only once. Custom headers go in customHeaders (an object of string values, max 10) and require a paid plan.

Scope: webhooks:write

Create an alias

curl -X POST https://app.emailconnect.eu/api/aliases \
  -H "X-API-KEY: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "localPart": "support",
    "domainId": "dom_123",
    "webhookId": "wh_456"
  }'

Required fields: localPart, domainId, webhookId — all three. localPart is the part before the @ (use "*" for a catch-all); the domain supplies the rest of the address. Optional fields include active, allowAttachments, includeEnvelope, includeHtml, includeText, includeMarkdown, includeReplyParsing, attachmentHandling (inline or storage), s3Folder and storageConnectionId.

Scope: aliases:write

Get email logs

curl "https://app.emailconnect.eu/api/v1/logs?aliasId=alias_456&status=FAILED&limit=50&offset=0" \
  -H "X-API-KEY: your-api-key-here"

Filters: domainId, aliasId, status (PENDING, DELIVERED, FAILED, RETRYING, EXPIRED), testWebhooksOnly, limit (1-100, default 50), offset.

Scope: logs:read

Get usage metrics

curl https://app.emailconnect.eu/api/v1/metrics \
  -H "X-API-KEY: your-api-key-here"

Returns counts and rates for the account: domains, verified_domains, emails_processed_24h, success_rate, monthly_usage, monthly_limit, total_available_emails, purchased_credits, webhooks, non_test_webhooks, aliases.

Scope: metrics:read

Retry or replay a webhook delivery

curl -X POST "https://app.emailconnect.eu/api/v1/logs/{messageId}/retry" \
  -H "X-API-KEY: your-api-key-here"

Retries a failed or expired delivery, or replays one that already succeeded. Available on all plans, with a 30-second cooldown per message.

Scope: logs:retry

Delete an email (Business+)

curl -X DELETE "https://app.emailconnect.eu/api/v1/emails/{messageId}" \
  -H "X-API-KEY: your-api-key-here"

Permanently removes the email record and all its attachments (database rows and stored objects). This is a retention control: it lets you shrink the storage window to seconds once your webhook has succeeded. Business plan or higher, and the key needs the emails:delete scope.

Security best practices

Key rotation

• Rotate keys every 90 days
• Use different keys per integration
• Revoke unused keys immediately

Scope limitation

• Use minimum required permissions
• Create separate keys for read vs write
• Audit key usage regularly

Environment separation

• Development: limited scope, test domains only
• Production: a dedicated key per service, scoped to what that service actually calls
• CI/CD: a separate key you can revoke on its own

API keys do not expire and do not carry IP restrictions — revoking a key in Settings > API Keys is how you retire one.

Storage guidelines

• Never commit keys to version control
• Use environment variables
• Encrypt keys in configuration files
• Use secret management services

Rate limits

Limits by plan

Plan	Requests per hour	Effective per minute
Free	60	1
Maker	600	10
Business	3,000	50
Platform	Unlimited	10,000 cap

Some endpoints have additional limits: sensitive operations are limited to 3 per 30 minutes, and test webhook deliveries to 10 per hour.

Rate limit headers

All API responses include rate limit headers:

x-ratelimit-limit: 600
x-ratelimit-remaining: 592
x-ratelimit-reset: 1640995200

When you exceed your limit, the response returns HTTP 429 with a retry-after header indicating how many seconds to wait.

Integration examples

Python

import requests

API_KEY = "your-api-key-here"
BASE_URL = "https://app.emailconnect.eu/api"

headers = {
    "X-API-KEY": API_KEY,
    "Content-Type": "application/json"
}

# List all domains
response = requests.get(f"{BASE_URL}/domains", headers=headers)
domains = response.json()

Node.js

const axios = require('axios');

const API_KEY = 'your-api-key-here';
const BASE_URL = 'https://app.emailconnect.eu/api';

const client = axios.create({
  baseURL: BASE_URL,
  headers: {
    'X-API-KEY': API_KEY,
    'Content-Type': 'application/json'
  }
});

// Create an alias (localPart, domainId and webhookId are all required)
async function createAlias(localPart, domainId, webhookId) {
  const response = await client.post('/aliases', {
    localPart,
    domainId,
    webhookId
  });
  return response.data;
}

cURL

# Get account usage metrics
curl -X GET https://app.emailconnect.eu/api/v1/metrics \
  -H "X-API-KEY: your-api-key-here"

Troubleshooting

Authentication errors

• Verify API key is correct
• Check key hasn't been revoked
• Ensure X-API-KEY header is included

Permission denied

• A 403 means the key is missing the scope the endpoint requires — check the scope table above and recreate the key with the right scopes (scopes cannot be edited after creation)
• Verify resource ownership
• Confirm account limits and plan (e.g. DELETE /api/v1/emails/{messageId} also requires Business+)

Rate limiting

• Implement exponential backoff
• Cache responses when possible
• Use webhooks instead of polling

Advanced usage

Webhook signature verification

Verify that webhook requests are genuinely from EmailConnect using Standard Webhooks signatures. See the Webhook signing guide for full implementation details and code examples in multiple languages.

Updating an alias

Update an existing alias with PUT (not PATCH) — send only the fields you want to change:

curl -X PUT https://app.emailconnect.eu/api/aliases/{aliasId} \
  -H "X-API-KEY: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false,
    "webhookId": "wh_789"
  }'

Updatable fields: email, webhookId, active, allowAttachments, includeEnvelope, includeHtml, includeText, includeMarkdown, includeReplyParsing, attachmentHandling, s3Folder, storageConnectionId. At least one must be present.

Scope: aliases:write

Pagination

Log listings page with limit and offset (not page):

curl "https://app.emailconnect.eu/api/v1/logs?limit=100&offset=100" \
  -H "X-API-KEY: your-api-key-here"

limit is capped at 100. The response includes total and hasMore so you know when to stop.

The API provides powerful programmatic access to all EmailConnect features, enabling seamless integration with your existing tools and workflows.