Quickstart

This guide walks you through sending your first email with the RelayPost REST API.

Prerequisites

• A RelayPost account — sign up free
• A domain you control (for production sending)

1. Create an organization

After signing up, you’ll be prompted to create an organization. This is your workspace — all API keys, domains, and emails are scoped to it.

2. Generate an API key

Go to Settings → API Keys and create a new key. Copy it immediately — it’s only shown once.

Your key looks like: rp_live_aBcDeFgHiJkLmNoPqRsT...

3. Send your first email

cURL

curl -X POST https://api.relaypost.dev/v1/emails/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": { "email": "hello@yourdomain.com", "name": "Your App" },
    "to": [{ "email": "test@example.com" }],
    "subject": "Hello from RelayPost",
    "html": "<h1>It works!</h1><p>Your email delivery is set up.</p>"
  }'

JavaScript

const response = await fetch("https://api.relaypost.dev/v1/emails/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    from: { email: "hello@yourdomain.com", name: "Your App" },
    to: [{ email: "test@example.com" }],
    subject: "Hello from RelayPost",
    html: "<h1>It works!</h1><p>Your email delivery is set up.</p>",
  }),
});

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

Python

import requests

response = requests.post(
    "https://api.relaypost.dev/v1/emails/send",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_KEY",
    },
    json={
        "from": {"email": "hello@yourdomain.com", "name": "Your App"},
        "to": [{"email": "test@example.com"}],
        "subject": "Hello from RelayPost",
        "html": "<h1>It works!</h1><p>Your email delivery is set up.</p>",
    },
)

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

Ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://api.relaypost.dev/v1/emails/send")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
from: { email: "hello@yourdomain.com", name: "Your App" },
to: [{ email: "test@example.com" }],
subject: "Hello from RelayPost",
html: "<h1>It works!</h1><p>Your email delivery is set up.</p>"
}.to_json

response = http.request(request)
result = JSON.parse(response.body)
puts result["data"]["message_id"]

PHP

use GuzzleHttp\Client;

$client = new Client(["base_uri" => "https://api.relaypost.dev"]);

$response = $client->post("/v1/emails/send", [
    "headers" => ["Authorization" => "Bearer YOUR_API_KEY"],
    "json" => [
        "from" => ["email" => "hello@yourdomain.com", "name" => "Your App"],
        "to" => [["email" => "test@example.com"]],
        "subject" => "Hello from RelayPost",
        "html" => "<h1>It works!</h1><p>Your email delivery is set up.</p>",
    ],
]);

$result = json_decode($response->getBody(), true);
echo $result["data"]["message_id"];

4. Check the response

A successful send returns:

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

Tip

For production sending, verify your domain first. Unverified domains may have lower deliverability.

What’s next

• Verify your domain for better inbox placement
• Set up webhooks to track delivery events
• Create templates for reusable email layouts
• Send via SMTP if your app uses SMTP

Frequently Asked Questions

How long does it take to set up RelayPost?

You can send your first email in under 5 minutes. Sign up, create an organization, generate an API key, and make a single API call. For production sending, domain verification takes an additional 5–30 minutes for DNS propagation.

What programming languages does RelayPost support?

RelayPost works with any language that can make HTTP requests. The REST API accepts JSON over HTTPS. The SMTP relay works with any SMTP client. Documentation includes examples for JavaScript, Python, Ruby, PHP, and cURL.

Do I need to verify my domain before sending?

Domain verification is not required for testing, but it is strongly recommended for production. Verified domains have SPF and DKIM authentication, which significantly improves inbox placement and prevents your emails from landing in spam.