Python SDK

SDK ufficiale per Python: tratto-email. Nessuna dipendenza esterna, costruito su urllib. Richiede Python 3.10+.

Installazione

pip install tratto-email

Inizializzazione

from tratto import Tratto

client = Tratto('tratto_live_...')

Invia Email

from tratto import SendEmailOptions

result = client.emails.send(SendEmailOptions(
    from_='[email protected]',
    to='[email protected]',
    subject='Ciao!',
    html='<h1>Benvenuto!</h1>',
    text='Benvenuto a Tratto',
))

print(result['id'])  # email_abc123

Invia con Template

result = client.emails.send(SendEmailOptions(
    from_='[email protected]',
    to='[email protected]',
    subject='Benvenuto su Acme!',
    template_id='tmpl_abc123',
    variables={
        'firstName': 'Alice',
        'code': 'SECRET123',
    },
))

Invia con Markdown

Il campo markdown arriva nella versione 1.1.0 dell'SDK, non ancora pubblicata. Sulla release 1.0.0 attuale questi esempi falliscono — nel frattempo usa direttamente la REST API.

Invia Markdown e lascia che il server renderizzi HTML responsive per email — markdown è mutuamente esclusivo con html:

# In arrivo nella 1.1.0
result = client.emails.send(SendEmailOptions(
    from_='[email protected]',
    to='[email protected]',
    subject='Benvenuto!',
    markdown='# Benvenuto, {{firstName}}!',
    variables={'firstName': 'Alice'},
))

La stessa release aggiunge markdown a templates.create / templates.update (creando template format: 'emailmd'), con format, source e renderWarnings nelle risposte dei template.

Pianifica Invio

result = client.emails.send(SendEmailOptions(
    from_='[email protected]',
    to='[email protected]',
    subject='Promemoria',
    text='Ci vediamo domani!',
    scheduled_at='2025-07-01T09:00:00Z',
))

Ottieni Status Email

email = client.emails.get('email_abc123')
print(email['data']['status'])  # 'delivered'

Lista Email

response = client.emails.list(limit=50)
for email in response['data']:
    print(f"{email['id']}: {email['status']}")

Registra un Dominio

domain = client.domains.add('hello.tuodominio.it')
for record in domain['data']['records']:
    print(record['type'], record['host'], record['value'])

Verifica Dominio

result = client.domains.verify('dom_abc123')
print(result['data']['status'])  # 'pending', 'verified' oppure 'failed'

Crea Contatto

from tratto import CreateContactOptions

contact = client.contacts.create(CreateContactOptions(
    email='[email protected]',
    first_name='Alice',
    last_name='Smith',
    tags=['vip', 'newsletter'],
    custom_fields={'plan': 'pro'},
))

Crea Campagna

from tratto import CreateCampaignOptions

campaign = client.campaigns.create(CreateCampaignOptions(
    name='Saldi Q3',
    template_id='tmpl_abc123',
    audience_id='aud_abc123',
    from_name='Acme Newsletter',
    from_email='[email protected]',
    subject_a='Le nostre migliori offerte del Q3',
))

print(campaign['data']['id'])

Invia Campagna

sent = client.campaigns.send('camp_xyz789')
print(sent['data']['status'])  # 'sending'

Statistiche Campagna

stats = client.campaigns.get_stats('camp_xyz789')
print(stats['data']['stats']['delivered'])   # 4950
print(stats['data']['rates']['openRate'])    # 50 → 50%, i tassi sono percentuali

Registra Webhook

from tratto import CreateWebhookOptions

webhook = client.webhooks.create(CreateWebhookOptions(
    url='https://tuoapi.com/webhooks/tratto',
    events=['sent', 'delivered', 'opened', 'clicked', 'bounced'],
))

print(webhook['data']['secret'])  # whsec_xyz789... (restituito una sola volta)

Gestione Errori

from tratto import TrattoError

try:
    result = client.emails.send(SendEmailOptions(
        from_='[email protected]',
        to='[email protected]',
        subject='Ciao',
        text='Test',
    ))
except TrattoError as e:
    if e.code == 'FORBIDDEN':
        # Il messaggio indica quale dominio non è verificato.
        print(e)