1// NOTE: DO NOT EDIT, this file is generated by gendoc.sh.

3/*

4Package webapi implements a simple HTTP/JSON-based API for interacting with

5email, and webhooks for notifications about incoming and outgoing deliveries,

6including delivery failures.

8# Overview

10The webapi can be used to compose and send outgoing messages. The HTTP/JSON

11API is often easier to use for developers since it doesn't require separate

12libraries and/or having (detailed) knowledge about the format of email messages

13("Internet Message Format"), or the SMTP protocol and its extensions.

15Webhooks can be configured per account, and help with automated processing of

16incoming email, and with handling delivery failures/success. Webhooks are

17often easier to use for developers than monitoring a mailbox with IMAP and

18processing new incoming email and delivery status notification (DSN) messages.

20# Webapi

22The webapi has a base URL at /webapi/v0/ by default, but configurable, which

23serves an introduction that points to this documentation and lists the API

24methods available.

26An HTTP POST to /webapi/v0/<method> calls a method. The form can be either

27"application/x-www-form-urlencoded" or "multipart/form-data". Form field

28"request" must contain the request parameters, encoded as JSON.

30HTTP basic authentication is required for calling methods, with an email address

31as user name. Use a login address configured for "unique SMTP MAIL FROM"

32addresses ("FromIDLoginAddresses" in the account configuration), and configure

33an interval to "keep retired messages delivered from the queue". This allows

34incoming DSNs to be matched to the original outgoing messages, and enables

35automatic suppression list management.

37HTTP response status 200 OK indicates a successful method call, status 400

38indicates an error. The response body of an error is a JSON object with a

39human-readable "Message" field, and a "Code" field for programmatic handling

40(common codes: "user" or user-induced errors, "server" for server-caused

41errors). Most successful calls return a JSON object, but some return data

42(e.g. a raw message or an attachment of a message). See [Methods] for the

43methods and and [Client] for their documentation. The first element of their

44return values indicate their JSON object type or io.ReadCloser for non-JSON

45data. The request and response types are converted from/to JSON. Optional and

46missing/empty fields/values are converted into Go zero values: zero for

47numbers, empty strings, empty lists and empty objects. New fields may be added

48in response objects in future versions, parsers should ignore unrecognized

49fields.

51An HTTP GET to a method URL serves an HTML page showing example

52request/response JSON objects in a form and a button to call the method.

54# Webhooks

56Webhooks for outgoing delivery events and incoming deliveries are configured

57per account.

59A webhook is delivered by an HTTP POST with headers "X-Mox-Webhook-ID" (unique

60ID of webhook) and "X-Mox-Webhook-Attempt" (number of delivery attempts,

61starting at 1), and a JSON body with the webhook data. Failing webhook

62deliveries are retried with backoff, each time doubling the interval between

63attempts, at 1m, 2m, 4m, 7.5m, 15m and unwards, until the last attempt after a

6416h wait period.

66See [webhook.Outgoing] for the fields in a webhook for outgoing deliveries, and

67in particular [webhook.OutgoingEvent] for the types of events.

69Only the latest event for the delivery of a particular outgoing message will be

70delivered, any webhooks for that message still in the queue (after failure to

71deliver) are retired as superseded when a new event occurs.

73Webhooks for incoming deliveries are configured separately from outgoing

74deliveries. Incoming DSNs for previously sent messages do not cause a webhook

75to the webhook URL for incoming messages, only to the webhook URL for outgoing

76delivery events. The incoming webhook JSON payload contains the message

77envelope (parsed To, Cc, Bcc, Subject and more headers), the MIME structure,

78and the contents of the first text and HTML parts. See [webhook.Incoming] for

79the fields in the JSON object. The full message and individual parts, including

80attachments, can be retrieved using the webapi.

82# Transactional email

84When sending transactional emails, potentially to many recipients, it is

85important to process delivery failure notifications. If messages are rejected,

86or email addresses no longer exist, you should stop sending email to those

87addresses. If you try to keep sending, the receiving mail servers may consider

88that spammy behaviour and blocklist your mail server.

90Automatic suppression list management already prevents most repeated sending

91attempts. The webhooks make it easy to receive failure notifications.

93To keep spam complaints about your messages to a minimum, include links to

94unsubscribe from future messages without requiring further actions from the

95user, such as logins. Include an unsubscribe link in the footer, and include

96List-* message headers, such as List-Id, List-Unsubscribe and

97List-Unsubscribe-Post.

99# Webapi examples

100

101Below are examples for making webapi calls to a locally running "mox

102localserve" with its default credentials.

103

104Send a basic message:

105

106 $ curl --user mox@localhost:moxmoxmox \

107 --data request='{"To": [{"Address": "mox@localhost"}], "Text": "hi ☺"}' \

108 http://localhost:1080/webapi/v0/Send

109 {

110 "MessageID": "<kVTha0Q-a5Zh1MuTh5rUjg@localhost>",

111 "Submissions": [

112 {

113 "Address": "mox@localhost",

114 "QueueMsgID": 10010,

115 "FromID": "ZfV16EATHwKEufrSMo055Q"

116 }

117 ]

118 }

119

120Send a message with files both from form upload and base64 included in JSON:

121

122 $ curl --user mox@localhost:moxmoxmox \

123 --form request='{"To": [{"Address": "mox@localhost"}], "Subject": "hello", "Text": "hi ☺", "HTML": "<img src=\"cid:hi\" />", "AttachedFiles": [{"Name": "img.png", "ContentType": "image/png", "Data": "bWFkZSB5b3UgbG9vayE="}]}' \

124 --form 'inlinefile=@hi.png;headers="Content-ID: <hi>"' \

125 --form attachedfile=@mox.png \

126 http://localhost:1080/webapi/v0/Send

127 {

128 "MessageID": "<eZ3OEEA2odXovovIxHE49g@localhost>",

129 "Submissions": [

130 {

131 "Address": "mox@localhost",

132 "QueueMsgID": 10011,

133 "FromID": "yWiUQ6mvJND8FRPSmc9y5A"

134 }

135 ]

136 }

137

138Get a message in parsed form:

139

140 $ curl --user mox@localhost:moxmoxmox --data request='{"MsgID": 424}' http://localhost:1080/webapi/v0/MessageGet

141 {

142 "Message": {

143 "From": [

144 {

145 "Name": "mox",

146 "Address": "mox@localhost"

147 }

148 ],

149 "To": [

150 {

151 "Name": "",

152 "Address": "mox@localhost"

153 }

154 ],

155 "CC": [],

156 "BCC": [],

157 "ReplyTo": [],

158 "MessageID": "<84vCeme_yZXyDzjWDeYBpg@localhost>",

159 "References": [],

160 "Date": "2024-04-04T14:29:42+02:00",

161 "Subject": "hello",

162 "Text": "hi \u263a\n",

163 "HTML": ""

164 },

165 "Structure": {

166 "ContentType": "multipart/mixed",

167 "ContentTypeParams": {

168 "boundary": "0ee72dc30dbab2ca6f7a363844a10a9f6111fc6dd31b8ff0b261478c2c48"

169 },

170 "ContentID": "",

171 "DecodedSize": 0,

172 "Parts": [

173 {

174 "ContentType": "multipart/related",

175 "ContentTypeParams": {

176 "boundary": "b5ed0977ee2b628040f394c3f374012458379a4f3fcda5036371d761c81d"

177 },

178 "ContentID": "",

179 "DecodedSize": 0,

180 "Parts": [

181 {

182 "ContentType": "multipart/alternative",

183 "ContentTypeParams": {

184 "boundary": "3759771adede7bd191ef37f2aa0e49ff67369f4000c320f198a875e96487"

185 },

186 "ContentID": "",

187 "DecodedSize": 0,

188 "Parts": [

189 {

190 "ContentType": "text/plain",

191 "ContentTypeParams": {

192 "charset": "utf-8"

193 },

194 "ContentID": "",

195 "DecodedSize": 8,

196 "Parts": []

197 },

198 {

199 "ContentType": "text/html",

200 "ContentTypeParams": {

201 "charset": "us-ascii"

202 },

203 "ContentID": "",

204 "DecodedSize": 22,

205 "Parts": []

206 }

207 ]

208 },

209 {

210 "ContentType": "image/png",

211 "ContentTypeParams": {},

212 "ContentID": "<hi>",

213 "DecodedSize": 19375,

214 "Parts": []

215 }

216 ]

217 },

218 {

219 "ContentType": "image/png",

220 "ContentTypeParams": {},

221 "ContentID": "",

222 "DecodedSize": 14,

223 "Parts": []

224 },

225 {

226 "ContentType": "image/png",

227 "ContentTypeParams": {},

228 "ContentID": "",

229 "DecodedSize": 7766,

230 "Parts": []

231 }

232 ]

233 },

234 "Meta": {

235 "Size": 38946,

236 "DSN": false,

237 "Flags": [

238 "$notjunk",

239 "\seen"

240 ],

241 "MailFrom": "mox@localhost",

242 "RcptTo": "mox@localhost",

243 "MailFromValidated": false,

244 "MsgFrom": "mox@localhost",

245 "MsgFromValidated": false,

246 "DKIMVerifiedDomains": [],

247 "RemoteIP": "",

248 "MailboxName": "Inbox"

249 }

250 }

251

252Errors (with a 400 bad request HTTP status response) include a human-readable

253message and a code for programmatic use:

254

255 $ curl --user mox@localhost:moxmoxmox --data request='{"MsgID": 999}' http://localhost:1080/webapi/v0/MessageGet

256 {

257 "Code": "notFound",

258 "Message": "message not found"

259 }

260

261Get a raw, unparsed message, as bytes:

262

263 $ curl --user mox@localhost:moxmoxmox --data request='{"MsgID": 123}' http://localhost:1080/webapi/v0/MessageRawGet

264 [message as bytes in raw form]

265

266Mark a message as read and set flag "custom":

267

268 $ curl --user mox@localhost:moxmoxmox --data request='{"MsgID": 424, "Flags": ["\\Seen", "custom"]}' http://localhost:1080/webapi/v0/MessageFlagsAdd

269 {}

270

271# Webhook examples

272

273A webhook is delivered by an HTTP POST, wich headers X-Mox-Webhook-ID and

274X-Mox-Webhook-Attempt and a JSON body with the data. To simulate a webhook call

275for incoming messages, use:

276

277 curl -H 'X-Mox-Webhook-ID: 123' -H 'X-Mox-Webhook-Attempt: 1' --json '{...}' http://localhost/yourapp

278

279Example webhook HTTP POST JSON body for successful outgoing delivery:

280