API: avaimet, päätepisteet ja webhookit

Pro-paketista alkaen

API antaa skriptille samat tiedot, jotka sovellus näyttää: organisaation verkkotunnukset, raportit, lähteet, DNS-tarkistukset ja hälytykset JSON-muodossa. Jokaisessa pyynnössä on mukana API-avain, ja kukin avain saa tehdä tietyn määrän pyyntöjä tunnissa, tasatunnista seuraavaan. Paketti määrää tämän määrän ja sen, montako avainta organisaatiolla voi olla.

Mitä kukin paketti sisältää

Pro-paketissa avaimella voi vain lukea. Teams-paketista alkaen avaimelle voi antaa myös kirjoitusoikeuden, ja kirjoittaminen tarkoittaa yhtä asiaa: viennin aloittamista. Näistä paketeista alkaen saat tietosi myös kolmella muulla tavalla:

• Webhookit, jotka kertovat palvelimellesi, kun jotain tapahtuu: Teams.
• Prometheus-mittarit: Teams.
• MCP avustajille: Teams.

Ensimmäinen pyyntö

Ylläpitäjä luo avaimen kohdassa Asetukset → Kehittäjille → API-avaimet, kuten sivu API-avaimet kertoo. Sivu näyttää avaimen vain kerran. Tämä pyyntö listaa verkkotunnuksesi:

curl -H "Authorization: Bearer YOUR_TOKEN" https://www.mailmoni.com/api/v1/domains

Jokaisen osoitteen alku on https://www.mailmoni.com/api/v1/, eikä osoitteen lopussa ole kauttaviivaa. Pyyntöjen luettelo luettelee jokaisen pyynnön ja kertoo, mitä se tekee.

Lähetä avain otsakkeessa

Laita avain Authorization-otsakkeeseen sanan Bearer ja välilyönnin jälkeen. Avain alkaa aina merkeillä mm_.

API hylkää osoitteessa olevan avaimen, vaikka otsake olisi oikein, koska osoitteet päätyvät lokeihin. Tämä koskee parametreja token, access_token ja api_key sekä mitä tahansa arvoa, joka näyttää avaimelta. Tällainen pyyntö saa vastauksen unauthorized.

API ei lähetä CORS-otsakkeita, joten verkkosivun JavaScript ei voi lukea sen vastauksia. Pidä avain skriptissä tai palvelimella.

Pyyntöjä tunnissa

Jokaisella avaimella on oma laskurinsa, joka laskee pyynnöt tunneittain UTC-ajassa. Laskenta alkaa alusta tasatunnilla. Jokaisessa vastauksessa laskettuun pyyntöön on kolme otsaketta:

• RateLimit-Limit: montako pyyntöä avain saa tehdä tämän tunnin aikana.
• RateLimit-Remaining: montako niistä on jäljellä.
• RateLimit-Reset: sekunnit seuraavaan tasatuntiin.

Rajan ylittävä pyyntö saa vastauksen rate_limited, jonka tila on 429 ja jossa Retry-After-otsake kertoo odotusajan sekunteina. Kaksi skriptiä, jotka käyttävät samaa avainta, jakavat sen laskurin, joten anna kullekin skriptille oma avain. Päätepisteellä /metrics on oma laskurinsa, ja avaimella tehdyt MCP-työkalukutsut käyttävät avaimen API-laskuria.

Luettelot tulevat sivuina

Luettelo vastaa objektilla, jossa on data, eli kohteet, ja next_cursor. Lähetä next_cursor takaisin cursor-parametrina, niin saat seuraavan sivun. Kun next_cursor on null, seuraavaa sivua ei ole.

Parametri limit määrää, montako kohdetta sivulla on: oletuksena 100 ja enintään 500. Suurempi luku pienennetään arvoon 500. Arvo, joka ei ole kokonaisluku tai on pienempi kuin yksi, saa vastauksen invalid_parameter.

Päivät ja aikavälit

from ja to ovat päiviä muodossa YYYY-MM-DD UTC-ajassa, ja molemmat kuuluvat aikaväliin. Ilman niitä pyyntö kattaa viimeiset 7 päivää, joista viimeinen on eilinen. to voi olla viimeistään kuluva päivä.

Jos from on ennen historiasi alkua, se siirretään historian ensimmäiseen päivään, ja verkkotunnuksen yhteenveto kertoo silloin "window_clamped": true. Vastausten aikaleimat ovat UTC-aikaa ISO 8601 -muodossa, ja niiden lopussa on Z.

Virheet

Virheen vastauksena tulee RFC 9457:n mukainen virhedokumentti, jonka tyyppi on application/problem+json. Siinä on kentät type, title, status, detail ja code, ja virheellinen parametri lisää kentän parameter, joka nimeää parametrin. Tunnista virhe skriptissäsi code-kentästä. type on osoite, joka avaa kyseisen koodin sivun, ja API:n virhetyypit luettelee ne kaikki.

Englanti vai suomi

Lähetä Accept-Language: fi, niin saat title- ja detail-kentät ja muut API:n kirjoittamat lauseet suomeksi. Ilman sitä, tai jos pyydät kieltä, jota emme tarjoa, ne ovat englanniksi. Vastauksen Content-Language-otsake kertoo, kumman sait.

OpenAPI-dokumentti

https://www.mailmoni.com/api/v1/openapi.json kuvaa OpenAPI 3.1 -muodossa jokaisen pyynnön, jokaisen vastauksen kentät ja jokaisen webhook-tapahtuman. Se ei vaadi avainta, ja sekin noudattaa Accept-Language-otsaketta. Voit luoda siitä asiakaskirjaston generaattorilla tai lukea siitä koostetun pyyntöjen luettelon.

• Luo ja mitätöi API-avaimia

  Ylläpitäjä luo ja mitätöi skriptien, Prometheuksen ja avustajien API-avaimet ja valitsee voimassaolon ja oikeudet. Pienempi paketti voi keskeyttää osan.

• Mihin pyyntöihin API vastaa?

  Jokainen pyyntö, johon API vastaa, koottuna sen OpenAPI-dokumentista, sekä se, mitä OpenAPI ei kerro aliverkkotunnuksista, tietueista ja viennistä.

• Vastaanota tapahtumat webhookeilla

  Lähetämme allekirjoitetun JSON-tapahtuman, kun raportti saapuu, hälytys avautuu tai poistuu tai vienti valmistuu. Päätepisteet ja uudelleenyritykset.

• Lue luvut Prometheukseen

  Päätepiste /metrics antaa Prometheukselle postisi lähteittäin ja tuloksittain, viimeisimmän raportin, DNS-tarkistukset ja avoimet hälytykset.

• Yhdistä avustaja MCP:n kautta

  Anna Clauden, ChatGPT:n, Cursorin tai muun avustajan lukea verkkotunnuksesi, lähteesi ja raporttisi MCP-palvelimeltamme kirjautumalla tai API-avaimella.

• API:n virhetyypit

  Jokainen API:n virhe nimeää virhetyypin. Jokainen sivu kertoo, mitä koodi tarkoittaa, miksi saat sen ja mitä teet seuraavaksi.

Julkaistu 27. lokakuuta 2026 · Tarkistettu 27. lokakuuta 2026