simple email API

Sure — here’s a simple email API design you can use.

Minimal REST API

1) Send an email

POST /emails

Request body

{
  "to": "user@example.com",
  "subject": "Welcome",
  "text": "Hello there",
  "html": "<p>Hello there</p>"
}

Response

{
  "id": "email_123",
  "status": "queued"
}

---

2) Get email status

GET /emails/{id}

Response

{
  "id": "email_123",
  "status": "sent"
}

Possible statuses:

• queued
• sent
• failed

---

3) Optional: list emails

GET /emails

Response

{
  "data": [
    {
      "id": "email_123",
      "to": "user@example.com",
      "status": "sent"
    }
  ]
}

---

Example with cURL

curl -X POST https://api.yoursite.com/emails \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "to": "user@example.com",
    "subject": "Hello",
    "text": "Test email"
  }'

---

Simple Node.js example

import express from "express";

const app = express();
app.use(express.json());

app.post("/emails", (req, res) => {
  const { to, subject, text } = req.body;

  if (!to || !subject || !text) {
    return res.status(400).json({ error: "Missing required fields" });
  }

  // pretend to queue email
  res.status(201).json({
    id: "email_123",
    status: "queued"
  });
});

app.get("/emails/:id", (req, res) => {
  res.json({
    id: req.params.id,
    status: "sent"
  });
});

app.listen(3000, () => console.log("API running on port 3000"));

If you want, I can also give you:

• a Python/FastAPI version
• a database schema
• or a production-ready email API with senders, templates, and retries