Quickstart

This guide takes you from nothing to a real email sent from your own domain.

1. Create an API key

   Open the dashboard, go to API keys and click Create API key. Choose full_access while you experiment. Copy the key right away: it starts with sp_live_ and is shown only once.

   export SPACEPOST_API_KEY="sp_live_YOUR_API_KEY"

   Caution

   Keep keys on the server. Never ship them in browser or mobile code. Create a sending_access key per service so you can revoke one without touching the others.

2. Send a test email

   You can send immediately, without a domain, using the shared test sender onboarding@test.spacepost.dev. It can only deliver to your own team members’ email addresses and to the test addresses such as delivered@test.spacepost.dev.

   Node.js

   npm install @spacepost/node

   send.ts

   import { SpacePost } from "@spacepost/node";
   
   const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);
   
   const { data, error } = await spacepost.emails.send({
     from: "Acme <onboarding@test.spacepost.dev>",
     to: ["delivered@test.spacepost.dev"],
     subject: "Hello from SpacePost",
     html: "<strong>It works!</strong>",
   });
   
   if (error) {
     console.error(error); // { statusCode, name, message }
   } else {
     console.log("Sent", data.id);
   }

   cURL

   curl -X POST https://api.spacepost.dev/emails \
     -H "Authorization: Bearer $SPACEPOST_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "from": "Acme <onboarding@test.spacepost.dev>",
       "to": ["delivered@test.spacepost.dev"],
       "subject": "Hello from SpacePost",
       "html": "<strong>It works!</strong>"
     }'

   Python

   import os
   import requests
   
   r = requests.post(
       "https://api.spacepost.dev/emails",
       headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
       json={
           "from": "Acme <onboarding@test.spacepost.dev>",
           "to": ["delivered@test.spacepost.dev"],
           "subject": "Hello from SpacePost",
           "html": "<strong>It works!</strong>",
       },
   )
   print(r.status_code, r.json())

   Go

   package main
   
   import (
     "fmt"
     "io"
     "net/http"
     "os"
     "strings"
   )
   
   func main() {
     body := `{"from":"Acme <onboarding@test.spacepost.dev>","to":["delivered@test.spacepost.dev"],"subject":"Hello from SpacePost","html":"<strong>It works!</strong>"}`
     req, _ := http.NewRequest("POST", "https://api.spacepost.dev/emails", strings.NewReader(body))
     req.Header.Set("Authorization", "Bearer "+os.Getenv("SPACEPOST_API_KEY"))
     req.Header.Set("Content-Type", "application/json")
     res, err := http.DefaultClient.Do(req)
     if err != nil {
       panic(err)
     }
     defer res.Body.Close()
     out, _ := io.ReadAll(res.Body)
     fmt.Println(res.StatusCode, string(out))
   }

   The response is { "id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10" }. Open the email in the dashboard to see its timeline: sent, then delivered.

3. Add and verify your domain

   To send to anyone, send from a domain you own.

   curl -X POST https://api.spacepost.dev/domains \
     -H "Authorization: Bearer $SPACEPOST_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "name": "acme.com" }'

   The response lists the DNS records to create: three DKIM CNAMEs, plus an MX and a TXT record for the send subdomain (the custom return path). Add them at your DNS provider (guides for Cloudflare, Route 53 and more), then ask SpacePost to check:

   curl -X POST https://api.spacepost.dev/domains/$DOMAIN_ID/verify \
     -H "Authorization: Bearer $SPACEPOST_API_KEY"

   Or let the CLI do the work and watch DNS live:

   npx spacepost domains doctor acme.com

   Verification usually completes within minutes. The domain status turns verified once DKIM is confirmed.

4. Send from your domain

   await spacepost.emails.send({
     from: "Acme <hello@acme.com>",
     to: ["you@example.com"],
     subject: "First real email",
     html: "<p>Sent from my own domain.</p>",
   });

New account limits

For the first 7 days a new account can send 100 emails per day. See Account sandbox.

What next

Language quickstartsNext.js, Express, Hono, Python, Go, PHP, Ruby, Rust and more.

Set up webhooksKnow when emails are delivered, bounce or are opened.

Deliverability best practicesReach the inbox, not the spam folder.