Forwarding

Forward the email an inbox receives to up to 5 addresses you confirm. Forwards do not count against your monthly sending limit.

Add a forwarding address #

POST /v1/inboxes/{inbox_id}/forwarding

Adds an address, emails it a 6-digit code and marks it pending. Nothing is forwarded until you confirm the code. Call it again for a pending address to send a new code. An address that is already verified does not change.

Path parameters

inbox_id string required: The inbox, for example inb_mvdlh9c06724trm1.

Body

address string required: The address to forward to. It cannot be a Maila address.

If forwarding_verification on the inbox is none, the address is verified at once and no code is sent. Check its status in the response.
An inbox holds up to 5 addresses. A sixth returns 409, and so does a disabled inbox.
An address on your block list, or one the inbox firewall does not allow, returns 422.
You can request one code a minute for an address and 20 a month in all. Over that you get 429.

curl

curl -X POST "https://api.maila.ai/v1/inboxes/inb_mvdlh9c06724trm1/forwarding" \
  -H "Authorization: Bearer $MAILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "address": "jane@example.com" }'

Response

{
  "object": "inbox",
  "id": "inb_mvdlh9c06724trm1",
  "address": "support-agent@mailbox.maila.ai",
  "status": "active",
  "forwarding_addresses": [
    { "address": "jane@example.com", "status": "pending", "verified_at": null, "created_at": 1792335167 }
  ],
  "forwarding_verification": "code"
}

Confirm a forwarding address #

POST /v1/inboxes/{inbox_id}/forwarding/{address}/verify

Confirms an address with the emailed code. From then on, every email the inbox receives is also forwarded there, except spam, viruses and email Maila already forwarded.

Path parameters

inbox_id string required: The inbox, for example inb_mvdlh9c06724trm1.
address string required: The address the code was sent to. Write the @ as %40.

Body

code string required: The 6-digit code.

A code works for one hour and allows 5 wrong attempts.

curl

curl -X POST "https://api.maila.ai/v1/inboxes/inb_mvdlh9c06724trm1/forwarding/jane%40example.com/verify" \
  -H "Authorization: Bearer $MAILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "482913" }'

Response

{
  "object": "inbox",
  "id": "inb_mvdlh9c06724trm1",
  "address": "support-agent@mailbox.maila.ai",
  "status": "active",
  "forwarding_addresses": [
    { "address": "jane@example.com", "status": "verified", "verified_at": 1792335267, "created_at": 1792335167 }
  ],
  "forwarding_verification": "code"
}

Remove a forwarding address #

DELETE /v1/inboxes/{inbox_id}/forwarding/{address}

Stops forwarding to one address. Write the @ as %40.

Path parameters

inbox_id string required: The inbox, for example inb_mvdlh9c06724trm1.
address string required: The forwarding address to remove.

curl

curl -X DELETE "https://api.maila.ai/v1/inboxes/inb_mvdlh9c06724trm1/forwarding/jane%40example.com" \
  -H "Authorization: Bearer $MAILA_API_KEY"

Remove all forwarding addresses #

DELETE /v1/inboxes/{inbox_id}/forwarding

Stops forwarding to every address of the inbox.

Path parameters

inbox_id string required: The inbox, for example inb_mvdlh9c06724trm1.

curl

curl -X DELETE "https://api.maila.ai/v1/inboxes/inb_mvdlh9c06724trm1/forwarding" \
  -H "Authorization: Bearer $MAILA_API_KEY"