Transact-SQL Reference

xp_startmail

Starts a SQL Mail client session.

Syntax

xp_startmail [[@user =] 'mapi_profile_name']
[,[@password =] 'mapi_profile_password']

Arguments

[@user =] 'mapi_profile_name'

Is an optional parameter specifying a mail user name. mapi_profile_name is sysname, with no default.

[@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, Microsoft® SQL Server™ attempts to log on to Windows NT Mail (or other MAPI provider) using that user 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 user name and password specified in the SQL Server Properties dialog box. If no user name or password is explicitly provided, SQL Server will attempt to log in to the MAPI provider using the default MAPI profile. Some MAPI providers may be configured to use Windows Authentication, in which a 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 piggyback an existing client session of Windows NT Mail 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 executed, or before SQL Server is started if SQL Mail is configured to automatically start when SQL Server starts.

Permissions

Execute permissions for xp_startmail default to members of the db_owner fixed database role in the master database and members of the sysadmin fixed server role, but can be granted to other users.

Examples

A. Use no variables with xp_startmail

This example starts mail using the username and password specified in SQL Server Setup.

USE master
EXEC xp_startmail

B. Use variables with xp_startmail

This example starts mail using the username janetl and the password abc12345.

USE master
EXEC xp_startmail 'janetl', 'abc12345'