Record a verification outcome for a sending domain

curl --request PUT \
  --url https://api.mercemur.com/api/v1/email-domains/{domain} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{}'

const options = {
  method: 'PUT',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
};

fetch('https://api.mercemur.com/api/v1/email-domains/{domain}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.mercemur.com/api/v1/email-domains/{domain}"

payload = {}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mercemur.com/api/v1/email-domains/{domain}"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mercemur.com/api/v1/email-domains/{domain}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "created_at": "<string>",
    "dkim_record": "<string>",
    "domain": "<string>",
    "status": "<string>",
    "updated_at": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

API Reference

Record a verification outcome for a sending domain

Records a verification outcome for a domain this store has already registered. Your integration is usually the only party that can see the provider’s verdict, so this is how a registration made through the API ever leaves pending. ONE FIELD. status is the whole of what this route writes. IT CANNOT WRITE dkim_record AND NEVER WILL. A record accepted from a caller could be an attacker’s signing key, published in the merchant’s own DNS on this API’s say-so and then usable to sign mail as their domain. Sending the key is a 400 that names it, rather than a silent drop that would leave you believing you set it. A domain this store has not registered is a 404 rather than a create: the registration is what asked a provider to verify in the first place.

PUT

api

email-domains

{domain}

Record a verification outcome for a sending domain

curl --request PUT \
  --url https://api.mercemur.com/api/v1/email-domains/{domain} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{}'

const options = {
  method: 'PUT',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
};

fetch('https://api.mercemur.com/api/v1/email-domains/{domain}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.mercemur.com/api/v1/email-domains/{domain}"

payload = {}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mercemur.com/api/v1/email-domains/{domain}"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mercemur.com/api/v1/email-domains/{domain}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "created_at": "<string>",
    "dkim_record": "<string>",
    "domain": "<string>",
    "status": "<string>",
    "updated_at": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "resource": "<string>",
    "field": "<string>"
  }
}

Authorizations

Authorization

string

header

required

A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.

Headers

Idempotency-Key

string

required

A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.

Path Parameters

domain

string

required

Body

application/json

ONE FIELD, and the narrowness is the contract. dkim_record is refused by name on this route: the admin surface writes both columns together, and a key able to set the record could put an attacker's signing key in front of the merchant, who would publish it in real DNS. No precondition is required. The route writes a single field, so the only thing a race can lose is a status two callers disagree about, which the next read shows and the next write corrects.

status

enum<string>

required

What the provider says about this domain now. Nothing on this platform gates a send on it: it is the merchant's record of their own DNS.

Available options:

pending,

verified,

failed

Response

Success

data

object

Show child attributes

Overview

Endpoints

Record a verification outcome for a sending domain

Authorizations

Headers

Path Parameters

Body

Response