Email API

curl -X POST https://api.mailgrid.space/api/emails \
  -H "Authorization: Bearer $MAILGRID_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1024-receipt" \
  -d '{
    "from":     "billing@mailgrid.space",
    "to":       ["anna@acme.com", "billing@acme.com"],
    "replyTo":  ["support@mailgrid.space"],
    "subject":  "Receipt for order #1024",
    "html":     "<h1>Thanks, {{name}}</h1><p>Total: ${{total}}</p>",
    "text":     "Thanks {{name}}. Total: ${{total}}",
    "variables": { "name": "Anna", "total": "42.00" },
    "streamId":  "transactional-prod",
    "trackOpens": true,
    "trackClicks": true,
    "tags":      ["receipt", "v3"],
    "headers":   { "X-Order-Id": "1024" },
    "attachments": [
      { "fileId": "logo-cached-fid" },
      { "filename": "receipt-1024.pdf", "content": "JVBERi0xLj...",
        "contentType": "application/pdf" }
    ]
  }'

{
  "success": true,
  "data": {
    "messageId": "0107019a-43cf-7e3d-9b8c-...",
    "status":    "sent",
    "to":        ["anna@acme.com", "billing@acme.com"]
  },
  "requestId": "fd067654-..."
}

{
  "success": true,
  "data": {
    "messageId": "",
    "status":    "replayed",
    "to":        ["anna@acme.com"]
  }
}

{
  "success": true,
  "data": {
    "messageId": "suppressed",
    "status":    "suppressed",
    "to":        ["unsubscribed@example.com"]
  }
}

async function send(payload) {
  const r = await fetch('https://api.mailgrid.space/api/emails', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.MAILGRID_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  });
  const json = await r.json();
  if (!json.success) throw new Error(`Mailgrid ${json.code}: ${json.message}`);
  return json.data;
}

await send({
  from: 'hello@yourdomain.com',
  to:   'user@example.com',
  subject: 'Hi',
  html: '<p>Hello</p>',
});

import os, httpx

def send(**payload):
    r = httpx.post(
        "https://api.mailgrid.space/api/emails",
        headers={
            "Authorization": f"Bearer {os.environ['MAILGRID_KEY']}",
            "Content-Type":  "application/json",
        },
        json=payload,
        timeout=15,
    )
    j = r.json()
    if not j.get("success"):
        raise RuntimeError(f"Mailgrid {j['code']}: {j['message']}")
    return j["data"]

send(
    from_="hello@yourdomain.com",
    to="user@example.com",
    subject="Hi",
    html="<p>Hello</p>",
)

package mailgrid

import (
    "bytes"; "encoding/json"; "fmt"; "net/http"; "os"
)

func Send(p map[string]any) (map[string]any, error) {
    body, _ := json.Marshal(p)
    req, _ := http.NewRequest("POST",
        "https://api.mailgrid.space/api/emails",
        bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer "+os.Getenv("MAILGRID_KEY"))
    req.Header.Set("Content-Type", "application/json")
    resp, err := http.DefaultClient.Do(req)
    if err != nil { return nil, err }
    defer resp.Body.Close()
    var j map[string]any
    json.NewDecoder(resp.Body).Decode(&j)
    if ok, _ := j["success"].(bool); !ok {
        return nil, fmt.Errorf("%v", j["message"])
    }
    return j["data"].(map[string]any), nil
}

{
  "emails": [
    { "from": ..., "to": ..., "subject": ..., "html": ... },
    { ... },
    ...
  ]
}

{
  "success": true,
  "data": {
    "total":      100,
    "sent":        97,
    "suppressed":   2,
    "failed":       1,
    "results": [
      { "index": 0, "status": "sent", "messageId": "..." },
      { "index": 1, "status": "suppressed" },
      { "index": 2, "status": "failed", "error": "SES sandbox" }
    ]
  }
}