Email Notifications

Send transactional emails, marketing campaigns, and automated notifications via the Ping API.

The email model

The email notification model contains all the information about emails sent through the Ping platform.

Properties

Name
public_id
Type
string
Description
Unique identifier for the email notification.
Name
from
Type
string
Description
Sender email address (must be a verified domain).
Name
to
Type
array
Description
Array of recipient email addresses.
Name
subject
Type
string
Description
Email subject line.
Name
html
Type
string
Description
HTML email body content.
Name
text
Type
string
Description
Plain text email body content (fallback for clients that don't support HTML).
Name
status
Type
string
Description
Delivery status: sent, delivered, bounced, failed.
Name
message_id
Type
string
Description
Email provider message ID for tracking.
Name
created_at
Type
timestamp
Description
Timestamp of when the email was created.

POST/v1/notification/api/email/send

Send email

Send an email to one or multiple recipients. Supports both HTML and plain text content.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key with email permission.
Name
Content-Type
Type
string
Description
Must be application/json.

Required attributes

Name
from
Type
string
Description
Sender email address (must be from a verified domain).
Name
to
Type
array
Description
Array of recipient email addresses.
Name
subject
Type
string
Description
Email subject line.

Optional attributes

Name
html
Type
string
Description
HTML email body content.
Name
text
Type
string
Description
Plain text email body (recommended as fallback).
Name
template_id
Type
string
Description
Email template ID to use instead of providing HTML/text directly.
Name
template_data
Type
object
Description
Variables for template personalization.
Name
reply_to
Type
string
Description
Reply-To email address.
Name
cc
Type
array
Description
Carbon copy recipients.
Name
bcc
Type
array
Description
Blind carbon copy recipients.

Request

POST

/v1/notification/api/email/send

curl -X POST https://api.ping.co.zw/v1/notification/api/email/send \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Welcome to Our Service",
    "html": "<h1>Welcome!</h1><p>Thank you for signing up.</p>"
  }'

Response

{
  "result": "success",
  "message": "Email sent successfully",
  "message_id": "msg_abc123def456"
}

HTML vs plain text

Best Practices

Always provide both HTML and text versions of your email for maximum compatibility:

HTML: Rich formatting, images, links, branding
Text: Fallback for clients that block HTML or prefer plain text

HTML Email Tips

Use inline CSS - Many email clients strip <style> tags
Use tables for layout - Flexbox and Grid aren't widely supported
Test across clients - Gmail, Outlook, Apple Mail render differently
Keep images small - Large images may be blocked by default
Include alt text - For when images don't load

Example: Dual Format Email

Request with both formats

{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Order Confirmation #12345",
  "html": "<div style='font-family: Arial, sans-serif;'><h1 style='color: #333;'>Order Confirmed</h1><p>Thank you for your order <strong>#12345</strong>.</p><p>We'll send you shipping updates soon.</p></div>",
  "text": "Order Confirmed\n\nThank you for your order #12345.\n\nWe'll send you shipping updates soon."
}

GET/v1/notification/api/history/email

List email history

Retrieve a paginated list of emails sent through your account.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key.

Optional parameters

Name
skip
Type
integer
Description
Number of records to skip (default: 0).
Name
limit
Type
integer
Description
Maximum number of records to return (default: 50, max: 100).

Request

GET

/v1/notification/api/history/email

curl -G https://api.ping.co.zw/v1/notification/api/history/email \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -d limit=10 \
  -d skip=0

Response

{
  "result": "success",
  "notifications": [
    {
      "public_id": "email_abc123def456",
      "from": "[email protected]",
      "to": ["[email protected]"],
      "subject": "Order Confirmation #12345",
      "status": "delivered",
      "message_id": "msg_abc123def456",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

Domain Verification

Before sending emails, you must verify your domain in the Ping dashboard:

Add your domain (e.g., yourdomain.com)
Add DNS records (SPF, DKIM, DMARC) provided by Ping
Wait for verification (usually 24-48 hours)
Start sending from *@yourdomain.com

Verified domains ensure:

Higher deliverability rates
Lower spam scores
Better sender reputation
Professional branding