Messages API

The Messages API handles all AS2 message operations including sending, receiving, tracking, and payload management.

Table of Contents

• Send Message
• List Messages
• Get Message Details
• Download Message Payload
• Message Status Codes
• Error Codes

Send Message

Send an AS2 message to a trading partner.

POST /v1/messages

Request Parameters

Required Parameters

Optional Parameters

Request Examples

JSON Payload

{
  "partner_id": "prt_000001",
  "subject": "Purchase Order #PO-2024-001",
  "payload": {
    "content": "ISA*00*          *00*          *ZZ*SENDER         *ZZ*RECEIVER       *240115*1030*U*00401*000000001*0*T*>~",
    "filename": "po-2024-001.edi"
  },
  "content_type": "application/edi-x12",
  "headers": {
    "Document-Type": "PurchaseOrder",
    "Document-ID": "PO-2024-001"
  },
  "priority": "high",
  "compress": true
}

File Upload (multipart/form-data)

curl -X POST https://api.as2aas.com/v1/messages \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -F "partner_id=prt_000001" \
  -F "subject=Invoice #INV-2024-001" \
  -F "[email protected]" \
  -F "content_type=application/edi-x12" \
  -F "priority=normal"

Response

Success Response (202 Accepted)

{
  "message": "Message queued for delivery",
  "data": {
    "id": "msg_000001",
    "message_id": "MSG_20240115_103000_ABC123",
    "partner": {
      "id": "prt_000001",
      "name": "Acme Corporation",
      "as2_id": "ACME-CORP-AS2"
    },
    "status": "queued",
    "direction": "outbound",
    "subject": "Purchase Order #PO-2024-001",
    "content_type": "application/edi-x12",
    "bytes": 1024,
    "compressed": true,
    "encrypted": true,
    "signed": true,
    "mdn_mode": "async",
    "created_at": "2024-01-15T10:30:00.000000Z"
  }
}

List Messages

Retrieve paginated list of messages with optional filtering.

GET /v1/messages

Query Parameters

Response Schema

Message Object Fields

Get Message Details

Retrieve detailed information about a specific message.

GET /v1/messages/{message_id}

Path Parameters

Response

Success Response (200 OK)

{
  "data": {
    "id": "msg_000001",
    "message_id": "MSG_20240115_103000_ABC123",
    "partner": {
      "id": "prt_000001",
      "name": "Acme Corporation",
      "as2_id": "ACME-CORP-AS2",
      "url": "https://acme.example.com/as2"
    },
    "status": "delivered",
    "direction": "outbound",
    "from_as2_id": "YOUR-AS2-ID",
    "to_as2_id": "ACME-CORP-AS2",
    "subject": "Purchase Order #PO-2024-001",
    "content_type": "application/edi-x12",
    "bytes": 1024,
    "compressed": true,
    "encrypted": true,
    "signed": true,
    "mdn_mode": "async",
    "mdn_status": "received",
    "mdn_data": {
      "disposition": "automatic-action/MDN-sent-automatically; processed",
      "received_content_mic": "abc123def456ghi789jkl012mno345",
      "reporting_ua": "Acme AS2 Server/1.0",
      "original_message_id": "MSG_20240115_103000_ABC123"
    },
    "attempts": 1,
    "last_attempt_at": "2024-01-15T10:30:15.000000Z",
    "sent_at": "2024-01-15T10:30:15.000000Z",
    "delivered_at": "2024-01-15T10:30:45.000000Z",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:45.000000Z"
  }
}

Download Message Payload

Download the original message payload content.

GET /v1/messages/{message_id}/payload

Path Parameters

Response

Success Response (200 OK)

Returns the original payload content with appropriate Content-Type header.

Response Headers:

Message Status Codes

Status Progression

MDN Status Codes

Error Codes

Message-Specific Error Codes

Transmission Error Details

{
  "error": {
    "type": "transmission_error",
    "code": "PARTNER_UNREACHABLE",
    "message": "Cannot establish connection to partner endpoint",
    "details": {
      "partner_id": "prt_000001",
      "endpoint_url": "https://partner.example.com/as2",
      "timeout_seconds": 60,
      "last_attempt": "2024-01-15T10:30:00.000000Z",
      "error_details": "Connection timeout after 60 seconds"
    }
  }
}

Message Filtering

Advanced Filtering Options

Complex Query Example

GET /v1/messages?partner_id=prt_000001&status=delivered&from_date=2024-01-01T00:00:00Z&to_date=2024-01-31T23:59:59Z&encrypted=true&per_page=50

Payload Handling

Content Encoding

Content Type Mapping

Size Limitations

Message Security

Encryption Configuration

Signing Configuration

AS2 Protocol Details

AS2 Headers

MDN (Message Disposition Notification)

MDN Modes

MDN Data Structure

Webhook Integration

Message Events

Webhook Payload Structure

{
  "event": "message.delivered",
  "data": {
    "id": "msg_000001",
    "message_id": "MSG_20240115_103000_ABC123",
    "partner": {
      "id": "prt_000001",
      "name": "Acme Corporation",
      "as2_id": "ACME-CORP-AS2"
    },
    "status": "delivered",
    "direction": "outbound",
    "mdn_data": {
      "disposition": "automatic-action/MDN-sent-automatically; processed",
      "received_content_mic": "abc123def456ghi789",
      "reporting_ua": "Partner AS2 Server/2.1"
    },
    "delivered_at": "2024-01-15T10:30:45.000000Z"
  },
  "timestamp": "2024-01-15T10:30:45.000000Z",
  "api_version": "v1"
}

Performance Considerations

Request Optimization

Concurrent Requests

Integration Patterns

Synchronous Processing

// Direct message sending with immediate response
const response = await fetch('https://api.as2aas.com/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_live_your_api_key',
    'Content-Type': 'application/json',
    'Idempotency-Key': generateUUID()
  },
  body: JSON.stringify({
    partner_id: 'prt_000001',
    subject: 'Business Document',
    payload: { content: documentContent },
    content_type: 'application/edi-x12'
  })
});

const result = await response.json();

Asynchronous Processing

// Queue messages for processing with webhook notifications
async function queueMessage(messageData) {
  const response = await sendMessage(messageData);
  
  // Store message ID for tracking
  await storeMessageReference(response.data.id, messageData.reference);
  
  // Webhook will notify when delivered
  return response.data.id;
}

// Webhook handler for delivery notifications
app.post('/webhooks/as2', (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'message.delivered') {
    updateOrderStatus(data.id, 'delivered');
  }
  
  res.status(200).send('OK');
});