1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.net.smtp;
19
20 import java.io.BufferedReader;
21 import java.io.BufferedWriter;
22 import java.io.IOException;
23 import java.io.InputStreamReader;
24 import java.io.OutputStreamWriter;
25 import java.util.ArrayList;
26
27 import org.apache.commons.net.MalformedServerReplyException;
28 import org.apache.commons.net.ProtocolCommandSupport;
29 import org.apache.commons.net.SocketClient;
30 import org.apache.commons.net.io.CRLFLineReader;
31 import org.apache.commons.net.util.NetConstants;
32
33 /**
34 * SMTP provides the basic the functionality necessary to implement your own SMTP client. To derive the full benefits of the SMTP class requires some knowledge
35 * of the FTP protocol defined in RFC 821. However, there is no reason why you should have to use the SMTP class. The
36 * {@link org.apache.commons.net.smtp.SMTPClient} class, derived from SMTP, implements all the functionality required of an SMTP client. The SMTP class is made
37 * public to provide access to various SMTP constants and to make it easier for adventurous programmers (or those with special needs) to interact with the SMTP
38 * protocol and implement their own clients. A set of methods with names corresponding to the SMTP command names are provided to facilitate this interaction.
39 * <p>
40 * You should keep in mind that the SMTP server may choose to prematurely close a connection for various reasons. The SMTP class will detect a premature SMTP
41 * server connection closing when it receives a {@link org.apache.commons.net.smtp.SMTPReply#SERVICE_NOT_AVAILABLE SMTPReply.SERVICE_NOT_AVAILABLE } response to
42 * a command. When that occurs, the SMTP class method encountering that reply will throw an {@link org.apache.commons.net.smtp.SMTPConnectionClosedException} .
43 * <code>SMTPConnectionClosedException</code> is a subclass of <code> IOException </code> and therefore need not be caught separately, but if you are going to
44 * catch it separately, its catch block must appear before the more general <code> IOException </code> catch block. When you encounter an
45 * {@link org.apache.commons.net.smtp.SMTPConnectionClosedException} , you must disconnect the connection with
46 * {@link org.apache.commons.net.SocketClient#disconnect disconnect() } to properly clean up the system resources used by SMTP. Before disconnecting, you may
47 * check the last reply code and text with {@link #getReplyCode getReplyCode }, {@link #getReplyString getReplyString }, and {@link #getReplyStrings
48 * getReplyStrings}.
49 * </p>
50 * <p>
51 * Rather than list it separately for each method, we mention here that every method communicating with the server and throwing an IOException can also throw a
52 * {@link org.apache.commons.net.MalformedServerReplyException} , which is a subclass of IOException. A MalformedServerReplyException will be thrown when the
53 * reply received from the server deviates enough from the protocol specification that it cannot be interpreted in a useful manner despite attempts to be as
54 * lenient as possible.
55 * </p>
56 *
57 * @see SMTPClient
58 * @see SMTPConnectionClosedException
59 * @see org.apache.commons.net.MalformedServerReplyException
60 */
61
62 public class SMTP extends SocketClient {
63 /** The default SMTP port (25). */
64 public static final int DEFAULT_PORT = 25;
65
66 // We have to ensure that the protocol communication is in ASCII,
67 // but we use ISO-8859-1 just in case 8-bit characters cross
68 // the wire.
69 private static final String DEFAULT_ENCODING = "ISO-8859-1";
70
71 /**
72 * The encoding to use (user-settable).
73 *
74 * @since 3.1 (changed from private to protected)
75 */
76 protected final String encoding;
77
78 /**
79 * A ProtocolCommandSupport object used to manage the registering of ProtocolCommandListeners and te firing of ProtocolCommandEvents.
80 */
81 protected ProtocolCommandSupport _commandSupport_;
82
83 BufferedReader reader;
84 BufferedWriter writer;
85
86 private int replyCode;
87 private final ArrayList<String> replyLines;
88 private boolean newReplyString;
89 private String replyString;
90
91 /**
92 * The default SMTP constructor. Sets the default port to <code>DEFAULT_PORT</code> and initializes internal data structures for saving SMTP reply
93 * information.
94 */
95 public SMTP() {
96 this(DEFAULT_ENCODING);
97 }
98
99 /**
100 * Overloaded constructor where the user may specify a default encoding.
101 *
102 * @param encoding the encoding to use
103 * @since 2.0
104 */
105 public SMTP(final String encoding) {
106 setDefaultPort(DEFAULT_PORT);
107 replyLines = new ArrayList<>();
108 newReplyString = false;
109 replyString = null;
110 _commandSupport_ = new ProtocolCommandSupport(this);
111 this.encoding = encoding;
112 }
113
114 /** Initiates control connections and gets initial reply. */
115 @Override
116 protected void _connectAction_() throws IOException {
117 super._connectAction_();
118 reader = new CRLFLineReader(new InputStreamReader(_input_, encoding));
119 writer = new BufferedWriter(new OutputStreamWriter(_output_, encoding));
120 getReply();
121 }
122
123 /**
124 * A convenience method to send the SMTP DATA command to the server, receive the reply, and return the reply code.
125 *
126 * @return The reply code received from the server.
127 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
128 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
129 * independently as itself.
130 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
131 */
132 public int data() throws IOException {
133 return sendCommand(SMTPCommand.DATA);
134 }
135
136 /**
137 * Closes the connection to the SMTP server and sets to null some internal data so that the memory may be reclaimed by the garbage collector. The reply text
138 * and code information from the last command is voided so that the memory it used may be reclaimed.
139 *
140 * @throws IOException If an error occurs while disconnecting.
141 */
142 @Override
143 public void disconnect() throws IOException {
144 super.disconnect();
145 reader = null;
146 writer = null;
147 replyString = null;
148 replyLines.clear();
149 newReplyString = false;
150 }
151
152 /**
153 * A convenience method to send the SMTP VRFY command to the server, receive the reply, and return the reply code.
154 *
155 * @param name The name to expand.
156 * @return The reply code received from the server.
157 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
158 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
159 * independently as itself.
160 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
161 */
162 public int expn(final String name) throws IOException {
163 return sendCommand(SMTPCommand.EXPN, name);
164 }
165
166 /**
167 * Provide command support to super-class
168 */
169 @Override
170 protected ProtocolCommandSupport getCommandSupport() {
171 return _commandSupport_;
172 }
173
174 /**
175 * Fetches a reply from the SMTP server and returns the integer reply code. After calling this method, the actual reply text can be accessed from either
176 * calling {@link #getReplyString getReplyString } or {@link #getReplyStrings getReplyStrings }. Only use this method if you are implementing your own SMTP
177 * client or if you need to fetch a secondary response from the SMTP server.
178 *
179 * @return The integer value of the reply code of the fetched SMTP reply.
180 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
181 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
182 * independently as itself.
183 * @throws IOException If an I/O error occurs while receiving the server reply.
184 */
185 public int getReply() throws IOException {
186 final int length;
187
188 newReplyString = true;
189 replyLines.clear();
190
191 String line = reader.readLine();
192
193 if (line == null) {
194 throw new SMTPConnectionClosedException("Connection closed without indication.");
195 }
196
197 // In case we run into an anomaly we don't want fatal index exceptions
198 // to be thrown.
199 length = line.length();
200 if (length < 3) {
201 throw new MalformedServerReplyException("Truncated server reply: " + line);
202 }
203
204 try {
205 final String code = line.substring(0, 3);
206 replyCode = Integer.parseInt(code);
207 } catch (final NumberFormatException e) {
208 throw new MalformedServerReplyException("Could not parse response code.\nServer Reply: " + line);
209 }
210
211 replyLines.add(line);
212
213 // Get extra lines if message continues.
214 if (length > 3 && line.charAt(3) == '-') {
215 do {
216 line = reader.readLine();
217
218 if (line == null) {
219 throw new SMTPConnectionClosedException("Connection closed without indication.");
220 }
221
222 replyLines.add(line);
223
224 // The length() check handles problems that could arise from readLine()
225 // returning too soon after encountering a naked CR or some other
226 // anomaly.
227 } while (!(line.length() >= 4 && line.charAt(3) != '-' && Character.isDigit(line.charAt(0))));
228 // This is too strong a condition because a non-conforming server
229 // could screw things up like ftp.funet.fi does for FTP
230 // line.startsWith(code)));
231 }
232
233 fireReplyReceived(replyCode, getReplyString());
234
235 if (replyCode == SMTPReply.SERVICE_NOT_AVAILABLE) {
236 throw new SMTPConnectionClosedException("SMTP response 421 received. Server closed connection.");
237 }
238 return replyCode;
239 }
240
241 /**
242 * Returns the integer value of the reply code of the last SMTP reply. You will usually only use this method after you connect to the SMTP server to check
243 * that the connection was successful since <code> connect </code> is of type void.
244 *
245 * @return The integer value of the reply code of the last SMTP reply.
246 */
247 public int getReplyCode() {
248 return replyCode;
249 }
250
251 /**
252 * Returns the entire text of the last SMTP server response exactly as it was received, including all end of line markers in NETASCII format.
253 *
254 * @return The entire text from the last SMTP response as a String.
255 */
256 public String getReplyString() {
257 final StringBuilder buffer;
258
259 if (!newReplyString) {
260 return replyString;
261 }
262
263 buffer = new StringBuilder();
264
265 for (final String line : replyLines) {
266 buffer.append(line);
267 buffer.append(SocketClient.NETASCII_EOL);
268 }
269
270 newReplyString = false;
271
272 replyString = buffer.toString();
273 return replyString;
274 }
275
276 /**
277 * Returns the lines of text from the last SMTP server response as an array of strings, one entry per line. The end of line markers of each are stripped
278 * from each line.
279 *
280 * @return The lines of text from the last SMTP response as an array.
281 */
282 public String[] getReplyStrings() {
283 return replyLines.toArray(NetConstants.EMPTY_STRING_ARRAY);
284 }
285
286 /**
287 * A convenience method to send the SMTP HELO command to the server, receive the reply, and return the reply code.
288 *
289 * @param hostname The hostname of the sender.
290 * @return The reply code received from the server.
291 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
292 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
293 * independently as itself.
294 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
295 */
296 public int helo(final String hostname) throws IOException {
297 return sendCommand(SMTPCommand.HELO, hostname);
298 }
299
300 /**
301 * A convenience method to send the SMTP HELP command to the server, receive the reply, and return the reply code.
302 *
303 * @return The reply code received from the server.
304 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
305 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
306 * independently as itself.
307 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
308 */
309 public int help() throws IOException {
310 return sendCommand(SMTPCommand.HELP);
311 }
312
313 /**
314 * A convenience method to send the SMTP HELP command to the server, receive the reply, and return the reply code.
315 *
316 * @param command The command name on which to request help.
317 * @return The reply code received from the server.
318 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
319 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
320 * independently as itself.
321 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
322 */
323 public int help(final String command) throws IOException {
324 return sendCommand(SMTPCommand.HELP, command);
325 }
326
327 /**
328 * A convenience method to send the SMTP MAIL command to the server, receive the reply, and return the reply code.
329 *
330 * @param reversePath The reverse path.
331 * @return The reply code received from the server.
332 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
333 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
334 * independently as itself.
335 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
336 */
337 public int mail(final String reversePath) throws IOException {
338 return sendCommand(SMTPCommand.MAIL, reversePath, false);
339 }
340
341 /**
342 * A convenience method to send the SMTP NOOP command to the server, receive the reply, and return the reply code.
343 *
344 * @return The reply code received from the server.
345 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
346 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
347 * independently as itself.
348 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
349 */
350 public int noop() throws IOException {
351 return sendCommand(SMTPCommand.NOOP);
352 }
353
354 /**
355 * A convenience method to send the SMTP QUIT command to the server, receive the reply, and return the reply code.
356 *
357 * @return The reply code received from the server.
358 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
359 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
360 * independently as itself.
361 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
362 */
363 public int quit() throws IOException {
364 return sendCommand(SMTPCommand.QUIT);
365 }
366
367 /**
368 * A convenience method to send the SMTP RCPT command to the server, receive the reply, and return the reply code.
369 *
370 * @param forwardPath The forward path.
371 * @return The reply code received from the server.
372 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
373 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
374 * independently as itself.
375 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
376 */
377 public int rcpt(final String forwardPath) throws IOException {
378 return sendCommand(SMTPCommand.RCPT, forwardPath, false);
379 }
380
381 /**
382 * Removes a ProtocolCommandListener.
383 *
384 * Delegates this incorrectly named method - removeProtocolCommandistener (note the missing "L")- to the correct method
385 * {@link SocketClient#removeProtocolCommandListener}
386 *
387 * @param listener The ProtocolCommandListener to remove
388 */
389 public void removeProtocolCommandistener(final org.apache.commons.net.ProtocolCommandListener listener) {
390 removeProtocolCommandListener(listener);
391 }
392
393 /**
394 * A convenience method to send the SMTP RSET command to the server, receive the reply, and return the reply code.
395 *
396 * @return The reply code received from the server.
397 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
398 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
399 * independently as itself.
400 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
401 */
402 public int rset() throws IOException {
403 return sendCommand(SMTPCommand.RSET);
404 }
405
406 /**
407 * A convenience method to send the SMTP SAML command to the server, receive the reply, and return the reply code.
408 *
409 * @param reversePath The reverse path.
410 * @return The reply code received from the server.
411 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
412 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
413 * independently as itself.
414 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
415 */
416 public int saml(final String reversePath) throws IOException {
417 return sendCommand(SMTPCommand.SAML, reversePath);
418 }
419
420 /**
421 * A convenience method to send the SMTP SEND command to the server, receive the reply, and return the reply code.
422 *
423 * @param reversePath The reverse path.
424 * @return The reply code received from the server.
425 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
426 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
427 * independently as itself.
428 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
429 */
430 public int send(final String reversePath) throws IOException {
431 return sendCommand(SMTPCommand.SEND, reversePath);
432 }
433
434 /**
435 * Sends an SMTP command with no arguments to the server, waits for a reply and returns the numerical response code. After invocation, for more detailed
436 * information, the actual reply text can be accessed by calling {@link #getReplyString getReplyString } or {@link #getReplyStrings getReplyStrings }.
437 *
438 * @param command The SMTPCommand constant corresponding to the SMTP command to send.
439 * @return The integer value of the SMTP reply code returned by the server in response to the command.
440 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
441 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
442 * independently as itself.
443 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
444 */
445 public int sendCommand(final int command) throws IOException {
446 return sendCommand(command, null);
447 }
448
449 /**
450 * Sends an SMTP command to the server, waits for a reply and returns the numerical response code. After invocation, for more detailed information, the
451 * actual reply text can be accessed by calling {@link #getReplyString getReplyString } or {@link #getReplyStrings getReplyStrings }.
452 *
453 * @param command The SMTPCommand constant corresponding to the SMTP command to send.
454 * @param args The arguments to the SMTP command. If this parameter is set to null, then the command is sent with no argument.
455 * @return The integer value of the SMTP reply code returned by the server in response to the command.
456 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
457 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
458 * independently as itself.
459 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
460 */
461 public int sendCommand(final int command, final String args) throws IOException {
462 return sendCommand(SMTPCommand.getCommand(command), args);
463 }
464
465 /**
466 *
467 * @param command the command to send (as an int defined in {@link SMTPCommand})
468 * @param args the command arguments, may be {@code null}
469 * @param includeSpace if {@code true}, add a space between the command and its arguments
470 * @return the reply code
471 * @throws IOException
472 */
473 private int sendCommand(final int command, final String args, final boolean includeSpace) throws IOException {
474 return sendCommand(SMTPCommand.getCommand(command), args, includeSpace);
475 }
476
477 /**
478 * Sends an SMTP command with no arguments to the server, waits for a reply and returns the numerical response code. After invocation, for more detailed
479 * information, the actual reply text can be accessed by calling {@link #getReplyString getReplyString } or {@link #getReplyStrings getReplyStrings }.
480 *
481 * @param command The text representation of the SMTP command to send.
482 * @return The integer value of the SMTP reply code returned by the server in response to the command.
483 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
484 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
485 * independently as itself.
486 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
487 */
488 public int sendCommand(final String command) throws IOException {
489 return sendCommand(command, null);
490 }
491
492 /**
493 * Sends an SMTP command to the server, waits for a reply and returns the numerical response code. After invocation, for more detailed information, the
494 * actual reply text can be accessed by calling {@link #getReplyString getReplyString } or {@link #getReplyStrings getReplyStrings }.
495 *
496 * @param command The text representation of the SMTP command to send.
497 * @param args The arguments to the SMTP command. If this parameter is set to null, then the command is sent with no argument.
498 * @return The integer value of the SMTP reply code returned by the server in response to the command.
499 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
500 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
501 * independently as itself.
502 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
503 */
504 public int sendCommand(final String command, final String args) throws IOException {
505 return sendCommand(command, args, true);
506 }
507
508 /**
509 * Send a command to the server. May also be used to send text data.
510 *
511 * @param command the command to send (as a plain String)
512 * @param args the command arguments, may be {@code null}
513 * @param includeSpace if {@code true}, add a space between the command and its arguments
514 * @return the reply code
515 * @throws IOException
516 */
517 private int sendCommand(final String command, final String args, final boolean includeSpace) throws IOException {
518 final StringBuilder __commandBuffer = new StringBuilder();
519 __commandBuffer.append(command);
520
521 if (args != null) {
522 if (includeSpace) {
523 __commandBuffer.append(' ');
524 }
525 __commandBuffer.append(args);
526 }
527
528 __commandBuffer.append(SocketClient.NETASCII_EOL);
529
530 final String message = __commandBuffer.toString();
531 writer.write(message);
532 writer.flush();
533
534 fireCommandSent(command, message);
535
536 return getReply();
537 }
538
539 /**
540 * A convenience method to send the SMTP SOML command to the server, receive the reply, and return the reply code.
541 *
542 * @param reversePath The reverse path.
543 * @return The reply code received from the server.
544 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
545 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
546 * independently as itself.
547 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
548 */
549 public int soml(final String reversePath) throws IOException {
550 return sendCommand(SMTPCommand.SOML, reversePath);
551 }
552
553 /**
554 * A convenience method to send the SMTP TURN command to the server, receive the reply, and return the reply code.
555 *
556 * @return The reply code received from the server.
557 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
558 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
559 * independently as itself.
560 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
561 */
562 public int turn() throws IOException {
563 return sendCommand(SMTPCommand.TURN);
564 }
565
566 /**
567 * A convenience method to send the SMTP VRFY command to the server, receive the reply, and return the reply code.
568 *
569 * @param user The user address to verify.
570 * @return The reply code received from the server.
571 * @throws SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason
572 * causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or
573 * independently as itself.
574 * @throws IOException If an I/O error occurs while either sending the command or receiving the server reply.
575 */
576 public int vrfy(final String user) throws IOException {
577 return sendCommand(SMTPCommand.VRFY, user);
578 }
579 }