Guides
Start typing to search…

Quick Start

This guide will help you send your first electronic letter via the STAMPEE API in minutes.

📘

Prerequisites

  • An approved STAMPEE reseller account
  • Your API token (generate from your dashboard or contact [email protected])
  • A tool to make API requests (cURL, Postman, or your preferred language)

Send Your First Message

Let's send a simple letter (LS) from your reseller account.

Step 1: Prepare Your Request

curl -X POST https://api.stampee.fr/messages/bulk_send \
  -H "X-API-TOKEN: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "LS",
    "body": "<p>Dear John,</p><p>This is your first electronic letter via STAMPEE!</p><p>Best regards</p>",
    "recipients": [
      {
        "email": "[email protected]",
        "firstname": "John",
        "lastname": "Doe"
      }
    ],
    "customerReference": "TEST-001"
  }'

Key parameters:

  • type: "LS" for simple letters or "LRE" for registered letters (requires mTLS)
  • body: HTML content for your message
  • recipients: Array of recipients (each gets an individual message)
  • customerReference: Optional reference to track this message in your system

Step 2: Get the Response

If successful, you'll receive a 201 Created response:

{
  "body": "<p>Dear John,</p><p>This is your first electronic letter via STAMPEE!</p><p>Best regards</p>",
  "createdAt": "2025-02-03T14:30:00.000Z",
  "type": "LS",
  "customerReference": "TEST-001",
  "fileReference": null,
  "messages": [
    {
      "id": "123456789012"
    }
  ]
}
✅

Success!

Save the 12-digit message id - you'll use it to track status and retrieve evidence documents.

Track Message Status

Use the message ID to check delivery status:

curl -X GET https://api.stampee.fr/messages/123456789012 \
  -H "X-API-TOKEN: YOUR_API_TOKEN"

Response:

{
  "id": "123456789012",
  "status": "RECEIVED",
  "evidences": [
    {
      "url": "https://storage.example.com/evidences/xxx.pdf?sig=abc",
      "eventType": "SENT"
    },
    {
      "url": "https://storage.example.com/evidences/xxx.pdf?sig=def",
      "eventType": "RECEIVED"
    }
  ]
}

The evidences array contains signed URLs to download PDF proof documents (valid for 24 hours).

Get Evidence Documents

Retrieve specific evidence by event type:

curl -X GET https://api.stampee.fr/messages/123456789012/evidences/SENT \
  -H "X-API-TOKEN: YOUR_API_TOKEN"

Available evidence types:

  • SENT - Proof the message was sent
  • RECEIVED - Proof recipient opened it (LS only)
  • ACCEPTED - Proof recipient accepted it (LRE only)
  • REFUSED - Proof recipient refused it (LRE only)
  • EXPIRED - Proof message expired
  • UNDELIVERED - Proof email was undeliverable

Common Scenarios

Send to Multiple Recipients

{
  "type": "LS",
  "body": "<p>Monthly newsletter content...</p>",
  "recipients": [
    {
      "email": "[email protected]",
      "firstname": "Alice",
      "lastname": "Smith"
    },
    {
      "email": "[email protected]",
      "firstname": "Bob",
      "lastname": "Johnson"
    }
  ]
}

Each recipient gets their own message with a unique ID.

Send to a Company

Use company and companySiren instead of firstname and lastname:

{
  "type": "LS",
  "body": "<p>Dear Acme Corp,</p><p>Your invoice is attached.</p>",
  "recipients": [
    {
      "email": "[email protected]",
      "company": "Acme Corporation",
      "companySiren": "123456789"
    }
  ]
}
⚠️

Recipient Requirements

Each recipient must include EITHER:

  • Natural person: email, firstname, lastname
  • Legal person: email, company, companySiren (9-digit SIREN)

Add File Attachments

Switch to multipart/form-data:

curl -X POST https://api.stampee.fr/messages/bulk_send \
  -H "X-API-TOKEN: YOUR_API_TOKEN" \
  -F 'type=LS' \
  -F 'body=<p>Please find the attached documents.</p>' \
  -F 'recipients=[{"email":"[email protected]","firstname":"John","lastname":"Doe"}]' \
  -F 'attachments=@/path/to/document.pdf' \
  -F 'attachments=@/path/to/invoice.pdf'

Attachment limits:

  • Maximum 250MB
  • Multiple attachments supported

Reseller Workflow: Managing Customers

As a reseller, you can send messages on behalf of your customers.

Step 1: Create a Customer

curl -X POST https://api.stampee.fr/customers/bulk_store \
  -H "X-API-TOKEN: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customers": [
      {
        "name": "Acme Corporation",
        "email": "[email protected]",
        "isPaying": true,
        "willSendLre": false
      }
    ]
  }'

Response:

{
  "customers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Corporation",
      "email": "[email protected]",
      "isPaying": true,
      "willSendLre": false,
      "state": "PENDING",
      "createdAt": "2025-02-03T14:30:00.000Z"
    }
  ]
}
📧

Delegation Request Sent

The customer receives an email to accept your management. They must accept before you can send messages on their behalf.

Step 2: Check Customer Status

curl -X GET https://api.stampee.fr/customers \
  -H "X-API-TOKEN: YOUR_API_TOKEN"

Filter by accepted customers:

curl -X GET "https://api.stampee.fr/customers?state=ACCEPTED" \
  -H "X-API-TOKEN: YOUR_API_TOKEN"

Customer states:

  • PENDING - Awaiting acceptance
  • ACCEPTED - Ready to send messages
  • REFUSED - Customer refused delegation
  • REVOKED - Customer revoked delegation
  • CANCELLED - You cancelled delegation

Step 3: Send on Behalf of Customer

Once state is ACCEPTED, include the sender parameter:

curl -X POST https://api.stampee.fr/messages/bulk_send \
  -H "X-API-TOKEN: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "LS",
    "sender": "550e8400-e29b-41d4-a716-446655440000",
    "body": "<p>Message sent on behalf of Acme Corporation.</p>",
    "recipients": [
      {
        "email": "[email protected]",
        "firstname": "Jane",
        "lastname": "Smith"
      }
    ]
  }'
⚠️

Important

Always include the sender parameter (customer ID) when sending on behalf of a customer. Without it, messages are sent from your reseller account.

Error Handling

Invalid Recipients (422)

{
  "message": "Some recipients are incomplete or incorrect",
  "code": "message-bad-contacts"
}

Fix: Ensure each recipient has either (firstname + lastname) or (company + companySiren).

Customer Not Found (422)

{
  "message": "Customer not found",
  "code": "customer-not-found"
}

Fix: Verify the customer ID in sender parameter exists.

Customer Not Accepted (422)

{
  "message": "Customer is not registered",
  "code": "customer-not-registered"
}

Fix: Wait for customer to accept delegation. Check status via GET /customers.

Unauthorized (401)

{
  "message": "Unauthorized access",
  "code": "unauthorized"
}

Fix: Verify your API token is correct in the X-API-TOKEN header.

Quick Reference

Base URL: https://api.stampee.fr

Authentication: X-API-TOKEN: your_api_token

Key Endpoints:

  • Send messages: POST /messages/bulk_send
  • Get message: GET /messages/{id}
  • Get evidence: GET /messages/{id}/evidences/{status}
  • Create customers: POST /customers/bulk_store
  • List customers: GET /customers

Next Steps

Need Help?

Updated about 23 hours ago