Send email with cURL

Prerequisites

Before you start, you need:

• A mails.ai API key. A test key (mk_test_…) runs everything on this page and sends no real email.
• curl on your machine. curl --version tells you whether it is there.

Guide

1. 1

   Set your API key

   Keep the key in an environment variable, so it stays out of your shell history and scripts.

   Terminal

   export MAILS_API_KEY="mk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. 2

   Send an email

   POST /v1/messages sends one message. from names the agent that sends it: an agent with that name is used if it exists, and created if it does not when the key may create agents (the manage scope) and your plan has room for another; without manage the send answers 403 insufficient_scope.

   Terminal

   curl https://api.mails.ai/v1/messages \
     -H "Authorization: Bearer $MAILS_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: welcome-jordan-1" \
     -d '{
       "from": "hello",
       "to": "reply@test.mails.ai",
       "subject": "Welcome aboard",
       "body_text": "Thanks for signing up. Reply any time and I will read it."
     }'

   The answer is the sent message, with its id, its thread_id and the address it was sent as in from. The Idempotency-Key header makes a retry safe: sending the same key again returns the first answer instead of sending twice.

3. 3

   Read the reply

   reply@test.mails.ai answers within about a second. The reply arrives as a reply.received event with an injection_score from 0 to 1. How the test address works.

   Terminal

   curl "https://api.mails.ai/v1/events?event_type=reply.received&limit=5" \
     -H "Authorization: Bearer $MAILS_API_KEY"

4. 4

   Answer in the same thread

   Take data.source_message_id from the event (it starts with rcv_) and reply to it. The reply goes to the person who wrote and stays in the same conversation.

   Terminal

   curl https://api.mails.ai/v1/messages/rcv_01JZX8K3M9Q4P7VN2YB6RTDC0E/reply \
     -H "Authorization: Bearer $MAILS_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "body_text": "Glad to hear it. Anything else I can help with?" }'

Next steps