Add MailAgent

Create a new Mail Agent in your ZeptoMail account. You can create up to 50 agents per account.

Endpoint

post /mailagents

Copy full URL

Request URL

https://api.zeptomail.com/v1.1/mailagents Copied!

Scope

Zeptomail.MailAgents.CREATECopied!

(or)

Zeptomail.MailAgents.ALLCopied!

- Request Body

application/json

JSON Object

Show Sub-Attributes

mailagent_namestringMandatory

Name for the Mail Agent. Must be unique within the account.

descriptionstringOptional

Description or purpose of the Mail Agent.

Sample Request

Curl

Java

Python

Deluge

Copied!

curl --request POST \
  --url https://api.zeptomail.com/v1.1/mailagents \
  --header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
  --header 'content-type: application/json' \
  --data '{"mailagent_name":"Mail_agent_name","description":"Production mail agent for transactional emails"}'

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.net.http.HttpTimeoutException;

public class Main {
  public static void main(String[] args) {

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.zeptomail.com/v1.1/mailagents"))
        .header("content-type", "application/json")
        .header("Authorization", "Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52")
        .method("POST", HttpRequest.BodyPublishers.ofString("{\"mailagent_name\":\"Mail_agent_name\",\"description\":\"Production mail agent for transactional emails\"}"))
        .build();
    HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  
  }
}

import http.client

conn = http.client.HTTPSConnection("api.zeptomail.com")

payload = "{\"mailagent_name\":\"Mail_agent_name\",\"description\":\"Production mail agent for transactional emails\"}"

headers = {
    'content-type': "application/json",
    'Authorization': "Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52"
    }

conn.request("POST", "/v1.1/mailagents", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))


    headersMap = Map();
    headersMap.put("Content-Type", "application/json");
    headersMap.put("Accept", "application/json");

    data=Map();
    data.put("mailagent_name","Mail_agent_name");
    data.put("description","Production mail agent for transactional emails");

    response = invokeUrl
    [
        url: "https://api.zeptomail.com/v1.1/mailagents"
        type: POST
        headers: headersMap
        body: data
        connection: connection_name
    ]

    info response;

Sample Request Body

Copied!

  {
    "mailagent_name": "Mail_agent_name",
    "description": "Production mail agent for transactional emails"
  }

▼ Show full

Response Parameters

- HTTP code 200

Response Body - application/json

JSON Object

Show Sub-Attributes

dataJSON Object

Show Sub-Attributes

mailagent_namestring

created_timestring

descriptionstring

mailagent_keystring

statusstring

- HTTP code 400

Response Body - application/json

JSON Object

Show Sub-Attributes

errorJSON Object

Show Sub-Attributes

codestring

messagestring

statusstring

Possible Response Codes

200HTTP code

Mail Agent created successfully.

400HTTP code

Bad Request — e.g. name already exists or max agent limit reached.

Sample Response: HTTP 200

Copied!

  {
    "data": {
      "mailagent_name": "mailagent_1",
      "created_time": "04 Jun 2025 08:19 PM",
      "description": "Production mail agent",
      "mailagent_key": "123456abcd78",
      "status": "active"
    },
    "status": "success"
  }

▼ Show full

Sample Response: HTTP 400

Copied!

  {
    "error": {
      "code": "MA_107",
      "message": "Mail agent name already exists"
    },
    "status": "failure"
  }

▼ Show full