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"
  }
}

When using JWT authentication instead of an API key, include projectId in the request body.

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": [
    {
      "recipient": "user1@example.com",
      "success": true,
      "messageId": "msg-id-1",
      "provider": "sendgrid",
      "deliveryLogId": "delivery-log-uuid"
    },
    {
      "recipient": "user2@example.com",
      "success": true,
      "messageId": "msg-id-2",
      "provider": "sendgrid",
      "deliveryLogId": "delivery-log-uuid"
    }
  ]
}

Retrying Failed Emails​

If an email fails to deliver, you can retry it using its delivery log ID.

Retry a Single Email​

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

{
  "deliveryLogId": "delivery-log-uuid"
}

Response:

{
  "message": "Email added to retry queue successfully"
}

Retry Multiple Emails​

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

{
  "deliveryLogIds": [
    "delivery-log-uuid-1",
    "delivery-log-uuid-2"
  ]
}

Response:

{
  "message": "Emails processed for retry"
}

You can get delivery log IDs from the Delivery Logs endpoint.

Email Queue Statistics​

Get statistics on the current state of the email processing queue:

GET /email/queue-stats
x-api-key: {your-api-key}

Response:

{
  "pending": 12,
  "processing": 3,
  "failed": 1,
  "completed": 4523
}

Required Fields​

  • templateId: UUID of the email template to use
  • to / recipients: Email address(es) of the recipient(s)
  • variables: Object containing template variable values
  • subject: Optional. It overrides the template subject if provided; required if the template has no subject set

Error Handling​

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 successful delivery or all providers are exhausted

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