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 a compressed binary blob; API responses return it base64-encoded — base64-decode, then zlib-decompress (PHP gzuncompress()) to read the original HTML
texttextPlain-text body of the email. Stored as a compressed binary blob; API responses return it base64-encoded — base64-decode, then zlib-decompress to read the original text
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)
Reading email bodies: The html and text fields store zlib-compressed binary data internally. API responses return them base64-encoded so records with body content serialize correctly. To read the original content: base64-decode the value, then zlib-decompress it (PHP gzuncompress(), or zlib inflate in other languages). Values written through the API as plain text are stored and returned the same way.

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