API v1.0

SendPigeon Documentation

Everything you need to send transactional emails. SDKs for Node.js, Python, Go, PHP and REST API.

Error Codes

HTTP status codes and error responses.

Status	Meaning	Resolution
400	Bad Request	Check request body format and required fields.
401	Unauthorized	Verify API key is valid and properly formatted.
402	Quota Exceeded	Upgrade your plan or wait for quota reset.
403	Domain Not Verified	Add DNS records for your sending domain.
404	Not Found	Check the resource ID exists.
429	Rate Limited	API: Max 100 req/min. New accounts: Max 20 emails/hour for first 7 days.
500	Server Error	Retry with exponential backoff.

Error Response

{
  "message": "Domain not verified. Add DNS records first.",
  "code": "DOMAIN_NOT_VERIFIED"
}

Code	Meaning
QUOTA_EXCEEDED	Monthly email limit reached
HOURLY_LIMIT_EXCEEDED	New accounts (< 7 days): 20 emails/hour limit. Includes retry info.
DOMAIN_NOT_VERIFIED	Domain needs DNS verification
SENDING_DISABLED	Account disabled (high bounce/complaint rate)
TEMPLATE_NOT_FOUND	Template ID doesn't exist
MISSING_VARIABLES	Required template variables not provided
ATTACHMENT_TOO_LARGE	Attachment exceeds 7MB or total exceeds 25MB
ATTACHMENT_FETCH_FAILED	Could not fetch attachment from URL
NOT_FOUND	Resource not found

Rate Limits

API Request Limit

100 requests/minute per API key. Headers included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

New Account Sending Limits

To prevent spam and protect deliverability, accounts less than 7 days old have temporary hourly sending limits:

Account Age	Hourly Limit	Monthly Quota
0-7 days (new)	20/hour	Plan quota applies
7+ days (established)	No hourly limit	Plan quota applies

Note: These limits apply automatically to all accounts. After 7 days and demonstrated good sending behavior (low bounce rate), hourly limits are removed.

Hourly Limit Headers

For new accounts, responses include hourly limit status:

X-RateLimit-Hourly-Limit: 20
X-RateLimit-Hourly-Remaining: 15
X-RateLimit-Hourly-Reset: 1709654400

Hourly Limit Error Response

When hourly limit is exceeded (429 status):

{
  "message": "Hourly limit exceeded. You can send 0 more emails this hour...",
  "code": "HOURLY_LIMIT_EXCEEDED",
  "hourly_limit": 20,
  "hourly_used": 20,
  "hourly_remaining": 0,
  "retry_after_seconds": 1800,
  "account_age_days": 2
}

Batch Send Validation

Batch requests are validated upfront. If your batch size exceeds your hourly remaining quota, the entire batch is rejected with a clear error message.