Send email

Send a single email using your organization’s active From identity. Endpoint: POST /api/v1/emails/send

BASE=https://api.fluxomail.com
curl -X POST "$BASE/api/v1/emails/send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: send-$(uuidgen)" \
  -d '{
    "to": "user@example.com",
    "subject": "Hello",
    "content": "Hi there",
    "htmlContent": "<p>Hi there</p>"
  }'

Headers

Header	Type	Required	Description
Authorization	string	yes	`Bearer <api_key>` or `x-api-key`
Idempotency-Key	string	no	Unique per logical request (recommended)

Body

Parameter	Type	Required	Description
to	string	yes	Recipient email
subject	string	yes	Subject line
content	string	yes	Text body (used to generate plain text)
htmlContent	string	no	HTML body (tracking auto‑injected)
cc	string or string[]	no	Carbon copy recipients
bcc	string or string[]	no	Blind carbon copy recipients (not exposed in MIME headers)
attachments	Attachment[]	no	List of attachments (see below)
policyKey	string	no	Policy to apply (e.g., `transactional`, `bulk`)
idempotencyKey	string	no	Idempotency key when header cannot be set

Attachment

Field	Type	Required	Description
filename	string	yes	File name as it should appear to recipients
contentBase64	string	yes	Base64‑encoded file content
contentType	string	no	MIME type (e.g., `application/pdf`)

Response

{
  "sendId": "sends_...",
  "status": "sent",
  "messageId": "0000000000000001-12345678-abcdef0123456789-000000",
  "reused": true
}

Response headers

X-Request-Id: unique id for this request
Idempotency-Key: echoes idempotency key used (when provided)
Idempotency-Replayed: true when a previous result is returned
X-RateLimit-* headers when a per-minute cap is configured

Status codes

200 success
401 invalid API key
403 missing scope send_email or tenant paused
402 plan required (attachments not enabled)
429 per‑minute rate limit exceeded (see Retry-After)
500 provider/internal error

Examples Limits

Max attachments per email: ATTACHMENTS_MAX_COUNT (default 5)
Max total attachments size: ATTACHMENTS_MAX_TOTAL_MB (default 10 MB)

Entitlements

Attachments may be gated by plan. If disabled, requests with attachments return 402.
When configured, Fluxomail checks the entitlement via Autumn with feature_id: attachments.

Example (Node)

import crypto from 'crypto';

const BASE = 'https://api.fluxomail.com';
const res = await fetch(`${BASE}/api/v1/emails/send`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.FLUXOMAIL_API_KEY}`,
    'Idempotency-Key': `send-${crypto.randomUUID()}`
  },
  body: JSON.stringify({
    to: 'user@example.com',
    subject: 'Hello',
    content: 'Hi there',
    htmlContent: '<p>Hi there</p>',
    cc: ['c1@example.com'],
    bcc: 'b1@example.com',
    attachments: [
      {
        filename: 'report.pdf',
        contentBase64: Buffer.from(await fs.promises.readFile('report.pdf')).toString('base64'),
        contentType: 'application/pdf'
      }
    ]
  })
});
const data = await res.json();

Example (Python)

import os, uuid, requests

BASE = 'https://api.fluxomail.com'
r = requests.post(
    f"{BASE}/api/v1/emails/send",
    headers={
        'Authorization': f"Bearer {os.environ['FLUXOMAIL_API_KEY']}",
        'Idempotency-Key': f"send-{uuid.uuid4()}"
    },
    json={
        'to': 'user@example.com',
        'subject': 'Hello',
        'content': 'Hi there',
        'htmlContent': '<p>Hi there</p>',
        'cc': ['c1@example.com'],
        'bcc': 'b1@example.com',
        'attachments': [
            {
              'filename': 'report.pdf',
              'contentBase64': open('report.pdf', 'rb').read().encode('base64'),
              'contentType': 'application/pdf'
            }
        ]
    }
)
print(r.status_code, r.json())

API documentation

Endpoints