وثائق API

دمج LegallyMail في تطبيقك مع واجهة برمجة التطبيقات REST

مقدمة

تتيح لك واجهة برمجة تطبيقات LegallyMail إرسال رسائل بريد إلكتروني معتمدة من تطبيقك. يتم تسجيل جميع الإرسالات ويمكنك الحصول على شهادات قانونية للتسليم والقراءة.

ملاحظة: يمكن فقط للمستخدمين الذين قاموا بعملية دفع واحدة على الأقل استخدام واجهة برمجة التطبيقات وإنشاء الرموز.

المصادقة

تتطلب جميع طلبات واجهة برمجة التطبيقات المصادقة عبر رمز وصول. يمكنك الحصول على رمزك من لوحة المستخدم.

الطريقة 1: رأس التفويض

قم بتضمين الرمز في رأس التفويض:

Authorization: Bearer YOUR_TOKEN_HERE

الطريقة 2: في جسم الطلب

قم بتضمين الرمز في JSON الجسم:

{
  "token": "YOUR_TOKEN_HERE",
  "recipient": "[email protected]",
  ...
}

الحصول على رمز

للحصول على رمز API، يجب عليك أولاً إجراء عملية دفع واحدة على الأقل. ثم يمكنك إنشاء الرموز من لوحة المستخدم.

تسجيل الدخول

النقاط النهائية

POST /api/send

إرسال بريد إلكتروني معتمد.

المعلمات
المعامل النوع مطلوب الوصف
Authorization string (header) نعم رمز المصادقة بتنسيق "Bearer {token}" أو الرمز فقط
recipient / to string نعم عنوان بريد المستلم
مستلمون متعددون: يمكنك الإرسال إلى عدة مستلمين عن طريق فصل عناوين البريد الإلكتروني بفاصلات (مثال: "[email protected], [email protected], [email protected]")
الحد الافتراضي: 10 مستلمين. يمكن زيادة هذا الحد عند الطلب من خلال التواصل مع الدعم.
subject string نعم موضوع البريد الإلكتروني
message / body / content string (HTML) نعم محتوى البريد الإلكتروني بتنسيق HTML
reply_to string (email) لا عنوان البريد الإلكتروني للردود. يجب أن يكون مرسلًا مسجلاً ومتحققًا منه في حسابك (اختياري).
reply_to_name string لا اسم الرد (اختياري)
attachments array لا مصفوفة من ملفات المرفقات (اختياري). يجب أن يحتوي كل ملف على: filename, content (base64), mime_type
webhook_url string لا عنوان URL عام بتشفير HTTPS حيث سترسل LegallyMail إشعارات POST فورية بالأحداث (اختياري).
webhook_secret string لا مفتاح سري مشترك للتحقق من توقيع HMAC-SHA256 في ترويسة X-LegallyMail-Signature (اختياري ولكن موصى به).
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": "[email protected], [email protected], [email protected]",
    "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' => '[email protected], [email protected], [email protected]',
    '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': '[email protected], [email protected], [email protected]',
    '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: '[email protected], [email protected], [email protected]',
    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': '[email protected], [email protected], [email protected]',
        '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', '[email protected]');
        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: '[email protected]',
    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 = '[email protected], [email protected], [email protected]',
            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": true,
  "message": "Email sent to 2 of 2 recipients",
  "data": {
    "tracking_id": "cm_parent_abc123",
    "recipients": [
      {
        "email": "[email protected]",
        "status": "sent",
        "tracking_id": "cm_rec1_xyz",
        "error_details": null
      },
      {
        "email": "[email protected]",
        "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

الحصول على معلومات واجهة برمجة التطبيقات والمستخدم المصادق عليه

إرجاع معلومات حول واجهة برمجة التطبيقات والمستخدم المصادق عليه، بما في ذلك البريد الإلكتروني وخطة الاشتراك ورسائل البريد الإلكتروني المتبقية.

المعلمات
المعامل النوع مطلوب الوصف
Authorization string (header) نعم رمز المصادقة بتنسيق "Bearer {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);
        }
    }
}
استجابة النجاح
{
  "name": "LegallyMail API",
  "version": "1.0.0",
  "user": {
    "email": "[email protected]",
    "name": "Nombre Usuario",
    "plan": "professional",
    "plan_name": "Profesional",
    "plan_limit": 100,
    "extra_emails": 0,
    "remaining_emails": 75
  }
}
GET /api/emails

الحصول على آخر رسائل البريد الإلكتروني المرسلة

إرجاع قائمة بآخر رسائل البريد الإلكتروني المرسلة من قبل المستخدم المصادق عليه، بما في ذلك حالتها (sent, read, failed). الحد الأقصى 25 نتيجة.

المعلمات
المعامل النوع مطلوب الوصف
Authorization string (header) نعم رمز المصادقة بتنسيق "Bearer {token}" أو الرمز فقط
limit integer (query) نعم عدد رسائل البريد الإلكتروني المراد إرجاعها (بين 1 و 25). مطلوب.
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": true,
  "count": 2,
  "limit": 10,
  "max_limit": 25,
  "emails": [
    {
      "id": 123,
      "tracking_id": "cm_abc123",
      "recipient": "[email protected]",
      "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

الحصول على حالة بريد إلكتروني محدد

إرجاع معلومات مفصلة عن بريد إلكتروني محدد يتم التعرف عليه من خلال tracking_id الخاص به، بما في ذلك حالته الحالية (sent, read, failed) وتواريخ الإرسال والقراءة، وشهادات الطابع الزمني (TSQ/TSR) إذا كانت موجودة.

المعلمات
المعامل النوع مطلوب الوصف
Authorization string (header) نعم رمز المصادقة بتنسيق "Bearer {token}" أو الرمز فقط
tracking_id string (query) نعم معرف التتبع الفريد لرسالة البريد الإلكتروني (tracking_id) الذي يتم إرجاعه عند إرسال البريد الإلكتروني.
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": 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": "[email protected]",
        "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": "[email protected]",
        "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

Solicita una firma electrónica

Crea una nueva solicitud de firma electrónica enviando un documento en formato base64.

المعلمات
المعامل النوع مطلوب الوصف
signer_name string نعم Nombre completo del firmante.
signer_email string نعم Email del firmante donde recibirá la solicitud.
signer_phone string لا Teléfono del firmante para validación SMS (opcional).
signers array لا Array de firmantes del documento (máx 5). Cada firmante debe tener: name, email, phone (opcional).
document string (base64) نعم Contenido del documento PDF codificado en base64 (máx 10MB).
document_name string نعم Nombre del archivo que verá el firmante.
language string لا Idioma de la interfaz de firma y emails (es, en, fr, it). (default: es)
webhook_url string لا عنوان URL عام بتشفير HTTPS حيث سترسل LegallyMail إشعارات POST فورية بالأحداث (اختياري).
webhook_secret string لا مفتاح سري مشترك للتحقق من توقيع HMAC-SHA256 في ترويسة X-LegallyMail-Signature (اختياري ولكن موصى به).
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": "[email protected]",
    "document": "BASE64_CONTENT_HERE",
    "document_name": "Contract.pdf",
    "language": "es"
  }'
Ejemplo multi-firmante (hasta 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": "[email protected]"},
        {"name": "Firmante 2", "email": "[email protected]", "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" => "[email protected]",
    "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;
?>
Ejemplo multi-firmante (PHP)
<?php
$url = "https://legallymail.com/api/signature/send";
$token = "YOUR_TOKEN_HERE";
$data = [
    "signers" => [
        ["name" => "Firmante 1", "email" => "[email protected]"],
        ["name" => "Firmante 2", "email" => "[email protected]", "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": "[email protected]",
    "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:
Ejemplo multi-firmante (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": "[email protected]"},
         {"name": "Firmante 2", "email": "[email protected]", "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: "[email protected]",
    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:
Ejemplo multi-firmante (JavaScript)
const url = "https://legallymail.com/api/signature/send";
 const token = "YOUR_TOKEN_HERE";
 
 const payload = {
     signers: [
         {name: "Firmante 1", email: "[email protected]"},
         {name: "Firmante 2", email: "[email protected]", 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": "[email protected]",
        "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\":\"[email protected]\",\"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: "[email protected]",
    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 = "[email protected]",
            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": true,
  "message": "Signature request sent successfully",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "signer_name": "John Doe",
    "signer_email": "[email protected]",
    "document_name": "Contract.pdf",
    "status": "pending",
    "created_at": "2024-01-15 10:30:00"
  }
}
GET /api/signatures

Lista tus solicitudes de firma

Devuelve un listado de las solicitudes de firma electrónica realizadas.

المعلمات
المعامل النوع مطلوب الوصف
limit int لا عدد رسائل البريد الإلكتروني المراد إرجاعها (بين 1 و 25). مطلوب. (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": true,
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "signer_name": "John Doe",
      "signer_email": "[email protected]",
      "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

Consulta el estado de una firma

Obtén los detalles y el estado actual de una solicitud de firma específica.

المعلمات
المعامل النوع مطلوب الوصف
uuid string نعم El identificador único (UUID) de la firma electrónica.
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": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "signer_name": "John Doe",
    "signer_email": "[email protected]",
    "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": "[email protected]",
        "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

Envía un SMS certificado. Se descuenta 1 crédito de SMS certificado de tu cuenta (hasta 320 caracteres).

المعلمات
المعامل النوع مطلوب الوصف
Authorization string (header) نعم Token Bearer o el token obtenido en /api/auth/login.
phone / recipient string نعم Número de teléfono con código de país (ej: +34600000000).
message / text string نعم Contenido del SMS. 1 crédito por cada mensaje hasta 320 caracteres.
استجابة النجاح
{
  "success": true,
  "uuid": "...",
  "status": "sent",
  "credits_deducted": 1,
  "message": "Certified SMS sent successfully"
}
GET /api/sms

Obtiene el estado de un SMS certificado previamente enviado.

المعلمات
المعامل النوع مطلوب الوصف
Authorization string (header) نعم Token Bearer o el token obtenido en /api/auth/login.
uuid / id string (query) نعم Identificador único del SMS devuelto al realizar el envío.
استجابة النجاح
{
  "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/..."
  }
}
WEBHOOKS HMAC-SHA256

الخطافات الشبكية (Webhooks) في الوقت الفعلي

استقبل إشعارات فورية وموقعة تشفيرياً (التسليم، الفتح، التوقيع) دون الحاجة للاستعلام المتكرر (Polling) أو مهام cron المستمرة.

بنية موجهة بالأحداث: التخلص التام من الاستعلام المتكرر (Zero Polling)

إن الاستعلام المستمر عن الحالة عبر طلبات متكررة (GET /api/email, GET /api/signature) يستهلك موارد الخوادم ويسبب تأخيراً غير ضروري. يرسل نظام Webhooks طلباً فورياً من نوع HTTP POST في الجزء الدقيق من الثانية عند تسليم الرسالة، أو فتحها، أو إتمام التوقيع الإلكتروني eIDAS.

1. ¿Cómo configurar Webhooks?

Puedes configurar el endpoint receptor de dos formas:

Por Envío (Granular)

Incluye los parámetros opcionales webhook_url y webhook_secret directamente en el cuerpo JSON de tus peticiones POST /api/send o POST /api/signature/send.

Nivel de Cuenta

Configura y gestiona tus endpoints de webhook directamente desde tu panel de usuario para recibir automáticamente todos los eventos de correos y firmas.

2. الأحداث المتاحة

Evento Servicio Disparador y Contenido
email.sent Correo Certificado Se emite inmediatamente cuando el correo certificado es procesado y aceptado en cola por los servidores de envío de LegallyMail.
email.delivered Correo Certificado Se despacha en el milisegundo en que el servidor MX del destinatario confirma la recepción del mensaje con evidencia SHA-256.
email.opened Correo Certificado Se dispara cuando el destinatario abre o visualiza el correo certificado (primera lectura fehaciente confirmada).
email.failed Correo Certificado Se notifica si la entrega falla de forma definitiva (rebote duro, buzón inexistente o bloqueo) con el código de diagnóstico SMTP.
signature.completed Firma Electrónica Se envía cuando todos los firmantes han completado su rúbrica eIDAS. Incluye URLs para descarga del PDF sellado y del acta probatoria.
signature.rejected Firma Electrónica Se despacha si un firmante rechaza formalmente la firma, adjuntando el motivo y fecha exacta.
sms.delivered SMS Certificado Confirmación inmediata de entrega del SMS certificado por parte de la red del operador móvil.

3. الأمان والتحقق من توقيع HMAC-SHA256

Cada petición enviada por LegallyMail a tu servidor incluye encabezados HTTP de seguridad que garantizan que el webhook proviene legítimamente de nuestros servidores y protegen contra ataques de repetición (Replay Attacks):

Encabezado HTTP Descripción y Formato
X-LegallyMail-Signature Firma criptográfica HMAC-SHA256 con formato: t={timestamp},v1={hash_hex}
X-LegallyMail-Timestamp Marca temporal UNIX en segundos del momento de emisión del evento.
X-LegallyMail-Event Nombre del evento disparado (ej: email.delivered, signature.completed).
X-LegallyMail-Delivery Identificador único del despacho (UUID v4) para garantizar idempotencia en tu backend.
User-Agent LegallyMail-Webhooks/1.0 (+https://legallymail.com)

4. Estructura del Payload JSON

Simulador Interactivo de Webhooks en Vivo: Puedes probar la recepción y verificación de tu firma HMAC al instante desde el Simulador de Eventos en /api-tokens#webhooks con datos simulados y respuestas en tiempo real.

{
  "id": "evt_94a7e3d12c9b",
  "event": "email.delivered",
  "timestamp": 1729722300,
  "created_at": "2026-10-23T22:30:15+02:00",
  "api_version": "2026-01-01",
  "data": {
    "tracking_id": "em_8f431b920ca7",
    "recipient": "[email protected]",
    "subject": "Comunicación formal de fin de contrato",
    "status": "delivered",
    "sent_at": "2026-10-23 22:30:02",
    "delivered_at": "2026-10-23 22:30:15",
    "delivery_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "delivery_ts_confirmed": "2026-10-23 22:30:15",
    "download_certificate_url": "https://legallymail.com/emails/certificate/em_8f431b920ca7"
  }
}

{
  "id": "evt_6b1e84fa920d",
  "event": "email.opened",
  "timestamp": 1729722340,
  "created_at": "2026-10-23T22:30:55+02:00",
  "api_version": "2026-01-01",
  "data": {
    "tracking_id": "em_8f431b920ca7",
    "recipient": "[email protected]",
    "subject": "Comunicación formal de fin de contrato",
    "status": "opened",
    "sent_at": "2026-10-23 22:30:02",
    "delivered_at": "2026-10-23 22:30:15",
    "read_at": "2026-10-23 22:30:55",
    "read_hash": "a45f93b18c0e9b119dc2345eaf8896fb92427ae41e4649b934ca495991b78912",
    "read_ts_confirmed": "2026-10-23 22:30:55",
    "download_certificate_url": "https://legallymail.com/emails/certificate/em_8f431b920ca7"
  }
}

{
  "id": "evt_1a98c7e42d31",
  "event": "signature.completed",
  "timestamp": 1729722420,
  "created_at": "2026-10-23T22:32:15+02:00",
  "api_version": "2026-01-01",
  "data": {
    "uuid": "sig_49f8021c-a81e-450b-bb99-35a9d821e901",
    "document_name": "Acuerdo_Confidencialidad_NDA.pdf",
    "status": "signed",
    "signed_at": "2026-10-23 22:32:15",
    "document_hash": "b2f0a1c9...",
    "signed_document_hash": "f183d02a...",
    "ts_confirmed_at": "2026-10-23 22:32:16",
    "download_signed_pdf_url": "https://legallymail.com/electronic-signature/download/sig_49f8021c-a81e-450b-bb99-35a9d821e901?signed=1",
    "download_acta_url": "https://legallymail.com/electronic-signature/download/sig_49f8021c-a81e-450b-bb99-35a9d821e901?acta=1"
  }
}

5. Código de Verificación de Firma (HMAC-SHA256)

<?php
$webhookSecret = 'whsec_tu_secreto_configurado';

$payload = file_get_contents('php://input');
$sigHeader = $_SERVER['HTTP_X_LEGALLYMAIL_SIGNATURE'] ?? '';

// Extraer t (timestamp) y v1 (hash)
preg_match('/t=(\d+),v1=([a-f0-9]+)/', $sigHeader, $matches);
if (count($matches) !== 3) {
    http_response_code(400);
    exit('Firma no proporcionada o formato inválido');
}

$timestamp = $matches[1];
$receivedHash = $matches[2];

// Proteger contra ataques de repetición (tolerancia de 5 minutos = 300 segundos)
if (abs(time() - $timestamp) > 300) {
    http_response_code(400);
    exit('Firma expirada (Timestamp fuera de tolerancia)');
}

// Calcular firma esperada
$expectedHash = hash_hmac('sha256', $timestamp . '.' . $payload, $webhookSecret);

if (!hash_equals($expectedHash, $receivedHash)) {
    http_response_code(401);
    exit('Firma criptográfica inválida');
}

// Firma verificada con éxito
$event = json_decode($payload, true);

switch ($event['event']) {
    case 'email.delivered':
        // Procesar entrega inmediata
        break;
    case 'email.opened':
        // Procesar lectura fehaciente
        break;
    case 'signature.completed':
        // Procesar documento firmado
        break;
}

http_response_code(200);
echo json_encode(['status' => 'received']);
const express = require('express');
const crypto = require('crypto');
const app = express();

const WEBHOOK_SECRET = 'whsec_tu_secreto_configurado';

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
    const sigHeader = req.headers['x-legallymail-signature'];
    const rawBody = req.body.toString('utf8');

    if (!sigHeader) return res.status(400).send('Missing signature');

    const match = sigHeader.match(/t=(\d+),v1=([a-f0-9]+)/);
    if (!match) return res.status(400).send('Invalid signature format');

    const [_, timestamp, receivedHash] = match;

    // Tolerancia anti-replay: 5 minutos
    if (Math.abs(Date.now() / 1000 - timestamp) > 300) {
        return res.status(400).send('Timestamp expired');
    }

    const expectedHash = crypto
        .createHmac('sha256', WEBHOOK_SECRET)
        .update(`${timestamp}.${rawBody}`)
        .digest('hex');

    if (!crypto.timingSafeEqual(Buffer.from(expectedHash), Buffer.from(receivedHash))) {
        return res.status(401).send('Invalid signature');
    }

    const event = JSON.parse(rawBody);
    console.log(`Evento recibido: ${event.event}`, event.data);

    res.status(200).json({ received: true });
});

app.listen(3000);
import hmac
import hashlib
import time
import re
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
WEBHOOK_SECRET = "whsec_tu_secreto_configurado"

@app.post("/webhook")
async def handle_legallymail_webhook(request: Request):
    sig_header = request.headers.get("x-legallymail-signature")
    if not sig_header:
        raise HTTPException(status_code=400, detail="Missing signature")

    match = re.search(r"t=(\d+),v1=([a-f0-9]+)", sig_header)
    if not match:
        raise HTTPException(status_code=400, detail="Invalid signature header format")

    timestamp, received_hash = match.group(1), match.group(2)

    # Validar tolerancia de 5 minutos
    if abs(time.time() - int(timestamp)) > 300:
        raise HTTPException(status_code=400, detail="Timestamp expired")

    raw_body = await request.body()
    expected_hash = hmac.new(
        WEBHOOK_SECRET.encode('utf-8'),
        f"{timestamp}.".encode('utf-8') + raw_body,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected_hash, received_hash):
        raise HTTPException(status_code=401, detail="Invalid HMAC signature")

    event = await request.json()
    # Procesar event["event"]
    return {"status": "ok"}

6. سياسة إعادة المحاولة وعدم التكرار (Idempotency)

  • Respuesta 2xx: Tu servidor debe responder con un código de estado HTTP 200 o 204 en un máximo de 5 segundos.
  • Reintentos automáticos: Si tu endpoint responde con un error 5xx, timeout o no es alcanzable, LegallyMail reintenta el envío de forma automática con retroceso exponencial (inmediato, +1m, +5m, +15m, +1h).
  • Idempotencia: Usa el identificador X-LegallyMail-Delivery para descartar eventos duplicados si tu servidor ya procesó la notificación anteriormente.

رموز الخطأ

الرمز الرسالة الوصف
400 Bad Request البيانات الم provided غير صالحة
401 Unauthorized رمز غير صالح أو مفقود
403 Forbidden ليس لديك إذن لأداء هذا الإجراء
يُعاد أيضًا عندما لا يمتلك المستخدم رصيدًا/رسائل بريد إلكتروني متبقية متاحة.
404 Not Found الموارد غير موجودة. تحقق من وجود المورد المطلوب (على سبيل المثال، بريد إلكتروني مع tracking_id المحدد).
405 Method Not Allowed طريقة HTTP غير مسموحة
429 Too Many Requests طلبات كثيرة جدًا. تم تجاوز حد المعدل.
500 Internal Server Error خطأ داخلي في الخادم

الحدود والقيود

لدي واجهة برمجة التطبيقات القيود التالية:

  • يمكن فقط للمستخدمين الذين لديهم عملية دفع واحدة على الأقل استخدام واجهة برمجة التطبيقات
  • تعتمد حدود البريد الإلكتروني على خطة المستخدم
  • يتم تطبيق حدود المعدل لحماية الخدمة
  • حد 10 طلبات في الدقيقة لكل عنوان IP (خطأ 429 عند التجاوز)
  • Archivos adjuntos: Máximo 4MB por archivo adjunto (hasta 4 archivos por envío)
Escalabilidad de Rate Limiting: El límite base de 10 peticiones por minuto previene saturaciones accidentales. Si tu aplicación, ERP o CRM requiere una mayor cadencia de peticiones en horas punta, este límite se amplía progresivamente según la demanda de tu proyecto contactando con nuestro equipo de soporte.
دردشة مباشرة Lukas
جاري تحميل الدردشة...
Lukas (وكيل الدعم) escribiendo...