Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fluxomail.com/llms.txt

Use this file to discover all available pages before exploring further.

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
HeaderTypeRequiredDescription
AuthorizationstringyesBearer <api_key> or x-api-key
Idempotency-KeystringnoUnique per logical request (recommended)
Body
ParameterTypeRequiredDescription
tostringyesRecipient email
subjectstringyesSubject line
contentstringyesText body (used to generate plain text)
htmlContentstringnoHTML body (tracking auto‑injected)
ccstring or string[]noCarbon copy recipients
bccstring or string[]noBlind carbon copy recipients (not exposed in MIME headers)
attachmentsAttachment[]noList of attachments (see below)
policyKeystringnoPolicy to apply (e.g., transactional, bulk)
idempotencyKeystringnoIdempotency key when header cannot be set
Attachment
FieldTypeRequiredDescription
filenamestringyesFile name as it should appear to recipients
contentBase64stringyesBase64‑encoded file content
contentTypestringnoMIME 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())