Incoming Mails

Base URL: /api/v1/incoming_mails

Auth required: Yes (auth:api) for all endpoints.

Incoming mails are email messages received by the system inbox. They can be converted to tickets or added as replies to existing tickets.

Model Properties

Incoming Mail

Incoming mails are receive-only: they cannot be created via the API. The API allows listing and deleting, or converting them to tickets/replies.

GET /v1/incoming_mails

List incoming mails, with optional filtering.

Query parameters:

Without a filter, returns all incoming mails paginated at 100 per page.

Response 200: Paginated list of incoming mail objects.

Examples:

curl -s -X GET "https://your-instance.bluerocktel.net/api/v1/incoming_mails?filter=out_ticket" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/incoming_mails",
    params={"filter": "out_ticket"},
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)
mails = response.json()

use Illuminate\Support\Facades\Http;

$response = Http::withToken($token)
    ->acceptJson()
    ->get('https://your-instance.bluerocktel.net/api/v1/incoming_mails', [
        'filter' => 'out_ticket',
    ]);

$mails = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/incoming_mails?filter=outTicket",
  {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
  }
);
const mails = await response.json();

DELETE /v1/incoming_mails/{incoming_mail}

Delete an incoming mail.

URL parameters:

Response 201: Success message. Response 404: Not found.

Examples:

curl -s -X DELETE "https://your-instance.bluerocktel.net/api/v1/incoming_mails/87" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.delete(
    "https://your-instance.bluerocktel.net/api/v1/incoming_mails/87",
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)

$response = Http::withToken($token)
    ->acceptJson()
    ->delete('https://your-instance.bluerocktel.net/api/v1/incoming_mails/87');

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/incoming_mails/87",
  {
    method: "DELETE",
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
  }
);

PUT /v1/incoming_mails/{incoming_mail}/ticket

Convert an incoming mail into a new ticket.

URL parameters:

Body (JSON):

Processing:

1. Creates a Contact if one does not already exist for the sender's email.
2. Creates a Ticket with the sanitized subject and body from the email.
3. Moves email attachments to the ticket.
4. Marks the mail as processed (ticket_id set, reply_to_closed_ticket = false).

Response 201: Created ticket object. Response 400: Validation error. Response 404: Mail or customer not found.

Examples:

curl -s -X PUT "https://your-instance.bluerocktel.net/api/v1/incoming_mails/87/ticket" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": 12}'

import requests

response = requests.put(
    "https://your-instance.bluerocktel.net/api/v1/incoming_mails/87/ticket",
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
    json={"customer_id": 12},
)
ticket = response.json()

$response = Http::withToken($token)
    ->acceptJson()
    ->put('https://your-instance.bluerocktel.net/api/v1/incoming_mails/87/ticket', [
        'customer_id' => 12,
    ]);

$ticket = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/incoming_mails/87/ticket",
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ customer_id: 12 }),
  }
);
const ticket = await response.json();

PUT /v1/incoming_mails/{incoming_mail}/reply

Add an incoming mail as a reply to an existing ticket (determined by the mail's ticket_id).

URL parameters:

Body: None. The ticket is inferred from the mail's ticket_id.

Processing:

1. Creates a Contact if needed.
2. Creates a Reply on the ticket.
3. Increments ticket exchange count.
4. Moves email attachments to the ticket.
5. Cancels any pending ticket closure.
6. Records a tracking event.

Response 201: Created reply (ticket) object. Response 404: Mail or ticket not found.

Examples:

curl -s -X PUT "https://your-instance.bluerocktel.net/api/v1/incoming_mails/87/reply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.put(
    "https://your-instance.bluerocktel.net/api/v1/incoming_mails/87/reply",
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)
reply = response.json()

$response = Http::withToken($token)
    ->acceptJson()
    ->put('https://your-instance.bluerocktel.net/api/v1/incoming_mails/87/reply');

$reply = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/incoming_mails/87/reply",
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
  }
);
const reply = await response.json();

Mailgun Webhook Endpoints

These endpoints receive Mailgun delivery event notifications. They do NOT require authentication.

Mail Report Webhook

POST /mail-report

Receive a mail delivery report from external mail systems.

Auth required: No.

Body: Mail report payload.