API: Send Email

Send one transactional email — an order confirmation, a password reset, a one-time code — from your own application. Write the message yourself with html / text, or send a saved template with merge-tag variables. Every call is recorded, so you can see exactly what happened to it under API Sends.

Your first email

The smallest valid call is a recipient, a subject and a body. With no from_email it sends from your account's own Pingovo address.

curl -X POST https://pingovo.com/api/v1/send \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Your order has shipped",
    "html": "<p>Hi Alex, your order #1042 is on its way.</p>",
    "tags": ["orders"]
  }'

Message

Grouping and tracking

Safety and pacing

Sending a saved template

Build the template in Templates, copy its id, and pass the merge-tag values in variables. Transactional mail never gets an unsubscribe footer appended.

curl -X POST https://pingovo.com/api/v1/send \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "from_email": "[email protected]",
    "from_name": "Acme Support",
    "templateId": "TEMPLATE_ID",
    "variables": { "firstName": "Alex", "orderNumber": "1042" }
  }'

Response

Open and click tracking

Tracking is off unless you ask. Turn on track_opens, track_clicks or both and each tracked email costs one flat tracking charge — the same whether you enable one or both. It appears as its own line in your credit history, and it is taken only for an email that was actually delivered.

• Tracking needs an html body (or an HTML template). Asking for it without one fails with 400 TRACKING_REQUIRES_HTML before anything is charged.
• If your balance cannot cover delivery and tracking, the call fails with 402 INSUFFICIENT_CREDITS. It is never silently downgraded to an untracked send.
• Open counts run high, because some mail apps pre-load images. Treat clicks as the more reliable engagement signal. Bots and prefetchers are filtered out of both.
• Click links always point to the destinations in your email — they cannot be redirected anywhere else.

Delivery controls in practice

This example paces sends 30 seconds apart, caps the account at 500 delivered emails a day, skips risky and role-based addresses, tracks opens and clicks, and handles the refusals. Set your HTTP client's timeout above 50 seconds when you use delay_between_emails — the call is held open while it waits.

curl --max-time 90 -i -X POST https://pingovo.com/api/v1/send \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Welcome aboard",
    "html": "<p>Welcome! <a href=\"https://example.com/start\">Get started</a></p>",
    "tags": ["onboarding"],
    "track_opens": true,
    "track_clicks": true,
    "delay_between_emails": 30,
    "daily_send_limit": 500,
    "skip_risky": true,
    "skip_role_based": true
  }'

What happens before a send

1. The request is validated. Any malformed field fails fast with a 400 and costs nothing.
2. The recipient is checked against your suppression list — addresses that bounced, unsubscribed or that you suppressed are never mailed (422).
3. Unless switched off, the recipient is verified. An invalid address is not sent to. The verification is charged even if it leads to a skip.
4. Your skip rules run (skip_risky, skip_role_based).
5. The credits for the send are reserved. If delivery then fails, they are returned in full.
6. The email is delivered, and you get the response above.

Refusals specific to /send

Every one of these — including calls refused before anything was sent — is recorded and visible under Dashboard → API Sends with its error code, so you can see why a call did nothing.