API Keys

1. Overview

MelMe provides a developer-friendly API that allows you to send transactional or bulk emails programmatically from your applications.

By generating an API Key, you can authenticate requests to our email-sending endpoint and route messages through your verified custom domains without using SMTP credentials.

2. Managing API Keys

To generate an API Key:

1. Navigate to the API Keys section in your dashboard sidebar.
2. Click Create API Key.
3. Provide a Key Name to identify the application or server using the credentials.
4. Select a Domain Restriction (Highly Recommended):
   • Any Domain: Allows this key to send emails from any verified domain in your MelMe account.
   • Specific Domain: Restricts this key to a single verified domain. If a request is received to send an email from a different domain, it will be rejected.
5. Click Generate Key and immediately copy the key. For security reasons, it will not be shown again.

3. Authentication

All requests to the email-sending endpoint must be authenticated. You can supply your API key in one of two ways:

HTTP Header (Recommended)

Add the key as a bearer token in the Authorization header:

Authorization: Bearer your_api_key_here

Custom Header

Alternatively, use the custom X-API-Key header:

X-API-Key: your_api_key_here

4. Send Email Endpoint

POST /api/v1/emails/send

This endpoint accepts a JSON payload to build, sign, log, and send a raw MIME message using AWS SES.

Request Body Schema (JSON)

* Note: Either text or html must be provided. If only html is provided, a fallback plain text preview will be generated automatically.

Attachment Object Schema

Attachments support two modes: sending file contents inline as Base64 encoded text, or sharing a downloadable URL pointing to the file. Using URLs is the most scalable approach for larger attachments since it avoids HTTP base64 payload size restrictions.

** Note: Each attachment must specify either content (base64) or url.

5. Security & Isolation Rules

MelMe runs strict security validations on the backend before sending any email:

• Domain Verification Check: The domain part of the from email address must exist in your MelMe account and be in the verified state (both DKIM and MX setup successfully completed).
• API Key Domain Restrictions: If the API Key was created with a restriction to a specific domain (e.g., app.domain.com), the from email's domain must match this restriction exactly.
• Recipient Cap: The total number of recipients (to + cc + bcc) must not exceed 50 per request.

Attachment Validation & Protection:

• Download Timeout: URL-based attachments must be fully downloaded within 10 seconds. Requests taking longer will time out and be rejected.
• Header Inspection: Before downloading files from a URL, MelMe inspects the Content-Length header. If the file size is verified to be larger than 10MB, the download is aborted immediately.
• Size Enforcement: Regardless of the source (base64 or URL), the maximum decoded size limit is 10MB per file and 10MB combined total for all attachments in an email.
• Payload Caps: The text body must be under 2MB, and the HTML body must be under 5MB.

6. Example cURL Request

Here is a copyable cURL command showing how to send an email combining both inline base64 data and a URL-hosted file:

curl -X POST https://your-melme-app.com/api/v1/emails/send \
  -H "Authorization: Bearer mm_live_xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["client@example.com"],
    "cc": ["manager@yourdomain.com"],
    "subject": "Project Deliverables & Assets",
    "text": "Hello, please find the attached documents and media assets.",
    "html": "<p>Hello,</p><p>Please find the attached <strong>documents and media assets</strong>.</p>",
    "attachments": [
      {
        "filename": "notes.txt",
        "content": "SGVsbG8gV29ybGQhIFRoaXMgaXMgdGhlIGNvbnRlbnQgb2YgbXkgYXR0YWNobWVudC4=",
        "contentType": "text/plain"
      },
      {
        "filename": "design-mockups.zip",
        "url": "https://example.com/assets/design-mockups.zip"
      }
    ]'
  }'

7. API Responses

Success (200 OK)

Returned when the email is successfully built, downloaded, verified, stored in S3, and sent via AWS SES.

{
  "success": true,
  "messageId": "<ses-unique-message-id@email.amazonses.com>",
  "emailLogId": "cuid_email_log_id"
}

Unauthorized (401 Unauthorized)

Returned if the API key is missing or invalid.

{
  "error": "Unauthorized: Invalid API Key"
}

Forbidden (403 Forbidden)

Returned if the sender domain is not registered in the account or if the API key is restricted to a different domain.

{
  "error": "Forbidden: This API key is restricted to send emails from domain 'app.domain.com' only."
}

Validation Error (400 Bad Request)

Returned if inputs fail structural validation (e.g., missing subject), if size constraints are exceeded, or if an attachment download fails/times out.

{
  "error": "Failed to process attachment 'design-mockups.zip' from URL: Attachment exceeds the 10MB limit (size: 15.42MB)"
}