Skip to main content

Send Your First Letter

Send a test letter to verify your integration is working correctly.

Before You Begin​

Ensure you have completed:

Choose Your Method​

Select the integration method you've configured. We recommend starting with API Integration for most use cases.

API Integration​

Save as Draft:

curl -X PUT https://qa.sender.api.barid.ae/api/v1/letters/draft \
  -H "X-Session: YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Letter",
    "description": "This is a test letter",
    "genderTargeting": "All",
    "parts": [{
      "fileName": "document.pdf",
      "mimeType": "application/pdf",
      "base64Data": "BASE64_ENCODED_PDF"
    }]
  }'

Submit for Approval:

curl -X POST https://qa.sender.api.barid.ae/api/v1/letters/submit \
  -H "X-Session: YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Letter",
    "description": "This is a test letter",
    "genderTargeting": "All",
    "parts": [{
      "fileName": "document.pdf",
      "mimeType": "application/pdf",
      "base64Data": "BASE64_ENCODED_PDF"
    }]
  }'

Submitted letters are reviewed by Barid and typically approved or rejected within 12 hours.

For detailed request and response schemas, see the API Reference.

Response:

{
	"id": "123e4567-e89b-12d3-a456-426614174000",
	"status": "PendingApproval",
	"title": "Test Letter",
	"sender": { "companyNameEn": "Your Company" }
}

Update an Existing Letter (Keep or Replace Parts):

When updating a letter, the parts array controls which documents are attached. Each part can be either:

  • New upload: Provide fileName, mimeType, and base64Data
  • Existing part reference: Provide only id to keep an existing document
curl -X PUT https://qa.sender.api.barid.ae/api/v1/letters/draft \
  -H "X-Session: YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Updated Letter",
    "description": "This letter has been updated",
    "genderTargeting": "All",
    "parts": [
      { "id": "42" },
      {
        "fileName": "new-document.pdf",
        "mimeType": "application/pdf",
        "base64Data": "BASE64_ENCODED_PDF"
      }
    ]
  }'

In this example:

  • { "id": "42" } keeps the existing document with ID 42
  • The second object uploads a new document

To replace all documents, simply omit the existing part references and provide only new uploads.

Learn more about API Integration

Sender Client​

Send a test letter through the web interface.

Quick Test:

  1. Login to Sender Client

  2. Create New Letter

    • Click "Create Letter" button
    • Fill in letter details:
      • Title: Test Letter
      • Description: This is a test letter

  3. Upload PDF

    • Click "Upload PDF" or drag and drop
    • Select your test PDF document
    • Wait for upload confirmation

  4. Review and Submit

    • Preview letter details
    • Click "Submit for Approval"
    • Note the letter ID for tracking

Learn more about Sender Client

Email Integration​

Send a test letter via email.

Quick Test:

  1. Prepare Your Test PDF

    • Create or use an existing PDF document
    • Recommended: 1-2 pages for testing
    • Maximum file size: 10MB

  2. Compose Email

    TO: all.letter@qa.inbound.barid.ae
    FROM: your-verified-email@yourdomain.com
    SUBJECT: Test Letter - [Current Date]
    BODY: This is a test letter sent via email integration.
    ATTACHMENT: test-document.pdf

  3. Send Email

    • Send from your verified sender email address
    • Wait 30-60 seconds for processing

  4. Verify Receipt

    • Check webhook logs for processing confirmation
    • Letter status should be "PendingApproval"
    • Transaction ID returned in response

Learn more about Email Integration

Verify Letter Creation​

Check Letter Status​

Via API:

curl -X GET https://qa.sender.api.barid.ae/api/v1/letters/LETTER_ID \
  -H "X-Session: YOUR_SESSION_TOKEN"

Via Sender Client:

  1. Navigate to Letters list
  2. Find your test letter
  3. View status and details

Expected Status Flow​

  1. PendingApproval - Letter created, awaiting approval
  2. Approved - Letter approved for sending
  3. Sending - Letter being delivered to users
  4. Sent - Letter delivered successfully

Next Steps​

Once you've successfully sent a test letter:

  1. Review best practices
  2. Deep dive into your integration method:
  3. Set up production environment
  4. Configure monitoring and error handling
  5. Review compliance requirements

Support​

Need help with your first letter?