API Documentation

Integrate LegallyMail into your application with our REST API

View Service Status
Navigation

Introduction

The LegallyMail API allows you to send certified emails from your application. All sends are recorded and you can obtain legal certificates of delivery and reading.

Note: Only users who have made at least one payment can use the API and create tokens.
Test the API

Authentication

All API requests require authentication via an access token. You can get your token from the user panel.

Method 1: Authorization Header

Include the token in the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

Method 2: In request body

Include the token in the JSON body:

{
  "token": "YOUR_TOKEN_HERE",
  "recipient": "example@example.com",
  ...
}

Get a Token

To get an API token, you must first have made at least one payment. Then you can create tokens from your user panel.

Login

Endpoints

POST /api/send

Send a certified email.

Parameters
Parameter Type Required Description
Authorization string (header) Yes Authentication token in "Bearer {token}" format or just the token
recipient / to string Yes Recipient email address
Multiple Recipients: You can send to multiple recipients by separating emails with commas (e.g., "email1@example.com, email2@example.com, email3@example.com")
Default limit: 10 recipients. This limit can be increased upon request by contacting support.
subject string Yes Email subject
message / body / content string (HTML) Yes Email content in HTML format
reply_to string (email) No Email address for replies. It must be a registered and verified sender in your account (optional).
reply_to_name string No Reply name (optional)
attachments array No Array of attachment files (optional). Each file must have: filename, content (base64), mime_type
Ejemplos de código
curl -X POST https://legallymail.com/api/send \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "recipient1@example.com, recipient2@example.com, recipient3@example.com",
    "subject": "Test Email with Multiple Recipients",
    "message": "<h1>Hello World</h1><p>This email is sent to multiple recipients.</p>",
    "attachments": [
      {
        "filename": "document.pdf",
        "content": "base64_encoded_file_content_here",
        "mime_type": "application/pdf"
      }
    ]
  }'
<?php
$token = 'YOUR_TOKEN_HERE';
$url = 'https://legallymail.com/api/send';

// Leer el archivo y codificarlo en base64
$filePath = '/path/to/document.pdf';
$fileContent = base64_encode(file_get_contents($filePath));

$data = [
    'recipient' => 'recipient1@example.com, recipient2@example.com, recipient3@example.com',
    'subject' => 'Test Email with Multiple Recipients',
    'message' => '<h1>Hello World</h1><p>This email is sent to multiple recipients.</p>',
    'attachments' => [
        [
            'filename' => 'document.pdf',
            'content' => $fileContent,
            'mime_type' => 'application/pdf'
        ]
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
?>
import requests
import base64

token = 'YOUR_TOKEN_HERE'
url = 'https://legallymail.com/api/send'

# Leer el archivo y codificarlo en base64
with open('/path/to/document.pdf', 'rb') as file:
    file_content = base64.b64encode(file.read()).decode('utf-8')

data = {
    'recipient': 'recipient1@example.com, recipient2@example.com, recipient3@example.com',
    'subject': 'Test Email with Multiple Recipients',
    'message': '<h1>Hello World</h1><p>This email is sent to multiple recipients.</p>',
    'attachments': [
        {
            'filename': 'document.pdf',
            'content': file_content,
            'mime_type': 'application/pdf'
        }
    ]
}

headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json'
}

response = requests.post(url, json=data, headers=headers)
result = response.json()
const token = 'YOUR_TOKEN_HERE';
const url = 'https://legallymail.com/api/send';

// Leer el archivo y codificarlo en base64 (Node.js)
const fs = require('fs');
const filePath = '/path/to/document.pdf';
const fileContent = fs.readFileSync(filePath).toString('base64');

const data = {
    recipient: 'recipient1@example.com, recipient2@example.com, recipient3@example.com',
    subject: 'Test Email with Multiple Recipients',
    message: '<h1>Hello World</h1><p>This email is sent to multiple recipients.</p>',
    attachments: [
        {
            filename: 'document.pdf',
            content: fileContent,
            mime_type: 'application/pdf'
        }
    ]
};

fetch(url, {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.error('Error:', error));
package main

import (
    'bytes'
    'encoding/base64'
    'encoding/json'
    'io/ioutil'
    'net/http'
)

func main() {
    token := 'YOUR_TOKEN_HERE'
    url := 'https://legallymail.com/api/send'

    // Leer el archivo y codificarlo en base64
    filePath := '/path/to/document.pdf'
    fileContent, _ := ioutil.ReadFile(filePath)
    fileBase64 := base64.StdEncoding.EncodeToString(fileContent)

    data := map[string]interface{}{
        'recipient': 'recipient1@example.com, recipient2@example.com, recipient3@example.com',
        'subject':   'Test Email with Multiple Recipients',
        'message':   '<h1>Hello World</h1><p>This email is sent to multiple recipients.</p>',
        'attachments': []map[string]string{
            {
                'filename':  'document.pdf',
                'content':   fileBase64,
                'mime_type': 'application/pdf',
            },
        },
    }

    jsonData, _ := json.Marshal(data)

    req, _ := http.NewRequest('POST', url, bytes.NewBuffer(jsonData))
    req.Header.Set('Authorization', 'Bearer '+token)
    req.Header.Set('Content-Type', 'application/json')

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import com.google.gson.Gson;

public class SendEmail {
    public static void main(String[] args) throws IOException, InterruptedException {
        String token = 'YOUR_TOKEN_HERE';
        String url = 'https://legallymail.com/api/send';

        // Leer el archivo y codificarlo en base64
        String filePath = '/path/to/document.pdf';
        byte[] fileBytes = Files.readAllBytes(Paths.get(filePath));
        String fileBase64 = Base64.getEncoder().encodeToString(fileBytes);

        Map<String, Object> attachment = new HashMap<>();
        attachment.put('filename', 'document.pdf');
        attachment.put('content', fileBase64);
        attachment.put('mime_type', 'application/pdf');

        Map<String, Object> data = new HashMap<>();
        data.put('recipient', 'example@example.com');
        data.put('subject', 'Test Email with Attachment');
        data.put('message', '<h1>Hello World</h1><p>This email contains an attachment.</p>');
        data.put('attachments', Arrays.asList(attachment));

        Gson gson = new Gson();
        String jsonData = gson.toJson(data);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header('Authorization', 'Bearer ' + token)
            .header('Content-Type', 'application/json')
            .POST(HttpRequest.BodyPublishers.ofString(jsonData))
            .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    }
}
const https = require('https');
const fs = require('fs');

const token = 'YOUR_TOKEN_HERE';
const url = 'https://legallymail.com/api/send';

// Leer el archivo y codificarlo en base64
const filePath = '/path/to/document.pdf';
const fileContent = fs.readFileSync(filePath).toString('base64');

const data = {
    recipient: 'example@example.com',
    subject: 'Test Email with Attachment',
    message: '<h1>Hello World</h1><p>This email contains an attachment.</p>',
    attachments: [
        {
            filename: 'document.pdf',
            content: fileContent,
            mime_type: 'application/pdf'
        }
    ]
};

const options = {
    hostname: 'legallymail.com',
    path: '/api/send',
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
    }
};

const req = https.request(options, (res) => {
    let responseData = '';
    res.on('data', (chunk) => {
        responseData += chunk;
    });
    res.on('end', () => {
        const result = JSON.parse(responseData);
        console.log(result);
    });
});

req.on('error', (error) => {
    console.error('Error:', error);
});

req.write(JSON.stringify(data));
req.end();
using System;
using System.Net.Http;
using System.Text;
using System.IO;
using Newtonsoft.Json;

class Program
{
    static async System.Threading.Tasks.Task Main()
    {
        string token = 'YOUR_TOKEN_HERE';
        string url = 'https://legallymail.com/api/send';

        // Leer el archivo y codificarlo en base64
        string filePath = '/path/to/document.pdf';
        byte[] fileBytes = File.ReadAllBytes(filePath);
        string fileBase64 = Convert.ToBase64String(fileBytes);

        var attachment = new
        {
            filename = 'document.pdf',
            content = fileBase64,
            mime_type = 'application/pdf'
        };

        var data = new
        {
            recipient = 'recipient1@example.com, recipient2@example.com, recipient3@example.com',
            subject = 'Test Email with Multiple Recipients',
            message = '<h1>Hello World</h1><p>This email is sent to multiple recipients.</p>',
            attachments = new[] { attachment }
        };

        string jsonData = JsonConvert.SerializeObject(data);

        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add('Authorization', 'Bearer ' + token);
            var content = new StringContent(jsonData, Encoding.UTF8, 'application/json');

            var response = await client.PostAsync(url, content);
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}
Success Response
{
  "success": true,
  "message": "Email sent to 2 of 2 recipients",
  "data": {
    "tracking_id": "cm_parent_abc123",
    "recipients": [
      {
        "email": "recipient1@example.com",
        "status": "sent",
        "tracking_id": "cm_rec1_xyz",
        "error_details": null
      },
      {
        "email": "recipient2@example.com",
        "status": "sent",
        "tracking_id": "cm_rec2_abc",
        "error_details": null
      }
    ],
    "subject": "Test Email",
    "sent_at": "2024-01-15 10:30:00",
    "success_count": 2,
    "fail_count": 0,
    "error_status": null
  }
}
GET /api/info

Get API and authenticated user information

Returns information about the API and the authenticated user, including email, subscription plan, and remaining emails.

Parameters
Parameter Type Required Description
Authorization string (header) Yes Authentication token in "Bearer {token}" format or just the token
Ejemplos de código
curl -X GET https://legallymail.com/api/info \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
<?php
$token = 'YOUR_TOKEN_HERE';
$url = 'https://legallymail.com/api/info';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
?>
import requests

token = 'YOUR_TOKEN_HERE'
url = 'https://legallymail.com/api/info'

headers = {
    'Authorization': f'Bearer {token}'
}

response = requests.get(url, headers=headers)
result = response.json()
const token = 'YOUR_TOKEN_HERE';
const url = 'https://legallymail.com/api/info';

fetch(url, {
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${token}`
    }
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.error('Error:', error));
package main

import (
    'net/http'
    'io/ioutil'
)

func main() {
    token := 'YOUR_TOKEN_HERE'
    url := 'https://legallymail.com/api/info'

    req, _ := http.NewRequest('GET', url, nil)
    req.Header.Set('Authorization', 'Bearer '+token)

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
}
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class GetInfo {
    public static void main(String[] args) throws Exception {
        String token = 'YOUR_TOKEN_HERE';
        String url = 'https://legallymail.com/api/info';

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header('Authorization', 'Bearer ' + token)
            .GET()
            .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        String result = response.body();
    }
}
const https = require('https');

const token = 'YOUR_TOKEN_HERE';
const url = 'https://legallymail.com/api/info';

const options = {
    hostname: 'legallymail.com',
    path: '/api/info',
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${token}`
    }
};

const req = https.request(options, (res) => {
    let responseData = '';
    res.on('data', (chunk) => {
        responseData += chunk;
    });
    res.on('end', () => {
        const result = JSON.parse(responseData);
        console.log(result);
    });
});

req.on('error', (error) => {
    console.error('Error:', error);
});

req.end();
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        string token = 'YOUR_TOKEN_HERE';
        string url = 'https://legallymail.com/api/info';

        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add('Authorization', 'Bearer ' + token);
            
            var response = await client.GetAsync(url);
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}
Success Response
{
  "name": "LegallyMail API",
  "version": "1.0.0",
  "user": {
    "email": "usuario@example.com",
    "name": "Nombre Usuario",
    "plan": "professional",
    "plan_name": "Profesional",
    "plan_limit": 100,
    "extra_emails": 0,
    "remaining_emails": 75
  }
}
GET /api/emails

Get last sent emails

Returns a list of the last certified emails sent, including their status (sent, read, failed, bounced). Maximum 25 results. The error_status field provides additional information in case of failure or bounce.

Parameters
Parameter Type Required Description
Authorization string (header) Yes Authentication token in "Bearer {token}" format or just the token
limit integer (query) Yes Number of emails to return (between 1 and 25). Required.
Ejemplos de código
curl -X GET "https://legallymail.com/api/emails?limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
<?php
$token = 'YOUR_TOKEN_HERE';
$url = 'https://legallymail.com/api/emails?limit=10';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
?>
import requests

token = 'YOUR_TOKEN_HERE'
url = 'https://legallymail.com/api/emails'
params = {'limit': 10}

headers = {
    'Authorization': f'Bearer {token}'
}

response = requests.get(url, params=params, headers=headers)
result = response.json()
const token = 'YOUR_TOKEN_HERE';
const url = 'https://legallymail.com/api/emails?limit=10';

fetch(url, {
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${token}`
    }
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.error('Error:', error));
package main

import (
    'net/http'
    'io/ioutil'
)

func main() {
    token := 'YOUR_TOKEN_HERE'
    url := 'https://legallymail.com/api/emails?limit=10'

    req, _ := http.NewRequest('GET', url, nil)
    req.Header.Set('Authorization', 'Bearer '+token)

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
}
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class GetEmails {
    public static void main(String[] args) throws Exception {
        String token = 'YOUR_TOKEN_HERE';
        String url = 'https://legallymail.com/api/emails?limit=10';

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header('Authorization', 'Bearer ' + token)
            .GET()
            .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        String result = response.body();
    }
}
const https = require('https');

const token = 'YOUR_TOKEN_HERE';
const url = 'https://legallymail.com/api/emails?limit=10';

const options = {
    hostname: 'legallymail.com',
    path: '/api/emails?limit=10',
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${token}`
    }
};

const req = https.request(options, (res) => {
    let responseData = '';
    res.on('data', (chunk) => {
        responseData += chunk;
    });
    res.on('end', () => {
        const result = JSON.parse(responseData);
        console.log(result);
    });
});

req.on('error', (error) => {
    console.error('Error:', error);
});

req.end();
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        string token = 'YOUR_TOKEN_HERE';
        string url = 'https://legallymail.com/api/emails?limit=10';

        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add('Authorization', 'Bearer ' + token);
            
            var response = await client.GetAsync(url);
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}
Success Response
{
  "success": true,
  "count": 2,
  "limit": 10,
  "max_limit": 25,
  "emails": [
    {
      "id": 123,
      "tracking_id": "cm_abc123",
      "recipient": "example@example.com",
      "subject": "Test Email",
      "status": "read",
      "sent_at": "2024-01-15 10:30:00",
      "read_at": "2024-01-15 11:00:00",
      "created_at": "2024-01-15 10:30:00",
      "mailsender_id": "mail_xyz789",
      "is_multi_recipient": false,
      "recipient_count": 1,
      "error_status": null
    },
    {
      "id": 122,
      "tracking_id": "cm_def456",
      "recipient": "Multiple Recipients",
      "subject": "Group Email",
      "status": "pending",
      "sent_at": "2024-01-14 15:20:00",
      "read_at": null,
      "created_at": "2024-01-14 15:20:00",
      "mailsender_id": "mail_uvw012",
      "is_multi_recipient": true,
      "recipient_count": 5,
      "error_status": "Soft Bounce"
    }
  ]
}
GET /api/email

Get status of a specific email

Returns detailed information about a specific email identified by its tracking_id, including its current status (sent, read, failed, bounced), send and read dates, timestamp certificates (TSQ/TSR) if they exist, and error details in the error_status field.

Parameters
Parameter Type Required Description
Authorization string (header) Yes Authentication token in "Bearer {token}" format or just the token
tracking_id string (query) Yes The unique tracking identifier (tracking_id) returned when sending the email.
Ejemplos de código
curl -X GET "https://legallymail.com/api/email?tracking_id=cm_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
<?php
$token = 'YOUR_TOKEN_HERE';
$trackingId = 'cm_abc123';
$url = 'https://legallymail.com/api/email?tracking_id=' . urlencode($trackingId);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
?>
import requests

token = 'YOUR_TOKEN_HERE'
url = 'https://legallymail.com/api/email'
params = {'tracking_id': 'cm_abc123'}

headers = {
    'Authorization': f'Bearer {token}'
}

response = requests.get(url, params=params, headers=headers)
result = response.json()
const token = 'YOUR_TOKEN_HERE';
const trackingId = 'cm_abc123';
const url = `https://legallymail.com/api/email?tracking_id=${trackingId}`;

fetch(url, {
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${token}`
    }
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.error('Error:', error));
package main

import (
    'net/http'
    'io/ioutil'
    'net/url'
)

func main() {
    token := 'YOUR_TOKEN_HERE'
    trackingId := 'cm_abc123'
    baseUrl := 'https://legallymail.com/api/email'
    
    params := url.Values{}
    params.Add('tracking_id', trackingId)
    fullUrl := baseUrl + '?' + params.Encode()

    req, _ := http.NewRequest('GET', fullUrl, nil)
    req.Header.Set('Authorization', 'Bearer '+token)

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
}
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class GetEmail {
    public static void main(String[] args) throws Exception {
        String token = 'YOUR_TOKEN_HERE';
        String trackingId = 'cm_abc123';
        String url = 'https://legallymail.com/api/email?tracking_id=' + trackingId;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header('Authorization', 'Bearer ' + token)
            .GET()
            .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        String result = response.body();
    }
}
const https = require('https');

const token = 'YOUR_TOKEN_HERE';
const trackingId = 'cm_abc123';
const url = `https://legallymail.com/api/email?tracking_id=${trackingId}`;

const options = {
    hostname: 'legallymail.com',
    path: `/api/email?tracking_id=${trackingId}`,
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${token}`
    }
};

const req = https.request(options, (res) => {
    let responseData = '';
    res.on('data', (chunk) => {
        responseData += chunk;
    });
    res.on('end', () => {
        const result = JSON.parse(responseData);
        console.log(result);
    });
});

req.on('error', (error) => {
    console.error('Error:', error);
});

req.end();
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        string token = 'YOUR_TOKEN_HERE';
        string trackingId = 'cm_abc123';
        string url = $"https://legallymail.com/api/email?tracking_id={trackingId}";

        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add('Authorization', 'Bearer ' + token);
            
            var response = await client.GetAsync(url);
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}
Success Response
{
  "success": true,
  "email": {
    "id": 123,
    "tracking_id": "cm_abc123",
    "recipient": "Multiple Recipients",
    "subject": "Group Email",
    "status": "pending",
    "sent_at": "2024-01-15 10:30:00",
    "read_at": null,
    "created_at": "2024-01-15 10:30:00",
    "mailsender_id": "mail_xyz789",
    "is_multi_recipient": true,
    "recipient_count": 2,
    "error_status": null,
    "certificates": [],
    "recipients": [
      {
        "email": "recipient1@example.com",
        "name": "Recipient One",
        "status": "read",
        "tracking_id": "cm_rec1_xyz",
        "sent_at": "2024-01-15 10:30:05",
        "delivered_at": "2024-01-15 10:30:10",
        "read_at": "2024-01-15 11:00:00",
        "error_details": null,
        "certificates": [
          {
            "certificate_type": "read",
            "file_hash": "sha256_hash_read_1",
            "confirmed_at": "2024-01-15 11:00:00",
            "has_tsr": true,
            "has_tsq": true,
            "pdf_download_url": "https://legallymail.com/emails/download-certificate?id=cm_rec1_xyz&status=read"
          }
        ]
      },
      {
        "email": "recipient2@example.com",
        "name": "Recipient Two",
        "status": "delivered",
        "tracking_id": "cm_rec2_abc",
        "sent_at": "2024-01-15 10:30:05",
        "delivered_at": "2024-01-15 10:30:12",
        "read_at": null,
        "error_details": "Recipient inbox full",
        "certificates": [
          {
            "certificate_type": "delivered",
            "file_hash": "sha256_hash_del_2",
            "confirmed_at": "2024-01-15 10:30:12",
            "has_tsr": true,
            "has_tsq": true,
            "pdf_download_url": "https://legallymail.com/emails/download-certificate?id=cm_rec2_abc&status=delivered"
          }
        ]
      }
    ]
  }
}
POST /api/signature/send

Request an electronic signature

Create a new electronic signature request by sending a document in base64 format.

Parameters
Parameter Type Required Description
signer_name string Yes Signer's full name.
signer_email string Yes Signer's email where the request will be received.
signer_phone string No Signer's phone for SMS validation (optional).
signers array No Array of signers for the document (max 5). Each signer must have: name, email, phone (optional).
document string (base64) Yes Base64 encoded PDF document content (max 10MB).
document_name string Yes File name the signer will see.
language string No Language for the signature interface and emails (es, en, fr, it). (default: es)
Ejemplos de código
curl -X POST https://legallymail.com/api/signature/send \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "signer_name": "John Doe",
    "signer_email": "john.doe@example.com",
    "document": "BASE64_CONTENT_HERE",
    "document_name": "Contract.pdf",
    "language": "es"
  }'
Multi-signer example (up to 5)
curl -X POST https://legallymail.com/api/signature/send \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "signers": [
        {"name": "Firmante 1", "email": "firmante1@example.com"},
        {"name": "Firmante 2", "email": "firmante2@example.com", "phone": "+34600000000"}
    ],
    "document": "BASE64_CONTENT_HERE",
    "document_name": "Contract.pdf",
    "language": "es"
  }'
<?php
$url = "https://legallymail.com/api/signature/send";
$token = "YOUR_TOKEN_HERE";
$data = [
    "signer_name" => "John Doe",
    "signer_email" => "john.doe@example.com",
    "document" => base64_encode(file_get_contents("document.pdf")),
    "document_name" => "Contract.pdf",
    "language" => "es"
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $token",
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
Multi-signer example (PHP)
<?php
$url = "https://legallymail.com/api/signature/send";
$token = "YOUR_TOKEN_HERE";
$data = [
    "signers" => [
        ["name" => "Firmante 1", "email" => "firmante1@example.com"],
        ["name" => "Firmante 2", "email" => "firmante2@example.com", "phone" => "+34600000000"]
    ],
    "document" => base64_encode(file_get_contents("document.pdf")),
    "document_name" => "Contract.pdf",
    "language" => "es"
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $token",
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
import requests
import base64

url = "https://legallymail.com/api/signature/send"
token = "YOUR_TOKEN_HERE"

with open("document.pdf", "rb") as f:
    doc_base64 = base64.b64encode(f.read()).decode("utf-8")

payload = {
    "signer_name": "John Doe",
    "signer_email": "john.doe@example.com",
    "document": doc_base64,
    "document_name": "Contract.pdf",
    "language": "es"
}

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
2622:
Multi-signer example (Python)
import requests
 import base64
 
 url = "https://legallymail.com/api/signature/send"
 token = "YOUR_TOKEN_HERE"
 
 with open("document.pdf", "rb") as f:
     doc_base64 = base64.b64encode(f.read()).decode("utf-8")
 
 payload = {
     "signers": [
         {"name": "Firmante 1", "email": "firmante1@example.com"},
         {"name": "Firmante 2", "email": "firmante2@example.com", "phone": "+34600000000"}
     ],
     "document": doc_base64,
     "document_name": "Contract.pdf",
     "language": "es"
 }
 
 headers = {
     "Authorization": f"Bearer {token}",
     "Content-Type": "application/json"
 }
 
 response = requests.post(url, json=payload, headers=headers)
 print(response.json())
const url = "https://legallymail.com/api/signature/send";
const token = "YOUR_TOKEN_HERE";

const payload = {
    signer_name: "John Doe",
    signer_email: "john.doe@example.com",
    document: "BASE64_CONTENT_HERE",
    document_name: "Contract.pdf",
    language: "es"
};

fetch(url, {
    method: "POST",
    headers: {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));
2672:
Multi-signer example (JavaScript)
const url = "https://legallymail.com/api/signature/send";
 const token = "YOUR_TOKEN_HERE";
 
 const payload = {
     signers: [
         {name: "Firmante 1", email: "firmante1@example.com"},
         {name: "Firmante 2", email: "firmante2@example.com", phone: "+34600000000"}
     ],
     document: "BASE64_CONTENT_HERE",
     document_name: "Contract.pdf",
     language: "es"
 };
 
 fetch(url, {
     method: "POST",
     headers: {
         "Authorization": `Bearer ${token}`,
         "Content-Type": "application/json"
     },
     body: JSON.stringify(payload)
 })
 .then(response => response.json())
 .then(data => console.log(data))
 .catch(error => console.error("Error:", error));
package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    url := "https://legallymail.com/api/signature/send"
    token := "YOUR_TOKEN_HERE"

    payload := map[string]string{
        "signer_name":  "John Doe",
        "signer_email": "john.doe@example.com",
        "document":      "BASE64_CONTENT_HERE",
        "document_name": "Contract.pdf",
        "language":      "es",
    }
    jsonPayload, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonPayload))
    req.Header.Set("Authorization", "Bearer "+token)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class SendSignature {
    public static void main(String[] args) throws Exception {
        String url = "https://legallymail.com/api/signature/send";
        String token = "YOUR_TOKEN_HERE";
        String json = "{\"signer_name\":\"John Doe\",\"signer_email\":\"john.doe@example.com\",\"document\":\"BASE64\",\"document_name\":\"Contract.pdf\"}";

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", "Bearer " + token)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
const axios = require('axios');
const fs = require('fs');

const url = "https://legallymail.com/api/signature/send";
const token = "YOUR_TOKEN_HERE";

const docBase64 = fs.readFileSync('document.pdf', { encoding: 'base64' });

const payload = {
    signer_name: "John Doe",
    signer_email: "john.doe@example.com",
    document: docBase64,
    document_name: "Contract.pdf",
    language: "es"
};

axios.post(url, payload, {
    headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
    }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));
using System;
using System.Net.Http;
using System.Text;
using System.IO;
using Newtonsoft.Json;

class Program {
    static async System.Threading.Tasks.Task Main() {
        string url = "https://legallymail.com/api/signature/send";
        string token = "YOUR_TOKEN_HERE";
        
        byte[] fileBytes = File.ReadAllBytes("document.pdf");
        string docBase64 = Convert.ToBase64String(fileBytes);

        var payload = new {
            signer_name = "John Doe",
            signer_email = "john.doe@example.com",
            document = docBase64,
            document_name = "Contract.pdf",
            language = "es"
        };

        using (var client = new HttpClient()) {
            client.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);
            var content = new StringContent(JsonConvert.SerializeObject(payload), Encoding.UTF8, "application/json");
            var response = await client.PostAsync(url, content);
            Console.WriteLine(await response.Content.ReadAsStringAsync());
        }
    }
}
Success Response
{
  "success": true,
  "message": "Signature request sent successfully",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "signer_name": "John Doe",
    "signer_email": "john.doe@example.com",
    "document_name": "Contract.pdf",
    "status": "pending",
    "created_at": "2024-01-15 10:30:00"
  }
}
GET /api/signatures

List your signature requests

Returns a list of electronic signature requests made.

Parameters
Parameter Type Required Description
limit int No Number of emails to return (between 1 and 25). Required. (max 25)
Ejemplos de código
curl -X GET "https://legallymail.com/api/signatures?limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
<?php
$token = "YOUR_TOKEN_HERE";
$url = "https://legallymail.com/api/signatures?limit=10";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $token"
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
import requests

url = "https://legallymail.com/api/signatures"
headers = {"Authorization": "Bearer YOUR_TOKEN_HERE"}
params = {"limit": 10}

response = requests.get(url, headers=headers, params=params)
print(response.json())
fetch("https://legallymail.com/api/signatures?limit=10", {
    headers: {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
    }
})
.then(res => res.json())
.then(data => console.log(data));
package main
import ("net/http"; "io/ioutil")

func main() {
    req, _ := http.NewRequest("GET", "https://legallymail.com/api/signatures?limit=10", nil)
    req.Header.Set("Authorization", "Bearer YOUR_TOKEN_HERE")
    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    body, _ := ioutil.ReadAll(resp.Body)
    _ = body
}
import java.net.http.*;
import java.net.URI;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create("https://legallymail.com/api/signatures?limit=10"))
            .header("Authorization", "Bearer YOUR_TOKEN_HERE")
            .build();
        System.out.println(client.send(req, HttpResponse.BodyHandlers.ofString()).body());
    }
}
const axios = require("axios");
axios.get("https://legallymail.com/api/signatures?limit=10", {
    headers: { Authorization: "Bearer YOUR_TOKEN_HERE" }
}).then(res => console.log(res.data));
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_TOKEN_HERE");
var res = await client.GetStringAsync("https://legallymail.com/api/signatures?limit=10");
Console.WriteLine(res);
Success Response
{
  "success": true,
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "signer_name": "John Doe",
      "signer_email": "john.doe@example.com",
      "document_name": "Contract.pdf",
      "status": "signed",
      "created_at": "2024-01-15 10:30:00",
      "signed_at": "2024-01-15 11:00:00"
    },
    ...
  ]
}
GET /api/signature

Get status of a signature

Get detailed information and the current status of a specific signature request.

Parameters
Parameter Type Required Description
uuid string Yes The unique identifier (UUID) of the electronic signature.
Ejemplos de código
curl -X GET "https://legallymail.com/api/signature?uuid=YOUR_UUID_HERE" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
<?php
$token = "YOUR_TOKEN_HERE";
$uuid = "YOUR_UUID_HERE";
$url = "https://legallymail.com/api/signature?uuid=$uuid";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer $token"]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
import requests
url = "https://legallymail.com/api/signature"
headers = {"Authorization": "Bearer YOUR_TOKEN_HERE"}
params = {"uuid": "YOUR_UUID_HERE"}
response = requests.get(url, headers=headers, params=params)
print(response.json())
fetch("https://legallymail.com/api/signature?uuid=YOUR_UUID_HERE", {
    headers: { Authorization: "Bearer YOUR_TOKEN_HERE" }
}).then(res => res.json()).then(data => console.log(data));
package main
import ("net/http"; "io/ioutil")
func main() {
    req, _ := http.NewRequest("GET", "https://legallymail.com/api/signature?uuid=YOUR_UUID_HERE", nil)
    req.Header.Set("Authorization", "Bearer YOUR_TOKEN_HERE")
    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    body, _ := ioutil.ReadAll(resp.Body)
    _ = body
}
import java.net.http.*;
import java.net.URI;
public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create("https://legallymail.com/api/signature?uuid=YOUR_UUID_HERE"))
            .header("Authorization", "Bearer YOUR_TOKEN_HERE")
            .build();
        System.out.println(client.send(req, HttpResponse.BodyHandlers.ofString()).body());
    }
}
const axios = require("axios");
axios.get("https://legallymail.com/api/signature?uuid=YOUR_UUID_HERE", {
    headers: { Authorization: "Bearer YOUR_TOKEN_HERE" }
}).then(res => console.log(res.data));
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_TOKEN_HERE");
var res = await client.GetStringAsync("https://legallymail.com/api/signature?uuid=YOUR_UUID_HERE");
Console.WriteLine(res);
Success Response
{
  "success": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "signer_name": "John Doe",
    "signer_email": "john.doe@example.com",
    "document_name": "Contract.pdf",
    "status": "signed",
    "created_at": "2024-01-15 10:30:00",
    "signed_at": "2024-01-15 11:00:00",
    "expires_at": "2024-01-22 10:30:00",
    "document_hash": "...",
    "signed_document_hash": "...",
    "signers": [
      {
        "signer_name": "John Doe",
        "signer_email": "john.doe@example.com",
        "signer_phone": "+34600000000",
        "status": "signed",
        "signed_at": "2024-01-15 11:00:00"
      }
    ],
    "download_original_url": "https://legallymail.com/dashboard/electronic-signature/download-original/...",
    "download_acta_url": "https://legallymail.com/dashboard/electronic-signature/download-acta/..."
  }
}
POST /api/sms/send

Sends a certified SMS. 1 certified SMS credit is deducted from your account (up to 300 characters).

Parameters
Parameter Type Required Description
Authorization string (header) Yes Bearer token or the token obtained from /api/auth/login.
phone / recipient string Yes Phone number with country code (e.g., +34600000000).
message / text string Yes SMS content. 1 credit per message up to 300 characters.
Success Response
{
  "success": true,
  "uuid": "...",
  "status": "sent",
  "credits_deducted": 1,
  "message": "Certified SMS sent successfully"
}
GET /api/sms

Gets the status of a previously sent certified SMS.

Parameters
Parameter Type Required Description
Authorization string (header) Yes Bearer token or the token obtained from /api/auth/login.
uuid / id string (query) Yes Unique SMS identifier returned when sending.
Success Response
{
  "success": true,
  "data": {
    "uuid": "...",
    "recipient": "+34600000000",
    "message": "Contenido del SMS",
    "status": "delivered",
    "credits": 1,
    "sent_at": "2024-01-15 10:30:00",
    "delivered_at": "2024-01-15 10:30:05",
    "failed_at": null,
    "ts_confirmed_at": "2024-01-15 10:30:10",
    "download_certificate_url": "https://legallymail.com/dashboard/certified-sms/download-certificate/..."
  }
}

Error Codes

Code Message Description
400 Bad Request The provided data is not valid
401 Unauthorized Invalid or missing token
403 Forbidden You do not have permission to perform this action
Also returned when the user has no remaining credits/emails available.
404 Not Found Resource not found. Verify that the requested resource exists (e.g., an email with the specified tracking_id).
405 Method Not Allowed HTTP method not allowed
429 Too Many Requests Too many requests. Rate limit exceeded.
500 Internal Server Error Internal server error

Limits and Restrictions

The API has the following restrictions:

  • Only users with at least one payment can use the API
  • Email limits depend on the user plan
  • Rate limits are applied to protect the service
  • Limit of 10 requests per minute per IP address (429 error if exceeded)
Real-Time