Send via API

Note

The RelayPost dashboard uses a separate internal GraphQL API. This documentation covers the public REST API for external integrations.

Send an email

POST /api/v1/emails/send

cURL

curl -X POST https://relaypost.dev/api/v1/emails/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": { "email": "[email protected]", "name": "Your App" },
    "to": [{ "email": "[email protected]" }],
    "subject": "Your receipt",
    "html": "<h1>Thanks for your purchase!</h1><p>Order #1234</p>"
  }'

JavaScript

const response = await fetch("https://relaypost.dev/api/v1/emails/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    from: { email: "[email protected]", name: "Your App" },
    to: [{ email: "[email protected]" }],
    subject: "Your receipt",
    html: "<h1>Thanks for your purchase!</h1><p>Order #1234</p>",
  }),
});

const result = await response.json();
console.log(result.data.message_id);

Python

import requests

response = requests.post(
    "https://relaypost.dev/api/v1/emails/send",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_KEY",
    },
    json={
        "from": {"email": "[email protected]", "name": "Your App"},
        "to": [{"email": "[email protected]"}],
        "subject": "Your receipt",
        "html": "<h1>Thanks for your purchase!</h1><p>Order #1234</p>",
    },
)

result = response.json()
print(result["data"]["message_id"])

Request body

Field	Type	Required	Description
from	object	Yes	Sender — { "email": "...", "name": "..." }
to	array	Yes	Recipients — [{ "email": "...", "name": "..." }]
cc	array	No	CC recipients
bcc	array	No	BCC recipients
subject	string	Yes	Email subject line
html	string	No	HTML body
text	string	No	Plain text body
template_id	string	No	Use a saved template instead of inline content
template_data	object	No	Key-value pairs for template variables
headers	object	No	Custom email headers
priority	string	No	high, normal (default), or low
scheduled_at	string	No	ISO 8601 datetime for scheduled delivery

You must provide either html, text, or template_id.

Response (201)

{
  "data": {
    "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "queued",
    "queued_at": "2025-01-15T10:30:00.000Z"
  }
}

Errors

Status	Code	Description
400	VALIDATION_ERROR	Missing or invalid fields
400	DOMAIN_NOT_VERIFIED	From address uses an unverified domain
400	RECIPIENTS_SUPPRESSED	One or more recipients are on the suppression list
429	LIMIT_EXCEEDED	Organization email sending limit exceeded

Examples

With template

{
  "from": { "email": "[email protected]" },
  "to": [{ "email": "[email protected]" }],
  "subject": "Your receipt",
  "template_id": "tmpl_abc123",
  "template_data": {
    "order_number": "1234",
    "total": "$49.99"
  }
}

Scheduled

{
  "from": { "email": "[email protected]" },
  "to": [{ "email": "[email protected]" }],
  "subject": "Weekly digest",
  "html": "<p>Here's what happened this week...</p>",
  "scheduled_at": "2026-02-14T09:00:00Z"
}

Multiple recipients

{
  "from": { "email": "[email protected]", "name": "Team" },
  "to": [
    { "email": "[email protected]", "name": "Alice" },
    { "email": "[email protected]", "name": "Bob" }
  ],
  "cc": [{ "email": "[email protected]" }],
  "subject": "Meeting notes",
  "text": "Here are the notes from today's meeting."
}

Caution

The from address must use a verified domain. Emails from unverified domains will be rejected.

Check email status

GET /api/v1/emails/:id

Retrieve a specific email by its ID or message ID, including delivery events.

cURL

curl https://relaypost.dev/api/v1/emails/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const response = await fetch(
  "https://relaypost.dev/api/v1/emails/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  {
    headers: { "Authorization": "Bearer YOUR_API_KEY" },
  }
);

const result = await response.json();
console.log(result.data.status);

Python

import requests

response = requests.get(
    "https://relaypost.dev/api/v1/emails/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

result = response.json()
print(result["data"]["status"])

Response (200)

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "from_address": "[email protected]",
    "to_addresses": ["[email protected]"],
    "subject": "Your receipt",
    "status": "delivered",
    "priority": "normal",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:05.000Z",
    "scheduled_at": null,
    "events": [
      {
        "id": "evt_001",
        "type": "delivered",
        "recipient": "[email protected]",
        "smtp_code": 250,
        "smtp_message": "OK",
        "created_at": "2025-01-15T10:30:05.000Z"
      }
    ]
  }
}

Errors

Status	Code	Description
404	NOT_FOUND	Email not found or belongs to another organization

List emails

GET /api/v1/emails

Retrieve a paginated list of emails for your organization.

cURL

curl "https://relaypost.dev/api/v1/emails?status=delivered&page=1&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  status: "delivered",
  page: "1",
  limit: "10",
});

const response = await fetch(
`https://relaypost.dev/api/v1/emails?${params}`,
{
headers: { "Authorization": "Bearer YOUR_API_KEY" },
}
);

const result = await response.json();
console.log(result.data);
console.log(result.pagination);

Python

import requests

response = requests.get(
    "https://relaypost.dev/api/v1/emails",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"status": "delivered", "page": 1, "limit": 10},
)

result = response.json()
print(result["data"])
print(result["pagination"])

Query parameters

Parameter	Type	Default	Description
status	string	—	Filter by status: queued, delivered, bounced, failed, opened
from_date	string	—	ISO 8601 start date
to_date	string	—	ISO 8601 end date
page	integer	1	Page number
limit	integer	20	Results per page (max 100)

Response (200)

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "from_address": "[email protected]",
      "to_addresses": ["[email protected]"],
      "subject": "Your receipt",
      "status": "delivered",
      "priority": "normal",
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:05.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total_count": 42,
    "total_pages": 5
  }
}

Email lifecycle

Every email goes through these statuses:

queued → processing → delivered → opened
                   ↘ bounced
                   ↘ failed
                   ↘ rejected

Status	Meaning
queued	Accepted and waiting in the delivery queue
scheduled	Queued for future delivery at scheduled_at
processing	Currently being sent
delivered	Successfully delivered to the recipient’s mail server
opened	Recipient opened the email (if tracking is enabled)
bounced	Recipient’s mail server rejected the email
rejected	RelayPost rejected the email (suppression list, validation failure)
failed	Delivery failed after all retry attempts