API-First Email: Building Modern Applications

Email for the Modern Developer

Building applications that send and receive email shouldn't require a PhD in SMTP. CalimaticMail's API-first approach makes email integration straightforward.

Why API-First?

Traditional email integration involves:

• Setting up SMTP servers
• Managing complex authentication
• Handling bounces and complaints
• Dealing with deliverability issues

Our API abstracts this complexity, letting you focus on your application.

Getting Started

Authentication

All API requests require a Bearer token:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.calimatic.app/v1/messages

Sending an Email

const response = await fetch('https://api.calimatic.app/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: ['[email protected]'],
    subject: 'Hello from CalimaticMail',
    html: '<h1>Welcome!</h1><p>This is a test email.</p>',
    text: 'Welcome! This is a test email.'
  })
});

Receiving Emails via Webhooks

Configure webhooks to receive real-time notifications:

// Your webhook endpoint
app.post('/webhooks/email', (req, res) => {
  const { event, data } = req.body;

  switch (event) {
    case 'email.received':
      console.log('New email from:', data.from);
      break;
    case 'email.delivered':
      console.log('Email delivered to:', data.to);
      break;
    case 'email.bounced':
      console.log('Bounce:', data.bounceType);
      break;
  }

  res.status(200).send('OK');
});

Common Use Cases

Transactional Emails

Send password resets, order confirmations, and notifications:

await calimatic.send({
  to: user.email,
  template: 'password-reset',
  data: {
    resetLink: generateResetLink(user.id),
    expiresIn: '24 hours'
  }
});

Email Parsing

Extract data from incoming emails for automation:

webhook.on('email.received', async (email) => {
  if (email.subject.includes('Order #')) {
    const orderNumber = parseOrderNumber(email.subject);
    await processOrder(orderNumber, email.body);
  }
});

Rate Limits & Best Practices

| Plan | Requests/minute | Emails/hour | |------|-----------------|-------------| | Starter | 60 | 1,000 | | Business | 300 | 10,000 | | Enterprise | Custom | Custom |

Best Practices:

• Use exponential backoff for retries
• Batch operations when possible
• Cache frequently accessed data
• Monitor your usage dashboard

SDKs & Libraries

Official SDKs available for:

• JavaScript/TypeScript
• Python
• Ruby
• Go
• PHP

npm install @calimatic/sdk

View API Documentation