Quickstart

Create a key at dashboard.mailfully.com/api-keys. New keys default to the send scope, which is all this guide needs.

The secret is shown once at creation. Copy it and store it where your code can read it:

export MAILFULLY_API_KEY="mf_live_xxxxxxxxxxxx"

Live sends require a verified domain. Without one, POST /v1/emails returns 403 unverified_domain_required. Add a subdomain you control, either in the dashboard or via the API:

curl -X POST https://api.mailfully.com/v1/domains \
  -H "Authorization: Bearer mf_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "mail.acme.com" }'

Replace mail.acme.com with a subdomain of a domain you own. The 201 response includes six DNS records to publish. Three are DKIM CNAMEs, plus one MX and two TXT records (abbreviated here):

{
  "object": "domain",
  "id": "dom_01J9ZC7XW2K5M8P3Q4R6T9VBHD",
  "name": "mail.acme.com",
  "status": "pending",
  "records": [
    { "type": "CNAME", "name": "6gbrjpgwjskckoa6a5zn6fwqkn67xbtw._domainkey.mail.acme.com", "value": "6gbrjpgwjskckoa6a5zn6fwqkn67xbtw.dkim.amazonses.com" },
    { "type": "CNAME", "name": "yybhvng4tqglsubhkkbwfwbtvvxjb5lb._domainkey.mail.acme.com", "value": "yybhvng4tqglsubhkkbwfwbtvvxjb5lb.dkim.amazonses.com" },
    { "type": "CNAME", "name": "wrx2s7fgbfyvfh2c3wch5bqk3gpjrmtp._domainkey.mail.acme.com", "value": "wrx2s7fgbfyvfh2c3wch5bqk3gpjrmtp.dkim.amazonses.com" },
    { "type": "MX", "name": "send.mail.acme.com", "value": "feedback-smtp.us-east-1.amazonses.com", "priority": 10 },
    { "type": "TXT", "name": "send.mail.acme.com", "value": "v=spf1 include:amazonses.com ~all" },
    { "type": "TXT", "name": "_dmarc.mail.acme.com", "value": "v=DMARC1; p=none;" }
  ]
}

Add each record at your DNS provider, then trigger a verification check:

curl -X POST https://api.mailfully.com/v1/domains/dom_01J9ZC7XW2K5M8P3Q4R6T9VBHD/verify \
  -H "Authorization: Bearer mf_live_xxxxxxxxxxxx"

Re-run until status flips from pending to verified. Amazon SES keeps checking your DNS for up to 72 hours after the domain is created; each verify call reads its latest result. Per-record statuses, tracking, and troubleshooting are covered in Verify a domain.

Send from an address on the domain you just verified. Replace you@yourcompany.com with an inbox you own (example.com addresses bounce).

curl -X POST https://api.mailfully.com/v1/emails \
  -H "Authorization: Bearer mf_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "orders@mail.acme.com",
    "to": "you@yourcompany.com",
    "subject": "Your order shipped",
    "html": "<p>Your order is on its way.</p>"
  }'

The API responds 202 Accepted with a message id and a Location: /v1/emails/{id} header:

{ "id": "01J9ZCE1Q6XKD8R4W2N7VT3MHB" }

A 202 means Mailfully validated and queued the message. Delivery happens asynchronously.

The next step shows how to confirm it.

Fetch the message by id:

curl https://api.mailfully.com/v1/emails/01J9ZCE1Q6XKD8R4W2N7VT3MHB \
  -H "Authorization: Bearer mf_live_xxxxxxxxxxxx"

{
  "object": "email",
  "id": "01J9ZCE1Q6XKD8R4W2N7VT3MHB",
  "to": ["you@yourcompany.com"],
  "from": "orders@mail.acme.com",
  "created_at": "2026-07-08T14:02:11.000Z",
  "subject": "Your order shipped",
  "html": "<p>Your order is on its way.</p>",
  "text": null,
  "cc": [],
  "bcc": [],
  "reply_to": [],
  "last_event": "delivered",
  "scheduled_at": null,
  "tags": []
}

The detail response reports lifecycle through last_event. A message moves queued → sending → sent as it is handed to the mail infrastructure, then delivered once the recipient's server accepts it. A bad address shows bounced instead. For the full timeline of events, use GET /v1/emails/{id}/events.

Once last_event reads delivered, check your inbox for your first delivered email.