Integrointi

Kytke sovelluksesi
minuuteissa.

Kolme vaihetta, kaksi tapaa lähettää. Tällä sivulla ovat käyttöönotto-ohjeet, HTTP-rajapinnan kuvaus ja webhookit.

Luo lähetysympäristö

Kirjaudu app.hattara.io-sovellukseen ja luo sovelluksellesi lähetysympäristö. Saat sille omat SMTP-tunnukset ja API-avaimen.
Vahvista lähettäjädomain

Lisää sovelluksen näyttämät SPF-, DKIM- ja palautusosoitetietueet domainisi DNS:ään. Vahvistuksen jälkeen viestisi allekirjoitetaan automaattisesti.
Lähetä ensimmäinen viesti

Valitse SMTP tai HTTP API alta. Kehitystilassa viestit pysähtyvät lokiin, joten voit testata turvallisesti ennen tuotantoa.

SMTP

Nopein tapa: vaihda asetukset.

Jos sovelluksesi lähettää sähköpostia jo nyt, riittää että osoitat sen Hattaraan. Kaikki kirjastot ja rungot, jotka osaavat SMTP:n, toimivat sellaisenaan.

Käytä porttia 587 (STARTTLS) tai 465 (TLS). Tunnukset ovat ympäristökohtaisia, joten tuotannon avaimet eivät koskaan päädy testiympäristöön.

SMTP.env

SMTP_HOST=smtp.hattara.io
SMTP_PORT=587
SMTP_USER=omasovellus-tuotanto
SMTP_PASS=ympäristön salasana

# STARTTLS päälle — muuta ei tarvita

HTTP API

Rajapintakuvaus

Viestin lähetys

POST https://api.hattara.io/api/v1/send/message

Lähetä JSON-runko HTTPS:llä ja laita ympäristön API-avain X-Server-API-Key-otsakkeeseen. Esimerkki on oikealla.

Onnistunut vastaus sisältää status: "success" sekä lähetyksen message_id-tunnisteen. Sama tunniste näkyy viestilokissa ja webhookeissa, joten yksittäisen viestin matkan voi aina jäljittää.

curlsend/message

curl https://api.hattara.io/api/v1/send/message \
  -H "X-Server-API-Key: <avain>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["asiakas@example.com"],
    "from": "kuitit@omasovellus.fi",
    "subject": "Tilausvahvistus #1024",
    "html_body": "<h1>Kiitos tilauksesta!</h1>"
  }'

→ 200 OK
status: "success"
data.message_id: "9b2f-4c81-a3e7"

Kentät

Vastaanottajat ja lähettäjä

tolistaPakollinen

Vastaanottajat, enintään 50 per kutsu. Vähintään yksi vastaanottaja tässä tai kentissä cc/bcc.

frommerkkijonoPakollinen

Lähettäjäosoite vahvistetusta domainista.

cc · bcclista

Kopio- ja piilokopiovastaanottajat.

reply_tomerkkijono

Vastausosoite.

sendermerkkijono

Tekninen lähettäjä (Sender-otsake), jos eri kuin from.

Sisältö

subjectmerkkijonoPakollinen

Viestin aihe.

html_bodymerkkijonoVähintään toinen

HTML-sisältö. Anna tämä, plain_body tai molemmat, jolloin lähetetään multipart-viesti.

plain_bodymerkkijonoVähintään toinen

Tekstisisältö ilman muotoiluja.

attachmentslista

Liitteet objekteina: name, content_type ja data (base64).

headersobjekti

Omat otsakkeet avain–arvo-pareina.

Lisäasetukset

tagmerkkijono

Vapaa luokittelutunniste lokia ja tilastoja varten.

bouncetotuusarvo

Merkitse viesti bounce-viestiksi (ei automaattivastauksia).

Muut kutsut

POST /api/v1/send/raw

Lähetä valmis RFC 2822 -muotoinen viesti: mail_from, rcpt_to ja data (base64). Sopii kirjastoille, jotka rakentavat viestin itse.

POST /api/v1/messages/message

Hae yksittäisen viestin tiedot id:llä: tila, otsakkeet, sisältö ja toimitusketju.

POST /api/v1/messages/deliveries

Hae viestin toimitusyritykset ja SMTP-vastaukset id:llä.

Virheet

Virhetilanteessa vastauksen status on "error" tai "parameter-error" ja data.code kertoo syyn:

InvalidServerAPIKey

API-avain puuttuu tai on virheellinen.

ValidationError

Pakollinen kenttä puuttuu tai on väärän muotoinen.

NoRecipients

Yhtään vastaanottajaa ei annettu.

UnauthenticatedFromAddress

from-osoitteen domainia ei ole vahvistettu ympäristöön.

TooManyToAddresses

Yli 50 vastaanottajaa yhdessä kutsussa.

AttachmentMissingData

Liitteestä puuttuu sisältö tai nimi.

Webhookit

Tapahtumat suoraan sovellukseesi.

Lisää webhook-osoite ympäristön asetuksissa, niin Hattara kutsuu sitä HTTP POSTilla JSON-rungolla aina kun viestin tila muuttuu. Voit tilata kaikki tapahtumat tai vain osan.

Tapahtuma	Milloin
`MessageSent`	Viesti toimitettu vastaanottavalle palvelimelle
`MessageDelayed`	Toimitus viivästyi, uutta yritetään
`MessageDeliveryFailed`	Toimitus epäonnistui lopullisesti
`MessageBounced`	Viestistä saapui palautus
`MessageHeld`	Viesti pysäytetty (esim. kehitystila)
`MessageLoaded`	Vastaanottaja avasi viestin
`MessageLinkClicked`	Vastaanottaja klikkasi linkkiä

WebhookMessageSent

event: "MessageSent"
timestamp: 1783330867
payload:
  message.id: 1210
  message.token: "9b2f4c81"
  message.to: "asiakas@example.com"
  status: "Sent"
  details: "Message accepted"

Tunnukset odottavat.

Luo ilmainen ympäristö ja lähetä ensimmäinen viestisi tänään.

Luo tili