Introduction

Welcome to the MySendingBox API ! You can use our API to access MySendingBox API endpoints, which let you send physical mail or postcard with a simple HTTP request.

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

If you have any question don't hesitate to contact us from your MySendingBox API Dashboard or by sending us an email.

Postman

Click on this button to open the Postman Collection and start testing the MySendingBox API.

Libraries

Visit our GitHub to check our supported wrappers :

Available Endpoint

Method	Endpoint	Action
`GET`	https://api.mysendingbox.fr/	Ping the API
	Letters API
`POST`	https://api.mysendingbox.fr/letters	Create and send a letter
`GET`	https://api.mysendingbox.fr/letters	Get all letters for the authenticated user
`GET`	https://api.mysendingbox.fr/letters/1234	Get a specific letter
`POST`	https://api.mysendingbox.fr/letters/price	Get price for a letter
	Postcards API - Beta
`POST`	https://api.mysendingbox.fr/postcards	Create and send a postcard
`GET`	https://api.mysendingbox.fr/postcards	Get all postcards for the authenticated user
`GET`	https://api.mysendingbox.fr/postcards/1234	Get a specific postcard
	Accounts API
`POST`	https://api.mysendingbox.fr/accounts	Create a new account company
`PUT`	https://api.mysendingbox.fr/accounts/1234	Update the email of an account company
	Invoices API
`GET`	https://api.mysendingbox.fr/invoices	Get all invoices for the authenticated company
`GET`	https://api.mysendingbox.fr/invoices/1234	Get a specific invoice

Authentication

To authorize, use this code:

# With shell, you can just pass the correct username with each request
curl "https://api.mysendingbox.fr/" \
  -u "test_12345678901234567890:"

var Seeuletter = require('seeuletter')('test_12345678901234567890')

<?php
  require 'vendor/autoload.php';
  $seeuletter = new \Seeuletter\Seeuletter('test_12345678901234567890');
?>

require 'seeuletter'
eeuletter = Seeuletter::Client.new(api_key: 'test_12345678901234567890')

import seeuletter
seeuletter.api_key = 'test_12345678901234567890'

Make sure to replace test_12345678901234567890 with your API key.

MySendingBox uses API keys to allow access to the API. You can register a new MySendingBox API key at our developer portal.

MySendingBox expects for the API key to be included in all API requests to the server with Basic Auth where the username is your API key (no password necessary).

VERY IMPORTANT INFO

You must use the live API key to actually send the letter or postcard. Use the test API key to preview the rendered PDF. With the test API key the letter or the postcard is not send.

You must replace test_12345678901234567890 with your personal API key.

Cancellation Window

By default, all new accounts have a 15 minute cancellation window for postcards and letters. Within that timeframe, you can cancel a letter or a postcard from production, free of charge. Once the window has passed for a postcard or a letter, the mailing is no longer cancelable.

You can edit your cancellation window by product in your Dashboard Settings.

For more details on this feature, see our Cancellation Guide.

Cancel a postcard
Cancel a letter

Idempotent Requests

POST https://api.mysendingbox.fr/letters

Example Request with an Idempotency-Key header

curl -X POST "https://api.mysendingbox.fr/letters" \
  -u "test_12345678901234567890:" \
  -H "Idempotency-Key: 9d115c93-42a9-4579-bef4-fd57adc05dd1" \
  -d '{
   "to": {
    "name": "MySendingBox",
    "address_line1": "30 rue de la république",
    "address_city": "Paris",
    "address_postalcode": "75015",
    "address_country": "France"
   },
   "color" : "color",
   "postage_type" : "prioritaire",
   "source_file": "<html style=\"padding-top: 3px; margin: 0.5px;\">Lettre HTML for {{name}}<\/html>",
   "source_file_type": "html"
}'

MySendingBox supports idempotency for safely retrying POST requests to create postcards, and letters without accidentally creating duplicates.

For example, if a request to create a letter fails due to a network error, you can safely retry the same request with the same idempotency key and guarantee that only one check will ultimately be created and sent. When a request is sent with an idempotency key for an already created resource, the response object for the existing resource will be returned.

To perform an idempotent POST request to one of the two product endpoints, provide an additional Idempotency-Key header to the request. How you create unique keys is up to you, but we suggest using random values, such as V4 UUIDs. Idempotency keys are intended to prevent issues over a short periods of time, therefore keys expire after 24 hours.Keys are unique by mode (Test or Live) as well as by resource (postcard or letter).

By default, all GET and DELETE requests are idempotent by nature, so they do not require an additional idempotency key.

Package to generate V4 UUIDs for various languages :

Letters

Letter object

An letter object is structured like this

{
    "_id": "HJvwBdY7Z",
    "description": "Demo Letter 1",
    "created_from": "api",
    "object": "letter",
    "user": "HJRWFavX=",
    "channel": "paper",
    "page_count": 1,
    "sheet_count": 1,
    "pdf_margin": 0,
    "postage_speed" : "d1",
    "manage_delivery_proof" : false,
    "manage_returned_mail" : false,
    "envelope_window" : "simple",
    "mail_provider" : "A",
    "send_date" : "2017-06-22T10:00:00.000Z",
    "tracking_number" : "AZ59302348DE",
    "mode": "test",
    "color": "color",
    "postage_type": "prioritaire",
    "print_sender_address" : false,
    "staple" : false,
    "address_placement": "first_page",
    "both_sides" : true,
    "envelope": "c6",
    "error" : false,
    "wrong_address" : false,
    "price": {
      "pack": "business",
      "postage": 0.567,
      "service": 0.48,
      "total": 1.047
    },
    "variables": {
      "name": "MySendingBox"
    },
    "from": {
      "company": "MySendingBox.fr",
      "address_line1": "222 rue terradou",
      "address_city": "Carpentras",
      "address_postalcode": "84200",
      "address_country": "France"
    },
    "to": {
      "name": "Erlich Bachman",
      "address_line1": "30 rue de Rivoli",
      "address_city": "Paris",
      "address_postalcode": "75004",
      "address_country": "France"
    },
    "file": {
      "url": "https://lifebot.s3.amazonaws.com/v4/files/user_HJRWFavX%3D/letter_SkZkonqQZ.pdf?AWSAccessKeyId=AKIAIVWGUB33FDOLMQ4A&Expires=1498234466&Signature=uCweBZkmLyEv0jakZrJgxvTaGGE%3D",
      "_id": "SJgZksh9mb",
      "updated_at": "2017-06-23T15:59:26.467Z",
      "created_at": "2017-06-23T15:59:26.467Z",
      "user": "HJRWFavX=",
      "letter": "SkZkonqQZ",
      "path": "v4/files/user_HJRWFavX=/letter_SkZkonqQZ.pdf",
      "page_count": 1
    },
    "delivery_proof" : {
      "url": "https://lifebot.s3.amazonaws.com/v4/files/user_HJRWFavX%3D/letter_SkZkonqQZ.pdf?AWSAccessKeyId=AKIAIVWGUB33FDOLMQ4A&Expires=1498234466&Signature=uCweBZkmLyEv0jakZrJgxvTaGGE%3D",
      "_id": "SJgZksh9mb",
      "updated_at": "2017-06-23T15:59:26.467Z",
      "created_at": "2017-06-23T15:59:26.467Z",
      "user": "HJRWFavX=",
      "letter": "SkZkonqQZ",
      "path": "v4/files/user_HJRWFavX=/letter_SkZkonqQZ.pdf"
    },
    "events": [
      {
        "_id": "r1EU2VpFAf",
        "name": "letter.created",
        "letter" : "HJvwBdY7Z",
        "user": "HJRWFavX=",
        "description": "This letter has been created.",
        "created_at": "2017-06-22T16:50:44.555Z",
        "updated_at": "2017-06-22T16:50:44.555Z",
        "webhook_failed": false,
        "webhook_called": false
      }
    ],
    "tracking_events": [],
    "metadata" : {},
    "updated_at": "2017-06-22T16:50:44.568Z",
    "created_at": "2017-06-22T16:50:44.568Z",
    "billingAccountAllocationKeys": {
      "service": "aO2v3P6KpbMY2FiLz8LDo",
      "postage": "4hC94vcCRgw4jYsinaMrs",
    }
}

Parameter	Description
_id	id of the letter. Use it to retrieve a specific letter with the GET /letters/`ID`
channel	Sending channel for the letter. Can be `paper` or `electronic`. Default `paper`.
price	A object with sub items `pack`, `postage`, `service` and `total` containing the price of this letter. The price is based on the pack used the previous month. It can change if you send more than 100 or 1000 letters.
from	An Address object
to	An Address object
page_count	Number of page on this letter For channel `electronic`, the value is 0
sheet_count	Number of sheet on this letter (1 sheet = 2 pages when `both_sides` : `true`) For channel `electronic`, the value is 0
file	A File object Caution : The address zone and the datamatrix is faked to help you imagine how the printed document will be. The numbers and the barcode are faked. See "Zones d'écrasements" for more info.
source_file_type	Can be `file`, `template_id`, `remote` or `html`
mode	In test the letter is not send. In live, it's send : `test` or `live`
color	Black & white or Color : `bw` or `color` For channel `electronic`, the value is `none`
both_sides	If the letter must be printed using both sides`true` or `false` For channel `electronic`, the value is `false`
postage_type	Type of postage. For channel `paper`, can be : `ecopli` `prioritaire` `lr` `lrar` For channel `electronic`, can be `ere`, `lre` or `email`
postage_speed	Can be : `express`, `D`, `D1`. See "Vitesse de traitement" for more info. For channel `electronic`, the value is `none`
pdf_margin	Margin applied to every borders of the document. It's a number in pixel.
manage_delivery_proof	Can be `true` (The delivery proof is handle by the API and available in the `delivery_proof`object 5-10 days after the `letter.distributed` event) or `false` (Delivery proof send by physical mail to sender).
manage_returned_mail	Can be `true` : an event (`letter.wrong_address`) will be send by webhook if the letter can't be distributed because the address is wrong (NPAI - N'habite pas à l'adresse indiquée). Or `false`
envelope_window	Can be `simple` (only one window on the envelope for the recipient address) or `double` (a window for the recipient address and an other window at the top left corner of the envelope) For channel `electronic`, the value is `none`
mail_provider	For channel `paper`, can be `A` or `B`. For channel `electronic`, can be `equisign`, `ar24` or `postmark`
print_sender_address	A Boolean. Should the `from` address be printed on the letter. See "Zones d'écrasements" for more info.
address_placement	Can be `first_page` or `insert_blank_page`. If `first_page` the address will be write on the first page of your document. Follow the guide ("Zones d'écrasements") to know where to leave some space. If `insert_blank_page` a new blank page will be inserted and the address will be write on it. This page will be charged. Careful : Nothing will be print in the back face of this page even if both_sides is true. For channel `electronic`, the value is `none`
envelope	Can be `c4` or `c6`. If their is more that 4 sheets with `postage_speed : express` or more than 6 sheets with `postage_speed : D or D1`, the envelope will be a C4. You can force a C4 envelope for less than 4 sheets if you don't want your letter to be fold by passing `c4` as parameter. If `postage_speed : express`, when envelope is `c4` (chosen in the api or forced by the number of sheets) a blank page will be added like if the `address_placement` parameter was set to `insert_blank_page`. For channel `electronic`, the value is `none`
staple	Can be `true` or `false`. Used to staple all sheets together.
send_date	The date at which the letter must be send. Based on the chosen value on the dashboard (https://app.mysendingbox.fr/account)
delivery_proof	A File object
filing_proof	A File object
lost_proof	A File object Proof if the letter is lost.
return_to_sender_proof	A File object Proof if the letter is returned to the sender.
download_proof	A File object Only set for channel `electronic`
rejection_proof	A File object Only set for channel `electronic`
negligence_proof	A File object Only set for channel `electronic`
tracking_events	An array of Tracking Events object
tracking_number	A number assigned by La Poste use to track the letter
events	An array of Event object
created_at	Date of creation
updated_at	Date of last update
user	Id of the owner of the letter
error	`true` if the letter is an error state
wrong_address	`true` if the letter can't be distributed because of a bad address. (NPAI - N'habite pas à l'adresse indiquée)
created_from	Indicate if this letter has been created from the `api` or from the `dashboard`
object	`letter`
description	Description of the letter. Set by you.
content	Only set for channel `electronic` and if `postage_type` is `email`. Body content of the email.
content_type	Only set for channel `electronic`. Body content type for the email. Can be `text` or `html`.
term_of_use_validation	Only set for channel `electronic`. `true` if the user accepted the website terms of use (dashboard only).
metadata	An object. Set by you.
variables	Object used to add variables to a HTML template
billingAccountAllocationKeys	Allows you to allocate service charges and postage costs to different billing accounts. This parameter is restricted. Contact-us for access. An BillingAccountAllocationKeys object

Send a new Letter

POST https://api.mysendingbox.fr/letters

Example Request with an HTML string

curl -X POST "https://api.mysendingbox.fr/letters" \
  -u "test_12345678901234567890:" \
  -H 'Content-Type: application/json' \
  -d '{
   "description": "Demo Letter 1",
   "to": {
    "name": "MySendingBox",
    "address_line1": "30 rue de la république",
    "address_city": "Paris",
    "address_postalcode": "75015",
    "address_country": "France"
   },
   "color" : "color",
   "postage_type" : "prioritaire",
   "from": {
    "name": "MySendingBox",
    "address_line1": "30 rue de la république",
    "address_city": "Paris",
    "address_postalcode": "75015",
    "address_country": "France"
   },
   "source_file": "<html style=\"padding-top: 3px; margin: 0.5px;\">Lettre HTML for {{name}}<\/html>",
   "source_file_type": "html",
   "variables" : {
    "name" : "MySendingBox"
   }
}'

var Seeuletter = require('seeuletter')('test_12345678901234567890')

Seeuletter.letters.create({
   "description": "Demo Letter 1",
   "color" : "color",
   "postage_type" : "prioritaire",
   "postage_speed" : "D1",
   "to": {
    "name": "SEEULETTER",
    "address_line1": "30 rue de la république",
    "address_city": "Paris",
    "address_postalcode": "75015",
    "address_country": "France"
   },
   "source_file": "<html style=\"padding-top: 3px; margin: 0.5px;\">Lettre HTML for {{name}}<\/html>",
   "source_file_type": "html",
   "variables" : {
    "name" : "Seeuletter"
   }
}, function(err, response){
  if(err) console.log('err : ', err)
  console.log('response : ', response)
})

<?php
require 'vendor/autoload.php';

$seeuletter = new \Seeuletter\Seeuletter('test_12345678901234567890');

$to_address = array(
  'name'                  => 'Seeuletter',
  'address_line1'         => '30 rue de rivoli',
  'address_line2'         => '',
  'address_city'          => 'Paris',
  'address_country'       => 'France',
  'address_postalcode'    => '75004'
);

$letter = $seeuletter->letters()->create(array(
  'to'                  => $to_address,
  'source_file'         => '<html>HELLO</html>',
  'description'         => 'Test Letters',
  'color'               => 'bw',
  'source_file_type'    => 'html',
  'postage_type'        => 'prioritaire'
));

print_r($letter);
?>

require 'seeuletter'

seeuletter = Seeuletter::Client.new(api_key: 'test_12345678901234567890')

puts seeuletter.letters.create(
  description: "Test letter from the Ruby Wrapper",
  to: {
    name: 'Erlich',
    address_line1: '30 rue de rivoli',
    address_line2: '',
    address_city: 'Paris',
    address_country: 'France',
    address_postalcode: '75004'
  },
  source_file: '<html>HELLO {{name}}</html>',
  source_file_type: 'html',
  postage_type: 'prioritaire',
  variables: { name: 'Erlich'},
  color: 'color'
)

import seeuletter
seeuletter.api_key = 'test_12345678901234567890'

example_letter = seeuletter.Letter.create(
    description='Test Letter from Python Bindings',
    to_address={
        'name': 'Erlich',
        'address_line1': '30 rue de rivoli',
        'address_city': 'Paris',
        'address_postalcode': '75004',
        'address_country': 'France'
    },
    source_file="""<html>Hello {{name}},</html>""",
    source_file_type="html",
    variables={
        'name': 'Erlich'
    },
    postage_type="prioritaire",
    color="bw"
)

print example_letter

Seeuletter.init("test_12345678901234567890");

final Map<String, String> variables = new HashMap<String, String>();
variables.put("website", "Seeuletter.com");

SeeuletterResponse<Letter> response = new Letter.RequestBuilder()
        .setTo(
                new Address.RequestBuilder()
                        .setName("Seeuletter")
                        .setLine1("25 passage dubail")
                        .setCity("Paris")
                        .setPostalCode("75010")
                        .setCountry("France")
        )
        .setSourceFileType("html")
        .setSourceFile("<h1>Hello from {{website}}</h1>")
        .setPostageSpeed("D1")
        .setDescription("Send with the Java Wrapper")
        .setBothSides(false)
        .setPostageType("prioritaire")
        .setColor("bw")
        .setVariables(variables)
        .setPdfMargin(5)
        .create();

Letter letter = response.getResponseBody();

System.out.println(letter);

POST https://api.mysendingbox.fr/letters

Example Request with a Local File

curl -X POST https://api.mysendingbox.fr/letters \
  -u "test_12345678901234567890:" \
  -F to.name=MySendingBox \
  -F 'to.address_line1=30 rue de la république' \
  -F to.address_postalcode=75015 \
  -F to.address_city=Paris \
  -F to.address_country=France \
  -F color=color \
  -F postage_type=prioritaire \
  -F 'source_file=@path/to/your/local/file.pdf' \
  -F source_file_type=file

var Seeuletter = require('seeuletter')('test_12345678901234567890')
var fs = require('fs')

Seeuletter.letters.create({
   "description": "Demo Letter 1",
   "to": {
    "name": "MySendingBox",
    "address_line1": "30 rue de la république",
    "address_city": "Paris",
    "address_postalcode": "75015",
    "address_country": "France"
   },
   "color" : "color",
   "postage_type" : "prioritaire",
   "source_file": fs.createReadStream('./path/to/your/local/file.pdf'),
   "source_file_type": "file"
}, function(err, response){
  if(err) console.log('err : ', err)
  console.log('response : ', response)
})

<?php
  require 'vendor/autoload.php';

  $seeuletter = new \Seeuletter\Seeuletter('test_12345678901234567890');

  $to_address = array(
    'name'                  => 'Seeuletter',
    'address_line1'         => '30 rue de rivoli',
    'address_line2'         => '',
    'address_city'          => 'Paris',
    'address_country'       => 'France',
    'address_postalcode'    => '75004'
  );

  $letter = $seeuletter->letters()->create(array(
    'to'                  => $to_address,
    'source_file'         => '@/path/to/your/local/file.pdf',
    'description'         => 'Test Letters',
    'color'               => 'bw',
    'source_file_type'    => 'file',
    'postage_type'        => 'prioritaire'
  ));

  print_r($letter);
?>

require 'seeuletter'

seeuletter = Seeuletter::Client.new(api_key: 'test_12345678901234567890')

puts seeuletter.letters.create(
  description: "Test letter from the Ruby Wrapper",
  to: {
    name: 'Erlich',
    address_line1: '30 rue de rivoli',
    address_line2: '',
    address_city: 'Paris',
    address_country: 'France',
    address_postalcode: '75004'
  },
  source_file: File.new("/path/to/your/file.pdf"),
  source_file_type: 'file',
  postage_type: 'prioritaire',
  variables: { name: 'Erlich'},
  color: 'color'
)

import seeuletter
seeuletter.api_key = 'test_12345678901234567890'

example_letter = seeuletter.Letter.create(
    description='Test Letter from Python Bindings',
    to_address={
        'name': 'Erlich',
        'address_line1': '30 rue de rivoli',
        'address_city': 'Paris',
        'address_postalcode': '75004',
        'address_country': 'France'
    },
    source_file=open('/path/to/your/file.pdf', 'rb'),
    source_file_type="file",
    variables={
        'name': 'Erlich'
    },
    postage_type="prioritaire",
    color="bw"
)

print example_letter

Seeuletter.init("test_12345678901234567890");

final File file = new File(getClass().getClassLoader().getResource("local_file.pdf").getPath());

SeeuletterResponse<Letter> response = new Letter.RequestBuilder()
        .setTo(
                new Address.RequestBuilder()
                        .setName("Seeuletter")
                        .setLine1("25 passage dubail")
                        .setCity("Paris")
                        .setPostalCode("75010")
                        .setCountry("France")
        )
        .setSourceFileType("file")
        .setSourceFile(file)
        .setPostageSpeed("D1")
        .setDescription("Send with the Java Wrapper")
        .setBothSides(false)
        .setPostageType("prioritaire")
        .setColor("bw")
        .setVariables(variables)
        .setPdfMargin(5)
        .create();

Letter letter = response.getResponseBody();

System.out.println(letter);

The above command returns JSON structured like this:

{
    "_id": "SkZkonqQZ",
    "updated_at": "2017-06-23T15:59:26.480Z",
    "created_at": "2017-06-23T15:59:26.480Z",
    "page_count": 1,
    "file": {
      "url": "https://lifebot.s3.amazonaws.com/v4/files/user_HJRWFavX%3D/letter_SkZkonqQZ.pdf?AWSAccessKeyId=AKIAIVWGUB33FDOLMQ4A&Expires=1498234466&Signature=uCweBZkmLyEv0jakZrJgxvTaGGE%3D",
      "_id": "SJgZksh9mb",
      "updated_at": "2017-06-23T15:59:26.467Z",
      "created_at": "2017-06-23T15:59:26.467Z",
      "user": "HJRWFavX=",
      "letter": "SkZkonqQZ",
      "path": "v4/files/user_HJRWFavX=/letter_SkZkonqQZ.pdf",
      "page_count": 1
    },
    "user": "HJRWFavX=",
    "description": "Demo Letter 1",
    "mode": "test",
    "channel": "paper",
    "color": "color",
    "postage_type": "prioritaire",
    "print_sender_address" : false,
    "staple" : false,
    "address_placement": "first_page",
    "envelope": "c6",
    "sheet_count": 1,
    "pdf_margin": 0,
    "postage_speed" : "D1",
    "manage_delivery_proof" : false,
    "envelope_window" : "simple",
    "mail_provider" : "B",
    "variables": {
      "name": "Seeuletter"
    },
    "events": [
      {
        "_id": "594d3ade05321f08a21fdeae",
        "name": "created",
        "description": "Our API receive your data. Letter has been generated. Test mode : Letter will not be send.",
        "created_at": "2017-06-22T16:50:44.555Z",
        "updated_at": "2017-06-22T16:50:44.555Z",
        "webhook_failed": false,
        "webhook_called": false
      }
    ],
    "tracking_events": [],
    "price": {
        "total": 1.42
    },
    "from": {
      "name": "MySendingBox",
      "address_line1": "30 rue de la république",
      "address_city": "Paris",
      "address_postalcode": "75015",
      "address_country": "France"
   },
    "to": {
      "name": "MySendingBox",
      "address_line1": "30 rue de la république",
      "address_city": "Paris",
      "address_postalcode": "75015",
      "address_country": "France"
   },
    "billingAccountAllocationKeys": {
      "service": "aO2v3P6KpbMY2FiLz8LDo",
      "postage": "4hC94vcCRgw4jYsinaMrs",
    }
}

This endpoint create a Letter object.

Using the live API key will send the letter.

Using the test API key will not send the letter.

HTTP Request

POST https://api.mysendingbox.fr/letters

Body Parameters

Parameter	Description
description	string You can write anything here.
to	*Required* - object Careful : Each line of the address should not exceed 38 characters for `postage_speed` : `express` or 45 characters for `postage_speed` : `D` or `D1`. An Address object
from	(Required* if postage_type is `lr`or `lrar`)* - object Careful : Each line of the address should not exceed 38 characters for `postage_speed` : `express` or 45 characters for `postage_speed` : `D` or `D1`. An Address object
color	*Required* - string Can be : `bw` : Will be print in black & white `color` : Will be print in color.
postage_type	*Required* - string Can be : `ecopli` `prioritaire` `lr` `lrar` See pricing
source_file	*Required* - mixed Accepts an HTML string, a template_id, a remote PDF file or a local PDF file. The HTML string will be rendered with Mustache. So you can add variables. Use the variables parameters to set them. You can also pass the id of a template created on your MySendingBox Dashboard. Or you can pass a file (only PDF for now). See "Zones d'écrasements" for more info. You can also pass an url pointing to an accessible pdf file. If the PDF that you are sending is not in A4 format it will be resize to fit A4 format. Check with your `test` key if the resized file is okay for you.
source_file_type	*Required* - string Can be `file`, `template_id`, `remote` or `html`. Use : - `file` for passing a local PDF file to `source_file`. - `template_id` for passing the ID of a template to `source_file`. - `remote` for passing the URL of a remote accessible PDF file to `source_file`. - `html` for passing an HTML string to `source_file`.
source_file_`X`	mixed `X` is a number from `2` to `5`. Same as `source_file`. You can add up to 5 `source_file` that will be merged in order (`source_file` then `source_file_2` then `source_file_3` then `source_file_4` then `source_file_5`). For example, use this to create a letter from an HTML string and an existing PDF file. Or to merge multiples existing PDF files together.
source_file_`X`_type	Required if corresponding `source_file_X`exists - string Same as `source_file_type`. Describe the type of the corresponding `source_file_X`. (Can be `file`, `template_id`, `remote` or `html`.)
both_sides	boolean - Default : `true` Can be : `true` : Will be print on front & back `false` : Will only be print on front
staple	boolean - Default : `false` Can be : `true` : All sheets of the document are stapled together `false` : No staple. Careful : You can staple documents containing from 2 to 90 sheets. If there is one sheet or more than 90 sheets, the sheets are not stapled and the letter is still processed.
send_date	Date in `YYYY-MM-DD` format - Default : 15 minutes after sending to the API. Can be change on the dashboard. Should be a date in `YYYY-MM-DD` format. Careful : Once the send_date date has passed it is impossible to cancel sending
address_placement	boolean - Default : `first_page` Can be `first_page` or `insert_blank_page`. If `first_page` the address will be write on the first page of your document. Follow the guide to know where to leave some space. If `insert_blank_page` a new blank page will be inserted and the address will be write on it. If `postage_speed : express` and the number of sheets is 5 or more than 5 then `insert_blank_page` is automatically set to `insert_blank_page` This page will be charged. Careful : Nothing will be print in the back face of this page even if both_sides is true. See "Zones d'écrasements" for more info.
postage_speed	string Can be : `express`, `D`, `D1`. `express` : If the request is made before 14h the letter will be send the same day. For `lr` and `lrar` the stamp date and the `filing_proof` date will be at the API request time (+/- 2-3 hours). `D` : If the request is made before 12h the letter will be send the same day. For `lr` and `lrar` if the request is made after 12h the stamp date and the `filing_proof` date will be at the next day. `D1` : If the request is made before 12h the stamp date and the `filing_proof` will be at the next day. If the request is made after 12h the stamp date and the `filing_proof` will be 2 days later. See "Vitesse de traitement" for more info.
pdf_margin	number - default : `0` Add a margin all around the document. Useful when content is too close from the border. It's a number who represent pixels.
read_address_from_pdf	object - default : `{}` If you don't know the address of the recipient but you have the address already drawn on the PDF you can pass an object with coordinate of this address block. The API will try to read the address from this block then this block will be erased. Use Zone d'adresse to get the address block coordinate of a PDF. `read_address_from_pdf` should be an object construct like this Read Address from PDF - Example
manage_delivery_proof	boolean - default : `false` If `true` the delivery proof for `lrar` will be handle by the API and available in the `delivery_proof`object. If `false`, the delivery proof for `lrar` will be send by physical mail to sender.
manage_returned_mail	boolean - default : `false` if `true` : an event (`letter.wrong_address`) will be send by webhook if the letter can't be distributed because the address is wrong (NPAI - N'habite pas à l'adresse indiquée).
envelope	string - Default : `c6` Can be `c4` or `c6`. If their is more that 4 sheets with `postage_speed : express` or more than 6 sheets with `postage_speed : D or D1`, the envelope will be a C4. You can force a C4 envelope for less than 4 sheets (or 6 sheets) if you don't want your letter to be fold by passing `c4` as parameter. If `postage_speed : express`, when envelope is `c4` (chosen in the api or forced by the number of sheets) a blank page will be added like if the `address_placement` parameter was set to `insert_blank_page`. See Types d'enveloppe for more info.
envelope_window	string - default : `simple` `simple` : only one window on the envelope for the recipient address `double` : a window for the recipient address and an other window at the top left corner of the envelope. See Types d'enveloppe for more info.
print_sender_address	boolean - Default : `false` Should the `from` address be printed on the letter. See "Les principaux paramètres de l'API" for more info.
variables	object Must be an object with up to 50 key-value pairs. Keys must be at most 50 characters and values must be at most 500 characters. " and \ are prohibited. Nested objects are not supported yet. You can pass HTML. It will be merged. (Use 3 curly braces around your variable in your HTML template to unescape the variable.) To add a variable in your HTML, insert double curly braces into the HTML that you pass to `source_file` like so: `{{variable_name}}`. See Fusion de variable and the Mustache.JS documentation for more info.
metadata	object Set of key/value pairs that you can attach to an object. It can be useful for storing additional information about the object in a structured format.
billingAccountAllocationKeys	Allows you to allocate service charges and postage costs to different billing accounts. This parameter is restricted. Contact-us for access. An BillingAccountAllocationKeys object

Response Object

A Letter Object

Response Errors

This endpoint can return following error codes, in addition of global ones :

Message	Status code	Description
multiple-billing-account-not-enabled	400	You have provided billingAccountAllocationKeys but it is not allowed for your company
billing-account-desactivated	400	The billing account passed in parameter is deactivated
invalid-id	400	The billing account passed in parameter is deactivated
not-found	404	The id of billing account passed in parameter is invalid

Send a new electronic Letter

POST https://api.mysendingbox.fr/letters/electronic

Example Request with an HTML string

curl -X POST "https://api.mysendingbox.fr/letters/electronic" \
  -u "test_12345678901234567890:" \
  -H 'Content-Type: application/json' \
  -d '{
   "description": "Demo Letter Electronic 1",
   "to": {
    "email": "no-reply@mysendingbox.fr",
    "status": "individual",
    "first_name": "Erlich",
    "last_name": "Dumas"
   },
   "postage_type" : "lre",
   "content": "Please review the attached documents:",
   "content_type": "text" ,
   "source_file": "<html style=\"padding-top: 3px; margin: 0.5px;\">Lettre HTML for {{name}}<\/html>",
   "source_file_type": "html",
   "variables" : {
    "name" : "MySendingBox"
   }
}'

var Seeuletter = require('seeuletter')('test_12345678901234567890')

Seeuletter.letters.createElectronic({
  description: 'Demo Letter Electronic 1',
  to: {
    email: 'erlich.dumas@example.com',
    first_name: 'Erlich',
    last_name: 'Dumas',
    status: 'individual'
  },
  postage_type: 'lre',
  content: 'Please review the attached documents:',
  content_type: 'text',
  source_file: '<html>Hello, {{nom}}</html>',
  source_file_type: 'html',
  variables: {
    nom : 'Seeuletter'
  }
}, function(err, response){
  if(err) console.log('err : ', err)
  console.log('response : ', response)
})

<?php
require 'vendor/autoload.php';

$seeuletter = new \Seeuletter\Seeuletter('test_12345678901234567890');

$to_address_electronic = array(
  'first_name'            => 'Erlich',
  'last_name'             => 'Dumas',
  'status'                => 'individual',
  'email'                 => 'erlich.dumas@example.com'
);

$letter = $seeuletter->letters()->createElectronic(array(
  'to'                  => $to_address_electronic,
  'source_file'         => '<html>This is the electronic letter attached document</html>',
  'source_file_type'    => 'html',
  'description'         => 'Demo Letter Electronic 1',
  'content'             => 'Please review the attached documents:',
  'content_type'        => 'text',
  'postage_type'        => 'lre'
));


print_r($letter);
?>

require 'seeuletter'

seeuletter = Seeuletter::Client.new(api_key: 'test_12345678901234567890')

puts seeuletter.letters.createElectronic(
    description: "Demo Letter Electronic 1",
    to: {
        email: 'erlich.dumas@example.com',
        first_name: 'Erlich',
        last_name: 'Dumas',
        status: 'individual'
    },
    source_file: '<html>Hello {{name}}</html>',
    source_file_type: 'html',
    content: 'Please review the attached documents:',
    content_type: 'text',
    postage_type: 'lre',
    variables: {
        name: 'Seeuletter'
    }
)

import seeuletter
seeuletter.api_key = 'test_12345678901234567890'

example_letter = seeuletter.Letter.createElectronic(
    description='Demo Letter Electronic 1',
    to_address={
        email: 'erlich.dumas@example.com',
        first_name: 'Erlich',
        last_name: 'Dumas', 
        status: 'individual'
    },
    content: 'Please review the attached documents:',
    content_type: 'text',
    source_file="""<html>Hello {{name}},</html>""",
    source_file_type="html",
    variables={
        'name': 'Seeuletter'
    },
    postage_type="lre"
)


print example_letter

Seeuletter.init("test_12345678901234567890");

final Map<String, String> variables = new HashMap<String, String>();
variables.put("name", "Seeuletter");

SeeuletterResponse<LetterElectronic> responseElectronic = new LetterElectronic.RequestBuilder()
    .setTo(
        new Address.RequestBuilder()
            .setFirstName("Erlich")
            .setLastName("Dumas")
            .setEmail("erlich.dumas@example.com")
            .setStatus("individual")
    )
    .setPostageType("lre")
    .setSourceFile("<h1>Hello {{name}}</h1>", "html")
    .setDescription("Demo Letter Electronic 1")
    .setContent("Please review the attached documents:")
    .setVariables(variables)
    .create();

LetterElectronic letterElectronic = responseElectronic.getResponseBody();

System.out.println(letterElectronic);

POST https://api.mysendingbox.fr/letters

Example Request with a Local File

curl -X POST https://api.mysendingbox.fr/letters/electronic \
  -u "test_12345678901234567890:" \
  -F to.email=no-reply@mysendingbox.fr \
  -F to.status=individual \
  -F to.first_name=Erlich \
  -F to.last_name=Dumas \
  -F 'content=Please review the attached documents:' \
  -F content_type=text \
  -F postage_type=lre \
  -F 'source_file=@path/to/your/local/file.pdf' \
  -F source_file_type=file

var Seeuletter = require('seeuletter')('test_12345678901234567890')
var fs = require('fs')

Seeuletter.letters.createElectronic({
  description: 'Demo Letter Electronic 1',
  to: {
    email: 'erlich.dumas@example.com',
    first_name: 'Erlich',
    last_name: 'Dumas',
    status: 'individual'
  },
  postage_type: 'lre',
  content: 'Please review the attached documents:',
  content_type: 'text',
  source_file: fs.createReadStream('./path/to/your/local/file.pdf'),
  source_file_type: 'file',
  variables: {
    nom : 'Seeuletter'
  }
}, function(err, response){
  if(err) console.log('err : ', err)
  console.log('response : ', response)
})

<?php
  require 'vendor/autoload.php';

  $seeuletter = new \Seeuletter\Seeuletter('test_12345678901234567890');

  $to_address_electronic = array(
    'first_name'            => 'Erlich',
    'last_name'             => 'Dumas',
    'status'                => 'individual',
    'email'                 => 'erlich.dumas@example.com'
  );

  $letter = $seeuletter->letters()->createElectronic(array(
    'to'                  => $to_address_electronic,
    'source_file'         => '@/path/to/your/local/file.pdf',
    'source_file_type'    => 'file',
    'description'         => 'Demo Letter Electronic 1',
    'content'             => 'Please review the attached documents:',
    'content_type'        => 'text',
    'postage_type'        => 'lre'
  ));

  print_r($letter);
?>

require 'seeuletter'

seeuletter = Seeuletter::Client.new(api_key: 'test_12345678901234567890')

puts seeuletter.letters.createElectronic(
    description: "Demo Letter Electronic 1",
    to: {
        email: 'erlich.dumas@example.com',
        first_name: 'Erlich',
        last_name: 'Dumas',
        status: 'individual'
    },
    source_file: File.new("/path/to/your/file.pdf"),
    source_file_type: 'file',
    content: 'Please review the attached documents:',
    content_type: 'text',
    postage_type: 'lre',
    variables: {
        name: 'Seeuletter'
    }
)

import seeuletter
seeuletter.api_key = 'test_12345678901234567890'

example_letter = seeuletter.Letter.createElectronic(
    description='Demo Letter Electronic 1',
    to_address={
        email: 'erlich.dumas@example.com',
        first_name: 'Erlich',
        last_name: 'Dumas', 
        status: 'individual'
    },
    content: 'Please review the attached documents:',
    content_type: 'text',
    source_file=open('/path/to/your/file.pdf', 'rb'),
    source_file_type="file",
    variables={
        'name': 'Seeuletter'
    },
    postage_type="lre"
)

print example_letter

Seeuletter.init("test_12345678901234567890");

final File file = new File(getClass().getClassLoader().getResource("local_file.pdf").getPath());
final Map<String, String> variables = new HashMap<String, String>();
variables.put("name", "Seeuletter");

SeeuletterResponse<LetterElectronic> responseElectronic = new LetterElectronic.RequestBuilder()
    .setTo(
        new Address.RequestBuilder()
            .setFirstName("Erlich")
            .setLastName("Dumas")
            .setEmail("erlich.dumas@example.com")
            .setStatus("individual")
    )
    .setPostageType("lre")
    .setSourceFile(file)
    .setSourceFileType("file")
    .setDescription("Demo Letter Electronic 1")
    .setContent("Please review the attached documents:")
    .setVariables(variables)
    .create();

LetterElectronic letterElectronic = responseElectronic.getResponseBody();

System.out.println(letterElectronic);

The above command returns JSON structured like this:

{
    "_id": "SkZkonqQZ",
    "updated_at": "2017-06-23T15:59:26.480Z",
    "created_at": "2017-06-23T15:59:26.480Z",
    "page_count": 0,
    "file": {
      "url": "https://lifebot.s3.amazonaws.com/v4/files/user_HJRWFavX%3D/letter_SkZkonqQZ.pdf?AWSAccessKeyId=AKIAIVWGUB33FDOLMQ4A&Expires=1498234466&Signature=uCweBZkmLyEv0jakZrJgxvTaGGE%3D",
      "_id": "SJgZksh9mb",
      "updated_at": "2017-06-23T15:59:26.467Z",
      "created_at": "2017-06-23T15:59:26.467Z",
      "user": "HJRWFavX=",
      "letter": "SkZkonqQZ",
      "path": "v4/files/user_HJRWFavX=/letter_SkZkonqQZ.pdf",
      "page_count": 1
    },
    "user": "HJRWFavX=",
    "description": "Demo Letter Electronic 1",
    "mode": "test",
    "channel": "electronic",
    "color": "none",
    "postage_type": "lre",
    "print_sender_address" : false,
    "staple" : false,
    "address_placement": "none",
    "envelope": "none",
    "sheet_count": 0,
    "pdf_margin": 0,
    "postage_speed" : "none",
    "manage_delivery_proof" : false,
    "envelope_window" : "none",
    "mail_provider" : "ar24",
    "content": "Please review the attached documents:",
    "content_type": "text",
    "variables": {
      "name": "Seeuletter"
    },
    "events": [
      {
        "_id": "594d3ade05321f08a21fdeae",
        "name": "created",
        "description": "Our API receive your data. Letter has been generated. Test mode : Letter will not be send.",
        "created_at": "2017-06-22T16:50:44.555Z",
        "updated_at": "2017-06-22T16:50:44.555Z",
        "webhook_failed": false,
        "webhook_called": false
      }
    ],
    "tracking_events": [],
    "price": {
        "total": 3.75
    },
    "to": {
        "email": "erlich.dumas@example.com",
        "first_name": "Erlich",
        "last_name": "Dumas",
        "status": "individual"
    },
    "billingAccountAllocationKeys": {
      "service": "aO2v3P6KpbMY2FiLz8LDo",
      "postage": "4hC94vcCRgw4jYsinaMrs",
    }
}

This endpoint create a Letter object with electronic channel.

Using the live API key will send the letter.

Using the test API key will not send the letter.

HTTP Request

POST https://api.mysendingbox.fr/letters/electronic

Body Parameters

Parameter	Description
description	string You can write anything here.
to	*Required* - object An Address object
postage_type	*Required* - string Can be : `ere` `lre` `email` See pricing
source_file	*Required* - mixed Accepts an HTML string, a template_id, a remote PDF file or a local PDF file. The HTML string will be rendered with Mustache. So you can add variables. Use the variables parameters to set them. You can also pass the id of a template created on your MySendingBox Dashboard. Or you can pass a file (only PDF for now). See "Zones d'écrasements" for more info. You can also pass an url pointing to an accessible pdf file. If the PDF that you are sending is not in A4 format it will be resize to fit A4 format. Check with your `test` key if the resized file is okay for you.
source_file_type	*Required* - string Can be `file`, `template_id`, `remote` or `html`. Use : - `file` for passing a local PDF file to `source_file`. - `template_id` for passing the ID of a template to `source_file`. - `remote` for passing the URL of a remote accessible PDF file to `source_file`. - `html` for passing an HTML string to `source_file`.
source_file_`X`	mixed `X` is a number from `2` to `5`. Same as `source_file`. You can add up to 5 `source_file` that will be merged in order (`source_file` then `source_file_2` then `source_file_3` then `source_file_4` then `source_file_5`). For example, use this to create a letter from an HTML string and an existing PDF file. Or to merge multiples existing PDF files together.
source_file_`X`_type	Required if corresponding `source_file_X`exists - string Same as `source_file_type`. Describe the type of the corresponding `source_file_X`. (Can be `file`, `template_id`, `remote` or `html`.)
send_date	Date in `YYYY-MM-DD` format - Default : 15 minutes after sending to the API. Can be change on the dashboard. Should be a date in `YYYY-MM-DD` format. Careful : Once the send_date date has passed it is impossible to cancel sending
content	string Only set for channel `electronic` and if `postage_type` is `email`. Body content of the email.
content_type	string Body content type for the email. Can be `text` or `html`.
from	object Only useful to set the `reply_to` parameter for the sender. No further parameters must be passed.
variables	object Must be an object with up to 50 key-value pairs. Keys must be at most 50 characters and values must be at most 500 characters. " and \ are prohibited. Nested objects are not supported yet. You can pass HTML. It will be merged. (Use 3 curly braces around your variable in your HTML template to unescape the variable.) To add a variable in your HTML, insert double curly braces into the HTML that you pass to `source_file` like so: `{{variable_name}}`. See Fusion de variable and the Mustache.JS documentation for more info.
metadata	object Set of key/value pairs that you can attach to an object. It can be useful for storing additional information about the object in a structured format.
billingAccountAllocationKeys	Allows you to allocate service charges and postage costs to different billing accounts. This parameter is restricted. Contact-us for access. An BillingAccountAllocationKeys object

Response Object

A Letter Object

Response Errors

This endpoint can return following error codes, in addition of global ones :

Message	Status code	Description
multiple-billing-account-not-enabled	400	You have provided billingAccountAllocationKeys but it is not allowed for your company
billing-account-desactivated	400	The billing account passed in parameter is deactivated
invalid-id	400	The billing account passed in parameter is deactivated
not-found	404	The id of billing account passed in parameter is invalid

Get all Letters

GET https://api.mysendingbox.fr/letters

curl "https://api.mysendingbox.fr/letters"
  -u "test_12345678901234567890:"

var Seeuletter = require('seeuletter')('test_12345678901234567890')

Seeuletter.letters.list(function(err, response){
  if(err) console.log('err : ', err)
  console.log('response : ', response)
})

<?php
  require 'vendor/autoload.php';

  $seeuletter = new \Seeuletter\Seeuletter('test_12345678901234567890');

  $letters = $seeuletter->letters()->all();

  print_r($letters);
?>

require 'seeuletter'

seeuletter = Seeuletter::Client.new(api_key: 'test_12345678901234567890')

puts seeuletter.letters.list()

import seeuletter
seeuletter.api_key = 'test_12345678901234567890'

list_letters = seeuletter.Letter.list()

print list_letters

**NOT WORKING YET**

Seeuletter.init("test_12345678901234567890");

SeeuletterResponse<Letter> response = Letter.list();
Letter Letter = response.getResponseBody();

System.out.println(Letter);

The above command returns JSON structured like this:

{
  "info": {
    "count": 2,
    "requested_at": "2017-06-23T16:00:59.363Z"
  },
  "letters": [
    {
      "_id": "HJvwBdY7Z",
      "updated_at": "2017-06-22T16:50:44.568Z",
      "created_at": "2017-06-22T16:50:44.568Z",
      "user": "HJRWFavX=",
      "page_count": 1,
      "file": "SJePDBdYXZ",
      "description": "Demo Letter 1",
      "mode": "test",
      "channel": "paper",
      "color": "color",
      "postage_type": "prioritaire",
      "address_placement": "first_page",
      "print_sender_address" : false,
      "staple" : false,
      "envelope": "c6",
      "sheet_count": 1,
      "pdf_margin": 0,
      "postage_speed" : "d1",
      "manage_delivery_proof" : false,
      "envelope_window" : "simple",
      "mail_provider" : "A",
      "variables": {
          "name": "Seeuletter"
      },
      "events": [
        {
          "_id": "594bf56491092e1595ecb60b",
          "name": "created",
          "description": "Our API receive your data. Letter has been generated. Test mode : Letter will not be send.",
          "created_at": "2017-06-22T16:50:44.555Z",
          "updated_at": "2017-06-22T16:50:44.555Z",
          "webhook_failed": false,
          "webhook_called": false
        }
      ],
      "tracking_events": [],
      "price": {
        "total": 1.27
      },
      "from": {
        "name": "SEEULETTER",
        "address_line1": "30 rue de la république",
        "address_city": "Paris",
        "address_postalcode": "75015",
        "address_country": "France"
      },
      "to": {
        "name": "SEEULETTER",
        "address_line1": "30 rue de la république",
        "address_city": "Paris",
        "address_postalcode": "75015",
        "address_country": "France"
      }
    },
    {
      "_id": "Hy3Eo35Xb",
      "updated_at": "2017-06-23T15:59:26.480Z",
      "created_at": "2017-06-23T15:59:26.480Z",
      "page_count": 0,
      "file": "SJl3No29mW",
      "user": "HJRWFavX=",
      "description": "Demo Letter Electronic 1",
      "mode": "test",
      "channel": "electronic",
      "color": "none",
      "postage_type": "lre",
      "print_sender_address" : false,
      "staple" : false,
      "address_placement": "none",
      "envelope": "none",
      "sheet_count": 0,
      "pdf_margin": 0,
      "postage_speed" : "none",
      "manage_delivery_proof" : false,
      "envelope_window" : "none",
      "mail_provider" : "ar24",
      "content": "Please review the attached documents:",
      "content_type": "text",
      "variables": {
        "name": "Seeuletter"
      },
      "events": [
        {
          "_id": "594d3ade05321f08a21fdeae",
          "name": "created",
          "description": "Our API receive your data. Letter has been generated. Test mode : Letter will not be send.",
          "created_at": "2017-06-22T16:50:44.555Z",
          "updated_at": "2017-06-22T16:50:44.555Z",
          "webhook_failed": false,
          "webhook_called": false
        }
      ],
      "tracking_events": [],
      "price": {
          "total": 3.75
      },
      "to": {
          "email": "erlich.dumas@example.com",
          "first_name": "Erlich",
          "last_name": "Dumas",
          "status": "individual"
      },
    "billingAccountAllocationKeys": {
      "service": "aO2v3P6KpbMY2FiLz8LDo",
      "postage": "4hC94vcCRgw4jYsinaMrs",
    }
    }
  ]
}

This endpoint retrieves all letters.

HTTP Request

GET https://api.mysendingbox.fr/letters

Query Parameters

Parameter	Default	Description
offset	0	An integer that designates the offset at which to begin returning results.
limit	10	An integer that designates how many results to return.
channel	All	Filter based on the letter channel. Can be `paper` or `electronic`. If not provided it will be both.
metadata		Filter by metadata key-value pair. Example : metadata[customer_id]=123456.
variables		Filter by variables key-value pair. Example : variables[customer_id]=123456.
created_at		Filter by ISO-8601 date or datetime, e.g. `{ gt: '2018-03-20', lt: '2018-03-23T18:10:12Z' }` where `gt` is `›`, `lt` is `‹`, `gte` is `≥`, and `lte` is `≤`. Use this to only get the letter created in the specified timeframe.
updated_at		Filter by ISO-8601 date or datetime, e.g. `{ gt: '2018-03-20', lt: '2018-03-23T18:10:12Z' }` where `gt` is `›`, `lt` is `‹`, `gte` is `≥`, and `lte` is `≤`. Use this to only get the letter updated in the specified timeframe.
send_date		Filter by ISO-8601 date or datetime, e.g. `{ gt: '2018-03-20', lt: '2018-03-23T18:10:12Z' }` where `gt` is `›`, `lt` is `‹`, `gte` is `≥`, and `lte` is `≤`. Use this to only get the letter programmed to be sent or already sent in the specified timeframe.
mode	All	Filter based on the API key used to create the letter. Can be `test` or `live`. If not provided it will be both.
postage_type	All	Filter based on the `postage_type` used to create the letter. Can be `ecopli` `prioritaire` `lr` `lrar` `ere` `lre` `email`. If not provided it will be all.
postage_speed	All	Filter based on the `postage_speed` used to create the letter. Can be `express` `D1` `D`. If not provided it will be all.
color	All	Filter based on the color param used to create the letter. Can be `color` or `bw`. If not provided it will be both. If provided, letters with `electronic` channel will not be returned.

Response Object

An array of Letter Object

The file parameter is not populated. If you want to retrieve the file use the /letters/ID endpoint

Get a specific Letter

GET https://api.mysendingbox.fr/letters/1234

curl "https://api.mysendingbox.fr/letters/HJvwBdY7Z"
  -u "test_12345678901234567890:"

var seeuletter = require('seeuletter')('test_12345678901234567890')

Seeuletter.letters.retrieve('LETTER_ID', function(err, response){
  if(err) console.log('err : ', err)
  console.log('response : ', response)
})

<?php
  require 'vendor/autoload.php';

  $seeuletter = new \Seeuletter\Seeuletter('test_12345678901234567890');

  $letter = $seeuletter->letters()->get('LETTER_ID');

  print_r($letter);
?>

require 'seeuletter'

seeuletter = Seeuletter::Client.new(api_key: 'test_12345678901234567890')

puts seeuletter.letters.find('LETTER_ID')

import seeuletter
seeuletter.api_key = 'test_12345678901234567890'

get_letter = seeuletter.Letter.retrieve('LETTER_ID')

print get_letter

Seeuletter.init("test_12345678901234567890");

SeeuletterResponse<Letter> response = Letter.retrieve("LETTER_ID");
Letter Letter = response.getResponseBody();

System.out.println(Letter);

The above command returns JSON structured like this:

{
    "_id": "HJvwBdY7Z",
    "updated_at": "2017-06-22T16:50:44.568Z",
    "created_at": "2017-06-22T16:50:44.568Z",
    "user": "HJRWFavX=",
    "page_count": 1,
    "file": "https://lifebot.s3.amazonaws.com/v4/files/user_HJRWFavX%3D/letter_HJvwBdY7Z.pdf?AWSAccessKeyId=AKIAIVWGUB33FDOLMQ4A&Expires=1498151809&Signature=DT07WqlHW0g6i6b6iQlKPX4EMf8%3D",
    "description": "Demo Letter 1",
    "mode": "test",
    "channel": "paper",
    "color": "color",
    "postage_type": "prioritaire",
    "address_placement": "first_page",
    "print_sender_address" : false,
    "staple" : false,
    "envelope": "c6",
    "sheet_count": 1,
    "pdf_margin": 0,
    "postage_speed" : "d1",
    "manage_delivery_proof" : false,
    "envelope_window" : "simple",
    "mail_provider" : "A",
    "variables": {
        "name": "MySendingBox"
    },
    "events": [
      {
        "_id": "594bf56491092e1595ecb60b",
        "name": "created",
        "description": "Our API receive your data. Letter has been generated. Test mode : Letter will not be send.",
        "created_at": "2017-06-22T16:50:44.555Z",
        "updated_at": "2017-06-22T16:50:44.555Z",
        "webhook_failed": false,
        "webhook_called": false
      }
    ],
    "tracking_events": [],
    "price": {
      "total": 1.27
    },
    "from": {
      "name": "MySendingBox",
      "address_line1": "30 rue de la république",
      "address_city": "Paris",
      "address_postalcode": "75015",
      "address_country": "France"
    },
    "to": {
      "name": "MySendingBox",
      "address_line1": "30 rue de la république",
      "address_city": "Paris",
      "address_postalcode": "75015",
      "address_country": "France"
    },
    "billingAccountAllocationKeys": {
      "service": "aO2v3P6KpbMY2FiLz8LDo",
      "postage": "4hC94vcCRgw4jYsinaMrs",
    }
}

This endpoint retrieves a specific letter.

HTTP Request

GET https://api.mysendingbox.fr/letters/<ID>

URL Parameters

Parameter	Description
ID	The ID of the letter to retrieve

Response Object

A Letter Object

Cancel a Letter

DELETE https://api.mysendingbox.fr/letters/1234

curl -X DELETE "https://api.mysendingbox.fr/letters/HJvwBdY7Z"
  -u "test_12345678901234567890:"

<?php
  require 'vendor/autoload.php';

  $seeuletter = new \Seeuletter\Seeuletter('test_12345678901234567890');

  $letter = $seeuletter->letters()->delete('ID_OF_THE_LETTER');

  print_r($letter);
?>

require 'seeuletter'

seeuletter = Seeuletter::Client.new(api_key: 'test_12345678901234567890')

puts seeuletter.letters.destroy('ID_OF_THE_LETTER')

The above command returns JSON structured like this:

{
  "canceled" : true,
  "letter" : {
    "_id": "HJvwBdY7Z",
    "updated_at": "2017-06-22T16:50:44.568Z",
    "created_at": "2017-06-22T16:50:44.568Z",
    "user": "HJRWFavX=",
    "page_count": 1,
    "file": "https://lifebot.s3.amazonaws.com/v4/files/user_HJRWFavX%3D/letter_HJvwBdY7Z.pdf?AWSAccessKeyId=AKIAIVWGUB33FDOLMQ4A&Expires=1498151809&Signature=DT07WqlHW0g6i6b6iQlKPX4EMf8%3D",
    "description": "Demo Letter 1",
    "mode": "test",
    "channel": "paper",
    "color": "color",
    "postage_type": "prioritaire",
    "address_placement": "first_page",
    "print_sender_address" : false,
    "staple" : false,
    "envelope": "c6",
    "sheet_count": 1,
    "pdf_margin": 0,
    "postage_speed" : "d1",
    "manage_delivery_proof" : false,
    "envelope_window" : "simple",
    "mail_provider" : "A",
    "variables": {
        "name": "Seeuletter"
    },
    "events": [
      {
        "_id": "1Rllaxrfwh",
        "name": "created",
        "description": "Our API receive your data. Letter has been generated. Test mode : Letter will not be send.",
        "created_at": "2017-06-22T16:50:44.555Z",
        "updated_at": "2017-06-22T16:50:44.555Z",
        "webhook_failed": false,
        "webhook_called": false
      },
      {
        "webhook_called": false,
        "webhook_failed": false,
        "_id": "7RlaxGfQh",
        "name": "letter.canceled",
        "category": "letter",
        "description": "This letter has been canceled.",
        "letter": "HJvwBdY7Z",
        "company": "HyeNmDukMm",
        "created_at": "2018-12-10T11:53:31.455Z",
        "updated_at": "2018-12-10T11:53:31.455Z"
      }
    ],
    "tracking_events": [],
    "price": {
      "total": 1.27
    },
    "from": {
      "name": "MySendingBox",
      "address_line1": "30 rue de la république",
      "address_city": "Paris",
      "address_postalcode": "75015",
      "address_country": "France"
    },
    "to": {
      "name": "MySendingBox",
      "address_line1": "30 rue de la république",
      "address_city": "Paris",
      "address_postalcode": "75015",
      "address_country": "France"
    },
    "billingAccountAllocationKeys": {
      "service": "aO2v3P6KpbMY2FiLz8LDo",
      "postage": "4hC94vcCRgw4jYsinaMrs",
    }
  }
}

This endpoint cancel a specific letter.

HTTP Request

DELETE https://api.mysendingbox.fr/letters/<ID>

URL Parameters

Parameter	Description
ID	The ID of the letter to cancel

Response Object

A Letter Object

Get the price of a Letter

POST https://api.mysendingbox.fr/letters/price

curl -X POST "https://api.mysendingbox.fr/letters/price" \
  -u "test_12345678901234567890:" \
  -H 'Content-Type: application/json' \
  -d '{
    "postage_type": "ecopli",
    "page_count": 11,
    "channel": "paper",
    "color": "color",
    "pack": "business",
    "both_sides": false,
    "postage_speed": "express"
}'

The above command returns JSON structured like this:

{
    "pack": "business",
    "total": 11.52,
    "postage": 1.74,
    "service": 9.78
}

HTTP Request

POST https://api.mysendingbox.fr/letters/price

URL Parameters

Parameter	Description
postage_type	*Required* - string Can be : `ecopli` `prioritaire` `lr` `lrar` for `paper` `ere` `lre` `email` for `electronic`. See pricing
pack	string - Can be : `developer`, `startup` or `business`. If not provided, use the configured pack of the company. Useful to determine the price of a letter based on the monthly consumption.
page_count	*Required* - number The number of page in the letter.
color	*Required* if channel `paper` - string Can be : -`bw` : for black & white -`color` : for color.
channel	string - Default : `paper` Channel for the letter. Can be : `paper` or `electronic`.
postage_speed	string - Default : `D1` Only for channel `paper`. Can be : `express`, `D`, `D1`. See pricing
both_sides	boolean - Default : `true` Only for channel `paper`. Can be : `true` : Will be print on front & back `false` : Will only be print on front. This option will change the number of sheet that will change the postage price.
to	object An optional address object to have specific pricing like international. Default address_country with value "France".
envelope	Only if channel `paper` - string - Default : `c6` Can be : `c4` or `c6` Apply special pricing for envelope type.
manage_delivery_proof	Only if channel `paper` - boolean - Default : `false` Apply special pricing to manage delivery proof.

You can also use extra body parameters from POST /letters endpoint to adjust the pricing if necessary.

Response Success

A Price Object

Postcards

Postcard object

An postcard object is structured like this

{
    "_id": "SkoaUYlA-",
    "description": "Postcard Demo Doc",
    "mode": "test",
    "object": "postcard",
    "to": {
        "name": "Erlich Bachman",
        "address_city": "PARIS",
        "address_line1": "30 rue de Rivoli",
        "address_country": "France",
        "address_postalcode": "75004"
    },
    "mail_provider": "C",
    "user": "ByDfBFlCW",
    "file": {
        "url": "https://lifebot.s3-eu-west-1.amazonaws.com/v4/files/user_ByDfBFlCW/postcard_SkoaUYlA-/file_to_send.pdf?AWSAccessKeyId=AKIAIVWGUB33FDOLMQ4A&Expires=1509100125&Signature=Q0qZWqHXrfHzsldAiAhBskr3pPw%3D",
        "_id": "BJ36IFgCb",
        "updated_at": "2017-10-27T10:13:45.863Z",
        "created_at": "2017-10-27T10:13:45.863Z",
        "user": "ByDfBFlCW",
        "postcard": "SkoaUYlA-",
        "type": "file_to_send",
        "path": "v4/files/user_ByDfBFlCW/postcard_SkoaUYlA-/file_to_send.pdf",
        "page_count": 2
    },
    "events": [
        {
            "_id": "S1G1vYgCZ",
            "updated_at": "2017-10-27T10:13:45.873Z",
            "created_at": "2017-10-27T10:13:45.873Z",
            "name": "postcard.created",
            "category": "postcard",
            "description": "This postcard has been created.",
            "postcard": "SkoaUYlA-",
            "user": "ByDfBFlCW",
            "webhook_failed": false,
            "webhook_called": false
        }
    ],
    "created_at": "2017-10-27T10:13:45.868Z",
    "updated_at": "2017-10-27T10:13:45.868Z"
}

Parameter	Description
_id	ID of the postcard. Use it to retrieve a specific postcard with the GET /postcards/`ID`
to	An Address object
file	A File object containing the final postcard that will be send.
mail_provider	Can be `C`.
send_date	The date at which the postcard must be send. Not yet available.
events	An array of Event object
created_at	Date of creation
updated_at	Date of last update
user	ID of the owner of the postcard
description	Description of the postcard. Set by you.
metadata	An object. Set by you.
variables	Object used to add variables to a HTML template

Send a new Postcard

POST https://api.mysendingbox.fr/postcards

Example Request with an HTML string or a template ID

curl -X POST "https://api.mysendingbox.fr/postcards" \
  -u "test_12345678901234567890:" \
  -H 'Content-Type: application/json' \
  -d '{
   "description": "Postcard Demo Doc",
   "to": {
    "name": "Erlich Bachman",
    "address_line1": "30 rue de la république",
    "address_city": "Paris",
    "address_postalcode": "75004",
    "address_country": "France"
   },
   "source_file_front": "<html style=\"padding-top: 3px; margin: 0.5px;\">Postcard HTML for {{name}}<\/html>",
   "source_file_front_type": "html",
   "source_file_back": "<html style=\"padding-top: 3px; margin: 0.5px;\">Postcard HTML for {{name}}<\/html>",
   "source_file_back_type": "html",
   "variables" : {
    "name" : "MySendingBox"
   }
}'

var Seeuletter = require('seeuletter')('test_12345678901234567890')

Seeuletter.postcards.create({
  "description": 'Test Postcard from the Node.js Wrapper',
  "to": {
    "name": 'Erlich',
    "address_line1": '30 rue de rivoli',
    "address_city": 'Paris',
    "address_country": 'France',
    "address_postalcode": '75004'
  },
  "source_file_front": 'Hy2GUkiyz',
  "source_file_front_type": 'template_id',

  "source_file_back": 'rkfnt1s1z',
  "source_file_back_type": 'template_id',

  "variables": {
    "PRENOM": 'Erlich',
    "NOM": 'Bachman',
    "CODE_PROMO_BIENVENUE": 'CODE',
    "URL_COURTE_BIENVENUE": 'https://goo.gl/uqTHnD',
    "ADRESSE": '30 rue de Rivoli',
    "CODE_POSTAL" : '75004',
    "VILLE" : 'Paris',
    "PAYS" : 'France'
  }
})
.then((postcard)=>{
  console.log('Postcard : ', postcard)
})
.catch((err)=>{
  console.log('err: ' , err)
})

POST https://api.mysendingbox.fr/postcards

Example Request with a Local File

curl -X POST https://api.mysendingbox.fr/postcards \
  -u "test_12345678901234567890:" \
  -F 'description=Postcard Demo Doc' \
  -F 'to.name=Erlich Bachman' \
  -F 'to.address_line1=30 rue de la république' \
  -F to.address_postalcode=75004 \
  -F to.address_city=Paris \
  -F to.address_country=France \
  -F 'source_file_front=@path/to/your/local/file_front.pdf' \
  -F source_file_front_type=file
  -F 'source_file_back=@path/to/your/local/file_back.pdf' \
  -F source_file_back_type=file

var Seeuletter = require('seeuletter')('test_12345678901234567890')
var fs = require('fs')

Seeuletter.postcards.create({
  "description": 'Test Postcard from the Node.js Wrapper',
  "to": {
    "name": 'Erlich',
    "address_line1": '30 rue de rivoli',
    "address_city": 'Paris',
    "address_country": 'France',
    "address_postalcode": '75004'
  },

  "source_file_front": fs.createReadStream('./path/to/your/local/file.pdf'),
  "source_file_front_type": 'file',
  "source_file_back": fs.createReadStream('./path/to/your/local/file.pdf'),
  "source_file_back_type": 'file'
})
.then((postcard)=>{
  console.log('Postcard : ', postcard)
})
.catch((err)=>{
  console.log('err: ' , err)
})

The above command returns JSON structured like this:

{
    "object": "postcard",
    "to": {
        "name": "Erlich Bachman",
        "address_city": "PARIS",
        "address_line1": "30 rue de Rivoli",
        "address_country": "France",
        "address_postalcode": "75004"
    },
    "events": [
        {
            "_id": "S1G1vYgCZ",
            "updated_at": "2017-10-27T10:13:45.873Z",
            "created_at": "2017-10-27T10:13:45.873Z",
            "name": "postcard.created",
            "category": "postcard",
            "description": "This postcard has been created.",
            "postcard": "SkoaUYlA-",
            "user": "ByDfBFlCW",
            "webhook_failed": false,
            "webhook_called": false
        }
    ],
    "mail_provider": "C",
    "_id": "SkoaUYlA-",
    "description": "Postcard Démo Doc",
    "user": "ByDfBFlCW",
    "mode": "test",
    "file": {
        "url": "https://lifebot.s3-eu-west-1.amazonaws.com/v4/files/user_ByDfBFlCW/postcard_SkoaUYlA-/file_to_send.pdf?AWSAccessKeyId=AKIAIVWGUB33FDOLMQ4A&Expires=1509100125&Signature=Q0qZWqHXrfHzsldAiAhBskr3pPw%3D",
        "_id": "BJ36IFgCb",
        "updated_at": "2017-10-27T10:13:45.863Z",
        "created_at": "2017-10-27T10:13:45.863Z",
        "user": "ByDfBFlCW",
        "postcard": "SkoaUYlA-",
        "type": "file_to_send",
        "path": "v4/files/user_ByDfBFlCW/postcard_SkoaUYlA-/file_to_send.pdf",
        "page_count": 2
    },
    "created_at": "2017-10-27T10:13:45.868Z",
    "updated_at": "2017-10-27T10:13:45.868Z"
}

This endpoint create a Postcard object.

Using the live API key will send the postcard.

Using the test API key will not send the postcard.

HTTP Request

POST https://api.mysendingbox.fr/postcards

Body Parameters

Parameter	Description
description	string You can write anything here. It can be used to put a name on the postcard. It will be displayed in the web interface.
to	*Required* - object An Address object You have to write the recipient address on the source_file_back of the postcard. On the bottom right side corner.
source_file_front	*Required* - mixed Accepts an HTML string, a template_id, a remote file or a local file. The HTML string will be rendered with Mustache. So you can add variables. Use the variables parameters to set them. You can also pass the id of a template created on your MySendingBox Dashboard. Or you can pass a file (PDF, PNG, JPG or JPEG). You can also pass an url pointing to an accessible file. The source file must be sized at 10,9cm x 15,2cm at 300 dpi. The API will resize your file to fit this size. Check the result with your `test` API key.
source_file_front_type	*Required* - string Can be `file`, `template_id`, `remote` or `html`. Use : - `file` for passing a local file to `source_file_front`. - `template_id` for passing the ID of a template to `source_file_front`. - `remote` for passing the URL of a remote accessible PDF file to `source_file_front`. - `html` for passing an HTML string to `source_file_front`.
source_file_back	*Required* - mixed Accepts an HTML string, a template_id, a remote file or a local file. The HTML string will be rendered with Mustache. So you can add variables. Use the variables parameters to set them. You can also pass the id of a template created on your MySendingBox Dashboard. Or you can pass a file (PDF, PNG, JPG or JPEG). You can also pass an url pointing to an accessible file. The source file must be sized at 10,9cm x 15,2cm at 300 dpi. The API will resize your file to fit this size. Check the result with your `test` API key.
source_file_back_type	*Required* - string Can be `file`, `template_id`, `remote` or `html`. Use : - `file` for passing a local file to `source_file_back`. - `template_id` for passing the ID of a template to `source_file_back`. - `remote` for passing the URL of a remote accessible PDF file to `source_file_back`. - `html` for passing an HTML string to `source_file_back`.
variables	object Must be an object with up to 50 key-value pairs. Keys must be at most 50 characters and values must be at most 500 characters. " and \ are prohibited. Nested objects are not supported yet. You can pass HTML. It will be merged. (Use 3 curly braces around your variable in your HTML template to unescape the variable.) To add a variable in your HTML, insert double curly braces into the HTML that you pass to `source_file_front` (or `source_file_back`) like so: `{{variable_name}}`. See Fusion de variable and the Mustache.JS documentation for more info.
metadata	object Set of key/value pairs that you can attach to an object. It can be useful for storing additional information about the object in a structured format.

Response Object

A Postcard Object

Get all Postcards

GET https://api.mysendingbox.fr/postcards

curl "https://api.mysendingbox.fr/postcards"
  -u "test_12345678901234567890:"

var Seeuletter = require('seeuletter')('test_12345678901234567890')

Seeuletter.postcards.list(function(err, response){
  if(err) console.log('err : ', err)
  console.log('response : ', response)
})

The above command returns JSON structured like this:

{
    "info": {
        "count": 2,
        "requested_at": "2017-10-27T10:18:53.060Z"
    },
    "postcards": [
        {
            "_id": "SkoaUYlA-",
            "object": "postcard",
            "to": {
                "name": "Erlich Bachman",
                "address_city": "PARIS",
                "address_line1": "30 rue de Rivoli",
                "address_country": "France",
                "address_postalcode": "75004"
            },
            "events": [
                {
                    "_id": "S1G1vYgCZ",
                    "updated_at": "2017-10-27T10:13:45.873Z",
                    "created_at": "2017-10-27T10:13:45.873Z",
                    "name": "postcard.created",
                    "category": "postcard",
                    "description": "This postcard has been created.",
                    "postcard": "SkoaUYlA-",
                    "user": "ByDfBFlCW",
                    "webhook_failed": false,
                    "webhook_called": false
                }
            ],
            "mail_provider": "C",
            "description": "Postcard Démo Doc",
            "user": "ByDfBFlCW",
            "mode": "test",
            "file": "BJ36IFgCb",
            "created_at": "2017-10-27T10:13:45.868Z",
            "updated_at": "2017-10-27T10:13:45.868Z"
        },
        {
            "_id": "HJMprte0b",
            "object": "postcard",
            "to": {
                "name": "Erlich Bachman",
                "address_city": "PARIS",
                "address_line1": "30 rue de Rivoli",
                "address_country": "France",
                "address_postalcode": "75004"
            },
            "events": [
                {
                    "_id": "H1_RrKg0b",
                    "updated_at": "2017-10-27T10:09:20.407Z",
                    "created_at": "2017-10-27T10:09:20.407Z",
                    "name": "postcard.created",
                    "category": "postcard",
                    "description": "This postcard has been created.",
                    "postcard": "HJMprte0b",
                    "user": "ByDfBFlCW",
                    "webhook_failed": false,
                    "webhook_called": false
                }
            ],
            "mail_provider": "C",
            "updated_at": "2017-10-27T10:09:20.405Z",
            "created_at": "2017-10-27T10:09:20.405Z",
            "file": "S1MfpBFl0W",
            "mode": "test",
            "user": "ByDfBFlCW",
            "description": "Postcard Démo Doc"
        }
    ]
}

This endpoint retrieves all postcards.

HTTP Request

GET https://api.mysendingbox.fr/postcards

Query Parameters

Parameter	Required	Default	Description

Response Object

An array of Postcard Object

The file parameter is not populated. If you want to retrieve the file use the /postcards/ID endpoint

Get a specific Postcard

GET https://api.mysendingbox.fr/postcard/1234

curl "https://api.mysendingbox.fr/postcards/SkoaUYlA-"
  -u "test_12345678901234567890:"

var Seeuletter = require('seeuletter')('test_12345678901234567890')

Seeuletter.postcards.retrieve('POSTCARD_ID', function(err, response){
  if(err) console.log('err : ', err)
  console.log('response : ', response)
})

The above command returns JSON structured like this:

{
    "_id": "SkoaUYlA-",
    "object": "postcard",
    "to": {
        "name": "Erlich Bachman",
        "address_city": "PARIS",
        "address_line1": "30 rue de Rivoli",
        "address_country": "France",
        "address_postalcode": "75004"
    },
    "events": [
        {
            "_id": "S1G1vYgCZ",
            "updated_at": "2017-10-27T10:13:45.873Z",
            "created_at": "2017-10-27T10:13:45.873Z",
            "name": "postcard.created",
            "category": "postcard",
            "description": "This postcard has been created.",
            "postcard": "SkoaUYlA-",
            "user": "ByDfBFlCW",
            "webhook_failed": false,
            "webhook_called": false
        }
    ],
    "mail_provider": "C",
    "description": "Postcard Démo Doc",
    "user": "ByDfBFlCW",
    "mode": "test",
    "file": {
        "url": "https://lifebot.s3-eu-west-1.amazonaws.com/v4/files/user_ByDfBFlCW/postcard_SkoaUYlA-/file_to_send.pdf?AWSAccessKeyId=AKIAIVWGUB33FDOLMQ4A&Expires=1509100470&Signature=XSt%2FqHiE6VXk%2B001wtDg%2FKHCHec%3D",
        "_id": "BJ36IFgCb",
        "updated_at": "2017-10-27T10:13:45.863Z",
        "created_at": "2017-10-27T10:13:45.863Z",
        "user": "ByDfBFlCW",
        "postcard": "SkoaUYlA-",
        "type": "file_to_send",
        "path": "v4/files/user_ByDfBFlCW/postcard_SkoaUYlA-/file_to_send.pdf",
        "page_count": 2
    },
    "created_at": "2017-10-27T10:13:45.868Z",
    "updated_at": "2017-10-27T10:13:45.868Z"
}

This endpoint retrieves a specific postcard.

HTTP Request

GET https://api.mysendingbox.fr/postcards/<ID>

URL Parameters

Parameter	Description
ID	The ID of the postcard to retrieve

Response Object

A Postcard Object

Cancel a Postcard

DELETE https://api.mysendingbox.fr/postcards/1234

curl -X DELETE "https://api.mysendingbox.fr/postcards/HJvwBdY7Z"
  -u "test_12345678901234567890:"

The above command returns JSON structured like this:

{
  canceled : true,
  postcard : {
      "_id": "HJvwBdY7Z",
      "object": "postcard",
      "to": {
          "name": "Erlich Bachman",
          "address_city": "PARIS",
          "address_line1": "30 rue de Rivoli",
          "address_country": "France",
          "address_postalcode": "75004"
      },
      "events": [
          {
              "_id": "S1G1vYgCZ",
              "updated_at": "2017-10-27T10:13:45.873Z",
              "created_at": "2017-10-27T10:13:45.873Z",
              "name": "postcard.created",
              "category": "postcard",
              "description": "This postcard has been created.",
              "postcard": "SkoaUYlA-",
              "user": "ByDfBFlCW",
              "webhook_failed": false,
              "webhook_called": false
          }
      ],
      "mail_provider": "C",
      "description": "Postcard Démo Doc",
      "user": "ByDfBFlCW",
      "mode": "test",
      "file": "BJ36IFgCb",
      "created_at": "2017-10-27T10:13:45.868Z",
      "updated_at": "2017-10-27T10:13:45.868Z"
  }
}

This endpoint cancel a specific postcard.

HTTP Request

DELETE https://api.mysendingbox.fr/postcards/<ID>

URL Parameters

Parameter	Description
ID	The ID of the postcard to cancel

Response Object

A postcard Object

Address

Address object

An Address object is structured like this

{
    "name": "The first name and name",
    "company" : "The company name",
    "address_line1": "30 rue de la république",
    "address_line2": "Batiment B",
    "address_line3": "4 ème Etage",
    "address_city": "Paris",
    "address_postalcode": "75015",
    "address_country": "France",
    "email": "The recipient email address",
    "first_name" : "The recipient first name",
    "last_name" : "The recipient last name",
    "status": "The recipient legal status, `individual` for a personn, `professional` for a company, default is `individual`"
}

Parameters

Parameter	Channel	Required	Type	Description
name	`paper`	no	string	Name of the person (Required if company is not specified) Max 38 characters for `postage_speed` : `express` Max 45 characters for `postage_speed` : `D` or `D1`
company	`paper` `electronic`	no	string	Name of the company `paper` : (Required if name is not specified) `electronic` : (Required if status is `professional`) Max 38 characters for `postage_speed` : `express` Max 45 characters for `postage_speed` : `D` or `D1`
address_line1	`paper`	yes	string	Address line 1 Max 38 characters for `postage_speed` : `express` Max 45 characters for `postage_speed` : `D` or `D1`
address_line2	`paper`	no	string	Address line 2 Max 38 characters for `postage_speed` : `express` Max 45 characters for `postage_speed` : `D` or `D1`
address_line3	`paper`	no	string	Address line 3 Max 38 characters for `postage_speed` : `express` Max 45 characters for `postage_speed` : `D` or `D1`
address_city	`paper`	yes	string	City The addition of `address_postalcode` and `address_city` must not be more than 38 characters for `postage_speed` : `express` or 45 characters for `postage_speed` : `D` or `D1`.
address_postalcode	`paper`	yes	string	Postal Code The addition of `address_postalcode` and `address_city` must not be more than 38 characters for `postage_speed` : `express` or 45 characters for `postage_speed` : `D` or `D1`.
address_country	`paper`	yes	string	Country Max 38 characters for `postage_speed` : `express` Max 45 characters for `postage_speed` : `D` or `D1` Must be in the ISO 3166 country list.
status	`electronic`	no	string	Type of person Can be `individual` or `professional`. Default `individual`
email	`electronic`	yes	string	Email address
first_name	`electronic`	no	string	First name of the person (Required if status is `individual`)
last_name	`electronic`	no	string	Last name of the person (Required if status is `individual`)
reply_to	`electronic`	no	string	Email address to reply

For "paper" channel, you have to, at least, provide either a name or a company. You can fill both. The address will be construct like this :




name 

company 

address_line1 

address_line2 

address_line3 

address_postalcode address_city 

address_country

File

File object

An File object is structured like this

{
    "url": "https://lifebot.s3-eu-west-1.amazonaws.com/v4/files/user_ByDfBFlCW/postcard_SkoaUYlA-/file_to_send.pdf?AWSAccessKeyId=AKIAIVWGUB33FDOLMQ4A&Expires=1509100125&Signature=Q0qZWqHXrfHzsldAiAhBskr3pPw%3D",
    "_id": "BJ36IFgCb",
    "updated_at": "2017-10-27T10:13:45.863Z",
    "created_at": "2017-10-27T10:13:45.863Z",
    "user": "ByDfBFlCW",
    "postcard": "SkoaUYlA-",
    "type": "file_to_send",
    "path": "v4/files/user_ByDfBFlCW/postcard_SkoaUYlA-/file_to_send.pdf",
    "page_count": 2
}

Parameters

Parameter	Description
_id	The ID of the file
url	A signed HTTPS S3 url of the file. Use it to retrieve the file. All links returned will expire in 30 days for security purpose (mis-sharing). Each time a GET request is initiated, a new signed URL will be generated.
user	The ID of the user who own the file.
postcard	The ID of the postcard who own the file.
letter	The ID of the letter who own the file.
type	Type of the file. Can be `file_to_send`, `delivery_proof`, `filing_proof`, `lost_proof`, `return_to_sender_proof`, `download_proof`, `rejection_proof` or `negligence_proof`.
page_count	Number of page in this file.
created_at	Date of creation of the file
updated_at	Date of the last update of the file
path	Path of the file on the S3 bucket. Deprecated. Will be remove.

Webhooks

An webhook call is structured like this

{
    "created_at": "2017-07-21T15:27:12.998Z",
    "event": {
        "_id": "rJY86qJUW",
        "updated_at": "2017-07-21T15:27:12.976Z",
        "created_at": "2017-07-21T15:27:12.976Z",
        "name": "letter.accepted",
        "category": "letter",
        "description": "This letter has been accepted by the printing and mailing system.",
        "letter": "SkyVo5yIZ",
        "user": "HJX1PJe4b",
        "webhook_failed": false,
        "webhook_called": false
    },
    "letter": {
        "_id": "SkyVo5yIZ",
        "updated_at": "2017-07-21T15:27:12.975Z",
        "created_at": "2017-07-21T15:18:07.847Z",
        "page_count": 1,
        "file": {
            "url": "https://seeuletter.s3-eu-west-1.amazonaws.com/v4/files/user_HJX1PJe4b/letter_SkyVo5yIZ/file_to_send.pdf?AWSAccessKeyId=AKIAIVWGUB33FDOLMQ4A&Expires=1500651732&Signature=5tgQENtE%2BerrQH0ZyCn9A%2BzLRBA%3D",
            "_id": "HJWNi51UZ",
            "updated_at": "2017-07-21T15:18:07.827Z",
            "created_at": "2017-07-21T15:18:07.827Z",
            "user": "HJX1PJe4b",
            "letter": "SkyVo5yIZ",
            "type": "file_to_send",
            "path": "v4/files/user_HJX1PJe4b/letter_SkyVo5yIZ/file_to_send.pdf",
            "page_count": 1
        },
        "original_file": "SkgWVoqyIZ",
        "user": "HJX1PJe4b",
        "description": "Lettre de bienvenue",
        "mode": "test",
        "color": "color",
        "postage_type": "lrar",
        "source_file_type": "template_id",
        "expected_sending_date": "2017-07-24T13:00:00.000Z",
        "tracking_number": "1E00121046208",
        "tracking_completed": false,
        "events": [
            {
                "_id": "HJ_4oqyL-",
                "updated_at": "2017-07-21T15:18:08.175Z",
                "created_at": "2017-07-21T15:18:07.850Z",
                "name": "letter.created",
                "category": "letter",
                "description": "This letter has been created.",
                "letter": "SkyVo5yIZ",
                "user": "HJX1PJe4b"
            },
            {
                "_id": "rJY86qJUW",
                "updated_at": "2017-07-21T15:27:12.976Z",
                "created_at": "2017-07-21T15:27:12.976Z",
                "name": "letter.accepted",
                "category": "letter",
                "description": "This letter has been accepted by the printing and mailing system.",
                "letter": "SkyVo5yIZ",
                "user": "HJX1PJe4b"
            }
        ],
        "tracking_events": [],
        "price": {
            "total": 7.28
        },
        "both_sides": true,
        "print_sender_address": false,
        "envelope": "c6",
        "sheet_count": 1,
        "pdf_margin": 0,
        "postage_speed" : "express",
        "manage_delivery_proof" : false,
        "envelope_window" : "simple",
        "mail_provider" : "A",
        "address_placement": "first_page",
        "from": {
            "company": "Pied Piper",
            "address_line1": "28 rue de Rivoli",
            "address_city": "Paris",
            "address_postalcode": "75004",
            "address_country": "France"
        },
        "to": {
            "name": "Erlich Bachman",
            "address_line1": "30 rue de Rivoli",
            "address_city": "Paris",
            "address_postalcode": "75004",
            "address_country": "France"
        }
    }
}

MySendingBox API use webhooks to keep you informed of the status of your letters.

A webhook call to your endpoint contain an Event object and a Letter object

See Webhooks - Suivi for more info.

Events

Event object

An Event object is structured like this

{
        "_id": "rJY86qJUW",
        "updated_at": "2017-07-21T15:27:12.976Z",
        "created_at": "2017-07-21T15:27:12.976Z",
        "name": "letter.accepted",
        "category": "letter",
        "description": "This letter has been accepted by the printing and mailing system.",
        "letter": "SkyVo5yIZ",
        "user": "HJX1PJe4b",
        "webhook_last_error_message" : "",
        "webhook_failed": false,
        "webhook_called": false
    }

Data	Info
`name`	Type of event
`category`	Product concern by this event (`postcard` or `letter`)
`description`	More verbose info about this event
`letter`	The letter id attached to this event
`postcard`	The postcard id attached to this event
`user`	The user id attached to this event
`webhook_last_error_message`	An error message with the message from the last try to help you debug.
`webhook_failed`	`true` if the webhook failed after the 8 retry (URL respond with a non 200 code). See Webhooks - Suivi for more info
`webhook_called`	`true` if the webhook was successfully called (URL respond with a 200 code)

Event Type Letter

Type	Channel	Occurred when
`letter.created`	`paper` `electronic`	Occurs when a letter is successfully created. Available for `ecopli` `prioritaire` `lr` `lrar` `ere` `lre` `email`
`letter.accepted`	`paper`	Occurs when a letter is accepted by the printing and mailing system. If `postage_speed` is `express` and `postage_type` is `lr` or `lrar` the letter object will now contain a `tracking_number`. Available for `ecopli` `prioritaire` `lr` `lrar`
`letter.filing_proof`	`paper`	Occurs when a letter receive a filing proof. The letter object will now contain a `filing_proof` file. If `postage_speed` is `D` or `D1` and `postage_type` is `lr` or `lrar` the letter object will now contain a `tracking_number`. Available for `lr` `lrar`
`letter.sent`	`paper`	Occurs when a letter is sent. Available for `ecopli` `prioritaire` `lr` `lrar`
`letter.error`	`paper`	Occurs when a letter is error state. Available for `ecopli` `prioritaire` `lr` `lrar`
`letter.lost`	`paper`	Occurs when a letter is lost. No more event will fire after this one. Available for `lr` `lrar`
`letter.in_transit`	`paper`	Occurs when a new Tracking event is available. Available for `lr` `lrar` `suivie`
`letter.waiting_to_be_withdrawn`	`paper`	Occurs when a letter is waiting to be withdraw by the recipient. Available for `lr` `lrar`
`letter.distributed`	`paper`	Occurs when a letter is distributed. No more event will fire after this one. Available for `lr` `lrar`
`letter.returned_to_sender`	`paper`	Occurs when a letter is returned to the sender. No more event will fire after this one. Available for `lr` `lrar`
`letter.return_to_sender_proof`	`paper`	Occurs when a letter is returned to the sender, and a proof of return is available. No more event will fire after this one. Available for `lr` `lrar`
`letter.delivery_proof`	`paper`	Occurs when a letter receive a delivery proof. Occurs generally 5 to 10 days after the `letter.distributed` event. The letter object will now contain a `delivery_proof` file. Available for `lrar` when `manage_delivery_proof` was set to `true`.
`letter.wrong_address`	`paper`	Occurs when a letter receive a "NPAI" event from La Poste (N'habite pas à l'adresse indiquée). Occurs generally 5 to 10 days after the `letter.sent` event. The letter object will now contain a `wrong_address` variable set to `true`. The field `additional_info` of `event` will indicate why the letter could not have been distributed : (Destinataire inconnu à l'adresse, N'habite pas à l'adresse indiquée, Défaut d'accès ou d'adressage, Motif Inconnu, ...). These informations are coming from La Poste. Available for `ecopli` `prioritaire` `lr` `lrar` when `manage_returned_mail` was set to `true`.
`letter.canceled`	`paper` `electronic`	Occurs when a letter is canceled. Available for `prioritaire` `lr` `lrar` `ere` `lre` `email`
`letter.electronic.sent`	`electronic`	Occurs when a letter is sent with `electronic` channel. Available for `ere`, `lre` or `email`
`letter.electronic.refused`	`electronic`	Occurs when the recipient refuses the electronic letter. Available for `ere` or `lre`
`letter.electronic.negligence`	`electronic`	Occurs automatically when the recipient didn't make any action on the electronic letter after 14 days. Available for `ere` or `lre`
`letter.electronic.locked`	`electronic`	Occurs when the recipient failed 5 times to enter the security code to open the electronic letter. Available only for `ere`
`letter.electronic.accepted`	`electronic`	Occurs when the recipient accepts the electronic letter. Available for `ere` or `lre`
`letter.electronic.not_distributed`	`electronic`	Occurs when an electronic letter cannot be distributed to the recipient. Available for `ere`, `lre` or `email`
`letter.electronic.failed_internal`	`electronic`	Occurs when an electronic letter sending failed in MySendingBox. Available for `ere`, `lre` or `email`
`letter.electronic.failed_tracking`	`electronic`	Occurs when it's impossible to get provider tracking information (id) from an electronic letter. Available for `ere`, `lre` or `email`
`letter.electronic.failed_external`	`electronic`	Occurs when an electronic letter sending failed from the provider. Available for `ere`, `lre` or `email`

Event Type Postcard

Type	Occured when
`postcard.created`	Occurs when a postcard is successfully created.
`postcard.accepted`	Occurs when a postcard is accepted by the printing and mailing system.
`postcard.sent`	Occurs when a postcard is sent.
`postcard.canceled`	Occurs when a postcard is canceled.

Event Type Company

An Event object for company.payment_method_added is structured like this

{
   "created_at":"2019-03-25T18:57:08.622Z",
   "event":{
      "webhook_called":false,
      "webhook_failed":false,
      "_id":"Qc-hoPuT0",
      "name":"company.payment_method_added",
      "category":"company",
      "description":"A new payment method has been added to this account.",
      "company":"93veGNxc-c",
      "created_at":"2019-03-25T18:51:17.321Z",
      "updated_at":"2019-03-25T18:51:17.321Z"
   },
   "company":{
      "partner":{
         "can_create_account_from_api":false,
         "without_payment_method":false
      },
      "address":{
         "name":"Company Name",
         "address_line1":"Address Line 1",
         "address_line2":"Address Line 2",
         "address_postalcode":"Postal Code",
         "address_city":"City",
         "address_country":"country"
      },
      "email_notifications":{
         "error":true,
         "wrong_address":true
      },
      "data_expiration":{
         "basic":{
            "type":"month",
            "value":12
         },
         "legal":{
            "type":"year",
            "value":3
         }
      },
      "cancellation_window":{
         "letters":60,
         "postcards":60
      },
      "api_keys":{
         "live":{
            "created_at":"2019-03-25T18:48:03.550Z",
            "key":"live_a3461dc6-ff8e-4f90-bb56-41f7076a49ca"
         },
         "test":{
            "created_at":"2019-03-25T18:48:03.550Z",
            "key":"test_541d6e74-edbf-4d55-a306-13ce84beccfc"
         }
      },
      "admin":false,
      "activated":true,
      "disable_webhook_for_dashboard_event":false,
      "postage_speed":"D1",
      "credit_card_exists":true,
      "default_pack":"business",
      "auto_invoicing":true,
      "billing_emails":[

      ],
      "events":[
         {
            "webhook_called":false,
            "webhook_failed":false,
            "_id":"Qc-hoPuT0",
            "name":"company.payment_method_added",
            "category":"company",
            "description":"A new payment method has been added to this account.",
            "company":"93veGNxc-c",
            "created_at":"2019-03-25T18:51:17.321Z",
            "updated_at":"2019-03-25T18:51:17.321Z"
         }
      ],
      "_id":"93veGNxc-c",
      "branded_for":"illicopro",
      "webhook_url":"http://test_webhook.mysendingbox.fr",
      "created_by_partner":"Bklz8gsPZm",
      "email":"email@email.com",
      "siren":"SIREN",
      "tva_intra":"TVA Intra",
      "created_at":"2019-03-25T18:48:03.563Z",
      "updated_at":"2019-03-25T18:56:40.002Z",
      "payment_type":"sepa"
   }
}

Type	Occured when
`company.payment_method_added`	Occurs when a payment method has been added to a company account.

Tracking Events

Tracking Events object

An Tracking Events object is structured like this

{
    "status" : "PRIS_EN_CHARGE", 
    "message" : "Départ", 
    "date" : "2017-10-04T14:00:00.000+0200", 
    "_id" : "59d519b0f4dabd001cf3b917", 
    "created_at" : "2017-10-04T10:25:07.557+0200"
}

Fields

Status	Message
PRIS_EN_CHARGE	Départ
PRIS_EN_CHARGE	Pris en charge
PRIS_EN_CHARGE	En cours de traitement
A_RETIRER	Attend d'être retiré au guichet
A_RETIRER	Pli présenté
DISTRIBUE	Distribué
RETOUR_DESTINATAIRE	Retourné à l'expéditeur
INCONNU	INCONNU

Pricing

Price object

An price object is structured like this

{
    "postage": 4.65,
    "service": 1.853,
    "total": 6.5,
    "pack" : "business"
}

Parameter	Description
postage	The postage cost. Paid by MySendingBox to La Poste. No TVA.
service	The printing, folding and sending cost. 20% TVA.
total	The global price of a letter.
pack	The pack used to calculate the price of a letter.

[Deprecated] Get the price of a letter

GET https://api.mysendingbox.fr/price/letter

curl "https://api.mysendingbox.fr/price/letter" -G -X GET\
  -u "test_12345678901234567890:" \
  -d color=bw \
  -d postage_type=lrar \
  -d postage_speed=D1 \
  -d page_count=1 \
  -d letter_count=1 \
  -d both_sides=true \
  -d country=France \

The above command returns JSON structured like this:

{
    "postage": 4.65,
    "service": 1.853,
    "total": 6.5,
    "country": "France",
    "pack": "developer"
}

Endpoint migration

To migrate to the new POST /letters/price endpoint, please apply following operation :

As the HTTP Method change, you need to change the request Method to POST and pass all parameters into the request Body instead of URL.
Change the country parameter by an object to with address_country key.

HTTP Request

GET https://api.mysendingbox.fr/price/letter?color=bw&postage_type=lrar&postage_speed=D1&page_count=1&both_sides=true&letter_count=1&country=France

URL Parameters

Parameter	Description
color	*Required* - string Can be : -`bw` : for black & white -`color` : for color.
postage_type	*Required* - string Can be : `prioritaire` `lr` `lrar`. See pricing
postage_speed	*Required* - string Can be : `express`, `D`, `D1`. See pricing
page_count	*Required* - number The number of page in the letter.
pack	boolean - Default : `developer` Can be : `developer`, `startup` or `business`. Useful to determine the price of a letter based on the monthly consumption.
both_sides	boolean - Default : `true` Can be : `true` : Will be print on front & back `false` : Will only be print on front. This option will change the number of sheet that will change the postage price.
country	string - Default : `France` Pass a country to get the international stamp price. Must be in the ISO 3166 country list.

Accounts

Create a new account from the API

POST https://api.mysendingbox.fr/accounts

curl -X POST "https://api.mysendingbox.fr/accounts" \
  -u "test_12345678901234567890:" \
  -d '{
    "email": "email@domain.com",
    "name": "Account Name",
    "phone": "0102030405",
    "webhook_url": "https://webhook_url_of_the_account.com",
    "company_name": "Company Name",
    "address_line1": "Address Line 1",
    "address_line2": "Address Line 2",
    "address_postalcode": "Postal Code",
    "address_city": "City",
    "address_country": "country",
    "siren": "SIREN",
    "cancellation_window": 60
}'  --header "Content-Type: application/json"

// Requirement : Package seeuletter version >= 1.5.0
var Seeuletter = require('seeuletter')('test_12345678901234567890')

Seeuletter.accounts.create({
    "email": "email@domain.com",
    "name": "Account Name",
    "phone": "0102030405",
    "webhook_url": "https://webhook_url_of_the_account.com",
    "company_name": "Company Name",
    "address_line1": "Address Line 1",
    "address_line2": "Address Line 2",
    "address_postalcode": "Postal Code",
    "address_city": "City",
    "address_country": "country",
    "siren": "SIREN",
    "cancellation_window": 60
})
  .then(function (account) {
    console.log('The Seeuletter API Account responded : ', account)
  })
  .catch(function (err) {
    console.log('Error message : ', err.message)
    console.log('Error status_code : ', err.status_code)
  })

<?php
// Requirement : Package seeuletter version >= 1.2.0
require 'vendor/autoload.php';

$seeuletter = new \Seeuletter\Seeuletter('test_12345678901234567890');

$account_response = $seeuletter->accounts()->create(array(
    "email"             => "email@domain.com",
    "name"              => "Account Name",
    "phone"             => "0102030405",
    "webhook_url"       => "https://webhook_url_of_the_account.com",
    "company_name"      => "Company Name",
    "address_line1"     => "Address Line 1",
    "address_line2":    => "Address Line 2",
    "address_postalcode"=> "Postal Code",
    "address_city"      => "City",
    "address_country"   => "country",
    "siren"             => "SIREN",
    "cancellation_window" => 60
));

print_r($account_response);
?>

# Requirement : Package seeuletter version >= 1.4.0
require 'seeuletter'

seeuletter = Seeuletter::Client.new(api_key: 'test_12345678901234567890')

puts seeuletter.accounts.create(
    email: "email@domain.com",
    name: "Account Name",
    phone: "0102030405",
    webhook_url: "https://webhook_url_of_the_account.com",
    company_name: "Company Name",
    address_line1: "Address Line 1",
    address_line2: "Address Line 2",
    address_postalcode: "Postal Code",
    address_city: "City",
    address_country: "country",
    siren: "SIREN",
    cancellation_window: 60
)

# Requirement : Package seeuletter version >= 1.2.0
import seeuletter
seeuletter.api_key = 'test_12345678901234567890'

example_account = seeuletter.Account.create(
    email="email@domain.com",
    name="Account Name",
    phone="0102030405",
    webhook_url="https://webhook_url_of_the_account.com",
    company_name="Company Name",
    address_line1="Address Line 1",
    address_line2="Address Line 2",
    address_postalcode="Postal Code",
    address_city="City",
    address_country="country",
    siren="SIREN",
    cancellation_window=60
)

print example_account

// Requirement : Package seeuletter version >= 1.2.0
Seeuletter.init("test_12345678901234567890");

SeeuletterResponse<Letter> response = new Account.RequestBuilder()
        .setEmail("email@domain.com")
        .setName("Account Name")
        .setPhone("0102030405")
        .setWebhookURL("https://webhook_url_of_the_account.com")
        .setCompanyName("Company Name")
        .setAddressLine1("Address Line 1")
        .setAddressLine2("Address Line 2")
        .setAddressPostalCode("Postal Code")
        .setAddressCity("City")
        .setAddressCountry("country")
        .setSiren("SIREN")
        .setCancellationWindow(60)
        .create();

Account account = response.getResponseBody();

System.out.println(account);

The above command returns JSON structured like this:

{
    "user": {
        "email_notifications": {
            "error": true,
            "wrong_address": true
        },
        "admin": false,
        "activated": false,
        "_id": "73aS71pmq",
        "email": "email@domain.com",
        "name": "Account Name",
        "phone": "0102030405",
        "role": "admin",
        "invite_pending": true,
        "invite_token": "b85dd205-3196-494d-a7bd-89138329ebb0",
        "company": "A5xOuu6P_G",
        "created_at": "2019-03-20T14:34:38.639Z",
        "updated_at": "2019-03-20T14:34:38.639Z"
    },
    "company": {
        "partner": {
            "can_create_account_from_api": false
        },
        "address": {
            "name": "Company Name",
            "address_line1": "Address Line 1",
            "address_line2": "Address Line 2",
            "address_postalcode": "Postal Code",
            "address_city": "City",
            "address_country": "country"
        },
        "email_notifications": {
            "error": true,
            "wrong_address": true
        },
        "data_expiration": {
            "basic": {
                "type": "month",
                "value": 12
            },
            "legal": {
                "type": "year",
                "value": 3
            }
        },
        "cancellation_window": {
            "letters": 60,
            "postcards": 60
        },
        "api_keys": {
            "live": {
                "created_at": "2019-03-20T14:34:38.211Z",
                "key": "live_320cebb0-4a23-47b3-978a-fc82a437b04c"
            },
            "test": {
                "created_at": "2019-03-20T14:34:38.211Z",
                "key": "test_f1036cf2-e035-4f7b-84e3-23badd4961d9"
            }
        },
        "integrations": {
            "sellsy": {
                "allowed": false,
                "activated": false,
                "initialized": false,
                "rules": []
            }
        },
        "admin": false,
        "activated": true,
        "disable_webhook_for_dashboard_event": false,
        "postage_speed": "D1",
        "credit_card_exists": false,
        "default_pack": "business",
        "auto_invoicing": true,
        "billing_emails": [],
        "_id": "A5xOuu6P_G",
        "branded_for": "partner_name",
        "webhook_url": "https://webhook_url_of_the_account.com",
        "email": "email@domain.com",
        "siren": "SIREN",
        "tva_intra": "TVA Intra",
        "created_at": "2019-03-20T14:34:38.219Z",
        "updated_at": "2019-03-20T14:34:38.219Z"
    }
}

Use this endpoint to create a new account on MySendingBox.fr.

The API will respond with an object containing an user and a company.

The user will automatically receive an email at the address entered in the email field. This email will contain a time-limited link so that the user can complete their registration. It is therefore necessary to warn users that they must complete their registration as soon as possible.

You will then be able to send your user to a page on MySendingBox.fr where he can add a payment method.

You should store the API keys received in the response (the company.api_keys.live.key and company.api_keys.test.key values in the body) in your database so that you can make API calls on behalf of your user.

This endpoint replaces the former one in the last version of MySendinxBox API :
POST https://api.mysendingbox.fr/users/create_from_api
There is no breaking changes and specifications are the same as the new one. To avoid further inconvenience, please consider migrating to the new endpoint.

HTTP Request

POST https://api.mysendingbox.fr/accounts

Body Parameters

Parameter	Description
email	*Required* - string The email address of the account you want to create
name	*Required* - string Name of the administrator of the account you want to create
phone	string Phone of the administrator of the account you want to create
webhook_url	string Webhook url for us to ping on the get live update
company_name	string Name of the company of the account you want to create
address_line1	string Address line 1 of the company of the account you want to create
address_line2	string Address line 2
address_postalcode	string Address postal code
address_city	string City
address_country	string Country
siren	string SIREN
cancellation_window	number Number in minutes to set the time window in which a letter can be canceled.

Response Success

The API will respond with an object containing two sub objects.

user
company

When the user add a payment method to his account a webhook call will be triggered to his webhook url. See Company Events.

Response Errors

This endpoint can return following error codes, in addition of global ones :

Message	Status code	Description
missing_email	400	The field email is empty.
user_exists	400	The email value already exists for another account.

Update account email

POST https://api.mysendingbox.fr/accounts/ACCOUNT_ID

curl -X PUT "https://api.mysendingbox.fr/accounts/ACCOUNT_ID" \
  -u "test_12345678901234567890:" \
  -d '{
    "email": "new.email@domain.com",
}'  --header "Content-Type: application/json"

// Requirement : Package seeuletter version >= 1.5.0
var Seeuletter = require('seeuletter')('test_12345678901234567890')

Seeuletter.accounts.updateEmail("ACCOUNT_ID", "new.email@domain.com")
  .then(function () {
    console.log('The Seeuletter API Account responded with success')
  })
  .catch(function (err) {
    console.log('Error message : ', err.message)
    console.log('Error status_code : ', err.status_code)
  })

<?php
// Requirement : Package seeuletter version >= 1.2.0
require 'vendor/autoload.php';

$seeuletter = new \Seeuletter\Seeuletter('test_12345678901234567890');

$seeuletter->accounts()->updateEmail("ACCOUNT_ID", "new.email@domain.com");
?>

# Requirement : Package seeuletter version >= 1.4.0
require 'seeuletter'

seeuletter = Seeuletter::Client.new(api_key: 'test_12345678901234567890')

seeuletter.accounts.updateEmail("ACCOUNT_ID", "new.email@domain.com")

# Requirement : Package seeuletter version >= 1.2.0
import seeuletter
seeuletter.api_key = 'test_12345678901234567890'

seeuletter.Account.updateEmail("ACCOUNT_ID", "new.email@domain.com")

// Requirement : Package seeuletter version >= 1.2.0
Seeuletter.init("test_12345678901234567890");

SeeuletterResponse<Letter> response = new Account.RequestBuilder()
        .setEmail("new.email@domain.com")
        .update("ACCOUNT_ID");

System.out.println(response);

HTTP Request

PUT https://api.mysendingbox.fr/accounts/ACCOUNT_ID

URL Parameters

Parameter	Description
ID	The ID of the account to update. Must be a linked company ID created with the /accounts API endpoint.

Body Parameters

Parameter	Description
email	*Required* - string The new email address for the account.

Response Success

The API will respond only with an HTTP Code 200 if the request succeed.

The process updates the company email with the new one.

It also updates the administrator user email with following conditions :

If the company has only one admin user, he is updated with the new email.
If the company has several admin users, the user with the same email as the company is updated with the new email.

Response Errors

This endpoint can return following error codes, in addition of global ones :

Message	Status code	Description
unauthorized_account	401	The company in the API Key is not linked with the company to update correctly. It's probably because the company account wasn't created properly.
missing_email	400	The field email is empty.
user_exists	400	The email value already exists for another account.
admin_email_detection_error	400	Cannot detect the admin user to update. This error occurred when the company has many administrator users but no one with the same email.
no_account_company	404	The company with the account ID passed doesn't exist.

Invoices

Invoice object

An invoice object is structured like this

{
    "_id": "123456789",
    "invoice_number": 1,
    "invoice_date": "2021-11-11T00:00:00.000Z",
    "due_date": "2021-11-11T00:00:00.000Z",
    "name": "Facture example MySendingBox",
    "pack": "business",
    "payment_date": "2021-11-12T12:00:00.000Z",
    "payment_type": "card",
    "payment_informations": {
        "paid": true,
        "error": null,
        "error_code": null,
        "charge": {
            "created": 1639126681,
            "receipt_url": "RECEIPT URL",
            "type": "card"
        }
    },
    "tva": 20,
    "country": "France",
    "invoice_lines": [
        {
            "_id": "61b3169159f851004024a12c",
            "text": "Affranchissement Prioritaire Industriel - moins de 50g",
            "tva": 0,
            "price": 0.63,
            "total_ht": 11.34
        },
        {
            "_id": "61b3169159f851004024a12e",
            "text": "1ère page - Couleur",
            "tva": 20,
            "price": 0.63,
            "total_ht": 11.34,
            "total_tva": 2.27,
            "total_ttc": 13.61
        },
        {
            "_id": "61b3169159f851004024a12d",
            "text": "Pages supplémentaires - Couleur",
            "tva": 20,
            "price": 0.3,
            "total_ht": 10.8,
            "total_tva": 2.16,
            "total_ttc": 12.96
        }
    ],
    "total": {
        "total_services_ht": 22.14,
        "total_postages_ht": 11.34,
        "total_ht": 33.48,
        "total_tva": 4.428,
        "total_ttc": 37.908
    },
    "discount": {},
    "status": "paid",
    "file": {
        "_id": "rSNSHCtCf3cDNYo-67UaK",
        "page_count": 1,
        "name": "Facture_example_MSB",
        "path": "FILE_PATH",
        "mimetype": "application/pdf",
        "extension": "pdf",
        "type": "invoice",
        "created_at": "2021-12-10T08:57:56.499Z",
        "updated_at": "2021-12-10T08:57:56.499Z",
        "url": "FILE_URL"
    }
}

Parameter	Description
_id	ID of the invoice. Use it to retrieve a specific invoice with the GET /invoices/`ID` endpoint.
invoice_number	Unique invoice identifier, incremental number.
invoice_date	Date of the invoice.
due_date	Date for the payment of the invoice.
name	Invoice label.
pack	The company pack applied for pricing.
payment_date	If status `paid`, the payment date.
payment_type	If status `paid`, the type of payment. Can be `card`, `sepa`, `transfer` or `sepa_debit`.
payment_informations	General informations about payment. It's an object with following properties : `paid` `error` `error_code` `charge.created` `charge.receipt_url` `charge.type`
tva	Applied Tax percentage.
country	Country name for invoicing.
invoices_lines	Array of Invoice line details. Each line is an object with following properties : `_id` `text` : Label of line `tva` `price` : Unit Price `total_ht` `total_tva` `total_ttc`
total	All invoice totals. It's an object with following properties : `total_services_ht` : Total for services only `total_postages_ht` : Total for postages only `total_ht` `total_tva` `total_ttc`
discount	Discount information. It's an object with following properties : `type` : Discount amount type applied. Can be `percentage` or `amount` `value` : Amount of discount `text` : Description `tva` : Tax applied `price` `total_ht`
status	Current Invoice status. Can be `created`, `waiting`, `paid` or `error`.
file	A File object

Get all Invoices

POST https://api.mysendingbox.fr/invoices

curl -X GET "https://api.mysendingbox.fr/invoices" \
  -u "test_12345678901234567890:"

// Requirement : Package seeuletter version >= 1.5.0
var Seeuletter = require('seeuletter')('test_12345678901234567890')

Seeuletter.invoices.list({
  // Example filters
  status: "paid",
  date_start: "2020-01-01",
})
  .then(function (response) {
    console.log('[List] The Seeuletter API Invoices responded : ', response)
  })
  .catch(function (err) {
    console.log('[List] Error message : ', err.message)
    console.log('[List] Error status_code : ', err.status_code)
  })

<?php
// Requirement : Package seeuletter version >= 1.2.0
$seeuletter = new \Seeuletter\Seeuletter('test_12345678901234567890');

$invoices_list = $seeuletter->invoices()->all(array(
  'status'               => "paid",
  'date_start'           => "2020-01-01",
));

echo '[List] The Seeuletter API Invoices responded : ';
print_r($invoices_list);
?>

# Requirement : Package seeuletter version >= 1.4.0
require 'seeuletter'

seeuletter = Seeuletter::Client.new(api_key: 'test_12345678901234567890')

list_response = seeuletter.invoices.list(
    status: "paid",
    date_start: "2020-01-01"
)
puts "The Seeuletter API Invoices responded : #{list_response}"

# Requirement : Package seeuletter version >= 1.2.0
import seeuletter
seeuletter.api_key = 'test_12345678901234567890'

example_list = seeuletter.Invoice.list(
  status="paid",
  date_start="2020-01-01"
)

print "List Invoice Response : "
print "\n"
print example_list
print "\n"

// Requirement : Package seeuletter version >= 1.2.0
Seeuletter.init("test_12345678901234567890");

Map<String, Object> params = new HashMap<String, Object>();
params.put("status", "paid");
params.put("date_start", "2020-01-01");

SeeuletterResponse<InvoiceCollection> response = Invoice.list(params);

System.out.println(response.getResponseBody().getData());

The above command returns JSON structured like this:

{
    "info": {
        "total": 1,
        "limit": 1,
        "page": 1,
        "pages": 1,
        "count": 1,
        "requested_at": "2022-01-03T13:52:23.919Z"
    },
    "invoices": [
        {
            "_id": "123456789",
            "invoice_number": 1,
            "invoice_date": "2021-11-11T00:00:00.000Z",
            "due_date": "2021-11-11T00:00:00.000Z",
            "name": "Facture example MySendingBox",
            "pack": "business",
            "payment_date": "2021-11-12T12:00:00.000Z",
            "payment_type": "card",
            "payment_informations": {
                "paid": true,
                "error": null,
                "error_code": null,
                "charge": {
                    "created": 1639126681,
                    "receipt_url": "RECEIPT URL",
                    "type": "card"
                }
            },
            "tva": 20,
            "country": "France",
            "invoice_lines": [
                {
                    "_id": "61b3169159f851004024a12c",
                    "text": "Affranchissement Prioritaire Industriel - moins de 50g",
                    "tva": 0,
                    "price": 0.63,
                    "total_ht": 11.34
                },
                {
                    "_id": "61b3169159f851004024a12e",
                    "text": "1ère page - Couleur",
                    "tva": 20,
                    "price": 0.63,
                    "total_ht": 11.34,
                    "total_tva": 2.27,
                    "total_ttc": 13.61
                },
                {
                    "_id": "61b3169159f851004024a12d",
                    "text": "Pages supplémentaires - Couleur",
                    "tva": 20,
                    "price": 0.3,
                    "total_ht": 10.8,
                    "total_tva": 2.16,
                    "total_ttc": 12.96
                }
            ],
            "total": {
                "total_services_ht": 22.14,
                "total_postages_ht": 11.34,
                "total_ht": 33.48,
                "total_tva": 4.428,
                "total_ttc": 37.908
            },
            "discount": {},
            "status": "paid",
            "file": {
                "_id": "rSNSHCtCf3cDNYo-67UaK",
                "page_count": 1,
                "name": "Facture_example_MSB",
                "path": "FILE_PATH",
                "mimetype": "application/pdf",
                "extension": "pdf",
                "type": "invoice",
                "created_at": "2021-12-10T08:57:56.499Z",
                "updated_at": "2021-12-10T08:57:56.499Z",
                "url": "FILE_URL"
            }
        }
    ]
}

This endpoint retrieves all invoices.

HTTP Request

POST https://api.mysendingbox.fr/invoices

Query Parameters

Parameter	Default	Description
date_start		Filter by invoice_date higher than parameter.
date_end		Filter by invoice_date lower than parameter.
status		Filter based on the current `status` of invoices.
order_by	`invoice_date`	Order invoices by a property. Can be `invoice_date`, `invoice_number` or `total`.
sort_by	`desc`	Apply descendant or ascendant order to invoices. Can be `asc` or `desc`.
page	1	(Pagination) Page number to return.
limit	10	(Pagination) Maximum number of invoices in a page.

Response Success

The response success object is split into to subdocuments :

info : The pagination information. It's an object with the following data :
- total : Number of results for all invoices filtered.
- limit : Number of results by page.
- page : The current page number returned.
- pages : Number of pages for all invoices filtered.
- count : Number of results only in the current page.
- requested_at : Date of the pagination request.
invoices : An array of Invoice Object .

Get a specific Invoice

GET https://api.mysendingbox.fr/invoices/INVOICE_ID

curl "https://api.mysendingbox.fr/invoices/INVOICE_ID"
  -u "test_12345678901234567890:"

// Requirement : Package seeuletter version >= 1.5.0
var seeuletter = require('seeuletter')('test_12345678901234567890')

Seeuletter.invoices.retrieve(INVOICE_ID)
  .then(function (invoice) {
    console.log('[Retrieve] The Seeuletter API Invoice responded : ', invoice)
  }).catch(function (err) {
    console.log('[Retrieve] Error message : ', err.message)
    console.log('[Retrieve] Error status_code : ', err.status_code)
  })

<?php
// Requirement : Package seeuletter version >= 1.2.0
$seeuletter = new \Seeuletter\Seeuletter('test_12345678901234567890');

$invoice = $seeuletter->invoices()->get(INVOICE_ID);

echo '[Retrieve] The Seeuletter API Invoices responded : ';
print_r($invoice);
?>

# Requirement : Package seeuletter version >= 1.4.0
require 'seeuletter'

seeuletter = Seeuletter::Client.new(api_key: 'test_12345678901234567890')

find_response = seeuletter.invoices.find(INVOICE_ID)
puts "The Seeuletter API Invoice responded : #{find_response}"

# Requirement : Package seeuletter version >= 1.2.0
import seeuletter
seeuletter.api_key = 'test_12345678901234567890'

example_invoice = seeuletter.Invoice.retrieve(INVOICE_ID)

print "Invoice Response : "
print "\n"
print example_invoice
print "\n"

// Requirement : Package seeuletter version >= 1.2.0
Seeuletter.init("test_12345678901234567890");

SeeuletterResponse<Invoice> responseInvoiceGet = Invoice.retrieve(INVOICE_ID);
Invoice invoice = responseInvoiceGet.getResponseBody();

System.out.println(invoice);

The above command returns JSON structured like this:

{
    "_id": "123456789",
    "invoice_number": 1,
    "invoice_date": "2021-11-11T00:00:00.000Z",
    "due_date": "2021-11-11T00:00:00.000Z",
    "name": "Facture example MySendingBox",
    "pack": "business",
    "payment_date": "2021-11-12T12:00:00.000Z",
    "payment_type": "card",
    "payment_informations": {
        "paid": true,
        "error": null,
        "error_code": null,
        "charge": {
            "created": 1639126681,
            "receipt_url": "RECEIPT URL",
            "type": "card"
        }
    },
    "tva": 20,
    "country": "France",
    "invoice_lines": [
        {
            "_id": "61b3169159f851004024a12c",
            "text": "Affranchissement Prioritaire Industriel - moins de 50g",
            "tva": 0,
            "price": 0.63,
            "total_ht": 11.34
        },
        {
            "_id": "61b3169159f851004024a12e",
            "text": "1ère page - Couleur",
            "tva": 20,
            "price": 0.63,
            "total_ht": 11.34,
            "total_tva": 2.27,
            "total_ttc": 13.61
        },
        {
            "_id": "61b3169159f851004024a12d",
            "text": "Pages supplémentaires - Couleur",
            "tva": 20,
            "price": 0.3,
            "total_ht": 10.8,
            "total_tva": 2.16,
            "total_ttc": 12.96
        }
    ],
    "total": {
        "total_services_ht": 22.14,
        "total_postages_ht": 11.34,
        "total_ht": 33.48,
        "total_tva": 4.428,
        "total_ttc": 37.908
    },
    "discount": {},
    "status": "paid",
    "file": {
        "_id": "rSNSHCtCf3cDNYo-67UaK",
        "page_count": 1,
        "name": "Facture_example_MSB",
        "path": "FILE_PATH",
        "mimetype": "application/pdf",
        "extension": "pdf",
        "type": "invoice",
        "created_at": "2021-12-10T08:57:56.499Z",
        "updated_at": "2021-12-10T08:57:56.499Z",
        "url": "FILE_URL"
    }
}

This endpoint retrieves a specific invoice.

HTTP Request

GET https://api.mysendingbox.fr/invoices/<ID>

URL Parameters

Parameter	Description
ID	The ID of the invoice to retrieve

Response Success

The response success returns an Invoice Object

Response Errors

This endpoint can return following error codes, in addition of global ones :

Message	Status code	Description
unauthorized_invoice	401	The invoice ID is not attached to the current company API Key, access is forbidden.
no_invoice	404	The invoice ID doesn't exist.

BillingAccountAllocationKeys

BillingAccountAllocationKeys object

An BillingAccountAllocationKeys object is structured like this

{
    "service": "A billing account id",
    "postage" : "A billing account id",
}

Parameters

Parameter	Required	Type	Description
service	no	string	The id of the billing account to which service charges will be billed
postage	no	string	The id of the billing account to which postage charges will be billed

Changelog

23/07/2024

Update api documentation for the new billing account feature

11/04/2024

Update api documentation for the new user registration process

19/12/2022

Update api documentation and java wrapper to add new LRAR statuses

01/06/2021

Update api documentation

01/05/2021

Update wrappers and sdk with electronic letters

01/04/2021

Add postage_type value ere

01/03/2021

Adding the ability to create electronic recorded letters :
Add channel to set to paper or electronic
Add postage_type value lre
Add content, term_of_use_validation, download_proof, rejection_proof, negligence_proof to the letter object
Add email, last_name, first_name, status to the Address Object

04/09/2019

Transform the application from Seeuletter for Mysendingbox.

04/02/2019

Idempotency-key is now unique by mode (if the same idempotency key is used in test and live mode, both will be created.)

10/01/2019

Add ability to staple sheets together : staple can be true or false. It's false by default.

27/11/2018

Adding the ability to choose at which date the letter should be sent

26/09/2018

Adding idempotency

17/05/2018

Adding the ability to ask for a notification through webhook if the letter can't be delivered (manage_returned_mail). Called PND (Pli Non Distribué) or NPAI (N'habite Pas à l'Adresse Indiqué) in french.

28/03/2018

Adding the ability to pass a country to the Pricing API.

23/03/2018

Adding multiples filters for the endpoint GET /letters

06/02/2018

Adding a pre-version of the Java wrapper

25/01/2018

Adding read_address_from_pdf documentation

24/01/2018

Adding Pricing documentation
Disable postage_type : prioritaire for postage_speed : express for cost reason.

16/11/2017

Adding Postcards documentation

10/11/2017

Adding Python documentation

17/10/2017

add letter.delivery_proof has a new event.

11/10/2017

add pdf_margin to add a margin around the PDF
add postage_speed to choose between express, D and D1
add manage_delivery_proof to ask the system to handle the delivery proof. The delivery proof will be available as a file in delivery_proof.
add envelope_window which can be simple or double
add mail_provider which can be A or B
add sheet_count to distinguish the page count and the sheet count (1 sheet = 2 pages when both_sides : true)
Remove source from file sub objects (file, delivery_proof, filing_proof)

26/09/2017

Adding Ruby documentation

07/09/2017

Adding PHP documentation
Adding Node.js documentation

26/07/2017

Replace nb_page by page_count
Remove all __v

28/06/2017

First API version

Errors

This code will throw an error :

# With shell, you can just pass the correct username with each request
curl "https://api.mysendingbox.fr/"
  -u "BAD_API_KEY"

If an error occured, you will get an object like this :

{
    "error": {
        "message": "This API key is not valid. Please sign up on lettres.mysendingbox.fr to get a valid api key.",
        "status_code": 401
    }
}

All errors are verbose. You will get a message explaining what failed.

The MySendingBox API uses the following error codes:

Message	Status code	Description
Bad authentication	401	You probably forgot to add your API key
Malformed api key	401	Your API key is wrong
You cannot access this letter. Check if this yours.	401	You are trying to access an object that is not yours.
insufficient_account_right	401	Your company cannot access this endpoint because it's restricted.
Missing some required fields	400	The message will contain the missing fields.
Internal Server Error	500	We had a problem with our server. Try again later.

TODO : List all error message

Annexes

Read address from PDF

{
    "active": true,
    "x": 290,
    "y": 156,
    "width": 202,
    "height": 88
}

BETA : This feature is highly experimental. If you have any feedbacks or questions please, email us !

If you don't know the address of a recipient but you already have it printed on the PDF, when sending a letter with the API you can pass an object containing coordinates of the address block to read_address_from_pdf when creating a new letter.

If possible the address will be read from this block. Then the block will be covered with white.

Use Zone d'adresse to get the coordinates of the address block from a PDF.

You can also use our online tool and click on new batch button to test some files without coding.

You have to provide the country of the recipient when you send a letter. If the country is not on the address block you should pass it with the to object as usual.

Country

ISO 3166 Country List

to.address_country and from.address_country must be one of the french country name in this list.

Alpha 2	Alpha 3	French Name
AF	AFG	Afghanistan
AL	ALB	Albanie
AQ	ATA	Antarctique
DZ	DZA	Algérie
AS	ASM	Samoa Américaines
AD	AND	Andorre
AO	AGO	Angola
AG	ATG	Antigua-et-Barbuda
AZ	AZE	Azerbaïdjan
AR	ARG	Argentine
AU	AUS	Australie
AT	AUT	Autriche
BS	BHS	Bahamas
BH	BHR	Bahreïn
BD	BGD	Bangladesh
AM	ARM	Arménie
BB	BRB	Barbade
BE	BEL	Belgique
BM	BMU	Bermudes
BT	BTN	Bhoutan
BO	BOL	Bolivie
BA	BIH	Bosnie-Herzégovine
BW	BWA	Botswana
BV	BVT	Île Bouvet
BR	BRA	Brésil
BZ	BLZ	Belize
IO	IOT	Territoire Britannique de l'Océan Indien
SB	SLB	Îles Salomon
VG	VGB	Îles Vierges Britanniques
BN	BRN	Brunéi Darussalam
BG	BGR	Bulgarie
MM	MMR	Myanmar
BI	BDI	Burundi
BY	BLR	Bélarus
KH	KHM	Cambodge
CM	CMR	Cameroun
CA	CAN	Canada
CV	CPV	Cap-vert
KY	CYM	Îles Caïmanes
CF	CAF	République Centrafricaine
LK	LKA	Sri Lanka
TD	TCD	Tchad
CL	CHL	Chili
CN	CHN	Chine
TW	TWN	Taïwan
CX	CXR	Île Christmas
CC	CCK	Îles Cocos (Keeling)
CO	COL	Colombie
KM	COM	Comores
YT	MYT	Mayotte
CG	COG	République du Congo
CD	COD	République Démocratique du Congo
CK	COK	Îles Cook
CR	CRI	Costa Rica
HR	HRV	Croatie
CU	CUB	Cuba
CY	CYP	Chypre
CZ	CZE	République Tchèque
BJ	BEN	Bénin
DK	DNK	Danemark
DM	DMA	Dominique
DO	DOM	République Dominicaine
EC	ECU	Équateur
SV	SLV	El Salvador
GQ	GNQ	Guinée Équatoriale
ET	ETH	Éthiopie
ER	ERI	Érythrée
EE	EST	Estonie
FO	FRO	Îles Féroé
FK	FLK	Îles (malvinas) Falkland
GS	SGS	Géorgie du Sud et les Îles Sandwich du Sud
FJ	FJI	Fidji
FI	FIN	Finlande
AX	ALA	Îles Åland
FR	FRA	France
GF	GUF	Guyane Française
PF	PYF	Polynésie Française
TF	ATF	Terres Australes Françaises
DJ	DJI	Djibouti
GA	GAB	Gabon
GE	GEO	Géorgie
GM	GMB	Gambie
PS	PSE	Territoire Palestinien Occupé
DE	DEU	Allemagne
GH	GHA	Ghana
GI	GIB	Gibraltar
KI	KIR	Kiribati
GR	GRC	Grèce
GL	GRL	Groenland
GD	GRD	Grenade
GP	GLP	Guadeloupe
GU	GUM	Guam
GT	GTM	Guatemala
GN	GIN	Guinée
GY	GUY	Guyana
HT	HTI	Haïti
HM	HMD	Îles Heard et Mcdonald
VA	VAT	Saint-Siège (état de la Cité du Vatican)
HN	HND	Honduras
HK	HKG	Hong-Kong
HU	HUN	Hongrie
IS	ISL	Islande
IN	IND	Inde
ID	IDN	Indonésie
IR	IRN	République Islamique d'Iran
IQ	IRQ	Iraq
IE	IRL	Irlande
IL	ISR	Israël
IT	ITA	Italie
CI	CIV	Côte d'Ivoire
JM	JAM	Jamaïque
JP	JPN	Japon
KZ	KAZ	Kazakhstan
JO	JOR	Jordanie
KE	KEN	Kenya
KP	PRK	République Populaire Démocratique de Corée
KR	KOR	République de Corée
KW	KWT	Koweït
KG	KGZ	Kirghizistan
LA	LAO	République Démocratique Populaire Lao
LB	LBN	Liban
LS	LSO	Lesotho
LV	LVA	Lettonie
LR	LBR	Libéria
LY	LBY	Jamahiriya Arabe Libyenne
LI	LIE	Liechtenstein
LT	LTU	Lituanie
LU	LUX	Luxembourg
MO	MAC	Macao
MG	MDG	Madagascar
MW	MWI	Malawi
MY	MYS	Malaisie
MV	MDV	Maldives
ML	MLI	Mali
MT	MLT	Malte
MQ	MTQ	Martinique
MR	MRT	Mauritanie
MU	MUS	Maurice
MX	MEX	Mexique
MC	MCO	Monaco
MN	MNG	Mongolie
MD	MDA	République de Moldova
MS	MSR	Montserrat
MA	MAR	Maroc
MZ	MOZ	Mozambique
OM	OMN	Oman
NA	NAM	Namibie
NR	NRU	Nauru
NP	NPL	Népal
NL	NLD	Pays-Bas
AN	ANT	Antilles Néerlandaises
AW	ABW	Aruba
NC	NCL	Nouvelle-Calédonie
VU	VUT	Vanuatu
NZ	NZL	Nouvelle-Zélande
NI	NIC	Nicaragua
NE	NER	Niger
NG	NGA	Nigéria
NU	NIU	Niué
NF	NFK	Île Norfolk
NO	NOR	Norvège
MP	MNP	Îles Mariannes du Nord
UM	UMI	Îles Mineures Éloignées des États-Unis
FM	FSM	États Fédérés de Micronésie
MH	MHL	Îles Marshall
PW	PLW	Palaos
PK	PAK	Pakistan
PA	PAN	Panama
PG	PNG	Papouasie-Nouvelle-Guinée
PY	PRY	Paraguay
PE	PER	Pérou
PH	PHL	Philippines
PN	PCN	Pitcairn
PL	POL	Pologne
PT	PRT	Portugal
GW	GNB	Guinée-Bissau
TL	TLS	Timor-Leste
PR	PRI	Porto Rico
QA	QAT	Qatar
RE	REU	Réunion
RO	ROU	Roumanie
RU	RUS	Fédération de Russie
RW	RWA	Rwanda
SH	SHN	Sainte-Hélène
KN	KNA	Saint-Kitts-et-Nevis
AI	AIA	Anguilla
LC	LCA	Sainte-Lucie
PM	SPM	Saint-Pierre-et-Miquelon
VC	VCT	Saint-Vincent-et-les Grenadines
SM	SMR	Saint-Marin
ST	STP	Sao Tomé-et-Principe
SA	SAU	Arabie Saoudite
SN	SEN	Sénégal
SC	SYC	Seychelles
SL	SLE	Sierra Leone
SG	SGP	Singapour
SK	SVK	Slovaquie
VN	VNM	Viet Nam
SI	SVN	Slovénie
SO	SOM	Somalie
ZA	ZAF	Afrique du Sud
ZW	ZWE	Zimbabwe
ES	ESP	Espagne
EH	ESH	Sahara Occidental
SD	SDN	Soudan
SR	SUR	Suriname
SJ	SJM	Svalbard etÎle Jan Mayen
SZ	SWZ	Swaziland
SE	SWE	Suède
CH	CHE	Suisse
SY	SYR	République Arabe Syrienne
TJ	TJK	Tadjikistan
TH	THA	Thaïlande
TG	TGO	Togo
TK	TKL	Tokelau
TO	TON	Tonga
TT	TTO	Trinité-et-Tobago
AE	ARE	Émirats Arabes Unis
TN	TUN	Tunisie
TR	TUR	Turquie
TM	TKM	Turkménistan
TC	TCA	Îles Turks et Caïques
TV	TUV	Tuvalu
UG	UGA	Ouganda
UA	UKR	Ukraine
MK	MKD	L'ex-République Yougoslave de Macédoine
EG	EGY	Égypte
GB	GBR	Royaume-Uni
IM	IMN	Île de Man
TZ	TZA	République-Unie de Tanzanie
US	USA	États-Unis
VI	VIR	Îles Vierges des États-Unis
BF	BFA	Burkina Faso
UY	URY	Uruguay
UZ	UZB	Ouzbékistan
VE	VEN	Venezuela
WF	WLF	Wallis et Futuna
WS	WSM	Samoa
YE	YEM	Yémen
CS	SCG	Serbie-et-Monténégro
ZM	ZMB	Zambie
RS	SRB	Serbie
ME	MNE	Monténégro
CW	CUW	Curaçao
GG	GGY	Guernesey
JE	JEY	Jersey
BQ	BES	Bonaire Saint Eustache et Saba
BL	BLM	Saint barthélemy
MF	MAF	Saint-Martin
SX	SXM	Saint-Martin partie Néerlandaise
SS	SSD	Soudan du Sud