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_12345678901234567890with 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.
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 Postcard Dashboard Settings or your Letter 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",
}
| 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 sidestrue 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_proofobject 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://www.mysendingbox.fr/app/dashboard/letters/settings) |
| 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. 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 |
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"
}
}
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 lror 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_Xexists - 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 : trueCan be : true : Will be print on front & back false : Will only be print on front |
| staple | boolean - Default : falseCan 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_pageCan 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_proofobject. 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 : c6Can 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 : falseShould 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. |
Response Object
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 'to.content=Please review the attached documents:' \
-F to.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"
}
}
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_Xexists - 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 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. |
Response Object
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"
}
}
]
}
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"
}
}
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
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"
}
}
}
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
Get the price of a Letter
GET 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 : paperChannel 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 : trueOnly 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
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'
},
// https://www.seeuletter.com/templates
"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
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
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
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 |
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 |
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_addedis 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
POSTand 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 : developerCan be : developer, startup or business. Useful to determine the price of a letter based on the monthly consumption. |
| both_sides | boolean - Default : trueCan 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
}'
// 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. You will then be able to send your user to a page on MySendingBox.fr where he can create a password and add a payment method.
You should save the API key received as an answer (in company.api_keys.live.key) in your database to be able to make API call on behalf of your user.
HTTP Request
POST https://api.mysendingbox.fr/accounts
Body Parameters
| Parameter | Description |
|---|---|
| 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.
usercompany
After getting an answer from the API you should send the user to
https://www.mysendingbox.fr/invite-register-partner/{user.invite_token}?branded_for=YOUR_COMPANY_NAME
On this page the user will be able to create a password for his account and add a payment method.
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",
}'
// 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 |
|---|---|
| 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 :
|
| tva | Applied Tax percentage. |
| country | Country name for invoicing. |
| invoices_lines | Array of Invoice line details. Each line is an object with following properties :
|
| total | All invoice totals. It's an object with following properties :
|
| discount | Discount information. It's an object with following properties :
|
| 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. |
Changelog
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
paperorelectronic - 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 :
staplecan betrueorfalse. It'sfalseby 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_pdfdocumentation
24/01/2018
- Adding Pricing documentation
- Disable
postage_type:prioritaireforpostage_speed:expressfor cost reason.
16/11/2017
- Adding Postcards documentation
10/11/2017
- Adding Python documentation
17/10/2017
- add
letter.delivery_proofhas a new event.
11/10/2017
- add
pdf_marginto add a margin around the PDF - add
postage_speedto choose betweenexpress,DandD1 - add
manage_delivery_proofto ask the system to handle the delivery proof. The delivery proof will be available as a file indelivery_proof. - add
envelope_windowwhich can besimpleordouble - add
mail_providerwhich can beAorB - add
sheet_countto distinguish the page count and the sheet count (1 sheet = 2 pages whenboth_sides:true) - Remove
sourcefrom 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_pagebypage_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 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 |