Emalc

Search Documentation

Quickly jump to any guide, document, or section...

Send an Email (POST /api/public/email/send)

Dispatches a single transactional or notification email payload to one or multiple recipients (up to 10 per request).

  • HTTP Method: POST
  • Path: /api/public/email/send
  • Content-Type: application/json
  • Required Scope: email:send or full_access

Headers#

HeaderTypeRequiredDescription
AuthorizationstringYesBearer <your_api_key> (must start with em_).
Content-TypestringYesMust be application/json.

Request Body Schema#

FieldTypeRequiredDescription & Constraints
tostring | string[]YesSingle email address or array of up to 10 recipient email addresses.
fromstringYesSender email address (e.g. "orders@acme.com" or "Acme Store <orders@acme.com>"). Must belong to a verified domain.
subjectstringYesSubject line (1 to 998 characters).
htmlstringOptional*HTML formatted email body. (*Either html or text is required).
textstringOptional*Plain text email body. (*Either html or text is required).
replyTostringOptionalValid email address for recipient replies.
attachmentsarrayOptionalArray of Base64 attachment objects (see schema below). Max payload 10 MB.
headersobjectOptionalCustom RFC MIME headers map (max 10 key-value pairs).
tagsobjectOptionalAnalytics tags map (max 10 key-value pairs).
trackingobjectOptionalOverride tracking options (openTracking, clickTracking).
idempotencyKeystringOptionalUnique identifier (max 255 chars) to prevent duplicate sends on retries.

Field Specifications#

1. Attachments Object Schema#

json
"attachments": [
  {
    "filename": "invoice-1042.pdf",
    "content": "JVBERi0xLjQKJcOkw7zDtsOfCDC...",
    "contentType": "application/pdf"
  }
]
  • filename (string, required): Name of the attached file.
  • content (string, required): Base64-encoded string of file content.
  • contentType (string, optional): MIME type (e.g., application/pdf, image/png, text/plain). Executables (.exe, .bat, .sh) are rejected.

2. Tracking Options Object#

json
"tracking": {
  "openTracking": true,
  "clickTracking": false
}

If omitted, defaults to your verified sender domain's organization-wide tracking settings.

3. Metadata Tags & Custom Headers#

  • tags: Up to 10 string key/value pairs ({"order_id": "1042", "env": "prod"}). Tag keys max 64 chars; values max 256 chars. Forwarded in webhooks and visible in delivery logs.
  • headers: Up to 10 custom MIME headers ({"X-Order-ID": "1042"}). Reserved headers (From, To, Subject, DKIM-Signature) cannot be overridden.

4. Idempotency & Deduplication#

  • Explicit Key: Pass idempotencyKey: "order_1042_attempt_1" to guarantee exactly-once delivery across network retries.
  • Automatic Hash Deduplication: If omitted, Emalc computes a SHA-256 hash of API key ID + recipients + subject + a 2-second time window. Duplicate calls within 2s are safely ignored without deducting extra credits.

Example Request#

json
{
  "to": ["john.doe@example.com"],
  "from": "Acme Store <orders@acme.com>",
  "subject": "Your Order Confirmation (#1042)",
  "html": "<h1>Thank you for your order!</h1><p>Your package is being prepared.</p>",
  "text": "Thank you for your order! Your package is being prepared.",
  "replyTo": "support@acme.com",
  "tracking": {
    "openTracking": true,
    "clickTracking": true
  },
  "tags": {
    "category": "receipt",
    "order_id": "1042"
  },
  "idempotencyKey": "order_conf_1042_attempt_1"
}

Response Payload Schemas#

1. Full Success (200 OK)#

json
{
  "success": true,
  "id": "0100018df5608034-7546e5fa-4965-4f46-99c0-9943630f55cf-000000",
  "emailId": "7132fa69-9064-44d4-9d41-4560ea605dfa",
  "accepted": [
    "john.doe@example.com"
  ]
}

2. Partial Success (200 OK)#

Returned when some recipients were suppressed or skipped due to insufficient workspace credit balance:

json
{
  "success": true,
  "id": "0100018df5608034-7546e5fa-4965-4f46-99c0-9943630f55cf-000000",
  "emailId": "7132fa69-9064-44d4-9d41-4560ea605dfa",
  "accepted": [
    "valid.user@example.com"
  ],
  "suppressed": [
    "bounced.user@example.com"
  ],
  "insufficientCredit": [
    "extra.user@example.com"
  ]
}

3. Schema Validation Error (400 Bad Request)#

json
{
  "error": "VALIDATION_ERROR",
  "message": "Invalid request body parameters",
  "issues": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": ["subject"],
      "message": "Subject line is required"
    }
  ]
}