Skip to main content

Quick Start

Send your first email with Sendmator in under 5 minutes. This guide will walk you through the basics.

Prerequisites​

  • Sendmator account with API key
  • Ability to make HTTP requests (cURL, Postman, or any HTTP client)

Send Your First Email​

Using cURL​

curl -X POST https://api.sendmator.com/v1/emails \
  -H "X-API-Key: $SENDMATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "from": "hello@yourapp.com",
    "subject": "Welcome to our app!",
    "html": "<h1>Welcome!</h1><p>Thanks for signing up. We'\''re excited to have you on board.</p><a href=\"https://yourapp.com/dashboard\">Get Started</a>"
  }'

Success Response​

When your email is sent successfully, you'll receive a response like this:

{
  "id": "msg_abc123",
  "status": "queued",
  "to": "recipient@example.com",
  "from": "hello@yourapp.com",
  "subject": "Welcome to our app!",
  "created_at": "2024-01-15T10:30:00Z"
}

Send Email with Template​

For more complex emails, use templates:

curl -X POST https://api.sendmator.com/v1/emails \
  -H "X-API-Key: $SENDMATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "template": "welcome-email",
    "template_data": {
      "user_name": "John Doe",
      "app_name": "YourApp", 
      "dashboard_url": "https://yourapp.com/dashboard"
    }
  }'

Error Handling​

When errors occur, the API returns appropriate HTTP status codes and error details:

# Example error response (400 Bad Request)
{
  "error": {
    "type": "validation_error",
    "message": "Invalid email address",
    "details": {
      "field": "to",
      "code": "invalid_email"
    }
  }
}

Track Email Status​

Check the status of your sent emails:

curl -H "X-API-Key: $SENDMATOR_API_KEY" \
     https://api.sendmator.com/v1/emails/msg_abc123

Response includes status and event history:

{
  "id": "msg_abc123",
  "status": "delivered",
  "events": [
    {"type": "queued", "timestamp": "2024-01-15T10:30:00Z"},
    {"type": "sent", "timestamp": "2024-01-15T10:30:15Z"},
    {"type": "delivered", "timestamp": "2024-01-15T10:30:45Z"}
  ]
}

Possible statuses: queued, sent, delivered, opened, clicked, bounced, failed

Common Patterns​

Bulk Email Sending​

For multiple emails, make individual API calls:

# Send multiple emails with a simple script
for email in user1@example.com user2@example.com user3@example.com; do
  curl -X POST https://api.sendmator.com/v1/emails \
    -H "X-API-Key: $SENDMATOR_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"to\": \"$email\", \"from\": \"hello@yourapp.com\", \"subject\": \"Hello\", \"html\": \"<p>Hello from our app!</p>\"}"
done

Using Webhooks​

Set up webhooks to receive real-time notifications:

// In your webhook endpoint
app.post('/webhooks/sendmator', (req, res) => {
  const event = req.body;
  
  switch (event.type) {
    case 'email.delivered':
      console.log(`Email ${event.data.id} was delivered`);
      break;
    case 'email.opened':
      console.log(`Email ${event.data.id} was opened`);
      break;
    case 'email.clicked':
      console.log(`Email ${event.data.id} had a link clicked`);
      break;
  }
  
  res.status(200).send('OK');
});

What's Next?​

Now that you've sent your first email, explore these features:

Need Help?​