How to Send a Test Email

The fastest way to test your email setup: run the SendPigeon CLI, send an email from your code, and see it at localhost:4100. No real emails delivered, no accounts needed.

---

Option 1: Local Testing with the CLI

The fastest way to test during development. No emails leave your machine.

npx @sendpigeon-sdk/cli dev

This starts:

• Local SMTP server on localhost:4125
• Web UI at localhost:4100 to view captured emails

Now send an email from your app. With the SDK:

import { SendPigeon } from "sendpigeon";

const pigeon = new SendPigeon("sp_test_anything");

const { data, error } = await pigeon.send({
  from: "hello@yourdomain.com",
  to: "user@example.com",
  subject: "Test email",
  html: "<h1>It works!</h1><p>This is a test email.</p>",
});

if (error) {
  console.error("Send failed:", error.message);
} else {
  console.log("Email captured:", data.id);
}

Open localhost:4100 — your email appears instantly. You can inspect the HTML, headers, and metadata.

---

Option 2: Test API Key (Sandbox Mode)

Test API keys (starting with sp_test_) capture emails in the SendPigeon dashboard without delivering them. This is useful for:

• CI/CD pipelines
• Staging environments
• Testing email flows end-to-end without real delivery

SENDPIGEON_API_KEY=sp_test_your_key_here

Send emails normally — they show up in the Test tab of your dashboard. The API response is identical to production, so your code works the same way.

---

Option 3: Send a Live Test Email

To test real delivery, use a live API key and send to your own address:

import { SendPigeon } from "sendpigeon";

const pigeon = new SendPigeon(process.env.SENDPIGEON_API_KEY!);

const { data, error } = await pigeon.send({
  from: "hello@yourdomain.com",
  to: "your-real-email@gmail.com",
  subject: "Live test email",
  html: `
    <h1>Live Test</h1>
    <p>If you're reading this, your email setup works.</p>
    <p>Sent at: ${new Date().toISOString()}</p>
  `,
});

if (error) {
  console.error("Send failed:", error.message);
} else {
  console.log("Email sent:", data.id, "Status:", data.status);
}

Check your inbox (and spam folder). If the email lands in spam, you need to set up email authentication.

---

Send a Test Email with curl

Test the API directly without writing code:

curl -X POST https://api.sendpigeon.dev/v1/emails \
  -H "Authorization: Bearer sp_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": "test@example.com",
    "subject": "Test email from curl",
    "html": "<h1>Hello from curl!</h1>"
  }'

A successful response:

{
  "id": "em_abc123",
  "status": "queued"
}

---

Send a Test Email with Python

import os
from sendpigeon import SendPigeon

client = SendPigeon(os.environ["SENDPIGEON_API_KEY"])

result = client.send(
    from_="hello@yourdomain.com",
    to="test@example.com",
    subject="Test email from Python",
    html="<h1>Hello from Python!</h1>",
)

if result.error:
    print(f"Failed: {result.error.message}")
else:
    print(f"Sent: {result.data.id}")

---

Test Email Checklist

Before going to production, verify:

---

Troubleshooting

Email not appearing in the CLI

• Confirm the CLI is running: npx @sendpigeon-sdk/cli dev
• Check the web UI at localhost:4100
• If using SMTP, verify your app points to localhost:4125

API returns 401 Unauthorized

• Check your API key is correct and starts with sp_test_ or sp_live_
• Ensure the key is set in your environment: echo $SENDPIGEON_API_KEY

Email lands in spam

• Set up DKIM, SPF, and DMARC on your sending domain
• Use a custom domain, not a free email address as the from field
• Warm up your domain if it's new
• Review our deliverability checklist

Email not delivered (no bounce, no spam)

• Check the email status in the SendPigeon dashboard
• Look for suppressions — if the recipient previously bounced, they may be suppressed
• Verify the to address is correct

---

Frequently Asked Questions

How do I send a test email without hitting real inboxes?

Two options. For local development, run npx @sendpigeon-sdk/cli dev — all emails are caught at localhost:4100. For CI/staging, use a test API key (sp_test_) — emails are captured in the dashboard without delivery.

How do I test email in CI/CD?

Use a test API key (starts with sp_test_). Set it as a secret in your CI environment. Emails are captured in the SendPigeon dashboard but never delivered to real inboxes. You can verify delivery via the API.

Why is my test email going to spam?

Most likely missing email authentication. Set up DKIM, SPF, and DMARC on your sending domain. If your domain is new, warm it up gradually.

How do I send a test email with curl?

Send a POST to https://api.sendpigeon.dev/v1/emails with your API key as a Bearer token and the email payload as JSON. See the curl example above.

Can I preview what my email looks like before sending?

Yes. The SendPigeon CLI web UI at localhost:4100 renders your HTML exactly as it will appear. For designing templates, use our free visual email builder.

---

Next Steps

• Set up DKIM, SPF, and DMARC for your sending domain
• Set up local email testing for your team
• Review the email deliverability checklist
• Browse our email templates for ready-to-use HTML