Skip to main content

Sending Emails

Send personalized emails using your templates and configured email providers.

Single Email Sending​

Send an email to a single recipient:

POST /email/send
Content-Type: application/json
x-api-key: {your-api-key}

{
  "templateId": "template-uuid",
  "to": "user@example.com",
  "subject": "Welcome to Our Platform",
  "variables": {
    "firstName": "John",
    "companyName": "Nobu",
    "activationUrl": "https://app.example.com/activate?token=xyz"
  }
}

Response:

{
  "message": "Email sent successfully",
  "messageId": "msg-id"
}

Bulk Email Sending​

Send the same email to multiple recipients:

POST /email/send-bulk
Content-Type: application/json
x-api-key: {your-api-key}

{
  "templateId": "template-uuid",
  "subject": "Monthly Newsletter",
  "recipients": [
    "user1@example.com",
    "user2@example.com",
  ],
  "variables": {
    "companyName": "Nobu",
    "monthYear": "January 2024"
  }
}

Response:

{
  "message": "Bulk email processed: 2 sent, 0 failed",
  "success": true,
  "results": [
    {
      "recepient": "user1@example.com",
      "success": true,
      "messageId": "msg-id-1",
      "provider": "provider-used",
      "deliveryLogId": "delivery-log-uuid"
    },
    {
      "to": "user2@example.com",
      "success": true,
      "messageId": "msg-id-2",
      "provider": "provider-used",
      "deliveryLogId": "delivery-log-uuid"
    }
  ]
}

Required Fields​

  • templateId: UUID of the email template to use
  • to/recipients: Email address(es) of recipients
  • subject: Email subject line (optional if template has a subject, can be used to override template subject but required if template has no subject)
  • variables: Object containing template variables

Error Handling​

Common error responses:

Template Not Found​

{
  "error": "Template not found",
  "statusCode": 404
}

Provider Failure​

When all configured providers fail:

{
  "message": "All providers failed: provider specific error",
  "error": "Internal Server Error",
  "statusCode": 500
}

Provider Failover​

MessagePipe automatically attempts providers in priority order:

  1. Primary provider (priority 1) is tried first
  2. If it fails, secondary provider (priority 2) is attempted
  3. The process continues until it's successful or all providers are exhausted

This ensures reliable email delivery even when individual providers experience issues.