Email API Integration Guide

Quick Answer

The NexusProMail API is a REST API authenticated with a Bearer token. Send your API key in every request as Authorization: Bearer YOUR_API_KEY. Register webhooks to receive real-time delivery events. Implement exponential backoff for 429 responses. Use separate sending subdomains for transactional and marketing email.

Key Takeaways

• API keys belong in environment variables — never in source code or client-side JavaScript
• The sandbox key works immediately on signup; production requires DKIM/SPF domain verification
• Every webhook payload is HMAC-SHA256 signed — always verify the signature before processing
• 429 responses include a Retry-After header; use exponential backoff, not a fixed sleep
• Hard bounce webhooks should trigger immediate suppression in your own database
• Use separate sending subdomains for transactional and marketing email to isolate reputation
• The REST API is preferred over SMTP for all new integrations

Authentication

Every API request requires a Bearer token. Keys are scoped per account and can be rotated at any time.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

const crypto = require('crypto')

function verifyWebhookSignature(rawBody, sig, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex')
  // timingSafeEqual prevents timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(sig, 'hex')
  )
}

// Express — parse raw body for signature check
const rawParser = express.raw({
  type: 'application/json',
})

app.post('/webhooks/email', rawParser, (req, res) => {
  const sig = req.headers['x-nexuspromail-signature']
  const secret = process.env.WEBHOOK_SECRET
  const valid = verifyWebhookSignature(req.body, sig, secret)
  if (!valid) {
    return res.status(401).send('Bad signature')
  }
  const event = JSON.parse(req.body)
  // Handle event.type and event.data
  res.sendStatus(200)
})

Subdomain Sending Architecture

Always send email from a subdomain — never from your root domain. This protects your main domain’s reputation if deliverability problems occur.

Recommended architecture: separate subdomains for transactional and marketing email. Each has its own DKIM key, SPF record and sender reputation. Problems with one do not affect the other.