Quickstart

Get from zero to your first sent email in under 5 minutes.

Step 1: Create an Account

Head over to app.postject.com/register and create your free account. Once registered, Postject automatically provisions a default server for you with three message streams (Transactional, Broadcast, and Inbound) along with an API token you can use immediately.

Step 2: Get Your Server Token

Every server in Postject has a unique API token prefixed with pt_live_. This token is used to authenticate requests scoped to that specific server, including sending emails and managing templates.

To find your token, navigate to Settings > API Tokens in the Postject dashboard. You can copy it directly from there. Keep this token secret - anyone with access to it can send emails on behalf of your server.

pt_live_sk7f2a9b3c4d5e6f7a8b9c0d1e2f3a4b

Step 3: Understand Sandbox Mode

All new Postject accounts start in sandbox mode. In sandbox mode, emails are delivered normally, but only to addresses you have explicitly whitelisted. You can manage your whitelist from Account → Sandbox Emails in the dashboard. This lets you test your full sending flow, including real email delivery to your own inboxes, before going live.

Once you have verified a domain and sent at least one sandbox email, you can submit a request for production access from the Account page. After approval, your account can send to any address with no whitelist restrictions. See the Domains & Identities guide to verify your sending domain.

Step 4: Send Your First Email

Use the Send endpoint to dispatch your first email. You can use cURL, our official SDKs, or the CLI tool. All methods require your server token for authentication.

Using cURL

curl -X POST https://api.postject.com/v1/send \
  -H "Authorization: Bearer pt_live_your_server_token" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Hello from Postject",
    "html": "<h1>It works!</h1><p>Your first email via Postject.</p>"
  }'

Using Node.js SDK

import { Postject } from 'postject-sdk';

const client = new Postject({
  apiKey: 'pt_live_your_server_token',
});

const result = await client.send({
  to: 'recipient@example.com',
  subject: 'Hello from Postject',
  html: '<h1>It works!</h1><p>Your first email via Postject.</p>',
});

console.log('Message ID:', result.id);

Install with: npm install postject-sdk. See full SDK documentation

Using Python SDK

from postject import Postject

client = Postject(api_key="pt_live_your_server_token")

result = client.send({
    "to": "recipient@example.com",
    "subject": "Hello from Postject",
    "html": "<h1>It works!</h1><p>Your first email via Postject.</p>"
})

print(f"Message ID: {result.id}")

Install with: pip install postject. See full SDK documentation

Using CLI

postject send \
  --to recipient@example.com \
  --subject "Hello from Postject" \
  --body "<h1>It works!</h1><p>Your first email via Postject.</p>"

Install with: npm install -g postject-cli. See full CLI documentation

Response

A successful request returns a 201 Created response with the message ID and its initial status:

{
  "id": "msg_01hy4z...",
  "status": "queued",
  "to": "recipient@example.com",
  "subject": "Hello from Postject"
}

Step 5: Check Delivery Status

After sending, you can check the delivery status of any message by its ID. This endpoint uses JWT Bearer authentication and returns the full event history for the message.

{
  "id": "msg_01hy4z...",
  "to": "recipient@example.com",
  "subject": "Hello from Postject",
  "status": "delivered",
  "createdAt": "2025-07-15T10:30:00.000Z",
  "sentAt": "2025-07-15T10:30:01.234Z",
  "events": [
    {
      "id": "evt_a1b2c3d4",
      "type": "sent",
      "timestamp": "2025-07-15T10:30:01.234Z",
      "metadata": {}
    },
    {
      "id": "evt_e5f6g7h8",
      "type": "delivered",
      "timestamp": "2025-07-15T10:30:03.567Z",
      "metadata": {
        "smtpResponse": "250 2.0.0 OK"
      }
    }
  ]
}

What's Next?

You have successfully sent your first email with Postject. Here are some next steps to explore:

• SDKs & Libraries - Integrate Postject using official Node.js, Python, PHP, or Ruby SDKs.
• CLI Tool - Manage your account and send emails from the command line.
• Templates - Create reusable email templates with dynamic variables.
• Webhooks - Receive real-time delivery notifications in your application.
• Domains & Identities - Verify your sending domain for production use.
• Team Management - Invite team members and manage access to your servers.