Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Bulkmail::Server(3)   User Contributed Perl Documentation  Bulkmail::Server(3)

NAME
       Mail::Bulkmail::Server -	handles	server connections and communication
       for Mail::Bulkmail

AUTHOR
       Jim Thomason, jim@jimandkoka.com

SYNOPSIS
	my $server = Mail::Bulkmail::Server->new(
	       'Smtp' => 'your.smtp.com',
	       'Port' => 25
	) || die Mail::Bulkmail::Server->error();

	#connect to the	SMTP relay
	$server->connect || die	$server->error();

	#talk to the server
	my $response = $server->talk_and_respond("RSET");

DESCRIPTION
       Mail::Bulkmail::Server now handles server connections. Mail::Bulkmail
       1.x and 2.x had all the server functionality built into the module
       itself. That was	nice in	terms of simplicity - one module, one
       connection, one server, and so on. But it had some downsides. For one
       thing, it only allowed for one connection. And since I wanted to	allow
       multiple	server connections in 3.00, that had to	go. For	another, it
       was a pain in the butt to change	the server implementation. This	way,
       you can easily write your own server class, drop	it in here, and	be off
       to the races.

       For example, the	Mail::Bulkmail::DummyServer module for debugging
       purposes.

       This is not a module that you'll	really need to access directly,	since
       it is accessed internally by Mail::Bulkmail when	it is needed. Specify
       the data	you need in the	conf file and the server_file attribute, and
       you won't ever need to touch this directly.

ATTRIBUTES
       Smtp	  stores the Smtp relay's address.

		   $server->Smtp("your.smtp.com");

		  can either be	an IP or a named address

		  Smtp values should be	set in your server file.

       Port	  stores the port on which you'll try to connect to the	SMTP
		  relay. Probably going	to be 25, since	that's the standard
		  SMTP port.

		   $server->Port(25);

		  Port values should be	set in either your server file,	or a
		  single default in your conf file.

       Domain	  When you connect to an SMTP server, you must say hello and
		  state	your domain. This is your domain that you use to say
		  hello.

		   $server->Domain('mydomain.com');

		  This should be the same name of the domain of	the machine
		  that you are connecting on.

		  Domain should	be set in your conf file.

       Tries	  When you try to connect to an	SMTP server via	->connect, you
		  may have issues with creating	the socket or making the
		  connection. Tries specifies how many times you should	re-try
		  making the socket or making the connection before failing to
		  connect.

		  Make this a small number.

		   $server->Tries(5);

		  Tries	should be set in your conf file.

       max_connection_attempts
		  This is similar to Tries, but	this governs the number	of
		  times	that you can call the ->connect	method.	 When you have
		  multiple servers in Mail::Bulkmail's ->servers array,
		  there's no point in constantly re-trying to connect to a
		  server that fails. it'll just	slow you down.
		  max_connection_attempts makes	sure that you stop trying to
		  connect to invalid servers.

		  Make this a small number as well.

		   $server->max_connection_attempts(7);

		  max_connection_attempts should be set	in your	conf file.

       envelope_limit
		  It's entirely	likely that with a very	large list you'll have
		  a very large number of people	in the same domain.  For
		  instance, there are an awful lot of people that have yahoo
		  addresses.  So, for example, say that	you have a list	of
		  100,000 people and 20,000 of them are	in the yahoo.com
		  domain and you're sending using the envelope.	 That means
		  that the server at yahoo.com is going	to receive one message
		  with 20,000 people in	the envelope!

		  Now, this might be a bad thing.  We don't know if the
		  yahoo.com mail server	will actually process a	message	with
		  20,000 envelope recipients.  It may or may not and the only
		  way to find out is to	try it.	 If it does work, then great
		  no worries. But if it	doesn't, then you're stuck.  If	you
		  stop using envelope sending, you sacrifice its major speed
		  gains, but if	you keep using it you can't send to yahoo.com.

		  envelope_limit fixes that.

		  envelope_limit is precisely what it sounds like, it allows
		  you to specify a limit on the	number of recipients that will
		  be specified in your envelope.  That way, with our previous
		  example, you can specify an envelope limit of	1000, for
		  example.

		   $bulk->envelope_limit(1000);

		  This means that yahoo.com will get 20	messages, each with
		  1000 recipients in the envelope.  Of course, this still may
		  not be small enough, so you can tweak	it as much as
		  necessary.

		  Setting an envelope limit does trade off some	of the gains
		  from using the envelope, but it's still over all a vast
		  speed	boost over not using it.

		  envelope_limit should	be set in your conf file. I recommend
		  setting it to	100, but tweak it as necessary.	Higher values
		  allow	you to send more information and do it faster, but
		  you're more likely to	run into server's that refuse that
		  many recipients. Lower values	are more compatible, but
		  slightly slower.

		  Set envelope_limit to	0 for an infinite limit. You should
		  never	have to	set it below 100 (unless you're	using an
		  infinite limit), since RFC 2822 says that SMTP servers
		  should always	accept at least	100 recipients in the envelope

       max_messages
		  max_messages sets the	maximum	number of messages to send to
		  a particular server. This is mainly useful if	you're
		  bulkmailing to multiple servers. You may have	a server that
		  can take some	of the load, but not much of it. Assume	that
		  your list has	over 100,000 people on it, and you're using
		  one primary SMTP relay and one smaller SMTP relay to help
		  take some of the load	off of the main	one. Your primary SMTP
		  server can handle lots of messages, but your smaller one can
		  only take a smaller load.  That'd a good place for
		  max_messages.

		   $aux_server->max_messages(10000);

		  That way, your smaller server	will relay no more than	10,000
		  messages.

		  Set max_messages to 0	for an infinite	number of messages to
		  go through the server. It is recommended to set max_messages
		  to 0.

       max_messages_per_robin
		  when you set up your bulkmail	object with multiple servers,
		  max_messages_per_robin is used to determine how many
		  messages are sent to a server	before moving onto the next.

		  This is the maximum number of	messages that would be sent to
		  a server in a	given iteration	before moving on to the	next,
		  but it is not	necessarily the	exact number of	messages that
		  will be sent.	If the server has reached the maximum number
		  of messages allowed, or the maximum number in	a given
		  connection, it will jump to the next server before reaching
		  the robin limit.

		  Set max_messages_per_robin to	0 for an infinite number of
		  messages allowed on a	given server iteration.	It is
		  recommended to set this to 500 if you're using multiple
		  servers, and to 0 if you're using 1 server.

		  The message robin counter is reset by	reset_all_counters

       max_messages_per_connection
		  This sets the	maximum	number of messages that	would be sent
		  to a given SMTP relay	in a given connection.	When this
		  limit	is reached, the	server will disconnect and return that
		  it has reached a limit.

		  set max_messages_per_connection to 0 for infinite messages
		  per connection. It is	recommended to keep this at 0.

		  The message connection counter is reset by
		  reset_all_counters

       max_messages_while_awake
		  Sometimes, it	may be useful to pause and give	your server a
		  break. max_messages_while_awake allows this. This will
		  specify the number of	messages to send to a server before
		  going	to sleep for a certain period of time.

		   $server->max_messages_while_awake(100);

		  Will send 100	messages to the	server and then	go to sleep.
		  for the time specified by sleep_length.

		  Note that reaching this limit	will not cause reached_limit
		  to return a true value, so in	a multi-server environment,
		  you'll end up	sleeping a lot.

		  The message-while-awake counter is reset by
		  reset_all_counters, so it is of dubious utility when using
		  multiple servers.

		  Set max_messages_while_awake to 0 to never sleep. It is
		  recommended to have max_messages_while_awake set to 0	when
		  using	multiple servers. Set it to a positive number when
		  using	one server.

       sleep_length
		  Specifies the	time to	sleep (in seconds) if the server has
		  reached the max_messages_while_awake limit.

       talk_attempts
		  The response codes for SMTP are pretty rigorously defined,
		  which	is obviously very usefull. a 5xy error is permanently
		  fatal.  a 4xy	error is temporarily fatal. It is recommended
		  that if a 4xy	error is encountered, that the client (us)
		  should try re-sending	the same command again.	talk_attempts
		  specifies the	number of times	to try resending a command
		  after	receiving a 400	level error from the server.

		   $server->talk_attempts(5);

       time_out	  We can *finally* time	out! So	if your	SMTP relay doesn't
		  respond for a	set period of time, the	connection will
		  automatically	disconnect and fail with an error. Set this to
		  something high, the value is in seconds.

		   $server->time_out(3000);	  # 5 minutes

       time_of_last_message
		  stores the time that the last	message	was sent through this
		  server, in epoch seconds.

       connected  boolean attribute that says whether or not this server
		  object is connected to an SMTP relay.

		  Don't	set this value,	only read it.

       CONVERSATION
		  This is an optional log file to keep track of	your SMTP
		  conversations

		  CONVERSATION may be either a coderef,	globref, arrayref, or
		  string literal.

		  If a string literal, then Mail::Bulkmail::Server will
		  attempt to open that file (in	append mode) as	your log:

		   $server->CONVERSATION("/path/to/my/conversation");

		  If a globref,	it is assumed to be an open filehandle in
		  append mode:

		   open	(C, ">>/path/to/my/conversation");
		   $server->CONVERSATION(\*C);

		  if a coderef,	it is assumed to be a function to call with
		  the address as an argument:

		   sub C { print "CONVERSATION : ", $_[1], "\n"}; #or whatever your code is
		   $server->CONVERSATION(\&C);

		  if an	arrayref, then the conversation	will be	pushed on to
		  the end of it

		   $server->CONVERSATION(\@conversation);

		  Use whichever	item is	most convenient, and
		  Mail::Bulkmail::Server will take it from there.

		  Be warned: This file is going	to get huge. Massively huge.
		  You should only turn this on for debugging purposes and
		  never	in a production	environment. It	will log the first 50
		  characters of	a message sent to the server, and the full
		  server response.

       socket	  socket contains the socket that this Server has opened to
		  its SMTP relay. You'll probably never	talk to	this directly,
		  but it's here, just in case you want it.

METHODS
       increment_messages_sent
		  This method will increment the server	object's internal
		  counters storing the total number of messages	sent, the
		  total	sent this robin, the total sent	this connection, the
		  total	sent while awake, and the total	sent this envelope.

		  It will also store the time the last message is sent.

       reset_message_counters
		  This message will reset the internal counters	for the
		  messages sent	this robin, messages sent this connection, and
		  messages sent	while awake back to 0.

       reset_envelope_counter
		  The envelope counter behaves slightly	differently than the
		  other	counters, so we	have a separate	method to reset	the
		  internal envelope counter.

       reached_envelope_limit
		  This method returns 1	if we've reached the envelope limit, 0
		  otherwise

       reached_limit
		  This method will tell	you if the server has reached the
		  max_messages,	max_messages_per_connection, or
		  max_messages_per_robin limits. Also, if you reach the
		  max_messages_while_awake limit, this method will cause you
		  to sleep for the time	period specified in sleep_length

		   Return values:
		   1 : reached max_messages limit, server becomes worthless and	will not be used again
		   2 : reached max_messages_per_connection limit, server will disconnect
		   3 : reached max_messages_per_robin limit

       new	  Standard constructor.	See Mail::Bulkmail::Object for more
		  information.

       connect	  Connects this	server object to the SMTP relay	specified with
		  ->Smtp and ->Port This method	will set ->connected to	1 if
		  it successfully connects.

		   $server->connect() || die "Could not	connect	: " . $server->error;

		  Upon connection, ->connect will issue	a HELO command for the
		  ->Domain specified.

		  This method is known to be able to return:

		   MBS001 - cannot connect to worthless	servers
		   MBS002 - could not make socket
		   MBS003 - could not connect to server
		   MBS004 - no response	from server
		   MBS005 - server won't say HELO
		   MBS010 - can't greet	server w/o domain
		   MBS011 - server gave	an error for EHLO
		   MBS015 - timed out waiting for response upon	connect
		   MBS016 - server didn't respond to EHLO, trying HELO (non-returning error)
		   MBS017 - cannot connect to server, no Tries parameter

       disconnect disconnects the server object	from the SMTP relay. Before
		  disconnect, it will issue a "RSET" and then a	"quit" command
		  to the SMTP server, then close the socket. disconnect	sets
		  ->connected to 0.

		  disconnect can also disconnect quietly, i.e.,	it won't try
		  to issue a RSET and then quit	before closing the socket.

		   $server->disconnect();			  #issues RSET and quit
		   $server->disconnect('quietly');	  #issues nothing

       talk_and_respond
		  talk_and_respond takes one argument and sends	it to your
		  SMTP relay. It then listens for a response.

		   my $response	= $server->talk_and_respond("RSET");

		  If you're not	connected to the relay,	talk_and_respond will
		  attempt to connect.

		  This method is known to be able to return:

		   MBS006 - cannot talk	w/o speech
		   MBS007 - cannot talk	to server
		   MBS008 - server won't respond to speech
		   MBS009 - server disconnected
		   MBS012 - temporarily	won't respond to speech...re-trying
		   MBS013 - could never	resolve	temporary error
		   MBS014 - timed out waiting for response
		   MBS018 - No file descriptor

       create_all_servers
		  create_all_servers will iterate through the file specified
		  in server_file in the	conf file and return an	arrayref of
		  all server objects created.

		   define package Mail::Bulkmail::Server

		   server_file	  = ./server_file.txt

		  your server file should be of	the format of another
		  Mail::Bulkmail conf file, containing definitions for all of
		  the SMTP servers you want to use. See	the examples below for
		  how to set up	the conf files.

		  If you would like to specify a different conf	file, pass
		  that as an argument.

		   my $servers = Mail::Bulkmail::Server->create_all_servers('/path/to/new/server_file.txt');

		  This will then ignore	the server_file	in the conf file and
		  use the one passed.

		  You may also pass hashrefs of	init data for new servers.

		   my $servers = Mail::Bulkmail::Server->create_all_servers(
			  {
				  'Smtp' => 'smtp.yourdomain.com'
			  },
			  {
				  'Smtp' => 'smtp2.yourdomain.com'
			  },
			  {
				  'Smtp' => 'smtp3.yourdomain.com'
			  }
		   ) ||	die Mail::Bulkmail::Server->error;

		  This is called internally by Mail::Bulkmail's	constructor,
		  so you probably won't	ever need to touch it.

SAMPLE SERVER FILE
       It is recommended that you define your server entries in	your server
       file. See Mail::Bulkmail::Object	and Mail::Bulkmail for more
       information on conf file	set up and how to define your server_file.

	#in your conf file, you	want this
	define package Mail::Bulkmail::Server

	#your server file
	server_file = /etc/mb/server.file.txt

       Now, your server	file should look like this:

	define package Mail::Bulkmail::Server

	#set up	the first server
	Smtp @=	smtp1.yourdomain.com
	Port @=	25
	Tries @= 5
	max_messages_per_robin @= 1000
	envelope_limit @= 100

	#set up	the second server
	Smtp @=	smtp2.yourdomain.com
	Port @=	25
	Tries @= 5
	max_messages_per_robin @= 1000
	envelope_limit @= 100

	#set up	the third server
	Smtp @=	smtp3.yourdomain.com
	Port @=	25
	Tries @= 5
	max_messages_per_robin @= 1000
	envelope_limit @= 100

       Alternatively, you can use defaults in your master conf file.

	#your server file
	server_file = /etc/mb/server.file.txt

	#These values will apply to all	servers
	Port = 25
	Tries =	5
	max_message_per_robin =	1000
	envelope_limit = 100

       Now, your server	file should look like this:

	define package Mail::Bulkmail::Server

	#set up	the first server
	Smtp @=	smtp1.yourdomain.com

	#set up	the second server
	Smtp @=	smtp2.yourdomain.com

	#set up	the third server
	Smtp @=	smtp3.yourdomain.com

       Be warned that if you want to set up a value for	one server, you	should
       set it up for all of them. Either specify the attribute for a server in
       the master conf file, or	specify	it multiple times for all servers.

SEE ALSO
       Mail::Bulkmail, Mail::Bulkmail::DummyServer

COPYRIGHT (again)
       Copyright and (c) 1999, 2000, 2001, 2002, 2003 James A Thomason III
       (jim@jimandkoka.com). All rights	reserved.  Mail::Bulkmail::Server is
       distributed under the terms of the Perl Artistic	License.

CONTACT	INFO
       So you don't have to scroll all the way back to the top,	I'm Jim
       Thomason	(jim@jimandkoka.com) and feedback is appreciated.  Bug
       reports/suggestions/questions/etc.  Hell, drop me a line	to let me know
       that you're using the module and	that it's made your life easier.  :-)

perl v5.32.0			  2020-08-10		   Bulkmail::Server(3)

NAME | AUTHOR | SYNOPSIS | DESCRIPTION | ATTRIBUTES | METHODS | SAMPLE SERVER FILE | SEE ALSO | COPYRIGHT (again) | CONTACT INFO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Mail::Bulkmail::Server&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help