Send Email

Send transactional emails via the REST API. Supports templates, attachments, scheduling, and tracking control.

POST /api/v1/emails

Request body

fromstringrequiredSender email (must be from a verified domain)

tostring | string[]requiredRecipient email address(es)

subjectstringrequiredEmail subject line (required unless using template_id)

htmlstringHTML email body (or use template_id)

textstringPlain text fallback

ccstring | string[]CC recipients

bccstring | string[]BCC recipients

replyTostringReply-to address

from_namestringSender display name

headersRecord<string, string>Custom email headers

template_idstringUUID of a template (overrides html/text)

variablesRecord<string, string>Template variable values

trackingobject{ open: boolean, click: boolean } — per-email control

tagsArray<{name, value}>Custom tags for filtering

attachmentsArray<{filename, content, contentType?}>Base64-encoded attachments (max 5MB each)

scheduled_forstringISO 8601 datetime for scheduled sending

priority"high" | "normal" | "low"Queue priority

stream_idstringEmail stream UUID

type"transactional" | "marketing"Email type — controls headers (default: "transactional")

smtp_portnumberOverride SMTP port (25, 465, 587)

Email types

The type field controls which SMTP headers are applied. Gmail, Yahoo, and Microsoft judge compliance per message class — a transactional password-reset and a promotional broadcast are held to different rules.

transactionalDefault. No List-Unsubscribe headers. No unsubscribe footer. For password resets, receipts, account notifications.

marketingAdds List-Unsubscribe, List-Id headers and auto-appends unsubscribe footer to HTML body. For newsletters, promos, broadcasts.

Basic example

Terminal

curl -X POST https://api.grosend.com/api/v1/emails \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["user@example.com"],
    "subject": "Your order is ready",
    "html": "<h1>Order #1234</h1><p>Your order has shipped.</p>",
    "text": "Order #1234 - Your order has shipped.",
    "tags": [{"name": "order_id", "value": "1234"}],
    "tracking": { "open": true, "click": true },
    "priority": "high"
  }'

Template example

Terminal

curl -X POST https://api.grosend.com/api/v1/emails \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["user@example.com"],
    "template_id": "template-uuid",
    "variables": {
      "name": "Alice",
      "activation_link": "https://yourapp.com/activate/abc123"
    }
  }'

Scheduled example

Terminal

curl -X POST https://api.grosend.com/api/v1/emails \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["user@example.com"],
    "subject": "Happy birthday!",
    "html": "<h1>Happy birthday {{name}}!</h1>",
    "variables": {"name": "Alice"},
    "scheduled_for": "2026-07-20T09:00:00Z"
  }'

Attachment example

Terminal

curl -X POST https://api.grosend.com/api/v1/emails \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["user@example.com"],
    "subject": "Your invoice",
    "html": "<h1>Invoice attached</h1>",
    "attachments": [{
      "filename": "invoice.pdf",
      "content": "base64-encoded-content...",
      "contentType": "application/pdf"
    }]
  }'

Response

200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued"
}

When scheduled_for is provided, status is "scheduled" instead of "queued".

Batch send

Send up to 100 emails in a single API call. Each email can have its own template and variables.

Terminal

curl -X POST https://api.grosend.com/api/v1/emails/batch \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      {
        "from": "hello@yourdomain.com",
        "to": ["alice@example.com"],
        "subject": "Welcome!",
        "html": "<h1>Welcome Alice</h1>"
      },
      {
        "from": "hello@yourdomain.com",
        "to": ["bob@example.com"],
        "template_id": "welcome-template-uuid",
        "variables": {"name": "Bob"}
      }
    ]
  }'

Response

{
  "data": [
    { "id": "email-uuid-1", "status": "queued" },
    { "id": "email-uuid-2", "status": "queued" }
  ],
  "total": 2,
  "succeeded": 2,
  "failed": 0
}

List emails

Terminal

curl "https://api.grosend.com/api/v1/emails?limit=10&status=delivered&tag=order_id:1234" \
  -H "Authorization: Bearer sv_live_..."

Rate limits

Grosend rate-limits at 100 requests per minute per API key. Exceeding this returns 429 Too Many Requests.

Each email costs 1 credit from your balance. Check your balance before sending bulk emails.