API Reference - Email Outbox

Link: https://support.brilliantdirectories.com/support/solutions/articles/12000108100

← Back to API Reference | Getting Started

Email Outbox

The Email Outbox queues outgoing emails before they are dispatched by the SMTP provider. Each record contains the full message payload including recipients, sender details, subject, HTML and plain-text content, and delivery status.

Model name in URL: email_outbox — DB table: email_outbox

The Email Outbox Object

FieldTypeDescription
outbox_idintegerUnique outbox record ID (primary key, read-only)
to_emailstringRecipient email address or addresses
from_emailstringSender email address
from_namestringSender display name
subjectstringEmail subject line
htmltextHTML body of the email (stored as binary blob)
texttextPlain-text body of the email (stored as binary blob)
digesttextHash or digest used to deduplicate outgoing messages
api_key_idstringSMTP API key or provider credential identifier used to send this message
statusstringSend status: pending, sent, failed
responsestringSMTP provider response message
paramstextJSON-encoded additional send parameters or metadata
send_datedatetimeScheduled send date and time
revision_timestampdatetimeTimestamp of the last record modification (auto-managed)
Known Issue: The html and text fields store compressed binary data internally. GET requests for records that contain email body content may return empty responses. Records created or updated via the API with plain-text values in these fields will work normally. This issue is being investigated.

List Email Outbox Records

GET /api/v2/email_outbox/get

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/email_outbox/get?limit=25" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "outbox_id": "1",
      "to_email": "recipient@example.com",
      "from_email": "hello@yourdomain.com",
      "from_name": "My Directory",
      "subject": "Welcome to our community",
      "html": "
Welcome! Thank you for joining.
",
      "text": "Welcome! Thank you for joining.",
      "digest": "",
      "api_key_id": "SG.abc123",
      "status": "sent",
      "response": "202 Accepted",
      "params": "",
      "send_date": "2024-04-01 12:00:00",
      "revision_timestamp": "2024-04-01 12:00:05"
    }
  ],
  "total": "250",
  "current_page": 1,
  "total_pages": 10,
  "next_page": "MipfKjI1"
}

Retrieve an Email Outbox Record

GET /api/v2/email_outbox/get/{outbox_id}

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/email_outbox/get/1" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "outbox_id": "1",
      "to_email": "recipient@example.com",
      "from_email": "hello@yourdomain.com",
      "from_name": "My Directory",
      "subject": "Welcome to our community",
      "html": "
Welcome! Thank you for joining.
",
      "text": "Welcome! Thank you for joining.",
      "digest": "",
      "api_key_id": "SG.abc123",
      "status": "sent",
      "response": "202 Accepted",
      "params": "",
      "send_date": "2024-04-01 12:00:00",
      "revision_timestamp": "2024-04-01 12:00:05"
    }
  ],
  "total": "250",
  "current_page": 1,
  "total_pages": 1
}

Create an Email Outbox Record

POST /api/v2/email_outbox/create

Example Request

Copy
curl -X POST "https://www.yourdomain.com/api/v2/email_outbox/create" \
  -H "X-Api-Key: your-api-key-here" \
  -d "to_email=recipient%40example.com" \
  -d "from_email=hello%40yourdomain.com" \
  -d "from_name=My+Directory" \
  -d "subject=Welcome+to+our+community" \
  -d "html=%3Cp%3EWelcome%21%3C%2Fp%3E" \
  -d "status=pending" \
  -d "send_date=2024-04-01+12%3A00%3A00"

Example Response

Copy
{
  "status": "success",
  "message": {
    "outbox_id": "251",
    "to_email": "recipient@example.com",
    "from_email": "hello@yourdomain.com",
    "from_name": "My Directory",
    "subject": "Welcome to our community",
    "html": "
Welcome!
",
    "text": null,
    "digest": null,
    "api_key_id": null,
    "status": "pending",
    "response": null,
    "params": null,
    "send_date": "2024-04-01 12:00:00",
    "revision_timestamp": null
  }
}

Update an Email Outbox Record

PUT /api/v2/email_outbox/update

Example Request

Copy
curl -X PUT "https://www.yourdomain.com/api/v2/email_outbox/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "outbox_id=251" \
  -d "status=sent" \
  -d "response=202+Accepted"

Example Response

Copy
{
  "status": "success",
  "message": {
    "outbox_id": "251",
    "to_email": "recipient@example.com",
    "status": "sent",
    "response": "202 Accepted",
    "revision_timestamp": "2024-04-01 12:05:00"
  }
}

Delete an Email Outbox Record

DELETE /api/v2/email_outbox/delete

Example Request

Copy
curl -X DELETE "https://www.yourdomain.com/api/v2/email_outbox/delete" \
  -H "X-Api-Key: your-api-key-here" \
  -d "outbox_id=251"

Example Response

Copy
{
  "status": "success",
  "message": "email_outbox record was deleted"
}