Docs · API reference

Send an email

Send one email from an address on your own domain. It goes out from our mail servers, signed for your domain, and the answer says it's queued.

Preview: may change before launch · Updated 1 November 2026

Preview

This is how the API is planned to work. Names and fields may change before launch. The APIs are in early access: join early access to get a key when they're ready.

POST https://api.magpie-cloud.com/v1/emails. What it's for, and how it works: Email sending API.

Request

A JSON body, with your API key in the Authorization header (see Authentication).

Field	Type	Required	What it is
`from`	string	Yes	The sender, as `Name <address>`, on a domain you've added and set up.
`to`	string	Yes	The recipient's address.
`subject`	string	Yes	The subject line.
`text`	string	No	The body, as plain text. Give this, `html`, or both.
`html`	string	No	The body, as HTML.
`reply_to`	string	No	Where replies go.
`unsubscribe_url`	string	No	An https address, for the unsubscribe link inboxes show.

Example

Request · POST /emails

curl https://api.magpie-cloud.com/v1/emails \
  -H "Authorization: Bearer $MAGPIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Jordan <jordan@yourcompany.example>",
    "to": "alex.sample@examplefreight.example",
    "subject": "Quick question about your depots",
    "text": "Hi Alex, ..."
  }'

const res = await fetch("https://api.magpie-cloud.com/v1/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAGPIE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "Jordan <jordan@yourcompany.example>",
    to: "alex.sample@examplefreight.example",
    subject: "Quick question about your depots",
    text: "Hi Alex, ...",
  }),
});
const data = await res.json();

import os
import requests

res = requests.post(
    "https://api.magpie-cloud.com/v1/emails",
    json={
        "from": "Jordan <jordan@yourcompany.example>",
        "to": "alex.sample@examplefreight.example",
        "subject": "Quick question about your depots",
        "text": "Hi Alex, ...",
    },
    headers={"Authorization": f"Bearer {os.environ['MAGPIE_API_KEY']}"},
    timeout=90,
)
data = res.json()

Response · 200

{
  "id": "msg_4b9e...",
  "status": "queued"
}

Response

Field	Type	What it is
`id`	string	The message's id, to keep with your record of it.
`status`	string	`queued`: accepted, and waiting to go out.

Errors

Errors come back as JSON with a code and a message. See Errors for the shape, and when to try again.

Status	Code	When
`400`	`invalid_request`	A field is missing or isn't valid.
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`402`	`out_of_credits`	Your sending allowance is used up.
`403`	`feature_unavailable`	Sending isn't switched on for your account yet, or it's paused.
`422`	`domain_not_verified`	`from` isn't on a domain of yours that's ready.
`422`	`recipient_suppressed`	This address has bounced, complained or opted out.
`429`	`daily_send_limit`	You've reached today's limit. `Retry-After` says when it resets.
`429`	`rate_limited`	Too many requests. Wait the number of seconds in the `Retry-After` header, then try again.
`5xx`	Varies	Something went wrong on our side. Safe to try again after a short wait.

Billing

The planned price is £0.15$0.25 for every 1,000 emails sent, as on MagpieCRM's hosted plan. It may change before launch.

Notes

Before you send, ask for sending to be switched on in the console, add your domain, and put the records we give you in its DNS: the DKIM record and, ideally, DMARC.
An address that hard-bounces or marks your email as spam isn't sent to again.
Sending has a daily limit that starts low and rises as your email is received well. See Rate limits and pacing.
Send an Idempotency-Key header with a value of your own, and sending the same key again won't send the email twice.
GET /emails/{id} says how an email went: queued, deferred, delivered, bounced or complained. We don't keep the recipient or subject.
Delivery and open events by webhook are planned but not built.

Questions about the APIs? Email pele@magpiecrm.com.