xp_startmail (Transact-SQL)
Starts a SQL Mail client session. Starting a mail session opens the MAPI client components and logs on to the e-mail server.
Note
This feature will be removed in a future version of Microsoft SQL Server. Avoid using this feature in new development work, and plan to modify applications that currently use this feature.
.gif "Topic link icon")
Transact-SQL Syntax Conventions
Syntax
xp_startmail [ [ @user= ] 'mapi_profile_name' ]
[ , [ @password= ] 'mapi_profile_password' ]
Arguments
- [ @user = ] 'mapi_profile_name'
Is an optional parameter specifying a mail profile name. mapi_profile_nameis sysname, with no default. If this parameter is not provided, then the default configured in Microsoft Outlook is used.
- [ @password = ] 'mapi_profile_password'
Is the mail password for the specified mapi_profile_name. mapi_profile_password is sysname, with no default. A value of NULL is allowed when the mail client is started (on the same computer) before running xp_startmail.
Return Code Values
0 (success) or 1 (failure)
Result Sets
xp_startmail returns this message:
SQL mail session started.
Remarks
If mapi_profile_name and mapi_profile_password are provided, SQL Server attempts to log on to the MAPI provider using that profile name and password. If mapi_profile_name and mapi_profile_password are provided but are incorrect, an error message is returned. If mapi_profile_name and mapi_profile_password are not provided, SQL Server uses the profile name and password specified in the SQL Mail Configuration dialog box. If no profile name or password is explicitly provided, SQL Server attempts to log in to the MAPI provider using the default MAPI profile. Some MAPI providers may be configured to use Windows Authentication, in which case the MAPI password is ignored.
Note
If you use xp_startmail to start your mail sessions, you can optionally supply your login name and password so that you do not have to type it at the command prompt. However, SQL Mail will not run on top of an existing MAPI session if one is running. This behavior differs from SQL Server version 7.0 and earlier.
If there is an existing mail session, xp_startmail does not start a new one. If mail is being used on the same computer on which SQL Server is also running, the mail client must be started either before xp_startmail is run, or before SQL Server is started if SQL Mail is configured to start automatically when SQL Server starts.
Permissions
Requires membership in the sysadmin fixed server role, but EXECUTE permissions can be granted to other users. However, for security reasons, we recommend that permissions for this stored procedure be limited to members of the sysadmin fixed server role.
Examples
The following example starts mail by using the user name and password specified in Microsoft Outlook as the default profile for the Microsoft Windows account that SQL Server runs as.
USE master
EXEC xp_startmail ;
GO
See Also
Reference
sp_processmail (Transact-SQL)
System Stored Procedures (Transact-SQL)
xp_deletemail (Transact-SQL)
xp_findnextmsg (Transact-SQL)
xp_readmail (Transact-SQL)
xp_sendmail (Transact-SQL)
xp_stopmail (Transact-SQL)