Getting Started with Transactional Emails: A Developer Guide

You need password resets, signup confirmations, and order receipts to leave your app. This guide gets you from zero to a working POST /v1/send call on OnePush.

Quick path: create a secret key (sk_), verify your domain, then send HTML or plain text with the REST API. Plans start at Starter for $20/month with 10,000 emails included.

What counts as transactional email

Transactional email is mail your product must send because a user did something: signed up, reset a password, paid an invoice. It is not a newsletter. Users expect it. If it fails, they open a support ticket or churn.

Step 1: Create an API key

Sign up at the OnePush dashboard. Open Settings → API Keys.

• Use a secret key (sk_) for sending email
• Use a public key (pk_) if you only need POST /v1/track from the browser or a less trusted client

Store the secret key in an environment variable. Never commit it.

Step 2: Verify your domain

Add your sending domain in the dashboard and publish SPF, DKIM, and DMARC DNS records. Production sends require a verified domain. Until that is done, treat any test as local only.

If you want the why behind those records, read our deliverability guide.

Step 3: Send your first email

OnePush is HTTP first. Any language that can call a REST API works. Here is a minimal Node example:

const response = await fetch('https://api.onepush.app/v1/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ONEPUSH_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: 'user@example.com',
    subject: 'Welcome',
    body: '<p>Thanks for signing up.</p>',
    // optional: from, name, reply, headers, attachments
  }),
});

if (!response.ok) {
  const err = await response.text();
  throw new Error(`Send failed: ${response.status} ${err}`);
}

Required fields: to, subject, body. Optional fields include from, name, reply, headers, and attachments. Full field list lives in the API reference.

Step 4: Prefer events for sequences

One-off receipts belong on /v1/send. Welcome series, reminders, and follow-ups belong on POST /v1/track so OnePush can run linked actions without your own cron layer.

curl -X POST https://api.onepush.app/v1/track \
  -H "Authorization: Bearer pk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "signup",
    "email": "user@example.com",
    "data": {
      "first_name": { "value": "Alex", "persistent": true }
    }
  }'

What usually goes wrong

• Sending with a public key instead of sk_ (send requires secret)
• Skipping domain verification
• Putting HTML in subject or forgetting to check non-2xx responses
• Building reminder cron jobs before you try /v1/track actions

Pricing note

Starter is $20/month for 10,000 emails, REST API access, webhooks, and event logs. Pro is $49/month for 100,000 emails plus unlimited social, unified campaigns, and forms. Details stay on OnePush pricing.

Next steps

• Wire webhooks for delivery and bounce events
• Read the Node.js Express integration for route-level patterns
• Open the documentation for contacts, templates, and forms