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: Verify a Domain (Optional)

Domain verification is optional for getting started. When you send emails from an unverified domain, Postject operates in test mode — the API accepts requests and returns valid responses, but no actual emails are delivered. This is perfect for integration testing and development.

When you are ready to send real emails, follow the Domains & Identities guide to verify your sending domain with DNS records.

Step 4: Send Your First Email

Use the Send endpoint to dispatch your first email. The request requires your server token for authentication and a JSON body with the recipient, subject, and HTML content.

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>"
  }'

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:

• 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.