Send email

POST /v1/emails accepts one email and queues it. Authentication is a project API key in the Authorization header.

Request

Field	Type	Notes
`from`	string	Address on a verified domain (live keys). Display names allowed: "Acme <hi@acme.com>".
`to`	string \| string[]	Also cc, bcc and replyTo. At most 50 recipients across to, cc and bcc.
`subject`	string	Required unless a template supplies it.
`html`, `text`	string	At least one, unless you use template.
`template`	string	Template alias or id. Supplies subject, html and text.
`variables`	object	Values for {{ placeholders }}. HTML-escaped in html.
`attachments`	array	{ filename, content (base64), contentType? }. Up to 10 files, 10 MB in total. Executables are refused.
`headers`	object	Custom headers. Single-line values; From, To, Subject and similar are reserved.
`tags`	object	Up to 10 key/value pairs, returned in webhooks.
`scheduledAt`	ISO 8601	Up to 30 days ahead. Cancel with POST /v1/emails/:id/cancel.
`type`	"TRANSACTIONAL" \| "MARKETING"	Default TRANSACTIONAL. Each type has its own queue, so a large send never delays a password reset.

Idempotency

Send an Idempotency-Key header (up to 256 printable ASCII characters) to make retries safe. Repeating a request with the same key returns the original result without sending again. Reusing a key with a different body returns 409 CONFLICT.

Terminal

curl https://api.mailfy.uz/v1/emails \
  -H "Authorization: Bearer $MAILFY_API_KEY" \
  -H "Idempotency-Key: order-1042-receipt" \
  -H "Content-Type: application/json" \
  -d '{ "from": "orders@acme.com", "to": "ada@example.com", "template": "receipt", "variables": { "order": "1042" } }'

Batch

POST /v1/emails/batch takes an array of up to 100 emails. Every email is validated before any is accepted, and the response lists one { id, status } per email in order.

Reading emails

GET /v1/emails (newest first, cursor pagination) and GET /v1/emails/:id (with the event timeline) need a full access key; sending-only keys get 403.

Statuses

Status	Meaning
QUEUED / SCHEDULED	Accepted and waiting for the worker (or for scheduledAt).
SENT	Handed to the delivery provider.
DELIVERED / DELIVERY_DELAYED	Reported by the provider for the recipient server.
BOUNCED / COMPLAINED	Permanent bounce or spam complaint. The address is added to your suppression list.
SUPPRESSED	Every recipient was on the suppression list; nothing was sent or counted.
SANDBOXED	Sent with a test key: processed, never delivered.
FAILED / CANCELED	Could not be sent (reason in lastError), or canceled before sending.

Status only moves forward. See Webhooks to be notified of each change.