How to used Zimbra API ?

Have a great idea for extending Zimbra? Share ideas, ask questions, contribute, and get feedback.
thang-mt
Posts: 14
Joined: Mon Jan 17, 2022 2:05 pm

How to used Zimbra API ?

Post by thang-mt »

Hello every one,
I don't know if anyone can give me documentation on how to connect and use zimbra api
Thanks!
User avatar
jeastman
Zimbra Employee
Zimbra Employee
Posts: 82
Joined: Tue Mar 29, 2016 1:36 pm

Re: How to used Zimbra API ?

Post by jeastman »

Hello thang-mt,

It might help if you describe what you are trying to accomplish. Zimbra has several APIs exposed, some of which have more functionality than others. Which access method to use depends a lot on what you are trying to do.

If you are looking for the SOAP API, you can find the latest documentation here. Additional information is available in the server documentation folder (check for "soap-*.txt" files).

If you are looking for the REST API, you can find information here. The REST API is more discoverable, but can be confusing if you do not understand the structure of the underlying data.

With a better understanding of your use case, more detailed information can be provided.
John Eastman
thang-mt
Posts: 14
Joined: Mon Jan 17, 2022 2:05 pm

Re: How to used Zimbra API ?

Post by thang-mt »

jeastman wrote:Hello thang-mt,

It might help if you describe what you are trying to accomplish. Zimbra has several APIs exposed, some of which have more functionality than others. Which access method to use depends a lot on what you are trying to do.

If you are looking for the SOAP API, you can find the latest documentation here. Additional information is available in the server documentation folder (check for "soap-*.txt" files).

If you are looking for the REST API, you can find information here. The REST API is more discoverable, but can be confusing if you do not understand the structure of the underlying data.

With a better understanding of your use case, more detailed information can be provided.
Hi jeastman,
I want to use the api so that I send emails automatically, but I can't find any specific examples on how to use it. Can you help me?
User avatar
jeastman
Zimbra Employee
Zimbra Employee
Posts: 82
Joined: Tue Mar 29, 2016 1:36 pm

Re: How to used Zimbra API ?

Post by jeastman »

Sending emails though the API can be complicated, depending on the content you are sending. If you have the ability to send via SMTP, that is probably your easiest bet (since there already exists a lot of tooling to do so).

If SMTP is not an option, or if you really need to use the Zimbra API directly, you can use the SendMsgRequest message (https://files.zimbra.com/docs/soap_api/ ... ndMsg.html).

I will do my best to step through the process here, but bear in mind this is only a simple example. It really is a matter of the content you are sending.

The example here will be using curl (explaining steps to make it easier), but you should be able to translate this to any programming language you choose.

Step 1 - obtain a Zimbra Auth Token

Create a file called login_request.json with the following content (replacing "ACCOUNT@example.com" with your account and "PASSWORD" with your account password, you can also set the user agent to whatever you want - helps with tracking in the server logs):

Code: Select all

{
   "Header": {
     "context": {
       "_jsns":"urn:zimbra",
       "userAgent":{
         "name":"curl",
         "version":"7.54.0"
       }
     }
   },
   "Body": {
     "AuthRequest": {
       "_jsns":"urn:zimbraAccount",
       "account":{
         "_content":"ACCOUNT@example.com",
         "by":"name"
       },
       "password": "PASSWORD"
     }
   }
}
Use curl to POST the request to your server (again, replace "example.com" with your server name):

Code: Select all

curl -X POST -c login_cookies -d @login_request.json https://example.com/service/soap
Note the "-c login_cookies" is not required, but can help make using curl easier. The server will return the AUTH_TOKEN as a cookie as well.

This will result in a AuthResponse which contains the authentication token you will need for future API calls. The response will look something like the following:

Code: Select all

{
  "_jsns": "urn:zimbraSoap",
  "Body": {
    "AuthResponse": {
      "_jsns": "urn:zimbraAccount",
      "skin": [
        {
          "_content": "harmony"
        }
      ],
      "lifetime": 604799986,
      "authToken": [
        {
          "_content": "[redacted]"
        }
      ]
    }
  },
  "Header": {
    "context": {
      "_jsns": "urn:zimbra",
      "change": {
        "token": 1372727
      }
    }
  }
}
You will want to extract the "authToken:_content" out and save it for future calls.

Step 2 - Send a message

Create another text file named "mymsg.json" with the following content (replace "ACCOUNT@example.com" with your account, "authToken" with the authentication token you received from the AuthRequest and, of course, change the content and addressing to what you want). For an explanation of all of the fields, check the documentation for SendMsgRequest linked above.

Code: Select all

{
  "Header": {
    "context": {
      "userAgent": {
        "name": "curl",
        "version": "7.54.0"
      },
      "authTokenControl": {
        "voidOnExpired": true
      },
      "account": {
        "_content": "ACCOUNT@example.com",
        "by": "name"
      },
      "authToken": "[redacted]",
      "_jsns": "urn:zimbra"
    }
  },
  "Body": {
    "SendMsgRequest": {
      "_jsns": "urn:zimbraMail",
      "m": {
        "su": "An example email",
        "e": [
          {
            "a": "FROM_ADDRESS@example.com",
            "t": "f"
          },
          {
            "a": "TO_ADDRESS@example.com",
            "t": "t"
          }
        ],
        "mp": [
          {
            "ct": "text/plain",
            "content": "Simple example"
          }
        ]
      }
    }
  }
}
You can now POST the message using curl (again using your server instead of "example.com"):

Code: Select all

curl -X POST -c login_cookies -d @mymsg.json https://example.com/service/soap
Your message should now be sent.

Additional note:

You could also upload the content of your message and simply refer to it in the SendMsgRequest. Uploading mail content for reference in this way is a whole other topic.

If you decided to take this route, the SendMsgRequest portion would look something like the following (where "50575" is the ID of the content:

Code: Select all

  "SendMsgRequest": {
    "_jsns_": "urn:zimbraMail",
    "m": [{id: "505757"}]
  }
I hope that helps.
John Eastman
thang-mt
Posts: 14
Joined: Mon Jan 17, 2022 2:05 pm

Re: How to used Zimbra API ?

Post by thang-mt »

Dear jeastman

Thank you, i will try it
thang-mt
Posts: 14
Joined: Mon Jan 17, 2022 2:05 pm

Re: How to used Zimbra API ?

Post by thang-mt »

jeastman wrote:Sending emails though the API can be complicated, depending on the content you are sending. If you have the ability to send via SMTP, that is probably your easiest bet (since there already exists a lot of tooling to do so).

If SMTP is not an option, or if you really need to use the Zimbra API directly, you can use the SendMsgRequest message (https://files.zimbra.com/docs/soap_api/ ... ndMsg.html).

I will do my best to step through the process here, but bear in mind this is only a simple example. It really is a matter of the content you are sending.

The example here will be using curl (explaining steps to make it easier), but you should be able to translate this to any programming language you choose.

Step 1 - obtain a Zimbra Auth Token

Create a file called login_request.json with the following content (replacing "ACCOUNT@example.com" with your account and "PASSWORD" with your account password, you can also set the user agent to whatever you want - helps with tracking in the server logs):

Code: Select all

{
   "Header": {
     "context": {
       "_jsns":"urn:zimbra",
       "userAgent":{
         "name":"curl",
         "version":"7.54.0"
       }
     }
   },
   "Body": {
     "AuthRequest": {
       "_jsns":"urn:zimbraAccount",
       "account":{
         "_content":"ACCOUNT@example.com",
         "by":"name"
       },
       "password": "PASSWORD"
     }
   }
}
Use curl to POST the request to your server (again, replace "example.com" with your server name):

Code: Select all

curl -X POST -c login_cookies -d @login_request.json https://example.com/service/soap
Note the "-c login_cookies" is not required, but can help make using curl easier. The server will return the AUTH_TOKEN as a cookie as well.

This will result in a AuthResponse which contains the authentication token you will need for future API calls. The response will look something like the following:

Code: Select all

{
  "_jsns": "urn:zimbraSoap",
  "Body": {
    "AuthResponse": {
      "_jsns": "urn:zimbraAccount",
      "skin": [
        {
          "_content": "harmony"
        }
      ],
      "lifetime": 604799986,
      "authToken": [
        {
          "_content": "[redacted]"
        }
      ]
    }
  },
  "Header": {
    "context": {
      "_jsns": "urn:zimbra",
      "change": {
        "token": 1372727
      }
    }
  }
}
You will want to extract the "authToken:_content" out and save it for future calls.

Step 2 - Send a message

Create another text file named "mymsg.json" with the following content (replace "ACCOUNT@example.com" with your account, "authToken" with the authentication token you received from the AuthRequest and, of course, change the content and addressing to what you want). For an explanation of all of the fields, check the documentation for SendMsgRequest linked above.

Code: Select all

{
  "Header": {
    "context": {
      "userAgent": {
        "name": "curl",
        "version": "7.54.0"
      },
      "authTokenControl": {
        "voidOnExpired": true
      },
      "account": {
        "_content": "ACCOUNT@example.com",
        "by": "name"
      },
      "authToken": "[redacted]",
      "_jsns": "urn:zimbra"
    }
  },
  "Body": {
    "SendMsgRequest": {
      "_jsns": "urn:zimbraMail",
      "m": {
        "su": "An example email",
        "e": [
          {
            "a": "FROM_ADDRESS@example.com",
            "t": "f"
          },
          {
            "a": "TO_ADDRESS@example.com",
            "t": "t"
          }
        ],
        "mp": [
          {
            "ct": "text/plain",
            "content": "Simple example"
          }
        ]
      }
    }
  }
}
You can now POST the message using curl (again using your server instead of "example.com"):

Code: Select all

curl -X POST -c login_cookies -d @mymsg.json https://example.com/service/soap
Your message should now be sent.

Additional note:

You could also upload the content of your message and simply refer to it in the SendMsgRequest. Uploading mail content for reference in this way is a whole other topic.

If you decided to take this route, the SendMsgRequest portion would look something like the following (where "50575" is the ID of the content:

Code: Select all

  "SendMsgRequest": {
    "_jsns_": "urn:zimbraMail",
    "m": [{id: "505757"}]
  }
I hope that helps.
Conguration, it run, thank you very much
thang-mt
Posts: 14
Joined: Mon Jan 17, 2022 2:05 pm

Re: How to used Zimbra API ?

Post by thang-mt »

jeastman wrote:Sending emails though the API can be complicated, depending on the content you are sending. If you have the ability to send via SMTP, that is probably your easiest bet (since there already exists a lot of tooling to do so).

If SMTP is not an option, or if you really need to use the Zimbra API directly, you can use the SendMsgRequest message (https://files.zimbra.com/docs/soap_api/ ... ndMsg.html).

I will do my best to step through the process here, but bear in mind this is only a simple example. It really is a matter of the content you are sending.

The example here will be using curl (explaining steps to make it easier), but you should be able to translate this to any programming language you choose.

Step 1 - obtain a Zimbra Auth Token

Create a file called login_request.json with the following content (replacing "ACCOUNT@example.com" with your account and "PASSWORD" with your account password, you can also set the user agent to whatever you want - helps with tracking in the server logs):

Code: Select all

{
   "Header": {
     "context": {
       "_jsns":"urn:zimbra",
       "userAgent":{
         "name":"curl",
         "version":"7.54.0"
       }
     }
   },
   "Body": {
     "AuthRequest": {
       "_jsns":"urn:zimbraAccount",
       "account":{
         "_content":"ACCOUNT@example.com",
         "by":"name"
       },
       "password": "PASSWORD"
     }
   }
}
Use curl to POST the request to your server (again, replace "example.com" with your server name):

Code: Select all

curl -X POST -c login_cookies -d @login_request.json https://example.com/service/soap
Note the "-c login_cookies" is not required, but can help make using curl easier. The server will return the AUTH_TOKEN as a cookie as well.

This will result in a AuthResponse which contains the authentication token you will need for future API calls. The response will look something like the following:

Code: Select all

{
  "_jsns": "urn:zimbraSoap",
  "Body": {
    "AuthResponse": {
      "_jsns": "urn:zimbraAccount",
      "skin": [
        {
          "_content": "harmony"
        }
      ],
      "lifetime": 604799986,
      "authToken": [
        {
          "_content": "[redacted]"
        }
      ]
    }
  },
  "Header": {
    "context": {
      "_jsns": "urn:zimbra",
      "change": {
        "token": 1372727
      }
    }
  }
}
You will want to extract the "authToken:_content" out and save it for future calls.

Step 2 - Send a message

Create another text file named "mymsg.json" with the following content (replace "ACCOUNT@example.com" with your account, "authToken" with the authentication token you received from the AuthRequest and, of course, change the content and addressing to what you want). For an explanation of all of the fields, check the documentation for SendMsgRequest linked above.

Code: Select all

{
  "Header": {
    "context": {
      "userAgent": {
        "name": "curl",
        "version": "7.54.0"
      },
      "authTokenControl": {
        "voidOnExpired": true
      },
      "account": {
        "_content": "ACCOUNT@example.com",
        "by": "name"
      },
      "authToken": "[redacted]",
      "_jsns": "urn:zimbra"
    }
  },
  "Body": {
    "SendMsgRequest": {
      "_jsns": "urn:zimbraMail",
      "m": {
        "su": "An example email",
        "e": [
          {
            "a": "FROM_ADDRESS@example.com",
            "t": "f"
          },
          {
            "a": "TO_ADDRESS@example.com",
            "t": "t"
          }
        ],
        "mp": [
          {
            "ct": "text/plain",
            "content": "Simple example"
          }
        ]
      }
    }
  }
}
You can now POST the message using curl (again using your server instead of "example.com"):

Code: Select all

curl -X POST -c login_cookies -d @mymsg.json https://example.com/service/soap
Your message should now be sent.

Additional note:

You could also upload the content of your message and simply refer to it in the SendMsgRequest. Uploading mail content for reference in this way is a whole other topic.

If you decided to take this route, the SendMsgRequest portion would look something like the following (where "50575" is the ID of the content:

Code: Select all

  "SendMsgRequest": {
    "_jsns_": "urn:zimbraMail",
    "m": [{id: "505757"}]
  }
I hope that helps.
Hi jeastman,
first, i am thank you help me.
But I have another problem that in the sendmsgrequest section I can't find a section to send a content with the content taken from another file with php or html format. Can you help me?
"ct": "text/plain",
"content": "content from file php or html, javascript"
User avatar
jeastman
Zimbra Employee
Zimbra Employee
Posts: 82
Joined: Tue Mar 29, 2016 1:36 pm

Re: How to used Zimbra API ?

Post by jeastman »

If you want to specify the content from another file, you would use the form I noted in the end of my post.

Code: Select all

 "SendMsgRequest": {
    "_jsns_": "urn:zimbraMail",
    "m": [{id: "505757"}]
  }
In order to upload the content referenced by the ID (505757 in the example), you would follow something similar to what is covered in this post: viewtopic.php?f=17&t=2306. However, you will need to compose the referenced file as multipart MIME format.

You can also construct the multipart in-line with the request (see the documentation for SendMsgRequest: https://files.zimbra.com/docs/soap_api/ ... ndMsg.html). Have a look at the m (MIME) and mp
(MIME Part) attributes. You could specify a top-level m with content type multipart/mixed with mp children specifying the different parts (text/plain, text/html, etc.). You could look at the MIME RFC-1341 (https://datatracker.ietf.org/doc/html/rfc1341) for details on how to properly compose the MIME content.
John Eastman
thang-mt
Posts: 14
Joined: Mon Jan 17, 2022 2:05 pm

Re: How to used Zimbra API ?

Post by thang-mt »

jeastman wrote:If you want to specify the content from another file, you would use the form I noted in the end of my post.

Code: Select all

 "SendMsgRequest": {
    "_jsns_": "urn:zimbraMail",
    "m": [{id: "505757"}]
  }
In order to upload the content referenced by the ID (505757 in the example), you would follow something similar to what is covered in this post: viewtopic.php?f=17&t=2306. However, you will need to compose the referenced file as multipart MIME format.

You can also construct the multipart in-line with the request (see the documentation for SendMsgRequest: https://files.zimbra.com/docs/soap_api/ ... ndMsg.html). Have a look at the m (MIME) and mp
(MIME Part) attributes. You could specify a top-level m with content type multipart/mixed with mp children specifying the different parts (text/plain, text/html, etc.). You could look at the MIME RFC-1341 (https://datatracker.ietf.org/doc/html/rfc1341) for details on how to properly compose the MIME content.
But I don't know how to generate the id of the file? The URL you sent me is very confusing, you give a variable but I don't understand how that variable is used to generate the id of the file.
So looking forward to your help on a specific example of generating file id.

Thanks !
User avatar
jeastman
Zimbra Employee
Zimbra Employee
Posts: 82
Joined: Tue Mar 29, 2016 1:36 pm

Re: How to used Zimbra API ?

Post by jeastman »

But I don't know how to generate the id of the file? The URL you sent me is very confusing, you give a variable but I don't understand how that variable is used to generate the id of the file.
From the referenced post:
To upload the file, you actually call the FileUploadServlet. This is not a SOAP request, just a POST to the appropriate URL with the content. You will need to specify a couple of things with the request.

ZM_AUTH_TOKEN - in the cookie HTTP header on the request.
CONTENT_TYPE - CONTENT_TYPE HTTP header
CONTENT_DISPOSITION - CONTENT_DISPOSITION HTTP header with "attachment: filename="myfile.txt"" fo the value.

This will return a plain text string with the ID of the uploaded content.
You will need to POST the contents of your file to the FileUploadServlet (http://example.com/service/upload) with ZM_AUTH_TOKEN (in Cookie), CONTENT_TYPE, and CONTENT_DISPOSITION set as HTTP headers on the POST request. This will return the ID for you to use in the SendMessageRequest as previously noted. The ZM_AUTH_TOKEN will already be set in a cookie as part of an AuthRequest.

Using curl (assuming the auth token is in "login_cookies" file - see original "Step 1 - obtain a Zimbra Auth Token") to upload "myfile.html" this would be:

Code: Select all

curl -X POST -b login_cookies -H "Content-Type: text/html" -H "Content-Disposition: attachment: filename=\"myfile.html\"" -d @myfile.html https://example.com/service/upload
John Eastman
Post Reply