VeruSuite APIs Console

Use cases

Turn mail into tickets

Poll a shared mailbox, open a ticket in your own system, and reply from the same address.

Why anyone does this

A support address is a queue that happens to be a mailbox. What is missing is the bit where a human has to notice it, and replying from the same address is what keeps the thread readable for the person who wrote in.

What a key needs

Grant these and nothing else. A key can never do more than the person who created it, and one that carries only what the job needs is one you can leave running.

mail.messages.readmail.messages.writemail.send

The flow

  1. Poll for unread

    Filter on unread rather than reading everything and remembering what you saw. The mailbox already tracks it.

    GET /v1/messages

  2. Read the whole message

    MIME traversal, transfer decoding and header decoding are done for you, so the body arrives as text rather than as an encoding exercise.

    GET /v1/messages/:id

  3. Mark it handled

    Set the read flag once your side has the ticket, so a crash between the two leaves the message unread and it is picked up again. Flags are set in bulk against the folder, so a batch of tickets costs one call.

    POST /v1/folders/:folder_id/messages/flags

  4. Reply from the same address

    Send with the thread's references so the reply lands in the same conversation rather than starting a new one.

    POST /v1/messages/send

The shape of it

Short enough to read in one go, and close enough to run that the gaps are obvious.

# Anything unread becomes a ticket, then gets a reply.
curl -s "https://api.veruapis.com/v1/messages?folder_id=$INBOX&unread=true" \
  -H "Authorization: Bearer $KEY" | jq -c '.data[]' | while read -r msg; do
  id=$(echo "$msg" | jq -r .id)

  # ... open the ticket in your own system first ...

  curl -s https://api.veruapis.com/v1/folders/$INBOX/messages/flags \
    -H "Authorization: Bearer $KEY" \
    -d "{\"ids\":[\"$id\"],\"add\":[\"read\"]}"

  curl -s https://api.veruapis.com/v1/messages/send \
    -H "Authorization: Bearer $KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d "{\"to\":[$(echo "$msg" | jq .from)],\"subject\":\"Re: ticket opened\",
         \"text\":\"Thanks — we have this.\"}"
done

What catches people out

Every one of these came from somebody getting it wrong.

  • Mark read after your ticket exists, never before. The other order loses mail when something fails in between.
  • Send an Idempotency-Key. A retried reply that sends twice is visible to the customer.
  • A 202 means queued, not delivered. Delivery failures arrive later as a bounce, not as an error on this call.

Build it

Create a key Read the reference