Submission API

Send through the Teneo relay with one HTTPS request instead of an SMTP session. JSON in, JSON out. The same relay login, the same IP addresses and the same delivery log as SMTP, so nothing changes in your console.

Endpoint

Always use https. The body carries your password.

One message

{
  "username": "mailclass-orders@tlsrelay.teneo.be",
  "password": "YOUR_RELAY_PASSWORD",
  "message": {
    "mailclass": "orders",
    "from_email": "orders@yourdomain.be",
    "from_name": "Your Company",
    "to": [{ "email": "jan@example.be", "name": "Jan Peeters" }],
    "subject": "Your order 4821 has shipped",
    "html": "<p>Your order is on its way.</p>",
    "text": "Your order is on its way.",
    "idempotence_key": "order-4821-shipped"
  }
}

curl -X POST https://tlsrelay.teneo.be/api/v1/send.json \
  -H "Content-Type: application/json" \
  --data-binary @message.json

Answer when the relay accepted it:

{"success":1,"message_id":"<3f9c…@yourdomain.be>","result_reason":"success_immediate"}

Answer when it did not:

{"success":0,"error":"incorrect username/password","result_reason":"request_error"}

Fields

Top level of the request body:

Message object:

Attachment object:

Batches

Put up to 500 message objects in messages instead of message. Each one needs its own mailclass. The answer lists a result per message, in order, with your id echoed:

{
  "success": 1,
  "messages": [
    {"success": 1, "message_id": "<…>", "attempted": 1, "id": "4821", "result_reason": "success_immediate"},
    {"success": 0, "error": "…",         "attempted": 1, "id": "4822", "result_reason": "message_validation_error"},
    {"success": 0, "error": "not attempting because previous messages have taken too long", "attempted": 0, "id": "4823", "result_reason": "skipped_batch_timeout"}
  ]
}

A message with "attempted": 0 was never tried: send it again, preferably in a smaller batch. A good batch size is what the relay accepts in about ten seconds; start with 100 and adjust. Reuse the TCP connection between calls.

Result reasons

Raw messages

If your application already builds complete messages, send them as they are. mime replaces the content fields and envelope_recipients becomes required. mailclass stays required.

{
  "username": "mailclass-orders@tlsrelay.teneo.be",
  "password": "YOUR_RELAY_PASSWORD",
  "message": {
    "mailclass": "orders",
    "envelope_recipients": ["jan@example.be"],
    "mime": "From: orders@yourdomain.be\r\nTo: jan@example.be\r\nSubject: Your order 4821\r\nMessage-ID: <4821@yourdomain.be>\r\nContent-Type: text/plain; charset=utf-8\r\n\r\nYour order is on its way.\r\n"
  }
}

With mime these fields are refused: html, text, amp_html, subject, to, cc, bcc, from_email, from_name, attachments, headers, message_id_domain. The relay does not inspect the content beyond checking it is not empty; include your own Message-ID if you want it back in the answer.

SMTP or HTTPS?

Both reach the same place. SMTP on port 587 with STARTTLS suits anything that already has a mail library or a mail server behind it. The Submission API suits applications that speak HTTP anyway, that want an answer per message, or that send in bursts: a batch of 500 is one request. You can use both with the same relay account at the same time.

Questions? Open a ticket on the Support page of the console; an engineer answers.